QTextFormat Class

The QTextFormat class provides formatting information for a QTextDocument. More...

Header: #include <QTextFormat>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Inherited By:

QTextBlockFormat, QTextCharFormat, QTextFrameFormat, and QTextListFormat

Note: All functions in this class are reentrant.

Public Types

enum FormatType { InvalidFormat, BlockFormat, CharFormat, ListFormat, FrameFormat, UserFormat }
enum ObjectTypes { NoObject, ImageObject, TableObject, TableCellObject, UserObject }
enum PageBreakFlag { PageBreak_Auto, PageBreak_AlwaysBefore, PageBreak_AlwaysAfter }
flags PageBreakFlags
enum Property { ObjectIndex, CssFloat, LayoutDirection, OutlinePen, ForegroundBrush, …, UserProperty }

Public Functions

QTextFormat()
QTextFormat(int type)
QTextFormat(const QTextFormat &other)
~QTextFormat()
QBrush background() const
bool boolProperty(int propertyId) const
QBrush brushProperty(int propertyId) const
void clearBackground()
void clearForeground()
void clearProperty(int propertyId)
QColor colorProperty(int propertyId) const
qreal doubleProperty(int propertyId) const
QBrush foreground() const
bool hasProperty(int propertyId) const
int intProperty(int propertyId) const
bool isBlockFormat() const
bool isCharFormat() const
bool isEmpty() const
bool isFrameFormat() const
bool isImageFormat() const
bool isListFormat() const
bool isTableCellFormat() const
bool isTableFormat() const
bool isValid() const
Qt::LayoutDirection layoutDirection() const
QTextLength lengthProperty(int propertyId) const
QList<QTextLength> lengthVectorProperty(int propertyId) const
void merge(const QTextFormat &other)
int objectIndex() const
int objectType() const
QPen penProperty(int propertyId) const
QMap<int, QVariant> properties() const
QVariant property(int propertyId) const
int propertyCount() const
void setBackground(const QBrush &brush)
void setForeground(const QBrush &brush)
void setLayoutDirection(Qt::LayoutDirection direction)
void setObjectIndex(int index)
void setObjectType(int type)
void setProperty(int propertyId, const QVariant &value)
void setProperty(int propertyId, const QList<QTextLength> &value)
QString stringProperty(int propertyId) const
void swap(QTextFormat &other)
QTextBlockFormat toBlockFormat() const
QTextCharFormat toCharFormat() const
QTextFrameFormat toFrameFormat() const
QTextImageFormat toImageFormat() const
QTextListFormat toListFormat() const
QTextTableCellFormat toTableCellFormat() const
QTextTableFormat toTableFormat() const
int type() const
QVariant operator QVariant() const
bool operator!=(const QTextFormat &other) const
QTextFormat &operator=(const QTextFormat &other)
bool operator==(const QTextFormat &other) const

Detailed Description

A QTextFormat is a generic class used for describing the format of parts of a QTextDocument. The derived classes QTextCharFormat, QTextBlockFormat, QTextListFormat, and QTextTableFormat are usually more useful, and describe the formatting that is applied to specific parts of the document.

A format has a FormatType which specifies the kinds of text item it can format; e.g. a block of text, a list, a table, etc. A format also has various properties (some specific to particular format types), as described by the Property enum. Every property has a corresponding Property.

The format type is given by type(), and the format can be tested with isCharFormat(), isBlockFormat(), isListFormat(), isTableFormat(), isFrameFormat(), and isImageFormat(). If the type is determined, it can be retrieved with toCharFormat(), toBlockFormat(), toListFormat(), toTableFormat(), toFrameFormat(), and toImageFormat().

A format's properties can be set with the setProperty() functions, and retrieved with boolProperty(), intProperty(), doubleProperty(), and stringProperty() as appropriate. All the property IDs used in the format can be retrieved with allPropertyIds(). One format can be merged into another using merge().

A format's object index can be set with setObjectIndex(), and retrieved with objectIndex(). These methods can be used to associate the format with a QTextObject. It is used to represent lists, frames, and tables inside the document.

See also Rich Text Processing.

Member Type Documentation

enum QTextFormat::FormatType

This enum describes the text item a QTextFormat object is formatting.

ConstantValueDescription
QTextFormat::InvalidFormat-1An invalid format as created by the default constructor
QTextFormat::BlockFormat1The object formats a text block
QTextFormat::CharFormat2The object formats a single character
QTextFormat::ListFormat3The object formats a list
QTextFormat::FrameFormat5The object formats a frame
QTextFormat::UserFormat100 

