Класс QFontMetrics

Класс QFontMetrics предоставляет информацию о метриках шрифта. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются повторно входящими.

Публичные функции

Подробное описание

Функции QFontMetrics вычисляют размер символов и строк для заданного шрифта. Существует три способа создания объекта QFontMetrics:

1. Вызов конструктора QFontMetrics с QFont создаёт объект метрик шрифта для шрифта, совместимого с экраном, т.е. шрифт не может быть шрифтом принтера. Если шрифт изменяется позже, объект метрик шрифта не обновляется.

   (Примечание: если вы используете шрифт принтера, возвращаемые значения могут быть неточными. Шрифты принтеров не всегда доступны, поэтому используется ближайший шрифт для экрана, если предоставлен шрифт принтера.)

2. QWidget::fontMetrics() возвращает метрики шрифта для шрифта виджета. Это эквивалентно QFontMetrics(widget->font()). Если шрифт виджета изменяется позже, объект метрик шрифта не обновляется.
3. QPainter::fontMetrics() возвращает метрики шрифта для текущего шрифта рисовальщика. Если шрифт рисовальщика изменяется позже, объект метрик шрифта не обновляется.

После создания объект предоставляет функции для доступа к индивидуальным метрикам шрифта, его символов и для строк, отрисованных в шрифте.

Существует несколько функций, которые работают со шрифтом: ascent(), descent(), height(), leading() и lineSpacing() возвращают основные свойства размера шрифта. Функции underlinePos(), overlinePos(), strikeOutPos() и lineWidth() возвращают свойства линии, которая подчеркивает, перечеркивает или зачёркивает символы. Все эти функции быстрые.

Также есть некоторые функции, которые работают с набором глифов в шрифте: minLeftBearing(), minRightBearing() и maxWidth(). Они по своей природе медленные, и мы рекомендуем избегать их, если это возможно.

Для каждого символа вы можете получить его horizontalAdvance(), leftBearing() и rightBearing(), и узнать, находится ли он в шрифте, используя inFont(). Вы также можете обработать символ как строку и использовать функции для строк на нём.

Функции для строк включают horizontalAdvance(), для возвращения ширины строки в пикселях (или пунктах, для принтера), boundingRect(), для возвращения прямоугольника, достаточно большого для отображения строки, и size(), для возвращения размера этого прямоугольника.

Пример:

QFont font("times", 24);
QFontMetrics fm(font);
int pixelsWide = fm.horizontalAdvance("What's the width of this text?");
int pixelsHigh = fm.height();

См. также QFont, QFontInfo, QFontDatabase, и Пример карты символов.

Документация по членам-функциям

QFontMetrics::QFontMetrics(const QFontMetrics &fm)

Создаёт копию fm.

[since 5.13] QFontMetrics::QFontMetrics(const QFont &font, const QPaintDevice *paintdevice)

Создаёт объект метрик шрифта для font и paintdevice.

Метрики шрифта будут совместимы с переданным устройством отрисовки. Если paintdevice nullptr, метрики будут совместимы с экраном, т. е. такими, как если бы вы использовали шрифт для отрисовки текста на виджетах или растровых изображениях, а не на QPicture или QPrinter.

Объект метрик шрифта содержит информацию о шрифте, переданном в конструктор во время его создания, и не обновляется, если атрибуты шрифта изменяются позднее.

Функция была добавлена в Qt 5.13.

QFontMetrics::QFontMetrics(const QFont &font)

Создаёт объект метрик шрифта для font.

Метрики шрифта будут совместимы с устройством отрисовки, используемым для создания font.

Объект метрик шрифта содержит информацию о шрифте, переданном в конструктор во время его создания, и не обновляется, если атрибуты шрифта изменяются позднее.

Используйте QFontMetrics(const QFont &, QPaintDevice *) для получения метрик шрифта, совместимых с определённым устройством отрисовки.

[since 5.2] QFontMetrics &QFontMetrics::operator=(QFontMetrics &&other)

Перемещающее присваивание other этому экземпляру QFontMetrics.

Функция была добавлена в Qt 5.2.

QFontMetrics &QFontMetrics::operator=(const QFontMetrics &fm)

Присваивает метрики шрифта fm.

QFontMetrics::~QFontMetrics()

Уничтожает объект метрик шрифта и освобождает все выделенные ресурсы.

int QFontMetrics::ascent() const

Возвращает величину восхождения шрифта.

Восхождение шрифта — это расстояние от базовой линии до самой высокой позиции, до которой доходят символы. На практике некоторые дизайнеры шрифтов нарушают это правило, например, когда они размещают более одного диакритического знака сверху символа или для адаптации определённого символа, поэтому возможно (хотя и редко), что это значение будет слишком малым.

