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

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

Функции для строк включают width(), возвращающую ширину строки в пикселях (или пунктах для принтера), 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 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 &) или horizontalAdvance() вместо этого.

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

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

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

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

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

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

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

См. также width(), 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() для расчёта высоты, а не высоты отдельных символов.

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

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

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

Если Qt::TextExpandTabs установлено в flags, а 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 определяет, усекается ли текст слева (например, "...техн"), посередине (например, "Тр...хн") или справа (например, "Трол...").

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

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

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

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

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

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

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

См. также 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() для графического описания этой метрики.

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

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

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

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

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

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

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

Два объекта метрики шрифта считаются равными, если они были созданы из одного и того же 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!=().