See also QTextCharFormat, QTextBlockFormat, QTextListFormat, QTextTableFormat, and type().

enum QTextFormat::ObjectTypes

This enum describes what kind of QTextObject this format is associated with.

ConstantValueDescription
QTextFormat::NoObject0 
QTextFormat::ImageObject1 
QTextFormat::TableObject2 
QTextFormat::TableCellObject3 
QTextFormat::UserObject0x1000The first object that can be used for application-specific purposes.

See also QTextObject, QTextTable, and QTextObject::format().

enum QTextFormat::PageBreakFlag
flags QTextFormat::PageBreakFlags

This enum describes how page breaking is performed when printing. It maps to the corresponding css properties.

ConstantValueDescription
QTextFormat::PageBreak_Auto0The page break is determined automatically depending on the available space on the current page
QTextFormat::PageBreak_AlwaysBefore0x001The page is always broken before the paragraph/table
QTextFormat::PageBreak_AlwaysAfter0x010A new page is always started after the paragraph/table

The PageBreakFlags type is a typedef for QFlags<PageBreakFlag>. It stores an OR combination of PageBreakFlag values.

See also QTextBlockFormat::pageBreakPolicy(), QTextFrameFormat::pageBreakPolicy(), and PageBreakPolicy.

enum QTextFormat::Property

This enum describes the different properties a format can have.

ConstantValueDescription
QTextFormat::ObjectIndex0x0The index of the formatted object. See objectIndex().

Paragraph and character properties

ConstantValueDescription
QTextFormat::CssFloat0x0800How a frame is located relative to the surrounding text
QTextFormat::LayoutDirection0x0801The layout direction of the text in the document (Qt::LayoutDirection).
QTextFormat::OutlinePen0x810 
QTextFormat::ForegroundBrush0x821 
QTextFormat::BackgroundBrush0x820 
QTextFormat::BackgroundImageUrl0x823 

Paragraph properties

ConstantValueDescription
QTextFormat::BlockAlignment0x1010 
QTextFormat::BlockTopMargin0x1030 
QTextFormat::BlockBottomMargin0x1031 
QTextFormat::BlockLeftMargin0x1032 
QTextFormat::BlockRightMargin0x1033 
QTextFormat::TextIndent0x1034 
QTextFormat::TabPositions0x1035Specifies the tab positions. The tab positions are structs of QTextOption::Tab which are stored in a QList (internally, in a QList<QVariant>).
QTextFormat::BlockIndent0x1040 
QTextFormat::LineHeight0x1048 
QTextFormat::LineHeightType0x1049 
QTextFormat::BlockNonBreakableLines0x1050 
QTextFormat::BlockTrailingHorizontalRulerWidth0x1060The width of a horizontal ruler element.
QTextFormat::HeadingLevel0x1070The level of a heading, for example 1 corresponds to an HTML H1 tag; otherwise 0. This enum value has been added in Qt 5.12.
QTextFormat::BlockCodeFence0x1091The character that was used in the "fences" around a Markdown code block. If the code block was indented rather than fenced, the block should not have this property. This enum value has been added in Qt 5.14.
QTextFormat::BlockQuoteLevel0x1080The depth of nested quoting on this block: 1 means the block is a top-level block quote. Blocks that are not block quotes should not have this property. This enum value has been added in Qt 5.14.
QTextFormat::BlockCodeLanguage0x1090The programming language in a preformatted or code block. Blocks that do not contain code should not have this property. This enum value has been added in Qt 5.14.
QTextFormat::BlockMarker0x10A0The type of adornment to be shown alongside the block. This enum value has been added in Qt 5.14.

Character properties

