- Qt 6.9
- Qt GUI
- C++ Classes
- QTextCharFormat
- Qt 6.9.3 Reference Documentation

# QTextCharFormat Class

The QTextCharFormat class provides formatting information for characters in a QTextDocument. More...

Header: | `#include <QTextCharFormat>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Gui)` `target_link_libraries(mytarget PRIVATE Qt6::Gui)`
qmake: | `QT += gui`
Inherits: | QTextFormat
Inherited By: | QTextImageFormat and QTextTableCellFormat

- List of all members, including inherited members
- Deprecated members
- QTextCharFormat is part of Rich Text Processing APIs and Implicitly Shared Classes.

Note: All functions in this class are reentrant.

## Public Types

enum | FontPropertiesInheritanceBehavior { FontPropertiesSpecifiedOnly, FontPropertiesAll }
enum | UnderlineStyle { NoUnderline, SingleUnderline, DashUnderline, DotLine, DashDotLine, …, SpellCheckUnderline }
enum | VerticalAlignment { AlignNormal, AlignSuperScript, AlignSubScript, AlignMiddle, AlignBottom, …, AlignBaseline }

## Public Functions

| QTextCharFormat()
QString | anchorHref() const
QStringList | anchorNames() const
`(since 6.0)` qreal | baselineOffset() const
QFont | font() const
QFont::Capitalization | fontCapitalization() const
QVariant | fontFamilies() const
bool | fontFixedPitch() const
QFont::HintingPreference | fontHintingPreference() const
bool | fontItalic() const
bool | fontKerning() const
qreal | fontLetterSpacing() const
QFont::SpacingType | fontLetterSpacingType() const
bool | fontOverline() const
qreal | fontPointSize() const
int | fontStretch() const
bool | fontStrikeOut() const
QFont::StyleHint | fontStyleHint() const
QVariant | fontStyleName() const
QFont::StyleStrategy | fontStyleStrategy() const
bool | fontUnderline() const
int | fontWeight() const
qreal | fontWordSpacing() const
bool | isAnchor() const
bool | isValid() const
void | setAnchor(bool anchor)
void | setAnchorHref(const QString &value)
void | setAnchorNames(const QStringList &names)
`(since 6.0)` void | setBaselineOffset(qreal baseline)
void | setFont(const QFont &font, QTextCharFormat::FontPropertiesInheritanceBehavior behavior = FontPropertiesAll)
void | setFontCapitalization(QFont::Capitalization capitalization)
void | setFontFamilies(const QStringList &families)
void | setFontFixedPitch(bool fixedPitch)
void | setFontHintingPreference(QFont::HintingPreference hintingPreference)
void | setFontItalic(bool italic)
void | setFontKerning(bool enable)
void | setFontLetterSpacing(qreal spacing)
void | setFontLetterSpacingType(QFont::SpacingType letterSpacingType)
void | setFontOverline(bool overline)
void | setFontPointSize(qreal size)
void | setFontStretch(int factor)
void | setFontStrikeOut(bool strikeOut)
void | setFontStyleHint(QFont::StyleHint hint, QFont::StyleStrategy strategy = QFont::PreferDefault)
void | setFontStyleName(const QString &styleName)
void | setFontStyleStrategy(QFont::StyleStrategy strategy)
void | setFontUnderline(bool underline)
void | setFontWeight(int weight)
void | setFontWordSpacing(qreal spacing)
`(since 6.0)` void | setSubScriptBaseline(qreal baseline)
`(since 6.0)` void | setSuperScriptBaseline(qreal baseline)
void | setTextOutline(const QPen &pen)
void | setToolTip(const QString &text)
void | setUnderlineColor(const QColor &color)
void | setUnderlineStyle(QTextCharFormat::UnderlineStyle style)
void | setVerticalAlignment(QTextCharFormat::VerticalAlignment alignment)
`(since 6.0)` qreal | subScriptBaseline() const
`(since 6.0)` qreal | superScriptBaseline() const
QPen | textOutline() const
QString | toolTip() const
QColor | underlineColor() const
QTextCharFormat::UnderlineStyle | underlineStyle() const
QTextCharFormat::VerticalAlignment | verticalAlignment() const

## Detailed Description

The character format of text in a document specifies the visual properties of the text, as well as information about its role in a hypertext document.

