class QTextFormat

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

Inherited by: QTextListFormat, QTextFrameFormat, QTextTableFormat, QTextCharFormat, QTextTableCellFormat, QTextImageFormat, QTextBlockFormat

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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.

class FormatType

(inherits enum.IntEnum) This enum describes the text item a QTextFormat object is formatting.

Constant

Description

QTextFormat.InvalidFormat

An invalid format as created by the default constructor

QTextFormat.BlockFormat

The object formats a text block

QTextFormat.CharFormat

The object formats a single character

QTextFormat.ListFormat

The object formats a list

QTextFormat.FrameFormat

The object formats a frame

QTextFormat.UserFormat

See also

QTextCharFormat QTextBlockFormat QTextListFormat QTextTableFormat type()

class Property

(inherits enum.IntEnum) This enum describes the different properties a format can have.

Constant

Description

QTextFormat.ObjectIndex

The index of the formatted object. See objectIndex() .

Paragraph and character properties

Constant

Description

QTextFormat.CssFloat

How a frame is located relative to the surrounding text

QTextFormat.LayoutDirection

The layout direction of the text in the document (Qt::LayoutDirection).

QTextFormat.OutlinePen

QTextFormat.ForegroundBrush

QTextFormat.BackgroundBrush

QTextFormat.BackgroundImageUrl

Paragraph properties

Constant

Description

QTextFormat.BlockAlignment

QTextFormat.BlockTopMargin

QTextFormat.BlockBottomMargin

QTextFormat.BlockLeftMargin

QTextFormat.BlockRightMargin

QTextFormat.TextIndent

QTextFormat.TabPositions

Specifies the tab positions. The tab positions are structs of Tab which are stored in a QList (internally, in a QList<QVariant>).

QTextFormat.BlockIndent

QTextFormat.LineHeight

QTextFormat.LineHeightType

QTextFormat.BlockNonBreakableLines

QTextFormat.BlockTrailingHorizontalRulerWidth

The width of a horizontal ruler element.

QTextFormat.HeadingLevel

The 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.BlockCodeFence

The 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.BlockQuoteLevel

The 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.BlockCodeLanguage

The 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.BlockMarker

The type of adornment to be shown alongside the block. This enum value has been added in Qt 5.14.

Character properties

Constant

Description

QTextFormat.FontFamily

e{This property has been deprecated.} Use QTextFormat::FontFamilies instead.

QTextFormat.FontFamilies

QTextFormat.FontStyleName

QTextFormat.FontPointSize

QTextFormat.FontPixelSize

QTextFormat.FontSizeAdjustment

Specifies the change in size given to the fontsize already set using FontPointSize or FontPixelSize.

QTextFormat.FontFixedPitch

QTextFormat.FontWeight

QTextFormat.FontItalic

QTextFormat.FontUnderline

This property has been deprecated. Use QTextFormat::TextUnderlineStyle instead.

QTextFormat.FontOverline

QTextFormat.FontStrikeOut

QTextFormat.FontCapitalization

Specifies the capitalization type that is to be applied to the text.

QTextFormat.FontLetterSpacingType

Specifies the meaning of the FontLetterSpacing property. The default is PercentageSpacing .

QTextFormat.FontLetterSpacing

Changes 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.FontWordSpacing

Changes the default spacing between individual words. A positive value increases the word spacing by the corresponding pixels; a negative value decreases the spacing.

QTextFormat.FontStretch

Corresponds to the Stretch property

QTextFormat.FontStyleHint

Corresponds to the StyleHint property

QTextFormat.FontStyleStrategy

Corresponds to the StyleStrategy property

QTextFormat.FontKerning

Specifies whether the font has kerning turned on.

QTextFormat.FontHintingPreference

Controls the use of hinting according to values of the HintingPreference enum.

QTextFormat.TextUnderlineColor

Specifies the color to draw underlines, overlines and strikeouts.

QTextFormat.TextVerticalAlignment

QTextFormat.TextOutline

QTextFormat.TextUnderlineStyle

QTextFormat.TextToolTip

Specifies the (optional) tool tip to be displayed for a fragment of text.

