Класс 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, он определяет 0-завершённую последовательность позиций пикселей для табуляции; иначе, если 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, он определяет 0-завершённую последовательность позиций пикселей для табуляции; иначе, если tabStops не равно нулю, используется как интервал табуляции (в пикселях).

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

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

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

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

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

int QFontMetrics::descent() const

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

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

См. также восход().

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

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

Она всегда равна восходу()+спуску().

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

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

Это естественное межстрочное расстояние.

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

Если Qt::TextExpandTabs установлено в flags, то: если 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() вместо этого.

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

Предупреждение: Вызов этого метода очень медленный в 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.

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

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

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

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

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

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