Класс 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.

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 *) для получения метрик шрифта, совместимых с определённым устройством отрисовки.

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

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

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

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.

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

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

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

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.

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

qreal QFontMetrics::fontDpi() const

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

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

int QFontMetrics::height() const

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

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

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

int QFontMetrics::horizontalAdvance(const QString &text, int len = -1) const

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

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

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

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

int QFontMetrics::horizontalAdvance(QChar ch) const

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

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

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

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

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

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

void QFontMetrics::swap(QFontMetrics &other)

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

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

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

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

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

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

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

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

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

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