The font used can be set by supplying a font to the setFont() function, and each aspect of its appearance can be adjusted to give the desired effect. setFontFamilies() and setFontPointSize() define the font's family (e.g. Times) and printed size; setFontWeight() and setFontItalic() provide control over the style of the font. setFontUnderline(), setFontOverline(), setFontStrikeOut(), and setFontFixedPitch() provide additional effects for text.

The color is set with setForeground(). If the text is intended to be used as an anchor (for hyperlinks), this can be enabled with setAnchor(). The setAnchorHref() and setAnchorNames() functions are used to specify the information about the hyperlink's destination and the anchor's name.

See also QTextFormat, QTextBlockFormat, QTextTableFormat, and QTextListFormat.

## Member Type Documentation

### enum QTextCharFormat::FontPropertiesInheritanceBehavior

This enum specifies how the setFont() function should behave with respect to unset font properties.

Constant | Value | Description
--- | --- | ---
`QTextCharFormat::FontPropertiesSpecifiedOnly` | `0` | If a property is not explicitly set, do not change the text format's property value.
`QTextCharFormat::FontPropertiesAll` | `1` | If a property is not explicitly set, override the text format's property with a default value.

See also setFont().

### enum QTextCharFormat::UnderlineStyle

This enum describes the different ways drawing underlined text.

Constant | Value | Description
--- | --- | ---
`QTextCharFormat::NoUnderline` | `0` | Text is draw without any underlining decoration.
`QTextCharFormat::SingleUnderline` | `1` | A line is drawn using Qt::SolidLine.
`QTextCharFormat::DashUnderline` | `2` | Dashes are drawn using Qt::DashLine.
`QTextCharFormat::DotLine` | `3` | Dots are drawn using Qt::DotLine;
`QTextCharFormat::DashDotLine` | `4` | Dashes and dots are drawn using Qt::DashDotLine.
`QTextCharFormat::DashDotDotLine` | `5` | Underlines draw drawn using Qt::DashDotDotLine.
`QTextCharFormat::WaveUnderline` | `6` | The text is underlined using a wave shaped line.
`QTextCharFormat::SpellCheckUnderline` | `7` | The underline is drawn depending on the SpellCheckUnderlineStyle theme hint of QPlatformTheme. By default this is mapped to WaveUnderline, on macOS it is mapped to DotLine.

See also Qt::PenStyle.

### enum QTextCharFormat::VerticalAlignment

This enum describes the ways that adjacent characters can be vertically aligned.

Constant | Value | Description
--- | --- | ---
`QTextCharFormat::AlignNormal` | `0` | Adjacent characters are positioned in the standard way for text in the writing system in use.
`QTextCharFormat::AlignSuperScript` | `1` | Characters are placed above the base line for normal text.
`QTextCharFormat::AlignSubScript` | `2` | Characters are placed below the base line for normal text.
`QTextCharFormat::AlignMiddle` | `3` | The center of the object is vertically aligned with the base line. Currently, this is only implemented for inline objects.
`QTextCharFormat::AlignBottom` | `5` | The bottom edge of the object is vertically aligned with the base line.
`QTextCharFormat::AlignTop` | `4` | The top edge of the object is vertically aligned with the base line.
`QTextCharFormat::AlignBaseline` | `6` | The base lines of the characters are aligned.

## Member Function Documentation

### QTextCharFormat::QTextCharFormat()

Constructs a new character format object.

### QString QTextCharFormat::anchorHref() const

Returns the text format's hypertext link, or an empty string if none has been set.

See also setAnchorHref().

### QStringList QTextCharFormat::anchorNames() const

Returns the anchor names associated with this text format, or an empty string list if none has been set. If the anchor names are set, text with this format can be the destination of a hypertext link.

See also setAnchorNames().

### `[since 6.0]` qreal QTextCharFormat::baselineOffset() const

Returns the the baseline offset in %.

This function was introduced in Qt 6.0.

See also setBaselineOffset(), setSubScriptBaseline(), subScriptBaseline(), setSuperScriptBaseline(), and superScriptBaseline().

### QFont QTextCharFormat::font() const

Returns the font for this character format.