См. также descent().

int QFontMetrics::averageCharWidth() const

Возвращает среднюю ширину глифов в шрифте.

QRect QFontMetrics::boundingRect(QChar ch) const

Возвращает прямоугольник, покрываемый чернилами, если символ ch был бы нарисован в начале системы координат.

Обратите внимание, что прямоугольник ограничивающей области может простираться влево от (0, 0) (например, для наклонных шрифтов), и что вывод текста может покрывать все пиксели в прямоугольнике ограничивающей области. Для пробела прямоугольник, как правило, будет пустым.

Обратите внимание, что прямоугольник, как правило, простирается как выше, так и ниже базовой линии.

Предупреждение: Ширина возвращаемого прямоугольника не является шириной продвижения символа. Используйте boundingRect(const QString &) или horizontalAdvance() вместо этого.

См. также horizontalAdvance().

QRect QFontMetrics::boundingRect(const QString &text) const

Возвращает прямоугольник, ограничивающий символы в строке, заданной text. Прямоугольник ограничивающей области всегда покрывает по крайней мере набор пикселей, которые текст покроет, если нарисован в (0, 0).

Обратите внимание, что прямоугольник ограничивающей области может простираться влево от (0, 0), например, для наклонных шрифтов, и что ширина возвращаемого прямоугольника может отличаться от того, что возвращает метод horizontalAdvance().

Если вам нужна ширина продвижения строки (для выкладки набора строк рядом друг с другом), используйте horizontalAdvance() вместо этого.

Символы новой строки обрабатываются как обычные символы, а не как разрывы строк.

Высота прямоугольника ограничивающей области по крайней мере так же велика, как возвращаемое значение height().

См. также horizontalAdvance(), height(), QPainter::boundingRect() и tightBoundingRect().

