Class: QgsTextDocumentMetrics

class qgis.core.QgsTextDocumentMetrics

Bases: sip.wrapper

Contains pre-calculated metrics of a QgsTextDocument.

Warning

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

New 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.

blockMaximumCharacterWidth

Returns the maximum character width for the specified block.

blockMaximumDescent

Returns the maximum descent encountered in the specified block.

blockWidth

Returns the width of the block at the specified index.

calculateMetrics

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

documentSize

Returns the overall size of the document.

firstLineCapHeight

Returns the cap height for the first line of text.

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.

ascentOffset(self) float

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

Return type

float

baselineOffset(self, blockIndex: int, mode: Qgis.TextLayoutMode) float

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

Parameters
Return type

float

blockHeight(self, blockIndex: int) float

Returns the height of the block at the specified index.

Parameters

blockIndex (int) –

Return type

float

blockMaximumCharacterWidth(self, blockIndex: int) float

Returns the maximum character width for the specified block.

Parameters

blockIndex (int) –

Return type

float

blockMaximumDescent(self, blockIndex: int) float

Returns the maximum descent encountered in the specified block.

Parameters

blockIndex (int) –

Return type

float

blockWidth(self, blockIndex: int) float

Returns the width of the block at the specified index.

Parameters

blockIndex (int) –

Return type

float

calculateMetrics(document: QgsTextDocument, format: QgsTextFormat, context: QgsRenderContext, scaleFactor: float = 1) QgsTextDocumentMetrics

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.FONT_WORKAROUND_SCALE 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.

Parameters
Return type

QgsTextDocumentMetrics

documentSize(self, mode: Qgis.TextLayoutMode, orientation: Qgis.TextOrientation) QSizeF

Returns the overall size of the document.

Parameters
Return type

QSizeF

firstLineCapHeight(self) float

Returns the cap height for the first line of text.

New in version 3.30.

Return type

float

fragmentFont(self, blockIndex: int, fragmentIndex: int) QFont

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

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

New in version 3.30.

Parameters
Return type

float

fragmentVerticalOffset(self, blockIndex: int, fragmentIndex: int, mode: Qgis.TextLayoutMode) float

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

New in version 3.30.

Parameters
Return type

float

isNullFontSize(self) bool

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

New in version 3.30.

Return type

bool

outerBounds(self, mode: Qgis.TextLayoutMode, orientation: Qgis.TextOrientation) QRectF

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.

New in version 3.30.

Parameters
Return type

QRectF

verticalOrientationXOffset(self, blockIndex: int) float

Returns the vertical orientation x offset for the specified block.

Parameters

blockIndex (int) –

Return type

float