Класс 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) (например, для наклонных шрифтов), и что вывод текста может занимать все пиксели в прямоугольнике ограничивающей области. Для пробела прямоугольник обычно будет пустым.

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

См. также 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(). Эта функция использует максимальные и правые отступы шрифта, как это необходимо для многострочного текста, чтобы обеспечить правильное выравнивание. Также для расчёта высоты используются 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 указывает, где усекается текст: слева (например, «…тех»), посередине (например, «Tr…ch») или справа (например, «Троль…»).

Ширина 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.

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

Эта функция была введена в 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(символ) всех символов в шрифте.

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

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

int QFontMetrics::minRightBearing() const

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

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

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

См. также 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 разбивает текст, чтобы он уместился в прямоугольник.

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

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

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

См. также 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() вместо этого.

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

См. также 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!=().