QFont Class

成员函数文档

QFont::QFont()

创建一个使用应用程序默认字体的字体对象。

另请参阅 QGuiApplication::setFont() 和QGuiApplication::font()。

QFont::QFont(const QFont &font, const QPaintDevice *pd)

从font 构建一个字体，用于绘图设备pd 。

QFont::QFont(const QString &family, int pointSize = -1, int weight = -1, bool italic = false)

根据指定的family 、pointSize 、weight 和italic 设置创建一个字体对象。

如果pointSize 为零或负数，则字体的点大小将设置为取决于系统的默认值。通常，该值为12点。

family 的名称可选地包含字体厂商名称，例如“Helvetica [Cronyx]”。如果同一字体家族family 由多个厂商提供且未指定厂商，则会随机选择一家厂商。如果该字体家族不可用，将通过font matching 算法设置字体家族。

这将按逗号分割字体家族字符串，并使用生成的列表调用setFamilies()。若要保留名称中包含逗号的字体，请使用接受QStringList 作为参数的构造函数。

另请参阅 Weight 、setFamily()、setPointSize()、setWeight()、setItalic()、setStyleHint()、setFamilies() 以及QGuiApplication::font()。

[explicit] QFont::QFont(const QStringList &families, int pointSize = -1, int weight = -1, bool italic = false)

根据指定的families 、pointSize 、weight 和italic 设置创建一个字体对象。

如果pointSize 为零或负数，则字体的点大小将设置为取决于系统的默认值。通常，该值为12点。

families 中的每个字体家族名称条目也可可选地包含字体厂商名称，例如“Helvetica [Cronyx]”。 如果该字体家族由多个字体厂商提供，且未指定具体厂商，则会随机选择一家厂商。如果该字体家族不可用，将使用font matching 算法设置一个字体家族。

另请参阅 Weight 、setPointSize()、setWeight()、setItalic()、setStyleHint()、setFamilies() 以及QGuiApplication::font()。

QFont::QFont(const QFont &font)

创建一个与font 相同的字体。

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

通过move操作构造一个QFont 实例。

[noexcept] QFont::~QFont()

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

bool QFont::bold() const

如果weight() 的值大于QFont::Medium ，则返回true ；否则返回false 。

另请参阅 weight()、setBold() 和QFontInfo::bold()。

QFont::Capitalization QFont::capitalization() const

返回字体的当前大写类型。

另请参阅 setCapitalization()。

[since 6.7] void QFont::clearFeatures()

清除QFont 上先前设置的任何字体特性。

有关字体特性的更多详细信息，请参阅setFeature()。

此函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setFeature()、unsetFeature()、featureTags() 和featureValue()。

[since 6.7] void QFont::clearVariableAxes()

清除QFont 上之前设置的任何变量轴值。

有关可变坐标轴的更多详细信息，请参阅setVariableAxis()。

该函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setVariableAxis()、unsetVariableAxis()、isVariableAxisSet() 和variableAxisValue()。

QString QFont::defaultFamily() const

返回与当前样式提示对应的字体家族名称。

另请参阅 StyleHint 、styleHint() 和setStyleHint()。

bool QFont::exactMatch() const

如果存在与该字体设置完全匹配的窗口系统字体，则返回true 。

另请参阅 QFontInfo 。

QStringList QFont::families() const

返回请求的字体家族名称，即在最近一次调用setFamilies() 时或通过构造函数设置的名称。否则，返回一个空列表。

另请参阅 setFamily()、setFamilies()、family()、substitutes() 以及substitute()。

QString QFont::family() const

返回所请求的字体家族名称。该名称始终与families()调用中的第一个条目相同。

另请参阅 setFamily()、substitutes()、substitute()、setFamilies() 以及families()。

[since 6.7] QList<QFont::Tag> QFont::featureTags() const

返回当前在此QFont 上设置的所有字体特征的标签列表。

有关字体特性的更多详细信息，请参阅setFeature()。

