QFontMetrics 类

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

成员函数文档

[显式] QFontMetrics::QFontMetrics(const QFont &font)

为 font 构造一个字体度量对象。

字体度量将与用于创建 font 的绘画设备兼容。

字体度量对象在创建时保持通过构造函数传入的字体信息，如果之后修改了字体的属性则不会更新。

使用 QFontMetrics(const QFont &, QPaintDevice *) 获取与某个绘画设备兼容的字体度量。

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

为 font 和 paintdevice 构造一个字体度量对象。

字体度量将与传递的绘画设备兼容。如果 paintdevice 是 nullptr，则度量将适用于屏幕，即如果您使用字体绘制窗口或位图的文本时所得到的度量，而不是在 QPicture 或 QPrinter 上。

字体度量对象在创建时保持通过构造函数传入的字体信息，如果之后修改了字体的属性则不会更新。

QFontMetrics::QFontMetrics(const QFontMetrics &fm)

构造 fm 的副本。

[noexcept] QFontMetrics::~QFontMetrics()

销毁字体度量对象并释放所有分配的资源。

int QFontMetrics::ascent() const

返回字体的升升量。

字体的升升量是从基线到最高字符伸展位置的间距。在实践中，一些字体设计师会打破这个规则，例如在字符顶部放置多个附加符号，或者为了适应某个字符，因此这个值可能太小，尽管这种情况很少。

另见 descent。

int QFontMetrics::averageCharWidth() const

返回字体中字符的平均宽度。

QRect QFontMetrics::boundingRect(QChar ch) const

返回一个矩形，该矩形为字符 ch 在坐标系原点处绘制时所覆盖的墨迹区域。

注意，边界矩形可能延伸到 (0, 0) 的左侧（例如，对于斜体字体），并且文本输出可能覆盖边界矩形中的所有像素。对于空格字符，该矩形通常为空。

注意，矩形通常延伸到基线之上和之下。

另请参阅：horizontal Advance ()。

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

返回由 text 指定的字符串中字符的边界矩形。边界矩形始终至少覆盖文本绘制在 (0, 0) 时将要覆盖的像素集。

注意，边界矩形可能延伸到 (0, 0) 的左侧，例如对于斜体字体，且返回矩形的宽度可能与 horizontal Advance () 方法返回的值不同。

如果您想了解字符串的进位宽度（用于将一组字符串并排放置），请改用 horizontal Advance ()。

换行符按正常字符处理，而不是按行断处理。

边界矩形的高度至少与 height () 返回的值相等。

另请参阅：horizontal Advance (), height (), QPainter::boundingRect(), 和 tightBoundingRect ()。

[自 6.3] QRect QFontMetrics::boundingRect(const QString &text, const QTextOption &option) const

返回由 text 指定的字符串的字符的边界矩形，使用 option 进行布局。边界矩形始终至少覆盖文本绘制在 (0, 0) 时将要覆盖的像素集。

注意，边界矩形可能延伸到 (0, 0) 的左侧，例如对于斜体字体，且返回矩形的宽度可能与 horizontal Advance () 方法返回的值不同。

如果您想了解字符串的进位宽度（用于将一组字符串并排放置），请改用 horizontal Advance ()。

换行符按正常字符处理，而不是按行断处理。

边界矩形的高度至少与 height () 返回的值相等。

此函数是在 Qt 6.3 中引入的。

另请参阅：horizontal Advance (), 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非空，则指定制表符的像素位置序列，以0结尾；否则如果 tabStops非零，则使用它作为制表符间距（以像素为单位）。

请注意，边界矩形可能延伸到（0, 0）左侧，例如对于斜体字体，且文本输出可能覆盖边界矩形的所有像素。

换行符被视为行断。

尽管实际字符大小不同，但“是”和“yes”的边界矩形高度相同。

此函数返回的边界矩形略大于简单的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

这是一个重载函数。

返回给定文本在由坐标x和y、width和height指定的矩形内的边界矩形。

如果 Qt::TextExpandTabs在flags中设置且tabArray非空，则它指定制表符的像素位置序列，以0结尾；否则，如果tabStops非零，则将使用它作为制表符间距（以像素为单位）。

int QFontMetrics::capHeight() const

返回字体的字母高度。

字体的大写字母高度是超过基线的大写字母的高度。具体来说，是平的字母的高度，如H或I，而不是圆形的字母，如O，或是尖形的字母如A，后两者可能会显示过冲。

另请参阅ascent。

int QFontMetrics::descent() const

返回字体的下降距离。

下降距离是从基线到字符延伸到的最低点之间的距离。在实际应用中，一些字体设计者会打破这个规则，例如为了适应某个特定字符，因此这个值可能太小（尽管这种情况很少见）。

另请参阅ascent。

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

如果字符串 text 的宽度大于 width，则返回一个省略后的字符串版本（即包含"..."的字符串）。否则，返回原始字符串。

