Class: QgsTextDocument

Represents a document consisting of one or more QgsTextBlock objects.

Warning

This API is not considered stable and may change in future QGIS versions.

Added in version 3.14.

Methods

append

Appends a block to the document.

applyCapitalization

Applies a capitalization style to the document's text.

at

Returns the block at the specified index.

hasBackgrounds

Returns True if any blocks or fragments in the document have background brushes set.

insert

Inserts a block into the document, at the specified index.

reserve

Reserves the specified count of blocks for optimised block appending.

size

Returns the number of blocks in the document.

splitLines

Splits lines of text in the document to separate lines, using a specified wrap character (wrapCharacter) or newline characters.

toPlainText

Returns a list of plain text lines of text representing the document.

Static Methods

fromHtml

Constructor for QgsTextDocument consisting of a set of HTML formatted lines.

fromPlainText

Constructor for QgsTextDocument consisting of a set of plain text lines.

fromTextAndFormat

Constructor for QgsTextDocument consisting of a set of lines, respecting settings from a text format.

class qgis.core.QgsTextDocument[source]

Bases: object

__init__()
__init__(block: QgsTextBlock)

Constructor for a QgsTextDocument consisting of a single text block.

Parameters:

block (QgsTextBlock)

__init__(fragment: QgsTextFragment)

Constructor for a QgsTextDocument consisting of a single text fragment.

Parameters:

fragment (QgsTextFragment)

__init__(a0: QgsTextDocument)
Parameters:

a0 (QgsTextDocument)

append(self, block: QgsTextBlock)[source]

Appends a block to the document.

Parameters:

block (QgsTextBlock)

applyCapitalization(self, capitalization: Qgis.Capitalization)[source]

Applies a capitalization style to the document’s text.

Added in version 3.16.

Parameters:

capitalization (Qgis.Capitalization)

at(self, index: int) QgsTextBlock

Returns the block at the specified index.

Raises:

KeyError – if no block exists at the specified index.

Parameters:

index (int)

Return type:

QgsTextBlock

static fromHtml(lines: Iterable[str | None]) QgsTextDocument[source]

Constructor for QgsTextDocument consisting of a set of HTML formatted lines.

If the HTML contains tab characters they will be appended as separate text fragments within the document, consisting of just the tab character.

Parameters:

lines (Iterable[Optional[str]])

Return type:

QgsTextDocument

static fromPlainText(lines: Iterable[str | None]) QgsTextDocument[source]

Constructor for QgsTextDocument consisting of a set of plain text lines.

If any line contains tab characters they will be appended as separate text fragments within the document, consisting of just the tab character.

Parameters:

lines (Iterable[Optional[str]])

Return type:

QgsTextDocument

static fromTextAndFormat(lines: Iterable[str | None], format: QgsTextFormat) QgsTextDocument[source]

Constructor for QgsTextDocument consisting of a set of lines, respecting settings from a text format.

This method will determine from the text format whether the lines should be treated as HTML or plain text.

Added in version 3.40.

Parameters:
Return type:

QgsTextDocument

hasBackgrounds(self) bool[source]

Returns True if any blocks or fragments in the document have background brushes set.

Added in version 3.42.

Return type:

bool

insert(self, index: int, block: QgsTextBlock)[source]

Inserts a block into the document, at the specified index.

Raises:

IndexError – if no block exists at the specified index.

Added in version 3.40.

Parameters:
reserve(self, count: int)[source]

Reserves the specified count of blocks for optimised block appending.

Parameters:

count (int)

size(self) int[source]

Returns the number of blocks in the document.

Return type:

int

splitLines(self, wrapCharacter: str | None, autoWrapLength: int = 0, useMaxLineLengthWhenAutoWrapping: bool = True)[source]

Splits lines of text in the document to separate lines, using a specified wrap character (wrapCharacter) or newline characters.

The autoWrapLength argument can be used to specify an ideal length of line to automatically wrap text to (automatic wrapping is disabled if autoWrapLength is 0). This automatic wrapping is performed after processing wrapping using wrapCharacter. When auto wrapping is enabled, the useMaxLineLengthWhenAutoWrapping argument controls whether the lines should be wrapped to an ideal maximum of autoWrapLength characters, or if False then the lines are wrapped to an ideal minimum length of autoWrapLength characters.

Parameters:
  • wrapCharacter (Optional[str])

  • autoWrapLength (int = 0)

  • useMaxLineLengthWhenAutoWrapping (bool = True)

toPlainText(self) List[str][source]

Returns a list of plain text lines of text representing the document.

Return type:

List[str]