该函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setFeature()、unsetFeature()、isFeatureSet() 以及clearFeatures()。

[since 6.7] quint32 QFont::featureValue(QFont::Tag tag) const

返回特定功能tag 的设置值。如果该标签尚未设置，则返回0。

有关字体特性的更多详细信息，请参阅setFeature()。

该函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setFeature()、unsetFeature()、featureTags() 以及isFeatureSet()。

bool QFont::fixedPitch() const

如果已设置固定步长，则返回true ；否则返回false 。

另请参见 setFixedPitch() 和QFontInfo::fixedPitch()。

bool QFont::fromString(const QString &descrip)

将此字体设置为与描述descrip 匹配。该描述是由逗号分隔的字体属性列表，与toString() 函数返回的结果一致。

另请参阅 toString()。

QFont::HintingPreference QFont::hintingPreference() const

返回使用此字体渲染的字形当前的首选提示级别。

另请参阅 setHintingPreference()。

[static] void QFont::insertSubstitution(const QString &familyName, const QString &substituteName)

将substituteName 插入到族familyName 的替换表中。

在替换字体后，通过销毁并重新创建所有QFont 对象来触发字体的更新。

另请参阅 insertSubstitutions()、removeSubstitutions()、substitutions()、substitute() 以及substitutes()。

[static] void QFont::insertSubstitutions(const QString &familyName, const QStringList &substituteNames)

将字体族列表substituteNames 插入到familyName 的替换列表中。

在替换字体后，通过销毁并重新创建所有QFont 对象来触发字体的更新。

另请参阅 insertSubstitution()、removeSubstitutions()、substitutions()，以及substitute()。

bool QFont::isCopyOf(const QFont &f) const

如果该字体与 `f ` 是彼此的副本（即其中一个是另一个的副本创建的，且自创建以来均未被修改），则返回 `true `。这比简单相等运算的判断要严格得多。

另请参阅 operator=() 和operator==()。

[since 6.7] bool QFont::isFeatureSet(QFont::Tag tag) const

如果已为QFont 设置了由tag 指定的特征值，则返回true；否则返回false。

有关字体特性的更多详细信息，请参阅setFeature()。

此函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setFeature()、unsetFeature()、featureTags() 和featureValue()。

[since 6.7] bool QFont::isVariableAxisSet(QFont::Tag tag) const

tag 如果QFont 中指定的变量axis的值已在 上设置，则返回true；否则返回false。

有关字体变量轴的更多详细信息，请参阅setVariableAxis()。

此函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setVariableAxis()、unsetVariableAxis()、variableAxisValue() 和clearVariableAxes()。

bool QFont::italic() const

true 如果字体的style() 不是QFont::StyleNormal

另请参阅 setItalic() 和style()。

bool QFont::kerning() const

如果使用此字体绘制文本时应使用字间距调整，则返回true 。

另请参阅 setKerning()。

QString QFont::key() const

返回字体的键，即字体的文本表示形式。它通常用作字体缓存或字典的键。

另请参阅 QMap 。

qreal QFont::letterSpacing() const

返回该字体的字母间距。

另请参阅 setLetterSpacing()、letterSpacingType() 以及setWordSpacing()。

QFont::SpacingType QFont::letterSpacingType() const

返回用于字母间距的间距类型。

另请参阅 letterSpacing()、setLetterSpacing()，以及setWordSpacing()。

bool QFont::overline() const

如果已设置上划线，则返回true ；否则返回false 。

另请参阅 setOverline()。

int QFont::pixelSize() const

如果字体大小是通过 `setPixelSize()` 设置的，则返回该字体的像素大小；如果字体大小是通过 `setPointSize()` 或 `setPointSizeF()` 设置的，则返回 -1。

另请参见 setPixelSize()、pointSize()、QFontInfo::pointSize() 和QFontInfo::pixelSize()。

int QFont::pointSize() const