ConstantValueDescription
QTextFormat::FontFamily0x2000e{This property has been deprecated.} Use QTextFormat::FontFamilies instead.
QTextFormat::FontFamilies0x1FE7 
QTextFormat::FontStyleName0x1FE8 
QTextFormat::FontPointSize0x2001 
QTextFormat::FontPixelSize0x2009 
QTextFormat::FontSizeAdjustment0x2002Specifies the change in size given to the fontsize already set using FontPointSize or FontPixelSize.
QTextFormat::FontFixedPitch0x2008 
QTextFormat::FontWeight0x2003 
QTextFormat::FontItalic0x2004 
QTextFormat::FontUnderline0x2005This property has been deprecated. Use QTextFormat::TextUnderlineStyle instead.
QTextFormat::FontOverline0x2006 
QTextFormat::FontStrikeOut0x2007 
QTextFormat::FontCapitalizationFirstFontPropertySpecifies the capitalization type that is to be applied to the text.
QTextFormat::FontLetterSpacingType0x1FE9Specifies the meaning of the FontLetterSpacing property. The default is QFont::PercentageSpacing.
QTextFormat::FontLetterSpacing0x1FE1Changes the default spacing between individual letters in the font. The value is specified as a percentage or absolute value, depending on FontLetterSpacingType. The default value is 100%.
QTextFormat::FontWordSpacing0x1FE2Changes the default spacing between individual words. A positive value increases the word spacing by the corresponding pixels; a negative value decreases the spacing.
QTextFormat::FontStretch0x1FEACorresponds to the QFont::Stretch property
QTextFormat::FontStyleHint0x1FE3Corresponds to the QFont::StyleHint property
QTextFormat::FontStyleStrategy0x1FE4Corresponds to the QFont::StyleStrategy property
QTextFormat::FontKerning0x1FE5Specifies whether the font has kerning turned on.
QTextFormat::FontHintingPreference0x1FE6Controls the use of hinting according to values of the QFont::HintingPreference enum.
QTextFormat::TextUnderlineColor0x2020Specifies the color to draw underlines, overlines and strikeouts.
QTextFormat::TextVerticalAlignment0x2021 
QTextFormat::TextOutline0x2022 
QTextFormat::TextUnderlineStyle0x2023 
QTextFormat::TextToolTip0x2024Specifies the (optional) tool tip to be displayed for a fragment of text.
QTextFormat::TextSuperScriptBaseline0x2025Specifies the baseline (in % of height) of superscript texts.
QTextFormat::TextSubScriptBaseline0x2026Specifies the baseline (in % of height) of subscript texts.
QTextFormat::TextBaselineOffset0x2027Specifies the baseline (in % of height) of text. A positive value moves up the text, by the corresponding %; a negative value moves it down.
QTextFormat::IsAnchor0x2030 
QTextFormat::AnchorHref0x2031 
QTextFormat::AnchorName0x2032 
QTextFormat::ObjectType0x2f00 

List properties

ConstantValueDescription
QTextFormat::ListStyle0x3000Specifies the style used for the items in a list, described by values of the QTextListFormat::Style enum.
QTextFormat::ListIndent0x3001Specifies the amount of indentation used for a list.
QTextFormat::ListNumberPrefix0x3002Defines the text which is prepended to item numbers in numeric lists.
QTextFormat::ListNumberSuffix0x3003Defines the text which is appended to item numbers in numeric lists.
QTextFormat::ListStart (since Qt 6.6)0x3004Defines the first value of a list.

Table and frame properties

ConstantValueDescription
QTextFormat::FrameBorder0x4000 
QTextFormat::FrameBorderBrush0x4009 
QTextFormat::FrameBorderStyle0x4010See the BorderStyle enum.
QTextFormat::FrameBottomMargin0x4006 
QTextFormat::FrameHeight0x4004 
QTextFormat::FrameLeftMargin0x4007 
QTextFormat::FrameMargin0x4001 
QTextFormat::FramePadding0x4002 
QTextFormat::FrameRightMargin0x4008 
QTextFormat::FrameTopMargin0x4005 
QTextFormat::FrameWidth0x4003 
QTextFormat::TableCellSpacing0x4102 
QTextFormat::TableCellPadding0x4103 
QTextFormat::TableColumns0x4100 
QTextFormat::TableColumnWidthConstraints0x4101 
QTextFormat::TableHeaderRowCount0x4104 
QTextFormat::TableBorderCollapse0x4105Specifies the QTextTableFormat::borderCollapse property.

Table cell properties

ConstantValue
QTextFormat::TableCellRowSpan0x4810
QTextFormat::TableCellColumnSpan0x4811
QTextFormat::TableCellLeftPadding0x4814
QTextFormat::TableCellRightPadding0x4815
QTextFormat::TableCellTopPadding0x4812
QTextFormat::TableCellBottomPadding0x4813

Table cell properties intended for use with QTextTableFormat::borderCollapse enabled

ConstantValue
QTextFormat::TableCellTopBorder0x4816
QTextFormat::TableCellBottomBorder0x4817
QTextFormat::TableCellLeftBorder0x4818
QTextFormat::TableCellRightBorder0x4819
QTextFormat::TableCellTopBorderStyle0x481a
QTextFormat::TableCellBottomBorderStyle0x481b
QTextFormat::TableCellLeftBorderStyle0x481c
QTextFormat::TableCellRightBorderStyle0x481d
QTextFormat::TableCellTopBorderBrush0x481e
QTextFormat::TableCellBottomBorderBrush0x481f
QTextFormat::TableCellLeftBorderBrush0x4820
QTextFormat::TableCellRightBorderBrush0x4821