参数 mode 指定文本是在左侧（例如，"...tech"）、中间（例如，"Tr...ch"）还是右侧（例如，"Trol..."）被省略。

width 以像素为单位指定，而不是字符。

flags 参数是可选的，目前仅支持 Qt::TextShowMnemonic 作为值。

省略标记遵循 layoutdirection。例如，如果 mode 是 Qt::ElideLeft，对于从右到左的布局，它将位于文本的右侧；如果 mode 是 Qt::ElideRight，它将位于文本的左侧。

qreal QFontMetrics::fontDpi() const

返回字体DPI。

int QFontMetrics::height() const

返回字体的高度。

这总是等于 ascent()+descent。

另请参阅leading() 和 lineSpacing。

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

返回 text 的前 len 个字符在像素中的水平前进距离。如果 len 是负数（默认值），则使用整个字符串。即使 len 相对较短，也会分析整个 text 的长度。

这是在 text 后绘制下一个字符的适当距离。

另请参阅boundingRect。

[自 6.3] int QFontMetrics::horizontalAdvance(const QString &text, const QTextOption &option) const

返回使用 option 布局的 text 的像素水平前进距离。

前进距离是在 text 后绘制下一个字符的适当距离。

此函数是在 Qt 6.3 中引入的。

另请参阅boundingRect。

int QFontMetrics::horizontalAdvance(QChar ch) const

这是一个重载函数。

返回字符 ch 在像素中的水平推进距离。这是一个适用于在 ch 之后绘制字符的距离。

某些度量在图片中进行了描述。中央的深色矩形覆盖了每个字符的逻辑 horizontalAdvance()。外围的浅色矩形覆盖了每个字符的 leftBearing() 和 rightBearing()。注意，在这个特定字体中，"f" 的基准值都是负的，而 "o" 的基准值都是正的。

另请参阅boundingRect。

bool QFontMetrics::inFont(QChar ch) const

如果字符 ch 是字体中的有效字符，则返回 true；否则返回 false。

bool QFontMetrics::inFontUcs4(uint ucs4) const

如果字符 ucs4 使用 UCS-4/UTF-32 编码是字体中的有效字符，则返回 true；否则返回 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()。

QChar 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非空，则指定制表符的像素位置序列，以0结尾；否则如果 tabStops非零，则使用它作为制表符间距（以像素为单位）。

换行符被视为行断。

尽管实际字符大小不同，但“是”和“yes”的边界矩形高度相同。

另请参阅boundingRect。

int QFontMetrics::strikeOutPos() const

返回从基准线到需要画上删除线的距离。

另请参阅 underlinePos()、overlinePos() 和 lineWidth()。

[noexcept] void QFontMetrics::swap(QFontMetrics &other)

将此字体度量实例与 other 交换。此函数非常快，绝不会失败。

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

返回由 text 指定的字符串中字符的紧密边界矩形。边界矩形始终覆盖至少在 (0,0) 画出文本会覆盖的像素集。

注意，边界矩形可能延伸到 (0, 0) 的左侧，例如对于斜体字体，且返回矩形的宽度可能与 horizontal Advance () 方法返回的值不同。

如果您想了解字符串的进位宽度（用于将一组字符串并排放置），请改用 horizontal Advance ()。

换行符按正常字符处理，而不是按行断处理。

另请参阅 horizontalAdvance()、height() 和 boundingRect().

[自6.3起] QRect QFontMetrics::tightBoundingRect(const QString &text, const QTextOption &option) const

返回使用option进行布局的字符串text周围的紧密边界矩形。边界矩形始终覆盖至少文本在(0, 0)处绘制时将覆盖的像素集。

注意，边界矩形可能延伸到 (0, 0) 的左侧，例如对于斜体字体，且返回矩形的宽度可能与 horizontal Advance () 方法返回的值不同。

如果您想了解字符串的进位宽度（用于将一组字符串并排放置），请改用 horizontal Advance ()。

换行符按正常字符处理，而不是按行断处理。

此函数是在 Qt 6.3 中引入的。

另请参阅 horizontalAdvance()、height() 和 boundingRect().

int QFontMetrics::underlinePos() const

返回基线到画下划线位置的距离。

另请参阅overlinePos()、strikeOutPos()和lineWidth()。

int QFontMetrics::xHeight() const

返回字体的'x'高度。这通常与字符'x'的高度相同，但不总是如此。

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

如果other与此对象不相等，则返回true；否则返回false。

如果两个字体度量是从相同的QFont构造的，并且它们构造的绘图设备被认为是兼容的，则认为两个字体度量是相等的。

另请参阅operator==()。

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

分配字体度量fm。

[noexcept] QFontMetrics &QFontMetrics::operator=(QFontMetrics &&other)

移动赋值other到这个QFontMetrics实例。

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

如果other与此对象相等，则返回true；否则返回false。

如果两个字体度量是从相同的QFont构造的，并且它们构造的绘图设备被认为是兼容的，则认为两个字体度量是相等的。

另请参阅operator!=()。