返回字体的点尺寸。如果字体大小以像素为单位指定，则返回 -1。

另请参阅 setPointSize() 和pointSizeF()。

qreal QFont::pointSizeF() const

返回字体的点大小。如果字体大小以像素为单位指定，则返回 -1。

另请参阅 pointSize()、setPointSizeF()、pixelSize()、QFontInfo::pointSize() 以及QFontInfo::pixelSize()。

[static] void QFont::removeSubstitutions(const QString &familyName)

删除所有对familyName 的替换。

另请参阅 insertSubstitutions()、insertSubstitution()、substitutions() 以及substitute()。

QFont QFont::resolve(const QFont &other) const

返回一个新的QFont 对象，该对象从other 中复制了尚未在此字体上设置过的属性。

void QFont::setBold(bool enable)

如果 `enable ` 为真，则将字体的粗细设置为 `QFont::Bold`；否则，将粗细设置为 `QFont::Normal`。

若需更精细的粗体控制，请使用setWeight()。

另请参阅 bold() 和setWeight()。

void QFont::setCapitalization(QFont::Capitalization caps)

将此字体中文本的大小写格式设置为caps 。

字体的首字母大写设置会使文本以所选的首字母大写模式显示。

另请参阅 capitalization()。

void QFont::setFamilies(const QStringList &families)

设置该字体的字体家族名称列表。这些名称不区分大小写，且可包含字体厂商名称。families 中排在首位的字体家族将被设为该字体的默认字体家族。

families 中的每个字体家族名称条目也可可选地包含字体厂商名称，例如“Helvetica [Cronyx]”。 如果该字体家族由多个字体厂商提供且未指定具体厂商，则会随机选择一家厂商。如果该字体家族不可用，则将使用font matching 算法设置一个字体家族。

另请参阅 family()、families()、setFamily()、setStyleHint() 以及QFontInfo 。

void QFont::setFamily(const QString &family)

设置字体的家族名称。该名称不区分大小写，且可包含字体厂商名称。

family 名称可选地包含字体厂商名称，例如“Helvetica [Cronyx]”。如果同一字体家族（family ）由多个厂商提供且未指定具体厂商，则会随机选择一家厂商。如果该字体家族不可用，将使用font matching 算法设置一个字体家族。

另请参阅 family()、setStyleHint()、setFamilies()、families() 以及QFontInfo 。

[since 6.7] void QFont::setFeature(QFont::Tag tag, quint32 value)

在对文本进行塑形时，将一个整数值应用于由tag 指定的排版特征。这提供了对字体塑形过程的高级访问权限，可用于支持API中未涵盖的字体特征。

该特征由tag 指定，其通常由字体特征映射中四字符的特征名称编码而来。

在大多数情况下，随标签传递的该整数value 代表一个布尔值：零值表示该特征已禁用，非零值表示已启用。然而，对于某些字体特征，它可能有其他含义。例如，当应用于salt 特征时，该值是一个索引，用于指定要使用的样式变体。

例如，frac 字体功能会将用斜杠分隔的斜向分数（如1/2 ）转换为不同的表示形式。通常，这会将整个分数“烘焙”成单个字符宽度（如½ ）。

如果字体支持frac 功能，则可在排版器中通过在字体功能映射中设置features["frac"] = 1 来启用该功能。

该函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、clearFeatures()、unsetFeature() 以及featureTags()。

void QFont::setFixedPitch(bool enable)

如果enable 为 true，则启用固定音高；否则，禁用固定音高。

另请参阅 fixedPitch() 和QFontInfo 。

void QFont::setHintingPreference(QFont::HintingPreference hintingPreference)

将字形提示级别的首选项设置为hintingPreference 。这是对底层字体渲染系统的一个提示，用于指定使用特定级别的提示，且不同平台对该功能的支持程度各不相同。更多详细信息，请参阅QFont::HintingPreference 文档中的表格。

默认提示首选项为QFont::PreferDefaultHinting 。

