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

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

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

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

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

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

Метрики шрифта будут совместимы с переданным устройством рисования. Если paintdevice равен 0, метрики будут совместимы с экраном, т.е. такими, которые вы получите, если вы используете шрифт для вывода текста на виджеты widgets или pixmap, а не на 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, он задаёт последовательность пиксельных позиций для табуляций; в противном случае, если tabStops не равно нулю, оно используется как интервал табуляции (в пикселях).

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

int QFontMetrics::descent() const

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

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

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

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

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

Параметр mode задаёт, усекается ли текст слева (например, «…тех»), посередине (например, «Tr…ч») или справа (например, «Трол…»).

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

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

Маркер усечения следует за направлением вывода. Например, он будет находиться справа от текста для направлений справа налево, если mode равен Qt::ElideLeft, и слева от текста, если mode равен 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 обрезает текст для соответствия прямоугольнику.

Если в flags установлен флаг Qt::TextExpandTabs, то: если tabArray не равен null, он определяет 0-терминированную последовательность пиксельных позиций для табуляции; иначе, если 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.

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

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