Image properties

ConstantValueDescription
QTextFormat::ImageName0x5000The filename or source of the image.
QTextFormat::ImageTitle0x5001The title attribute of an HTML image tag, or the quoted string that comes after the URL in a Markdown image link. This enum value has been added in Qt 5.14.
QTextFormat::ImageAltText0x5002The alt attribute of an HTML image tag, or the image description in a Markdown image link. This enum value has been added in Qt 5.14.
QTextFormat::ImageWidth0x5010 
QTextFormat::ImageHeight0x5011 
QTextFormat::ImageQuality0x5014 

Selection properties

ConstantValueDescription
QTextFormat::FullWidthSelection0x06000When set on the characterFormat of a selection, the whole width of the text will be shown selected.

Page break properties

ConstantValueDescription
QTextFormat::PageBreakPolicy0x7000Specifies how pages are broken. See the PageBreakFlag enum.
QTextFormat::UserProperty0x100000 

See also property() and setProperty().

Member Function Documentation

QTextFormat::QTextFormat()

Creates a new text format with an InvalidFormat.

See also FormatType.

[explicit] QTextFormat::QTextFormat(int type)

Creates a new text format of the given type.

See also FormatType.

QTextFormat::QTextFormat(const QTextFormat &other)

Creates a new text format with the same attributes as the other text format.

[noexcept] QTextFormat::~QTextFormat()

Destroys this text format.

QBrush QTextFormat::background() const

Returns the brush used to paint the document's background.

See also setBackground(), clearBackground(), and foreground().

bool QTextFormat::boolProperty(int propertyId) const

Returns the value of the property specified by propertyId. If the property isn't of QTextFormat::Bool type, false is returned instead.

See also setProperty(), intProperty(), doubleProperty(), stringProperty(), colorProperty(), lengthProperty(), lengthVectorProperty(), and Property.

QBrush QTextFormat::brushProperty(int propertyId) const

Returns the value of the property given by propertyId; if the property isn't of QMetaType::QBrush type, Qt::NoBrush is returned instead.

See also setProperty(), boolProperty(), intProperty(), doubleProperty(), stringProperty(), lengthProperty(), lengthVectorProperty(), and Property.

void QTextFormat::clearBackground()

Clears the brush used to paint the document's background. The default brush will be used.

See also background(), setBackground(), and clearForeground().

void QTextFormat::clearForeground()

Clears the brush used to paint the document's foreground. The default brush will be used.

See also foreground(), setForeground(), and clearBackground().

void QTextFormat::clearProperty(int propertyId)

Clears the value of the property given by propertyId

See also Property.

QColor QTextFormat::colorProperty(int propertyId) const

Returns the value of the property given by propertyId; if the property isn't of QMetaType::QColor type, an invalid color is returned instead.

See also setProperty(), boolProperty(), intProperty(), doubleProperty(), stringProperty(), lengthProperty(), lengthVectorProperty(), and Property.

qreal QTextFormat::doubleProperty(int propertyId) const

Returns the value of the property specified by propertyId. If the property isn't of QMetaType::Double or QMetaType::Float type, 0 is returned instead.

See also setProperty(), boolProperty(), intProperty(), stringProperty(), colorProperty(), lengthProperty(), lengthVectorProperty(), and Property.

QBrush QTextFormat::foreground() const

Returns the brush used to render foreground details, such as text, frame outlines, and table borders.

See also setForeground(), clearForeground(), and background().

bool QTextFormat::hasProperty(int propertyId) const

Returns true if the text format has a property with the given propertyId; otherwise returns false.

See also properties() and Property.

int QTextFormat::intProperty(int propertyId) const

Returns the value of the property specified by propertyId. If the property is not of QTextFormat::Integer type, 0 is returned instead.

See also setProperty(), boolProperty(), doubleProperty(), stringProperty(), colorProperty(), lengthProperty(), lengthVectorProperty(), and Property.

bool QTextFormat::isBlockFormat() const

Returns true if this text format is a BlockFormat; otherwise returns false.

bool QTextFormat::isCharFormat() const

Returns true if this text format is a CharFormat; otherwise returns false.

bool QTextFormat::isEmpty() const

Returns true if the format does not store any properties; false otherwise.

See also propertyCount() and properties().

bool QTextFormat::isFrameFormat() const

Returns true if this text format is a FrameFormat; otherwise returns false.

bool QTextFormat::isImageFormat() const

Returns true if this text format is an image format; otherwise returns false.

bool QTextFormat::isListFormat() const