This function takes into account the format's font attributes (such as fontWeight() and fontPointSize()) and resolves them on top of the default font, defined as follows. If the format is part of a document, that is the document's default font. Otherwise the properties are resolved on top of a default constructed QFont.

For example, if this format's font size hasn't been changed from the default font, fontPointSize() returns 0, while `font().pointSize()` returns the actual size used for drawing.

See also setFont() and QTextDocument::defaultFont().

### QFont::Capitalization QTextCharFormat::fontCapitalization() const

Returns the current capitalization type of the font.

See also setFontCapitalization().

### QVariant QTextCharFormat::fontFamilies() const

Returns the text format's font families.

Note: This function returns a QVariant for historical reasons. It will be corrected to return QStringList in Qt 7. The variant contains a QStringList object, which can be extracted by calling `toStringList()` on it.

See also setFontFamilies() and font().

### bool QTextCharFormat::fontFixedPitch() const

Returns `true` if the text format's font is fixed pitch; otherwise returns `false`.

See also setFontFixedPitch() and font().

### QFont::HintingPreference QTextCharFormat::fontHintingPreference() const

Returns the hinting preference set for this text format.

See also setFontHintingPreference(), font(), and QFont::hintingPreference().

### bool QTextCharFormat::fontItalic() const

Returns `true` if the text format's font is italic; otherwise returns `false`.

See also setFontItalic() and font().

### bool QTextCharFormat::fontKerning() const

Returns `true` if the font kerning is enabled.

See also setFontKerning() and font().

### qreal QTextCharFormat::fontLetterSpacing() const

Returns the current letter spacing.

See also setFontLetterSpacing(), setFontLetterSpacingType(), and fontLetterSpacingType().

### QFont::SpacingType QTextCharFormat::fontLetterSpacingType() const

Returns the letter spacing type of this format..

See also setFontLetterSpacingType(), setFontLetterSpacing(), and fontLetterSpacing().

### bool QTextCharFormat::fontOverline() const

Returns `true` if the text format's font is overlined; otherwise returns `false`.

See also setFontOverline() and font().

### qreal QTextCharFormat::fontPointSize() const

Returns the font size used to display text in this format.

See also setFontPointSize() and font().

### int QTextCharFormat::fontStretch() const

Returns the current font stretching.

See also setFontStretch().

### bool QTextCharFormat::fontStrikeOut() const

Returns `true` if the text format's font is struck out (has a horizontal line drawn through it); otherwise returns `false`.

See also setFontStrikeOut() and font().

### QFont::StyleHint QTextCharFormat::fontStyleHint() const

Returns the font style hint.

See also setFontStyleHint() and font().

### QVariant QTextCharFormat::fontStyleName() const

Returns the text format's font style name.

Note: This function returns a QVariant for historical reasons. It will be corrected to return QStringList in Qt 7. The variant contains a QStringList object, which can be extracted by calling `toStringList()` on it.

See also setFontStyleName(), font(), and QFont::styleName().

### QFont::StyleStrategy QTextCharFormat::fontStyleStrategy() const

Returns the current font style strategy.

See also setFontStyleStrategy() and font().

### bool QTextCharFormat::fontUnderline() const

Returns `true` if the text format's font is underlined; otherwise returns `false`.

See also setFontUnderline() and font().

### int QTextCharFormat::fontWeight() const

Returns the text format's font weight.

See also setFontWeight(), font(), and QFont::Weight.

### qreal QTextCharFormat::fontWordSpacing() const

Returns the current word spacing value.

See also setFontWordSpacing().

### bool QTextCharFormat::isAnchor() const

Returns `true` if the text is formatted as an anchor; otherwise returns `false`.

See also setAnchor(), setAnchorHref(), and setAnchorNames().

### bool QTextCharFormat::isValid() const

Returns `true` if this character format is valid; otherwise returns false.

### void QTextCharFormat::setAnchor(bool anchor)

If anchor is true, text with this format represents an anchor, and is formatted in the appropriate way; otherwise the text is formatted normally. (Anchors are hyperlinks which are often shown underlined and in a different color from plain text.)

The way the text is rendered is independent of whether or not the format has a valid anchor defined. Use setAnchorHref(), and optionally setAnchorNames() to create a hypertext link.

See also isAnchor().

### void QTextCharFormat::setAnchorHref(const QString &value)

