Class: QgsTextDocumentMetrics¶

Contains pre-calculated metrics of a QgsTextDocument.

Warning

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

Added in version 3.28.

Methods

`ascentOffset`	Returns the ascent offset of the first block in the document.
`baselineOffset`	Returns the offset from the top of the document to the text baseline for the given block index.
`blockHeight`	Returns the height of the block at the specified index.
`blockLeftMargin`	Returns the margin for the left side of the specified block index.
`blockMaximumAscent`	Returns the maximum ascent encountered in the specified block.
`blockMaximumCharacterWidth`	Returns the maximum character width for the specified block.
`blockMaximumDescent`	Returns the maximum descent encountered in the specified block.
`blockRightMargin`	Returns the margin for the right side of the specified block index.
`blockVerticalMargin`	Returns the vertical margin for the specified block index.
`blockWidth`	Returns the width of the block at the specified index.
`document`	Returns the document associated with the calculated metrics.
`documentSize`	Returns the overall size of the document.
`firstLineCapHeight`	Returns the cap height for the first line of text.
`fragmentAscent`	Returns the ascent of the fragment at the specified block and fragment index.
`fragmentDescent`	Returns the descent of the fragment at the specified block and fragment index.
`fragmentFixedHeight`	Returns the fixed height of the fragment at the specified block and fragment index, or -1 if the fragment does not have a fixed height.
`fragmentFont`	Returns the calculated font for the fragment at the specified block and fragment indices.
`fragmentHorizontalAdvance`	Returns the horizontal advance of the fragment at the specified block and fragment index.
`fragmentVerticalOffset`	Returns the vertical offset from a text block's baseline which should be applied to the fragment at the specified index within that block.
`isNullFontSize`	Returns `True` if the metrics could not be calculated because the text format has a null font size.
`outerBounds`	Returns the outer bounds of the document, which is the `documentSize()` adjusted to account for any text elements which fall outside of the usual document margins (such as super or sub script elements)
`verticalOrientationXOffset`	Returns the vertical orientation x offset for the specified block.

Static Methods

calculateMetrics

Returns precalculated text metrics for a text document, when rendered using the given base format and render context.

class qgis.core.QgsTextDocumentMetrics[source]¶

Bases: object

ascentOffset(self) → float[source]¶

Returns the ascent offset of the first block in the document.

Return type:: float

baselineOffset(self, blockIndex: int, mode: Qgis.TextLayoutMode) → float[source]¶

Returns the offset from the top of the document to the text baseline for the given block index.

Parameters:

blockIndex (int)
mode (Qgis.TextLayoutMode)

Return type:

float

blockHeight(self, blockIndex: int) → float[source]¶

Returns the height of the block at the specified index.

Parameters:: blockIndex (int)
Return type:: float

blockLeftMargin(self, blockIndex: int) → float[source]¶

Returns the margin for the left side of the specified block index.

See also

blockVerticalMargin()

See also

blockRightMargin()

Added in version 3.42.

Parameters:: blockIndex (int)
Return type:: float

blockMaximumAscent(self, blockIndex: int) → float[source]¶

Returns the maximum ascent encountered in the specified block.

See also

blockMaximumDescent()

Added in version 3.42.

Parameters:: blockIndex (int)
Return type:: float

blockMaximumCharacterWidth(self, blockIndex: int) → float[source]¶

Returns the maximum character width for the specified block.

Parameters:: blockIndex (int)
Return type:: float

blockMaximumDescent(self, blockIndex: int) → float[source]¶

Returns the maximum descent encountered in the specified block.

See also

blockMaximumAscent()

Parameters:: blockIndex (int)
Return type:: float

blockRightMargin(self, blockIndex: int) → float[source]¶

Returns the margin for the right side of the specified block index.

See also

blockVerticalMargin()

See also

blockLeftMargin()

Added in version 3.42.

Parameters:: blockIndex (int)
Return type:: float

blockVerticalMargin(self, blockIndex: int) → float[source]¶

Returns the vertical margin for the specified block index.

If blockIndex >= 0 then the returned value will be the margin to place after the block. If blockIndex < 0 then the returned value will be the margin to place before the first block.

See also

blockLeftMargin()

See also

blockRightMargin()

Added in version 3.42.

Parameters:: blockIndex (int)
Return type:: float

blockWidth(self, blockIndex: int) → float[source]¶

Returns the width of the block at the specified index.

Parameters:: blockIndex (int)
Return type:: float

