QTextBlockFormat Class

The QTextBlockFormat class provides formatting information for blocks of text in a QTextDocument. More...

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

List of all members, including inherited members

Note: All functions in this class are reentrant.

Public Types

enum	LineHeightTypes { SingleHeight, ProportionalHeight, FixedHeight, MinimumHeight, LineDistanceHeight }
enum class	MarkerType { NoMarker, Unchecked, Checked }

Public Functions

	QTextBlockFormat()
Qt::Alignment	alignment() const
qreal	bottomMargin() const
int	headingLevel() const
int	indent() const
bool	isValid() const
qreal	leftMargin() const
qreal	lineHeight(qreal scriptLineHeight, qreal scaling = 1.0) const
qreal	lineHeight() const
int	lineHeightType() const
QTextBlockFormat::MarkerType	marker() const
bool	nonBreakableLines() const
QTextFormat::PageBreakFlags	pageBreakPolicy() const
qreal	rightMargin() const
void	setAlignment(Qt::Alignment alignment)
void	setBottomMargin(qreal margin)
void	setHeadingLevel(int level)
void	setIndent(int indentation)
void	setLeftMargin(qreal margin)
void	setLineHeight(qreal height, int heightType)
void	setMarker(QTextBlockFormat::MarkerType marker)
void	setNonBreakableLines(bool b)
void	setPageBreakPolicy(QTextFormat::PageBreakFlags policy)
void	setRightMargin(qreal margin)
void	setTabPositions(const QList<QTextOption::Tab> &tabs)
void	setTextIndent(qreal indent)
void	setTopMargin(qreal margin)
QList<QTextOption::Tab>	tabPositions() const
qreal	textIndent() const
qreal	topMargin() const

Detailed Description

A document is composed of a list of blocks, represented by QTextBlock objects. Each block can contain an item of some kind, such as a paragraph of text, a table, a list, or an image. Every block has an associated QTextBlockFormat that specifies its characteristics.

To cater for left-to-right and right-to-left languages you can set a block's direction with setDirection(). Paragraph alignment is set with setAlignment(). Margins are controlled by setTopMargin(), setBottomMargin(), setLeftMargin(), setRightMargin(). Overall indentation is set with setIndent(), the indentation of the first line with setTextIndent().

Line spacing is set with setLineHeight() and retrieved via lineHeight() and lineHeightType(). The types of line spacing available are in the LineHeightTypes enum.

Line breaking can be enabled and disabled with setNonBreakableLines().

The brush used to paint the paragraph's background is set with setBackground(), and other aspects of the text's appearance can be customized by using the setProperty() function with the OutlinePen, ForegroundBrush, and BackgroundBrush QTextFormat::Property values.

If a text block is part of a list, it can also have a list format that is accessible with the listFormat() function.

See also QTextBlock and QTextCharFormat.

Member Type Documentation

enum QTextBlockFormat::LineHeightTypes

This enum describes the various types of line spacing support paragraphs can have.

Constant	Value	Description
`QTextBlockFormat::SingleHeight`	`0`	This is the default line height: single spacing.
`QTextBlockFormat::ProportionalHeight`	`1`	This sets the spacing proportional to the line (in percentage). For example, set to 200 for double spacing.
`QTextBlockFormat::FixedHeight`	`2`	This sets the line height to a fixed line height (in pixels).
`QTextBlockFormat::MinimumHeight`	`3`	This sets the minimum line height (in pixels).
`QTextBlockFormat::LineDistanceHeight`	`4`	This adds the specified height between lines (in pixels).

See also lineHeight(), lineHeightType(), and setLineHeight().

`[since 5.14]` enum class QTextBlockFormat::MarkerType

This enum describes the types of markers a list item can have. If a list item (a paragraph for which QTextBlock::textList() returns the list) has a marker, it is rendered instead of the normal bullet. In this way, checkable list items can be mixed with plain list items in the same list, overriding the type of bullet specified by the QTextListFormat::style() for the entire list.

Constant	Value	Description
`QTextBlockFormat::MarkerType::NoMarker`	`0`	This is the default: the list item's bullet will be shown.
`QTextBlockFormat::MarkerType::Unchecked`	`1`	Instead of the list item's bullet, an unchecked checkbox will be shown.
`QTextBlockFormat::MarkerType::Checked`	`2`	Instead of the list item's bullet, a checked checkbox will be shown.

In the future, this may be extended to specify other types of paragraph decorations.

This enum was introduced or modified in Qt 5.14.

See also QTextListFormat::style().

Member Function Documentation

QTextBlockFormat::QTextBlockFormat()

Constructs a new QTextBlockFormat.

Qt::Alignment QTextBlockFormat::alignment() const

Returns the paragraph's alignment.

See also setAlignment().

qreal QTextBlockFormat::bottomMargin() const

Returns the paragraph's bottom margin.

See also setBottomMargin() and topMargin().

`[since 5.12]` int QTextBlockFormat::headingLevel() const

Returns the paragraph's heading level if it is a heading, or 0 if not.

This function was introduced in Qt 5.12.

See also setHeadingLevel().

int QTextBlockFormat::indent() const

Returns the paragraph's indent.

See also setIndent().

bool QTextBlockFormat::isValid() const

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

qreal QTextBlockFormat::leftMargin() const

Returns the paragraph's left margin.