另请参阅 hintingPreference()。

void QFont::setItalic(bool enable)

如果enable 为真，则将字体的style()设置为QFont::StyleItalic ；否则，该样式将设置为QFont::StyleNormal 。

另请参阅 italic() 和QFontInfo 。

void QFont::setKerning(bool enable)

如果enable 为true，则启用此字体的字间距调整；否则禁用。默认情况下，字间距调整处于启用状态。

当字间距调整功能启用时，字形度量值将不再相加，即使是拉丁文也是如此。换言之，width('a') + width('b') 等于 width("ab") 这一假设并不一定成立。

另请参阅 kerning() 和QFontMetrics 。

void QFont::setLetterSpacing(QFont::SpacingType type, qreal spacing)

将字体的字间距设置为spacing ，间距类型设置为type 。

字母间距会更改字体中单个字母之间的默认间距。根据所选的间距类型，字母之间的间距既可以缩小，也可以扩大，单位可以是字符宽度的百分比，也可以是像素。

另请参阅 letterSpacing()、letterSpacingType() 以及setWordSpacing()。

void QFont::setOverline(bool enable)

如果enable 为真，则开启上划线；否则关闭上划线。

另请参阅 overline() 和QFontInfo 。

void QFont::setPixelSize(int pixelSize)

将字体大小设置为pixelSize 像素，最大值为一个无符号16位整数。

使用此函数会导致字体依赖于设备。请使用setPointSize() 或setPointSizeF() 以与设备无关的方式设置字体大小。

另请参阅 pixelSize()。

void QFont::setPointSize(int pointSize)

将字号设置为pointSize 。字号必须大于零。

另请参阅 pointSize() 和setPointSizeF()。

void QFont::setPointSizeF(qreal pointSize)

将点大小设置为pointSize 。点大小必须大于零。并非所有平台都能达到所请求的精度。

另请参阅 pointSizeF()、setPointSize() 和setPixelSize()。

void QFont::setStretch(int factor)

设置字体的拉伸系数。

拉伸系数可匹配字体的紧缩版或扩展版，或应用拉伸变换，将字体中所有字符的宽度按factor 百分比进行调整。 例如，将factor 设置为150，会导致字体中的所有字符宽度增加1.5倍（即150%）。拉伸系数的最小值为1，最大值为4000。默认拉伸系数为AnyStretch ，该设置将接受任何拉伸系数，但不会对字体应用任何变换。

拉伸系数仅适用于轮廓字体。对于位图字体，拉伸系数将被忽略。

另请参阅 stretch() 和QFont::Stretch 。

void QFont::setStrikeOut(bool enable)

如果 `enable ` 为真，则启用三振功能；否则禁用三振功能。

另请参阅 strikeOut() 和QFontInfo 。

void QFont::setStyle(QFont::Style style)

将字体样式设置为style 。

另请参阅 style()、italic() 以及QFontInfo 。

void QFont::setStyleHint(QFont::StyleHint hint, QFont::StyleStrategy strategy = PreferDefault)

将样式提示和样式策略分别设置为hint 和strategy 。

如果未显式设置这些参数，样式提示将默认为AnyStyle ，样式策略将默认为PreferDefault 。

Qt 不支持 X11 上的样式提示，因为窗口系统不提供此类信息。

另请参阅 StyleHint 、styleHint()、StyleStrategy 、styleStrategy() 以及QFontInfo 。

void QFont::setStyleName(const QString &styleName)

将字体的样式名称设置为styleName 。设置后，在字体匹配过程中将忽略style()和weight()等其他样式属性，但如果平台字体引擎支持，这些属性随后可能会被模拟出来。

由于人工模拟的样式质量较低，且缺乏全面的跨平台支持，因此不建议将按样式名称匹配与按样式属性匹配结合使用

另请参阅 styleName()。

void QFont::setStyleStrategy(QFont::StyleStrategy s)

将字体的样式策略设置为s 。

