Класс QFontMetrics

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

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

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

Пример:

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

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

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

QFontMetrics::QFontMetrics(const QFont &font)

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

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

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

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

QFontMetrics::QFontMetrics(const QFont &font, QPaintDevice *paintdevice)

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

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

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

QFontMetrics::QFontMetrics(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 &) или width() вместо этого.

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

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

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

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

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

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

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

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

QRect QFontMetrics::boundingRect(const QRect &rect, int flags, const QString &text, int tabStops = 0, int *tabArray = Q_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, 0), например, для наклонного шрифта, и что вывод текста может покрывать все пиксели в прямоугольнике ограничивающей области.

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

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

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

См. также width(), 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 = Q_NULLPTR) const

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

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

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

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 в качестве значения.

Отметка эллипса следует за направлением макета. Например, она будет расположена справа от текста для макетов справа налево, если режим равен Qt::ElideLeft, и слева от текста, если режим равен Qt::ElideRight.

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

int QFontMetrics::height() const

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

Это всегда равно ascent()+descent().

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

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 в шрифте.

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

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

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

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 в шрифте.

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

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

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

QSize QFontMetrics::size(int flags, const QString &text, int tabStops = 0, int *tabArray = Q_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), например, для наклонных шрифтов, и что ширина возвращённого прямоугольника может отличаться от значения, возвращаемого методом width().

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

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

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

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

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

int QFontMetrics::underlinePos() const

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

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

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

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

Обратите внимание, что это значение не равно boundingRect().width(); boundingRect() возвращает прямоугольник, описывающий пиксели, которые эта строка будет занимать, в то время как width() возвращает расстояние до того, где должна быть нарисована следующая строка.

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

int QFontMetrics::width(QChar ch) const

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

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

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

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

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

int QFontMetrics::xHeight() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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