See also setLeftMargin(), rightMargin(), and indent().

qreal QTextBlockFormat::lineHeight(qreal scriptLineHeight, qreal scaling = 1.0) const

Returns the height of the lines in the paragraph based on the height of the script line given by scriptLineHeight and the specified scaling factor.

The value that is returned is also dependent on the given LineHeightType of the paragraph as well as the LineHeight setting that has been set for the paragraph.

The scaling is needed for heights that include a fixed number of pixels, to scale them appropriately for printing.

See also LineHeightTypes, setLineHeight(), and lineHeightType().

qreal QTextBlockFormat::lineHeight() const

This returns the LineHeight property for the paragraph.

See also LineHeightTypes, setLineHeight(), and lineHeightType().

int QTextBlockFormat::lineHeightType() const

This returns the LineHeightType property of the paragraph.

See also LineHeightTypes, setLineHeight(), and lineHeight().

`[since 5.14]` QTextBlockFormat::MarkerType QTextBlockFormat::marker() const

Returns the paragraph's marker if one has been set, or NoMarker if not.

This function was introduced in Qt 5.14.

See also setMarker().

bool QTextBlockFormat::nonBreakableLines() const

Returns true if the lines in the paragraph are non-breakable; otherwise returns false.

See also setNonBreakableLines().

QTextFormat::PageBreakFlags QTextBlockFormat::pageBreakPolicy() const

Returns the currently set page break policy for the paragraph. The default is QTextFormat::PageBreak_Auto.

See also setPageBreakPolicy().

qreal QTextBlockFormat::rightMargin() const

Returns the paragraph's right margin.

See also setRightMargin() and leftMargin().

void QTextBlockFormat::setAlignment(Qt::Alignment alignment)

Sets the paragraph's alignment.

See also alignment().

void QTextBlockFormat::setBottomMargin(qreal margin)

Sets the paragraph's bottom margin.

See also bottomMargin(), setTopMargin(), setLeftMargin(), and setRightMargin().

`[since 5.12]` void QTextBlockFormat::setHeadingLevel(int level)

Sets the paragraph's heading level, where 1 is the highest-level heading type (usually with the largest possible heading font size), and increasing values are progressively deeper into the document (and usually with smaller font sizes). For example when reading an HTML H1 tag, the heading level is set to 1. Setting the heading level does not automatically change the font size; however QTextDocumentFragment::fromHtml() sets both the heading level and the font size simultaneously.

If the paragraph is not a heading, the level should be set to 0 (the default).

This function was introduced in Qt 5.12.

See also headingLevel().

void QTextBlockFormat::setIndent(int indentation)

Sets the paragraph's indentation. Margins are set independently of indentation with setLeftMargin() and setTextIndent(). The indentation is an integer that is multiplied with the document-wide standard indent, resulting in the actual indent of the paragraph.

See also indent() and QTextDocument::indentWidth().

void QTextBlockFormat::setLeftMargin(qreal margin)

Sets the paragraph's left margin. Indentation can be applied separately with setIndent().

See also leftMargin(), setRightMargin(), setTopMargin(), and setBottomMargin().

void QTextBlockFormat::setLineHeight(qreal height, int heightType)

Sets the line height for the paragraph to the value given by height which is dependent on heightType in the way described by the LineHeightTypes enum.

See also LineHeightTypes, lineHeight(), and lineHeightType().

`[since 5.14]` void QTextBlockFormat::setMarker(QTextBlockFormat::MarkerType marker)

Sets the type of adornment that should be rendered alongside the paragraph to marker. For example, a list item can be adorned with a checkbox, either checked or unchecked, as a replacement for its bullet. The default is NoMarker.

This function was introduced in Qt 5.14.

See also marker().

void QTextBlockFormat::setNonBreakableLines(bool b)

If b is true, the lines in the paragraph are treated as non-breakable; otherwise they are breakable.

See also nonBreakableLines().

void QTextBlockFormat::setPageBreakPolicy(QTextFormat::PageBreakFlags policy)

Sets the page break policy for the paragraph to policy.

See also pageBreakPolicy().

void QTextBlockFormat::setRightMargin(qreal margin)

Sets the paragraph's right margin.

See also rightMargin(), setLeftMargin(), setTopMargin(), and setBottomMargin().

void QTextBlockFormat::setTabPositions(const QList<QTextOption::Tab> &tabs)

Sets the tab positions for the text block to those specified by tabs.

See also tabPositions().

void QTextBlockFormat::setTextIndent(qreal indent)

Sets the indent for the first line in the block. This allows the first line of a paragraph to be indented differently to the other lines, enhancing the readability of the text.

See also textIndent(), setLeftMargin(), setRightMargin(), setTopMargin(), and setBottomMargin().

void QTextBlockFormat::setTopMargin(qreal margin)

Sets the paragraph's top margin.

See also topMargin(), setBottomMargin(), setLeftMargin(), and setRightMargin().

QList<QTextOption::Tab> QTextBlockFormat::tabPositions() const

Returns a list of tab positions defined for the text block.

See also setTabPositions().

qreal QTextBlockFormat::textIndent() const

Returns the paragraph's text indent.

See also setTextIndent().

qreal QTextBlockFormat::topMargin() const

Returns the paragraph's top margin.

See also setTopMargin() and bottomMargin().

Contents