另请参阅 styleStrategy() 和QFont::StyleStrategy 。

void QFont::setUnderline(bool enable)

如果enable 为真，则启用下划线；否则禁用下划线。

另请参阅 underline() 和QFontInfo 。

[since 6.7] void QFont::setVariableAxis(QFont::Tag tag, float value)

将value 应用于与tag 相对应的可变轴。

可变字体提供了一种在同一字体文件中存储多种变体（具有不同的字重、字宽或样式）的方法。这些变体以浮点数值的形式表示，对应于一组预定义的参数，称为“可变轴”。 具体实例通常由字体设计师命名，在 Qt 中，这些实例可以通过 `setStyleName()` 进行选择，就像传统的子字族一样。

在某些情况下，为不同的轴提供任意值也很有用。例如，如果一种字体有 Regular 和 Bold 子家族，您可能希望获得介于两者之间的字重。此时，您可以通过为字体的“wght”轴提供自定义值来手动请求该字重。

QFont font;
font.setVariableAxis("wght", (QFont::Normal + QFont::Bold) / 2.0f);

如果字体支持“wght”轴，且给定的值在其定义的范围内，则会提供对应字重为 550.0 的字体。

许多字体都提供了一些标准轴，例如“wght”（字重）、“wdth”（字宽）、“ital”（斜体）和“opsz”（光学尺寸）。它们各自在字体内部都有定义的独立范围。 例如，“wght”的范围可能从 100 到 900（QFont::Thin 到QFont::Black ），而“ital”的范围则可能从 0 到 1（从非斜体到完全斜体）。

字体还可以选择定义自定义坐标轴；唯一的限制是名称必须符合QFont::Tag 的要求（即由四个 Latin-1 字符组成的序列）。

默认情况下，未设置任何可变轴。

此函数在 Qt 6.7 中引入。

另请参阅 unsetVariableAxis 。

void QFont::setWeight(QFont::Weight weight)

将字体的权重设置为weight ，并使用QFont::Weight 枚举中定义的缩放比例。

另请参阅 weight() 和QFontInfo 。

void QFont::setWordSpacing(qreal spacing)

将该字体的词间距设置为spacing 。

单词间距会改变单词之间的默认间距。正值会相应地增加单词间距的像素数，而负值则会相应地减少单词间距。

对于单词之间没有空格分隔的书写系统，单词间距将不适用。

另请参阅 wordSpacing() 和setLetterSpacing()。

int QFont::stretch() const

返回该字体的拉伸系数。

另请参阅 setStretch()。

bool QFont::strikeOut() const

如果已设置“strikeout”，则返回true ；否则返回false 。

另请参阅 setStrikeOut()。

QFont::Style QFont::style() const

返回字体的样式。

另请参阅 ` setStyle()`。

QFont::StyleHint QFont::styleHint() const

返回StyleHint 。

该样式提示会影响font matching algorithm 。有关可用提示的列表，请参阅QFont::StyleHint 。

另请参阅 setStyleHint()、QFont::StyleStrategy 以及QFontInfo::styleHint()。

QString QFont::styleName() const

返回请求的字体样式名称。这可用于匹配具有非标准样式（无法在其他样式属性中进行规范化）的字体。

另请参阅 setStyleName()、setFamily() 和setStyle()。

QFont::StyleStrategy QFont::styleStrategy() const

返回StyleStrategy 。

样式策略会影响font matching 算法。有关可用策略的列表，请参阅QFont::StyleStrategy 。

另请参阅 setStyleStrategy()、setStyleHint() 以及QFont::StyleHint 。

[static] QString QFont::substitute(const QString &familyName)

返回在指定familyName 时将使用的第一个姓氏。该查找操作不区分大小写。

如果familyName 没有替换项，则返回familyName 。

要获取替换项列表，请使用substitutes()。

另请参阅 setFamily()、insertSubstitutions()、insertSubstitution() 和removeSubstitutions()。