Sets the hypertext link for the text format to the given value. This is typically a URL like "http://example.com/index.html".

The anchor will be displayed with the value as its display text; if you want to display different text call setAnchorNames().

To format the text as a hypertext link use setAnchor().

See also anchorHref().

### void QTextCharFormat::setAnchorNames(const QStringList &names)

Sets the text format's anchor names. For the anchor to work as a hyperlink, the destination must be set with setAnchorHref() and the anchor must be enabled with setAnchor().

See also anchorNames().

### `[since 6.0]` void QTextCharFormat::setBaselineOffset(qreal baseline)

Sets the base line (in % of height) of text to baseline. A positive value moves the text up, by the corresponding %; a negative value moves it down. The default value is 0.

This function was introduced in Qt 6.0.

See also baselineOffset(), setSubScriptBaseline(), subScriptBaseline(), setSuperScriptBaseline(), and superScriptBaseline().

### void QTextCharFormat::setFont(const QFont &font, QTextCharFormat::FontPropertiesInheritanceBehavior behavior = FontPropertiesAll)

Sets the text format's font.

If behavior is QTextCharFormat::FontPropertiesAll, the font property that has not been explicitly set is treated like as it were set with default value; If behavior is QTextCharFormat::FontPropertiesSpecifiedOnly, the font property that has not been explicitly set is ignored and the respective property value remains unchanged.

See also font().

### void QTextCharFormat::setFontCapitalization(QFont::Capitalization capitalization)

Sets the capitalization of the text that appears in this font to capitalization.

A font's capitalization makes the text appear in the selected capitalization mode.

See also fontCapitalization().

### void QTextCharFormat::setFontFamilies(const QStringList &families)

Sets the text format's font families.

See also fontFamilies() and setFont().

### void QTextCharFormat::setFontFixedPitch(bool fixedPitch)

If fixedPitch is true, sets the text format's font to be fixed pitch; otherwise a non-fixed pitch font is used.

See also fontFixedPitch() and setFont().

### void QTextCharFormat::setFontHintingPreference(QFont::HintingPreference hintingPreference)

Sets the hinting preference of the text format's font to be hintingPreference.

See also fontHintingPreference(), setFont(), and QFont::setHintingPreference().

### void QTextCharFormat::setFontItalic(bool italic)

If italic is true, sets the text format's font to be italic; otherwise the font will be non-italic.

See also fontItalic() and setFont().

### void QTextCharFormat::setFontKerning(bool enable)

Enables kerning for this font if enable is true; otherwise disables it.

When kerning is enabled, glyph metrics do not add up anymore, even for Latin text. In other words, the assumption that width('a') + width('b') is equal to width("ab") is not neccesairly true.

See also fontKerning() and setFont().

### void QTextCharFormat::setFontLetterSpacing(qreal spacing)

Sets the letter spacing of this format to the given spacing. The meaning of the value depends on the font letter spacing type.

For percentage spacing a value of 100 indicates default spacing; a value of 200 doubles the amount of space a letter takes.

See also fontLetterSpacing(), setFontLetterSpacingType(), and fontLetterSpacingType().

### void QTextCharFormat::setFontLetterSpacingType(QFont::SpacingType letterSpacingType)

Sets the letter spacing type of this format to letterSpacingType.

See also fontLetterSpacingType(), setFontLetterSpacing(), and fontLetterSpacing().

### void QTextCharFormat::setFontOverline(bool overline)

If overline is true, sets the text format's font to be overlined; otherwise the font is displayed non-overlined.

See also fontOverline() and setFont().

### void QTextCharFormat::setFontPointSize(qreal size)

Sets the text format's font size.

See also fontPointSize() and setFont().

### void QTextCharFormat::setFontStretch(int factor)

Sets the stretch factor for the font to factor.

The stretch factor changes the width of all characters in the font by factor percent. For example, setting factor to 150 results in all characters in the font being 1.5 times (ie. 150%) wider. The default stretch factor is 100. The minimum stretch factor is 1, and the maximum stretch factor is 4000.

The stretch factor is only applied to outline fonts. The stretch factor is ignored for bitmap fonts.

See also fontStretch().

### void QTextCharFormat::setFontStrikeOut(bool strikeOut)