Returns true if this text format is a ListFormat; otherwise returns false.

bool QTextFormat::isTableCellFormat() const

Returns true if this text format is a TableCellFormat; otherwise returns false.

bool QTextFormat::isTableFormat() const

Returns true if this text format is a TableFormat; otherwise returns false.

bool QTextFormat::isValid() const

Returns true if the format is valid (i.e. is not InvalidFormat); otherwise returns false.

Qt::LayoutDirection QTextFormat::layoutDirection() const

Returns the document's layout direction.

See also setLayoutDirection().

QTextLength QTextFormat::lengthProperty(int propertyId) const

Returns the value of the property given by propertyId.

See also setProperty(), boolProperty(), intProperty(), doubleProperty(), stringProperty(), colorProperty(), lengthVectorProperty(), and Property.

QList<QTextLength> QTextFormat::lengthVectorProperty(int propertyId) const

Returns the value of the property given by propertyId. If the property isn't of QTextFormat::LengthVector type, an empty list is returned instead.

See also setProperty(), boolProperty(), intProperty(), doubleProperty(), stringProperty(), colorProperty(), lengthProperty(), and Property.

void QTextFormat::merge(const QTextFormat &other)

Merges the other format with this format; where there are conflicts the other format takes precedence.

int QTextFormat::objectIndex() const

Returns the index of the format object, or -1 if the format object is invalid.

See also setObjectIndex().

int QTextFormat::objectType() const

Returns the text format's object type.

See also ObjectTypes and setObjectType().

QPen QTextFormat::penProperty(int propertyId) const

Returns the value of the property given by propertyId; if the property isn't of QMetaType::QPen type, Qt::NoPen is returned instead.

See also setProperty(), boolProperty(), intProperty(), doubleProperty(), stringProperty(), lengthProperty(), lengthVectorProperty(), and Property.

QMap<int, QVariant> QTextFormat::properties() const

Returns a map with all properties of this text format.

QVariant QTextFormat::property(int propertyId) const

Returns the property specified by the given propertyId.

See also setProperty() and Property.

int QTextFormat::propertyCount() const

Returns the number of properties stored in the format.

void QTextFormat::setBackground(const QBrush &brush)

Sets the brush use to paint the document's background to the brush specified.

See also background(), clearBackground(), and setForeground().

void QTextFormat::setForeground(const QBrush &brush)

Sets the foreground brush to the specified brush. The foreground brush is mostly used to render text.

See also foreground(), clearForeground(), and setBackground().

void QTextFormat::setLayoutDirection(Qt::LayoutDirection direction)

Sets the document's layout direction to the specified direction.

See also layoutDirection().

void QTextFormat::setObjectIndex(int index)

Sets the format object's object index.

See also objectIndex().

void QTextFormat::setObjectType(int type)

Sets the text format's object type to type.

See also ObjectTypes and objectType().

void QTextFormat::setProperty(int propertyId, const QVariant &value)

Sets the property specified by the propertyId to the given value.

See also property() and Property.

void QTextFormat::setProperty(int propertyId, const QList<QTextLength> &value)

Sets the value of the property given by propertyId to value.

See also lengthVectorProperty() and Property.

QString QTextFormat::stringProperty(int propertyId) const

Returns the value of the property given by propertyId; if the property isn't of QMetaType::QString type, an empty string is returned instead.

See also setProperty(), boolProperty(), intProperty(), doubleProperty(), colorProperty(), lengthProperty(), lengthVectorProperty(), and Property.

void QTextFormat::swap(QTextFormat &other)

Swaps this text format with other. This function is very fast and never fails.

QTextBlockFormat QTextFormat::toBlockFormat() const

Returns this format as a block format.

QTextCharFormat QTextFormat::toCharFormat() const

Returns this format as a character format.

QTextFrameFormat QTextFormat::toFrameFormat() const

Returns this format as a frame format.

QTextImageFormat QTextFormat::toImageFormat() const

Returns this format as an image format.

QTextListFormat QTextFormat::toListFormat() const

Returns this format as a list format.

QTextTableCellFormat QTextFormat::toTableCellFormat() const

Returns this format as a table cell format.

QTextTableFormat QTextFormat::toTableFormat() const

Returns this format as a table format.

int QTextFormat::type() const

Returns the type of this format.

See also FormatType.

QVariant QTextFormat::operator QVariant() const

Returns the text format as a QVariant

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

Returns true if this text format is different from the other text format.

QTextFormat &QTextFormat::operator=(const QTextFormat &other)

Assigns the other text format to this text format, and returns a reference to this text format.

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

Returns true if this text format is the same as the other text format.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.