[static] QStringList QFont::substitutes(const QString &familyName)

返回一个姓氏列表，该列表将在指定familyName 时使用。查找操作不区分大小写。

如果familyName 没有替换项，则返回一个空列表。

另请参阅 substitute()、insertSubstitutions()、insertSubstitution() 和removeSubstitutions()。

[static] QStringList QFont::substitutions()

返回一个按排序后的替换姓氏列表。

另请参阅 insertSubstitution()、removeSubstitutions() 和substitute()。

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

将此字体实例替换为other 。此操作速度极快，且绝不会失败。

QString QFont::toString() const

返回字体的描述。该描述是以逗号分隔的属性列表，非常适合在QSettings 中使用，包含以下内容：

• 字体家族
• 字号
• 像素大小
• 样式提示
• 字体粗细
• 字体样式
• 下划线
• 删除线
• 等宽字体
• 始终为0
• 大写
• 字母间距
• 单词间距
• 拉伸
• 样式策略
• 字体样式
• 字体特征
• 可变轴

另请参阅 fromString()。

bool QFont::underline() const

如果已设置下划线，则返回true ；否则返回false 。

另请参阅 setUnderline()。

[since 6.7] void QFont::unsetFeature(QFont::Tag tag)

从显式启用/禁用功能映射中移除tag 。

取消设置QFont 上的现有功能将使行为恢复为默认状态。

有关字体功能的更多详细信息，请参阅setFeature()。

此函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、clearFeatures()、setFeature()、featureTags() 以及featureValue()。

[since 6.7] void QFont::unsetVariableAxis(QFont::Tag tag)

撤销由tag 指定的先前设置的变量轴值。

此函数在 Qt 6.7 中引入。

另请参阅 setVariableAxis 。

[since 6.7] QList<QFont::Tag> QFont::variableAxisTags() const

返回当前在此QFont 上设置的所有可变坐标轴的标签列表。

有关可变坐标轴的更多详细信息，请参阅setVariableAxis()。

该函数于 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setVariableAxis()、unsetVariableAxis()、isVariableAxisSet() 以及clearVariableAxes()。

[since 6.7] float QFont::variableAxisValue(QFont::Tag tag) const

返回特定变量轴tag 的设置值。如果该标签尚未设置，则返回0.0。

有关可变坐标轴的更多详细信息，请参阅setVariableAxis()。

该函数在 Qt 6.7 中引入。

另请参阅 QFont::Tag 、setVariableAxis()、unsetVariableAxis()、isVariableAxisSet() 以及clearVariableAxes()。

QFont::Weight QFont::weight() const

返回字体的字重，采用与QFont::Weight 枚举相同的标度。

另请参阅 setWeight()、Weight 以及QFontInfo 。

qreal QFont::wordSpacing() const

返回该字体的词间距。

另请参阅 setWordSpacing() 和setLetterSpacing()。

QFont::operator QVariant() const

将字体作为QVariant

bool QFont::operator!=(const QFont &f) const

如果该字体与f 不相同，则返回true ；否则返回false 。

如果两个 QFont 的字体属性不同，则视为不同。

另请参阅 operator==()。

bool QFont::operator<(const QFont &f) const

提供对该字体与字体f 的任意比较。唯一能保证的是：当两个字体相等时，该运算符返回false ；当两个字体不相等时，(f1 < f2) == !(f2 < f1)。

在某些情况下，此函数非常有用，例如当您希望将QFont 对象用作QMap 中的键时。

另请参阅 operator==()、operator!=() 以及isCopyOf()。

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

将other 通过Move操作赋值给此QFont 实例。

QFont &QFont::operator=(const QFont &font)

将font 分配给此字体，并返回对其的引用。

bool QFont::operator==(const QFont &f) const

如果该字体等同于f ，则返回true ；否则返回 false。

如果两个 QFont 的字体属性相等，则视为相等。

另请参阅 operator!=() 和isCopyOf()。