QTextFormat.TextSuperScriptBaseline

Specifies the baseline (in % of height) of superscript texts.

QTextFormat.TextSubScriptBaseline

Specifies the baseline (in % of height) of subscript texts.

QTextFormat.TextBaselineOffset

Specifies the baseline (in % of height) of text. A positive value moves up the text, by the corresponding %; a negative value moves it down.

QTextFormat.IsAnchor

QTextFormat.AnchorHref

QTextFormat.AnchorName

QTextFormat.ObjectType

List properties

Constant

Description

QTextFormat.ListStyle

Specifies the style used for the items in a list, described by values of the Style enum.

QTextFormat.ListIndent

Specifies the amount of indentation used for a list.

QTextFormat.ListNumberPrefix

Defines the text which is prepended to item numbers in numeric lists.

QTextFormat.ListNumberSuffix

Defines the text which is appended to item numbers in numeric lists.

QTextFormat.ListStart

Defines the first value of a list.

Table and frame properties

Constant

Description

QTextFormat.FrameBorder

QTextFormat.FrameBorderBrush

QTextFormat.FrameBorderStyle

See the BorderStyle enum.

QTextFormat.FrameBottomMargin

QTextFormat.FrameHeight

QTextFormat.FrameLeftMargin

QTextFormat.FrameMargin

QTextFormat.FramePadding

QTextFormat.FrameRightMargin

QTextFormat.FrameTopMargin

QTextFormat.FrameWidth

QTextFormat.TableCellSpacing

QTextFormat.TableCellPadding

QTextFormat.TableColumns

QTextFormat.TableColumnWidthConstraints

QTextFormat.TableHeaderRowCount

QTextFormat.TableBorderCollapse

Specifies the borderCollapse property.

Table cell properties

Constant

Description

QTextFormat.TableCellRowSpan

QTextFormat.TableCellColumnSpan

QTextFormat.TableCellLeftPadding

QTextFormat.TableCellRightPadding

QTextFormat.TableCellTopPadding

QTextFormat.TableCellBottomPadding

Table cell properties intended for use with borderCollapse enabled

Constant

Description

QTextFormat.TableCellTopBorder

QTextFormat.TableCellBottomBorder

QTextFormat.TableCellLeftBorder

QTextFormat.TableCellRightBorder

QTextFormat.TableCellTopBorderStyle

QTextFormat.TableCellBottomBorderStyle

QTextFormat.TableCellLeftBorderStyle

QTextFormat.TableCellRightBorderStyle

QTextFormat.TableCellTopBorderBrush

QTextFormat.TableCellBottomBorderBrush

QTextFormat.TableCellLeftBorderBrush

QTextFormat.TableCellRightBorderBrush

Image properties

Constant

Description

QTextFormat.ImageName

The filename or source of the image.

QTextFormat.ImageTitle

The 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.ImageAltText

The 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.ImageWidth

QTextFormat.ImageHeight

QTextFormat.ImageQuality

QTextFormat.ImageMaxWidth

This enum value has been added in Qt 6.8.

Selection properties

Constant

Description

QTextFormat.FullWidthSelection

When set on the characterFormat of a selection, the whole width of the text will be shown selected.

Page break properties

Constant

Description

QTextFormat.PageBreakPolicy

Specifies how pages are broken. See the PageBreakFlag enum.

QTextFormat.UserProperty

See also

property() setProperty()

class ObjectTypes

(inherits enum.IntEnum) This enum describes what kind of QTextObject this format is associated with.

Constant

Description

QTextFormat.NoObject

QTextFormat.ImageObject

QTextFormat.TableObject

QTextFormat.TableCellObject

QTextFormat.UserObject

The first object that can be used for application-specific purposes.

See also

QTextObject QTextTable format()

class PageBreakFlag

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

Constant

Description

QTextFormat.PageBreak_Auto

The page break is determined automatically depending on the available space on the current page

QTextFormat.PageBreak_AlwaysBefore

The page is always broken before the paragraph/table

QTextFormat.PageBreak_AlwaysAfter