static calculateMetrics(document: QgsTextDocument, format: QgsTextFormat, context: QgsRenderContext, scaleFactor: float = 1, documentContext: QgsTextDocumentRenderContext = QgsTextDocumentRenderContext()) → QgsTextDocumentMetrics[source]¶

Returns precalculated text metrics for a text document, when rendered using the given base format and render context.

The optional scaleFactor parameter can specify a font size scaling factor. It is recommended to set this to QgsTextRenderer.calculateScaleFactorForFormat() and then manually calculations based on the resultant font metrics. Failure to do so will result in poor quality text rendering at small font sizes.

Since QGIS 3.40 the optional documentContext argument can be used to pass text renderer context to change the logistics of the calculated metrics.

Parameters:

document (QgsTextDocument)
format (QgsTextFormat)
context (QgsRenderContext)
scaleFactor (float = 1)
documentContext (QgsTextDocumentRenderContext = QgsTextDocumentRenderContext())

Return type:

QgsTextDocumentMetrics

document(self) → QgsTextDocument¶

Returns the document associated with the calculated metrics.

Note that this may not exactly match the original document which was used in the call to calculateMetrics(), as certain settings (such as text wrapping) require restructuring the document.

Added in version 3.40.

Return type:: QgsTextDocument

documentSize(self, mode: Qgis.TextLayoutMode, orientation: Qgis.TextOrientation) → QSizeF[source]¶

Returns the overall size of the document.

Parameters:

mode (Qgis.TextLayoutMode)
orientation (Qgis.TextOrientation)

Return type:

QSizeF

firstLineCapHeight(self) → float[source]¶

Returns the cap height for the first line of text.

Added in version 3.30.

Return type:: float

fragmentAscent(self, blockIndex: int, fragmentIndex: int, mode: Qgis.TextLayoutMode) → float[source]¶

Returns the ascent of the fragment at the specified block and fragment index.

See also

fragmentDescent()

Added in version 3.42.

Parameters:

blockIndex (int)
fragmentIndex (int)
mode (Qgis.TextLayoutMode)

Return type:

float

fragmentDescent(self, blockIndex: int, fragmentIndex: int, mode: Qgis.TextLayoutMode) → float[source]¶

Returns the descent of the fragment at the specified block and fragment index.

See also

fragmentAscent()

Added in version 3.42.

Parameters:

blockIndex (int)
fragmentIndex (int)
mode (Qgis.TextLayoutMode)

Return type:

float

fragmentFixedHeight(self, blockIndex: int, fragmentIndex: int, mode: Qgis.TextLayoutMode) → float[source]¶

Returns the fixed height of the fragment at the specified block and fragment index, or -1 if the fragment does not have a fixed height.

Added in version 3.40.

Parameters:

blockIndex (int)
fragmentIndex (int)
mode (Qgis.TextLayoutMode)

Return type:

float

fragmentFont(self, blockIndex: int, fragmentIndex: int) → QFont[source]¶

Returns the calculated font for the fragment at the specified block and fragment indices.

Parameters:

blockIndex (int)
fragmentIndex (int)

Return type:

QFont

fragmentHorizontalAdvance(self, blockIndex: int, fragmentIndex: int, mode: Qgis.TextLayoutMode) → float[source]¶

Returns the horizontal advance of the fragment at the specified block and fragment index.

Added in version 3.30.

Parameters:

blockIndex (int)
fragmentIndex (int)
mode (Qgis.TextLayoutMode)

Return type:

float

fragmentVerticalOffset(self, blockIndex: int, fragmentIndex: int, mode: Qgis.TextLayoutMode) → float[source]¶

Returns the vertical offset from a text block’s baseline which should be applied to the fragment at the specified index within that block.

Added in version 3.30.

Parameters:

blockIndex (int)
fragmentIndex (int)
mode (Qgis.TextLayoutMode)

Return type:

float

isNullFontSize(self) → bool[source]¶

Returns True if the metrics could not be calculated because the text format has a null font size.

Added in version 3.30.

Return type:: bool

outerBounds(self, mode: Qgis.TextLayoutMode, orientation: Qgis.TextOrientation) → QRectF[source]¶

Returns the outer bounds of the document, which is the documentSize() adjusted to account for any text elements which fall outside of the usual document margins (such as super or sub script elements)

Warning

Currently this is only supported for the Qgis.TextLayoutMode.Labeling mode.

Added in version 3.30.

Parameters:

mode (Qgis.TextLayoutMode)
orientation (Qgis.TextOrientation)

Return type:

QRectF

verticalOrientationXOffset(self, blockIndex: int) → float[source]¶

Returns the vertical orientation x offset for the specified block.

Parameters:: blockIndex (int)
Return type:: float