QFontMetrics Class

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

成员函数文档

[explicit] QFontMetrics::QFontMetrics(const QFont &font)

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

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

该字体度量对象保存着创建时通过构造函数传递的字体信息，如果后续更改了字体的属性，该对象不会更新。

使用 QFontMetrics(constQFont &,QPaintDevice *) 可获取与特定绘图设备兼容的字体度量。

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

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

字体度量将与传入的绘图设备兼容。如果paintdevice 是nullptr ，则度量将与屏幕兼容，即当您使用该字体在widgets 或pixmaps 上绘制文本时获得的度量，而非在QPicture 或QPrinter 上绘制文本时获得的度量。

字体度量对象保存的是在创建时通过构造函数传入的字体信息，如果后续更改了字体的属性，该对象不会被更新。

QFontMetrics::QFontMetrics(const QFontMetrics &fm)

创建fm 的副本。

[constexpr noexcept default] QFontMetrics::QFontMetrics(QFontMetrics &&)

通过Move操作构造一个QFontMetrics 的实例。

[noexcept] QFontMetrics::~QFontMetrics()

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

int QFontMetrics::ascent() const

返回字体的升高。

字体的升高是指从基线到字符延伸到的最高位置之间的距离。实际上，有些字体设计师会打破这一规则，例如在字符上方添加多个变音符号，或者为了适应特定字符，因此该值可能（尽管很少见）会过小。

另请参阅 descent()。

int QFontMetrics::averageCharWidth() const

返回该字体中字形的平均宽度。

QRect QFontMetrics::boundingRect(QChar ch) const

如果将字符ch 绘制在坐标系的原点处，则返回被墨水覆盖的矩形。

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

请注意，该矩形通常会延伸到基线以上和以下。

另请参阅 horizontalAdvance()。

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

返回由text 指定的字符串中各字符的边界矩形。该边界矩形始终至少覆盖文本若绘制在(0, 0)位置时所占的像素区域。

请注意，边界矩形可能会延伸到 (0, 0) 的左侧（例如，对于斜体字体），且返回的矩形宽度可能与horizontalAdvance() 方法返回的结果不同。

如果您想知道字符串的进距（以便将一组字符串并排布局），请改用horizontalAdvance()。

换行符被作为普通字符处理，而不是作为换行符处理。

边界矩形的高度至少与height() 返回的值一样大。

另请参阅 horizontalAdvance()、height()、QPainter::boundingRect() 和tightBoundingRect()。

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

返回使用option 布局的、由text 指定的字符串中字符的边界矩形。该边界矩形始终至少覆盖文本若绘制在 (0, 0) 位置时所覆盖的像素集合。

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

如果您想知道字符串的进字宽度（以便将一组字符串并排布局），请改用horizontalAdvance()。

换行符被视为普通字符，而不是换行符。

边界矩形的高度至少与height() 返回的值一样大。

该函数在 Qt 6.3 中引入。

另请参阅 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 不为空，它将指定一个以 0 结尾的制表符像素位置序列；否则，如果tabStops 不为零，则将其用作制表符间距（以像素为单位）。

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

换行符将被处理为换行。

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

另请参阅 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 所指定的矩形内的边界矩形。

如果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()。

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

返回使用 `option` 布局的 `text ` 的水平间距（以像素为单位）。

该间距是text 之后绘制下一个字符所需的距离。

该函数在 Qt 6.3 中引入。

另请参阅 boundingRect()。

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

返回text 中前len 个字符的水平间距（以像素为单位）。如果len 为负数（默认值），则使用整个字符串。即使len 明显较短，也会分析text 的整个长度。

这是在text 之后绘制下一个字符时应保留的间距。

另请参阅 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

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

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 将文本折行以适应矩形区域。

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

换行符将被处理为换行。

尽管实际字符高度不同，但“Yes”和“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) 的左侧（例如，对于斜体字体），并且返回的矩形宽度可能与horizontalAdvance() 方法返回的值不同。

如果您想知道字符串的进距（以便将一组字符串并排布局），请改用horizontalAdvance()。

换行符被视为普通字符，而非换行符。

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

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

返回一个紧包矩形，该矩形包围着由text 指定的字符串中、使用option 布局的字符。该紧包矩形始终至少覆盖文本若绘制在(0, 0)位置时所占的像素范围。

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

如果您想知道字符串的进距（以便将一组字符串并排布局），请改用horizontalAdvance()。

换行符被作为普通字符处理，而非换行符。

此函数在 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==()。

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

将other 通过move-assign操作赋值给此QFontMetrics 实例。

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

设置字体度量值为fm 。

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

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

如果两个字体度量是基于同一个QFont 构建的，且它们所针对的绘制设备被视为兼容，则认为这两个字体度量相等。

另请参阅 operator!=()。