A new page is always started after the paragraph/table

See also

pageBreakPolicy() pageBreakPolicy() PageBreakPolicy

__init__()

Creates a new text format with an InvalidFormat.

See also

FormatType

__init__(rhs)
Parameters:

rhs – QTextFormat

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

__init__(type)
Parameters:

type – int

Creates a new text format of the given type.

See also

FormatType

background()
Return type:

QBrush

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

boolProperty(propertyId)
Parameters:

propertyId – int

Return type:

bool

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

brushProperty(propertyId)
Parameters:

propertyId – int

Return type:

QBrush

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

clearBackground()

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

clearForeground()

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

clearProperty(propertyId)
Parameters:

propertyId – int

Clears the value of the property given by propertyId

See also

Property

colorProperty(propertyId)
Parameters:

propertyId – int

Return type:

QColor

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

doubleProperty(propertyId)
Parameters:

propertyId – int

Return type:

float

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.

foreground()
Return type:

QBrush

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

hasProperty(propertyId)
Parameters:

propertyId – int

Return type:

bool

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

intProperty(propertyId)
Parameters:

propertyId – int

Return type:

int

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

isBlockFormat()
Return type:

bool

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

isCharFormat()
Return type:

bool

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

isEmpty()
Return type:

bool

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

isFrameFormat()
Return type:

bool

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

isImageFormat()
Return type:

bool

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

isListFormat()
Return type:

bool

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

isTableCellFormat()
Return type:

bool

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

isTableFormat()
Return type:

bool

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

isValid()
Return type:

bool

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

layoutDirection()
Return type:

LayoutDirection

Returns the document’s layout direction.

lengthProperty(propertyId)
Parameters:

propertyId – int

Return type:

QTextLength

Returns the value of the property given by propertyId.

lengthVectorProperty(propertyId)
Parameters:

propertyId – int

Return type:

.list of QTextLength

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

merge(other)
Parameters:

other – QTextFormat

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

objectIndex()
Return type:

int

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

See also

setObjectIndex()

objectType()
Return type:

int

Returns the text format’s object type.

__ne__(rhs)
Parameters:

rhs – QTextFormat

Return type:

bool

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

__eq__(rhs)
Parameters:

rhs – QTextFormat

Return type:

bool

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

penProperty(propertyId)
Parameters:

propertyId – int

Return type:

QPen

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

properties()
Return type:

Dictionary with keys of type .int and values of type QVariant.

Returns a map with all properties of this text format.

property(propertyId)
Parameters:

propertyId – int

Return type:

object

Returns the property specified by the given propertyId.

propertyCount()
Return type:

int

Returns the number of properties stored in the format.

setBackground(brush)
Parameters:

brush – QBrush

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

setForeground(brush)
Parameters:

brush – QBrush

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

setLayoutDirection(direction)
Parameters:

direction – LayoutDirection

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

setObjectIndex(object)
Parameters:

object – int

Sets the format object’s object index.

See also

objectIndex()

setObjectType(type)
Parameters:

type – int

Sets the text format’s object type to type.

setProperty(propertyId, lengths)
Parameters:

  • propertyId – int

  • lengths – .list of QTextLength

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

setProperty(propertyId, value)
Parameters:

  • propertyId – int

  • value – object

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

See also

Property

stringProperty(propertyId)
Parameters:

propertyId – int

Return type:

str

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

swap(other)
Parameters:

other – QTextFormat

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

toBlockFormat()
Return type:

QTextBlockFormat

Returns this format as a block format.

toCharFormat()
Return type:

QTextCharFormat

Returns this format as a character format.

toFrameFormat()
Return type:

QTextFrameFormat

Returns this format as a frame format.

toImageFormat()
Return type:

QTextImageFormat

Returns this format as an image format.

toListFormat()
Return type:

QTextListFormat

Returns this format as a list format.

toTableCellFormat()
Return type:

QTextTableCellFormat

Returns this format as a table cell format.

toTableFormat()
Return type:

QTextTableFormat

Returns this format as a table format.

type()
Return type:

int

Returns the type of this format.

See also

FormatType