QRect QFontMetrics::boundingRect(const QRect &rect, int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const

Это перегруженная функция.

Возвращает прямоугольник, ограничивающий символы в строке, заданной text, которая представляет собой набор пикселей, которые текст покроет, если нарисован в (0, 0). Отрисовка, а следовательно, и прямоугольник ограничивающей области, ограничены прямоугольником rect.

Аргумент flags — это побитовое ИЛИ следующих флагов:

• Qt::AlignLeft выравнивает по левому краю, за исключением арабского и иврита, где он выравнивается по правому краю.
• Qt::AlignRight выравнивает по правому краю, за исключением арабского и иврита, где он выравнивается по левому краю.
• Qt::AlignJustify выравнивает текст по ширине.
• Qt::AlignHCenter выравнивает по горизонтали по центру.
• Qt::AlignTop выравнивает по верхнему краю.
• Qt::AlignBottom выравнивает по нижнему краю.
• Qt::AlignVCenter выравнивает по вертикали по центру
• Qt::AlignCenter (== Qt::AlignHCenter | Qt::AlignVCenter)
• Qt::TextSingleLine игнорирует символы новой строки в тексте.
• Qt::TextExpandTabs расширяет табуляцию (см. ниже)
• Qt::TextShowMnemonic интерпретирует "&x" как x; т. е. подчеркнутый.
• Qt::TextWordWrap разбивает текст, чтобы он уместился в прямоугольник.

Qt::Horizontal выравнивание по умолчанию — Qt::AlignLeft, а вертикальное выравнивание — Qt::AlignTop.

Если установлено несколько флагов горизонтального или нескольких вертикального выравнивания, результат выравнивания не определён.

Если установлен флаг Qt::TextExpandTabs в flags, то: если tabArray не равен null, он указывает на последовательность позиций пикселей для табуляции, заканчивающуюся нулём; в противном случае, если tabStops не равно нулю, оно используется в качестве отступа табуляции (в пикселях).

Обратите внимание, что прямоугольник ограничивающей области может простираться влево от (0, 0), например, для наклонных шрифтов, и что вывод текста может покрывать все пиксели в прямоугольнике ограничивающей области.

Символы новой строки обрабатываются как разрывы строк.

Несмотря на разную фактическую высоту символов, высоты прямоугольников ограничивающей области для "Да" и "да" одинаковы.

Прямоугольник ограничивающей области, возвращаемый этой функцией, немного больше, чем тот, который вычисляется с помощью более простой функции boundingRect(). Эта функция использует максимальные слева и справа отступы шрифта (bearings), что необходимо для многострочного текста, чтобы обеспечить правильное выравнивание. Кроме того, для вычисления высоты используются fontHeight() и lineSpacing(), а не высоты отдельных символов.

См. также horizontalAdvance(), QPainter::boundingRect() и Qt::Alignment.

QRect QFontMetrics::boundingRect(int x, int y, int width, int height, int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const

Это перегруженная функция.

Возвращает прямоугольник ограничивающей области для заданного text внутри прямоугольника, заданного координатами x и y, width и height.

Если установлен флаг Qt::TextExpandTabs в flags, и tabArray не равен null, он указывает на последовательность позиций пикселей для табуляции, заканчивающуюся нулём; в противном случае, если tabStops не равно нулю, оно используется в качестве отступа табуляции (в пикселях).

[since 5.8] int QFontMetrics::capHeight() const

Возвращает высоту крышки шрифта.

Высота крышки шрифта — это высота заглавной буквы над базовой линией. Конкретно, это высота заглавных букв, которые плоские — например, H или I — в отличие от круглых букв, таких как O, или заострённых букв, таких как A, которые могут отображать избыточность.

Функция была добавлена в Qt 5.8.

См. также ascent().

int QFontMetrics::descent() const

Возвращает величину нисхождения шрифта.

Нисхождение — это расстояние от базовой линии до самой нижней точки, до которой доходят символы. На практике некоторые дизайнеры шрифтов нарушают это правило, например, для адаптации определённого символа, поэтому возможно (хотя и редко), что это значение будет слишком малым.

См. также ascent().

QString QFontMetrics::elidedText(const QString &text, Qt::TextElideMode mode, int width, int flags = 0) const

Если строка text шире, чем width, возвращает усечённую версию строки (т.е., строку с "..." в ней). В противном случае возвращает исходную строку.

Параметр mode определяет, усекается ли текст слева (например, "...техн"), посередине (например, "Техн...") или справа (например, "Технол...").

width задаётся в пикселях, а не в символах.

Аргумент flags необязателен и в настоящее время поддерживает только Qt::TextShowMnemonic в качестве значения.

Усекающий символ следует за направлением выравнивания. Например, он будет расположен справа от текста для правосторонних выкладок, если mode равен Qt::ElideLeft, и слева от текста, если mode равен Qt::ElideRight.

[since 5.14] qreal QFontMetrics::fontDpi() const

Возвращает DPI шрифта.

Эта функция была добавлена в Qt 5.14.

int QFontMetrics::height() const

Возвращает высоту шрифта.

Она всегда равна ascent()+descent().

См. также leading() и lineSpacing().

[since 5.11] int QFontMetrics::horizontalAdvance(const QString &text, int len = -1) const

Возвращает горизонтальный отступ в пикселях первых len символов строки text. Если len отрицательно (по умолчанию), используется вся строка.

Это расстояние, необходимое для рисования последующего символа после text.

Эта функция была добавлена в Qt 5.11.

См. также boundingRect().

[since 5.11] int QFontMetrics::horizontalAdvance(QChar ch) const

Это перегруженная функция.

Возвращает горизонтальный отступ символа ch в пикселях. Это расстояние, необходимое для рисования последующего символа после ch.

Некоторые из метрик описаны на изображении. Центральные тёмные прямоугольники покрывают логический horizontalAdvance() каждого символа. Внешние светлые прямоугольники покрывают leftBearing() и rightBearing() каждого символа. Обратите внимание, что отступы "f" в этом шрифте оба отрицательные, а отступы "o" оба положительные.

Предупреждение: Эта функция может давать неверные результаты для арабских символов или неразрывных знаков посередине строки, так как форматирование и позиционирование глифов знаков при обработке строк не учитываются. При реализации интерактивного текстового элемента используйте QTextLayout вместо этого.

Эта функция была добавлена в Qt 5.11.

См. также boundingRect().

bool QFontMetrics::inFont(QChar ch) const

Возвращает true если символ ch является допустимым символом в шрифте; в противном случае возвращает false.

bool QFontMetrics::inFontUcs4(uint ucs4) const

Возвращает true если символ ucs4, закодированный в UCS-4/UTF-32, является допустимым символом в шрифте; в противном случае возвращает false.

int QFontMetrics::leading() const

Возвращает ведущее значение шрифта.

Это естественный интерлинейный интервал.

См. также height() и lineSpacing().

int QFontMetrics::leftBearing(QChar ch) const

Возвращает левый отступ символа ch в шрифте.

Левый отступ — это расстояние вправо от левого пикселя символа до логического начала символа. Это значение отрицательное, если пиксели символа выходят за пределы логического начала.

См. horizontalAdvance() для графического описания этой метрики.

См. также rightBearing(), minLeftBearing() и horizontalAdvance().

int QFontMetrics::lineSpacing() const

Возвращает расстояние от одной базовой линии до следующей.

Это значение всегда равно leading()+height().

См. также height() и leading().

int QFontMetrics::lineWidth() const

Возвращает ширину подчёркнутых и зачёркнутых линий, скорректированную с учётом размера шрифта.

См. также underlinePos(), overlinePos() и strikeOutPos().

int QFontMetrics::maxWidth() const

Возвращает ширину самого широкого символа в шрифте.

int QFontMetrics::minLeftBearing() const

Возвращает минимальный левый отступ шрифта.

Это наименьшее leftBearing(char) всех символов в шрифте.

Обратите внимание, что эта функция может быть очень медленной, если шрифт большой.

См. также minRightBearing() и leftBearing().

int QFontMetrics::minRightBearing() const

Возвращает минимальный правый отступ шрифта.

Это наименьший rightBearing(char) всех символов в шрифте.

Обратите внимание, что эта функция может быть очень медленной, если шрифт большой.

См. также minLeftBearing() и rightBearing().

int QFontMetrics::overlinePos() const

Возвращает расстояние от базовой линии до места, где должна быть нарисована верхняя черта.

См. также underlinePos(), strikeOutPos() и lineWidth().

int QFontMetrics::rightBearing(QChar ch) const

Возвращает правый отступ символа ch в шрифте.

Правый отступ — это расстояние влево от правого пикселя символа до логического начала последующего символа. Это значение отрицательное, если пиксели символа выходят за пределы horizontalAdvance() символа.

См. horizontalAdvance() для графического описания этой метрики.

См. также leftBearing(), minRightBearing() и horizontalAdvance().

QSize QFontMetrics::size(int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const

Возвращает размер text в пикселях.

Аргумент flags — это битовое ИЛИ следующих флагов:

• Qt::TextSingleLine игнорирует символы новой строки.
• Qt::TextExpandTabs расширяет табуляцию (см. ниже)
• Qt::TextShowMnemonic интерпретирует "&x" как x; т.е., подчёркнутое.
• Qt::TextWordWrap разбивает текст для соответствия прямоугольнику.

Если Qt::TextExpandTabs установлен в flags, то: если tabArray не равен null, он указывает на 0-терминированную последовательность положений табуляции в пикселях; в противном случае, если tabStops не равен 0, он используется как интервал табуляции (в пикселях).

Символы новой строки обрабатываются как разрывы строк.

Несмотря на разные фактические высоты символов, высоты прямоугольников обвода "Да" и "да" одинаковы.

См. также boundingRect().

int QFontMetrics::strikeOutPos() const

Возвращает расстояние от базовой линии до места, где должна быть нарисована зачёркнутая линия.

См. также underlinePos(), overlinePos() и lineWidth().

[since 5.0] void QFontMetrics::swap(QFontMetrics &other)

Меняет местами этот экземпляр метрик шрифта с other. Эта функция очень быстрая и никогда не завершается неудачей.

Эта функция была добавлена в Qt 5.0.

QRect QFontMetrics::tightBoundingRect(const QString &text) const

Возвращает плотный прямоугольник обвода вокруг символов в строке, заданной text. Прямоугольник обвода всегда охватывает по крайней мере набор пикселей, которые текст займёт при отрисовке в (0, 0).

Обратите внимание, что ограничивающая прямоугольная область может выходить за пределы (0, 0), например, для курсивного шрифта, и что ширина возвращаемого прямоугольника может отличаться от значения, возвращаемого методом horizontalAdvance().

Если вам нужно узнать ширину продвижения строки (для выравнивания набора строк рядом друг с другом), используйте horizontalAdvance() вместо этого.

Символы новой строки обрабатываются как обычные символы, а не как разрывы строк.

Предупреждение: Вызов этого метода очень медленный в Windows.

См. также horizontalAdvance(), height() и boundingRect().

int QFontMetrics::underlinePos() const

Возвращает расстояние от базовой линии до места, где должна быть нарисована черта подчеркивания.

См. также overlinePos(), strikeOutPos() и lineWidth().

int QFontMetrics::xHeight() const

Возвращает высоту 'x' шрифта. Это часто, но не всегда, совпадает с высотой символа 'x'.

bool QFontMetrics::operator!=(const QFontMetrics &other) const

Возвращает true если other не равно этому объекту; в противном случае возвращает false.

Два объекта QFontMetrics считаются равными, если они были созданы из одного и того же QFont и устройства рисования, для которого они были созданы, считаются совместимыми.

См. также operator==().

bool QFontMetrics::operator==(const QFontMetrics &other) const

Возвращает true если other равно этому объекту; в противном случае возвращает false.

Два объекта QFontMetrics считаются равными, если они были созданы из одного и того же QFont и устройства рисования, для которого они были созданы, считаются совместимыми.

См. также operator!=().