If strikeOut is true, sets the text format's font with strike-out enabled (with a horizontal line through it); otherwise it is displayed without strikeout.

See also fontStrikeOut() and setFont().

### void QTextCharFormat::setFontStyleHint(QFont::StyleHint hint, QFont::StyleStrategy strategy = QFont::PreferDefault)

Sets the font style hint and strategy.

Qt does not support style hints on X11 since this information is not provided by the window system.

See also fontStyleHint(), setFont(), and QFont::setStyleHint().

### void QTextCharFormat::setFontStyleName(const QString &styleName)

Sets the text format's font styleName.

See also fontStyleName(), setFont(), and QFont::setStyleName().

### void QTextCharFormat::setFontStyleStrategy(QFont::StyleStrategy strategy)

Sets the font style strategy.

See also fontStyleStrategy(), setFont(), and QFont::setStyleStrategy().

### void QTextCharFormat::setFontUnderline(bool underline)

If underline is true, sets the text format's font to be underlined; otherwise it is displayed non-underlined.

See also fontUnderline() and setFont().

### void QTextCharFormat::setFontWeight(int weight)

Sets the text format's font weight to weight.

See also fontWeight(), setFont(), and QFont::Weight.

### void QTextCharFormat::setFontWordSpacing(qreal spacing)

Sets the word spacing of this format to the given spacing, in pixels.

See also fontWordSpacing().

### `[since 6.0]` void QTextCharFormat::setSubScriptBaseline(qreal baseline)

Sets the subscript's base line as a % of font height to baseline. The default value is 16.67% (1/6 of height)

This function was introduced in Qt 6.0.

See also subScriptBaseline(), setSuperScriptBaseline(), superScriptBaseline(), setBaselineOffset(), and baselineOffset().

### `[since 6.0]` void QTextCharFormat::setSuperScriptBaseline(qreal baseline)

Sets the superscript's base line as a % of font height to baseline. The default value is 50% (1/2 of height).

This function was introduced in Qt 6.0.

See also superScriptBaseline(), setSubScriptBaseline(), subScriptBaseline(), setBaselineOffset(), and baselineOffset().

### void QTextCharFormat::setTextOutline(const QPen &pen)

Sets the pen used to draw the outlines of characters to the given pen.

See also textOutline().

### void QTextCharFormat::setToolTip(const QString &text)

Sets the tool tip for a fragment of text to the given text.

See also toolTip().

### void QTextCharFormat::setUnderlineColor(const QColor &color)

Sets the color used to draw underlines, overlines and strikeouts on the characters with this format to the color specified.

See also underlineColor().

### void QTextCharFormat::setUnderlineStyle(QTextCharFormat::UnderlineStyle style)

Sets the style of underlining the text to style.

See also underlineStyle().

### void QTextCharFormat::setVerticalAlignment(QTextCharFormat::VerticalAlignment alignment)

Sets the vertical alignment used for the characters with this format to the alignment specified.

See also verticalAlignment().

### `[since 6.0]` qreal QTextCharFormat::subScriptBaseline() const

Returns the subscript's base line as a % of font height.

This function was introduced in Qt 6.0.

See also setSubScriptBaseline(), setSuperScriptBaseline(), superScriptBaseline(), setBaselineOffset(), and baselineOffset().

### `[since 6.0]` qreal QTextCharFormat::superScriptBaseline() const

Returns the superscript's base line as a % of font height.

This function was introduced in Qt 6.0.

See also setSuperScriptBaseline(), setSubScriptBaseline(), subScriptBaseline(), setBaselineOffset(), and baselineOffset().

### QPen QTextCharFormat::textOutline() const

Returns the pen used to draw the outlines of characters in this format.

See also setTextOutline().

### QString QTextCharFormat::toolTip() const

Returns the tool tip that is displayed for a fragment of text.

See also setToolTip().

### QColor QTextCharFormat::underlineColor() const

Returns the color used to draw underlines, overlines and strikeouts on the characters with this format.

See also setUnderlineColor().

### QTextCharFormat::UnderlineStyle QTextCharFormat::underlineStyle() const

Returns the style of underlining the text.

See also setUnderlineStyle().

### QTextCharFormat::VerticalAlignment QTextCharFormat::verticalAlignment() const

Returns the vertical alignment used for characters with this format.

See also setVerticalAlignment().