Class: QgsTextRenderer¶

Handles rendering text using rich formatting options, including drop shadows, buffers and background shapes.

Enums

`DrawMode`	alias of `TextLayoutMode`
`HAlignment`	alias of `TextHorizontalAlignment`
`TextPart`	alias of `TextComponent`
`VAlignment`	alias of `TextVerticalAlignment`

Static Methods

`calculateScaleFactorForFormat`	Returns the scale factor used for upscaling font sizes and downscaling destination painter devices.
`convertQtHAlignment`	Converts a Qt horizontal alignment flag to a `Qgis`.TextHorizontalAlignment value.
`convertQtVAlignment`	Converts a Qt vertical alignment flag to a `Qgis`.TextVerticalAlignment value.
`drawDocument`	Draws a text document within a rectangle using the specified settings.
`drawDocumentOnLine`	Draws a text document along a line using the specified settings.
`drawPart`	Draws a single component of rendered text using the specified settings.
`drawText`	Draws text within a rectangle using the specified settings.
`drawTextOnLine`	Draws text along a line using the specified settings.
`fontMetrics`	Returns the font metrics for the given text format, when rendered in the specified render context.
`sizeToPixel`	Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling)
`textHeight`	Returns the height of a text based on a given format.
`textRequiresWrapping`	Returns `True` if the specified text requires line wrapping in order to fit within the specified width (in painter units).
`textWidth`	Returns the width of a text based on a given format.
`wrappedText`	Wraps a text string to multiple lines, such that each individual line will fit within the specified width (in painter units).

Attributes

`FONT_WORKAROUND_SCALE`	Scale factor for upscaling font sizes and downscaling destination painter devices.
`SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR`	Scale factor to use for super or subscript text which doesn't have an explicit font size set.

class qgis.core.QgsTextRenderer[source]¶

Bases: object

DrawMode¶: alias of TextLayoutMode

FONT_WORKAROUND_SCALE: float = 10.0¶

Scale factor for upscaling font sizes and downscaling destination painter devices.

Using this scale factor and manually adjusting any font metric based calculations results in more stable font metrics and sizes for small font sizes.

Warning

Deprecated, use calculateScaleFactorForFormat() instead.

Added in version 3.16.

HAlignment¶: alias of TextHorizontalAlignment

SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR: float = 0.6666666666666666¶: Scale factor to use for super or subscript text which doesn’t have an explicit font size set.

Added in version 3.32.

TextPart¶: alias of TextComponent

VAlignment¶: alias of TextVerticalAlignment

static calculateScaleFactorForFormat(context: QgsRenderContext, format: QgsTextFormat) → float[source]¶

Returns the scale factor used for upscaling font sizes and downscaling destination painter devices.

Using this scale factor and manually adjusting any font metric based calculations results in more stable font metrics and sizes for small font sizes.

Added in version 3.40.

Parameters:

context (QgsRenderContext)
format (QgsTextFormat)

Return type:

float

static convertQtHAlignment(alignment: Qt.Alignment | Qt.AlignmentFlag) → Qgis.TextHorizontalAlignment[source]¶

Converts a Qt horizontal alignment flag to a Qgis.TextHorizontalAlignment value.

See also

convertQtVAlignment()

Added in version 3.16.

Parameters:: alignment (Union[Qt.Alignment, Qt.AlignmentFlag])
Return type:: Qgis.TextHorizontalAlignment

static convertQtVAlignment(alignment: Qt.Alignment | Qt.AlignmentFlag) → Qgis.TextVerticalAlignment[source]¶

Converts a Qt vertical alignment flag to a Qgis.TextVerticalAlignment value.

See also

convertQtHAlignment()

Added in version 3.16.

Parameters:: alignment (Union[Qt.Alignment, Qt.AlignmentFlag])
Return type:: Qgis.TextVerticalAlignment

static drawDocument(rect: QRectF, format: QgsTextFormat, document: QgsTextDocument, metrics: QgsTextDocumentMetrics, context: QgsRenderContext, horizontalAlignment: Qgis.TextHorizontalAlignment = Qgis.TextHorizontalAlignment.Left, verticalAlignment: Qgis.TextVerticalAlignment = Qgis.TextVerticalAlignment.Top, rotation: float = 0, mode: Qgis.TextLayoutMode = Qgis.TextLayoutMode.Rectangle, flags: Qgis.TextRendererFlags | Qgis.TextRendererFlag = Qgis.TextRendererFlags())[source]¶

Draws a text document within a rectangle using the specified settings.

Calling this method is more efficient than calling drawText() if the text document and metrics have already been calculated.

Warning

Unlike drawText(), this method does not automatically update data defined properties in the text format. This is the caller’s responsibility to do, and must be done prior to generating the text document and metrics.

Parameters:

rect (QRectF) – destination rectangle for text, in painter units
format (QgsTextFormat) – base text format
document (QgsTextDocument) – text document to draw
metrics (QgsTextDocumentMetrics) – precalculated text metrics
context (QgsRenderContext) – destination render context
horizontalAlignment (Qgis.TextHorizontalAlignment = Qgis.TextHorizontalAlignment.Left) – horizontal alignment
verticalAlignment (Qgis.TextVerticalAlignment = Qgis.TextVerticalAlignment.Top) – vertical alignment
rotation (float = 0) – text rotation
mode (Qgis.TextLayoutMode = Qgis.TextLayoutMode.Rectangle) – text layout mode. Only Qgis.TextLayoutMode.Rectangle, Qgis.TextLayoutMode.RectangleCapHeightBased and Qgis.TextLayoutMode.RectangleAscentBased are accepted.
flags (Union[Qgis.TextRendererFlags, Qgis.TextRendererFlag] = Qgis.TextRendererFlags()) – text rendering flags

Added in version 3.30.

static drawDocument(point: QPointF | QPoint, format: QgsTextFormat, document: QgsTextDocument, metrics: QgsTextDocumentMetrics, context: QgsRenderContext, alignment: Qgis.TextHorizontalAlignment, rotation: float, mode: Qgis.TextLayoutMode = Qgis.TextLayoutMode.Point)[source]

Draws a text document at a point origin using the specified settings.

Calling this method is more efficient than calling drawText() if the text document and metrics have already been calculated.

Warning

Unlike drawText(), this method does not automatically update data defined properties in the text format. This is the caller’s responsibility to do, and must be done prior to generating the text document and metrics.

Parameters:

point (Union[QPointF, QPoint]) – origin of text, in painter units
format (QgsTextFormat) – base text format
document (QgsTextDocument) – text document to draw
metrics (QgsTextDocumentMetrics) – precalculated text metrics
context (QgsRenderContext) – destination render context
alignment (Qgis.TextHorizontalAlignment) – horizontal alignment
rotation (float) – text rotation
mode (Qgis.TextLayoutMode = Qgis.TextLayoutMode.Point) – optional layout mode (since QGIS 3.42)

Added in version 3.40.

static drawDocumentOnLine(line: QPolygonF, format: QgsTextFormat, document: QgsTextDocument, context: QgsRenderContext, offsetAlongLine: float = 0, offsetFromLine: float = 0)[source]¶

Draws a text document along a line using the specified settings.

Parameters:

line (QPolygonF) – line to render text along, in painter units
format (QgsTextFormat) – text format
document (QgsTextDocument) – text document to draw
context (QgsRenderContext) – render context
offsetAlongLine (float = 0) – offset along the line (in painter units) to start text at
offsetFromLine (float = 0) – offset from the line (in painter units). Negative values will shift the text to the left of the line, positive values will shift the text to the right.

Added in version 3.32.

static drawPart(rect: QRectF, rotation: float, alignment: Qgis.TextHorizontalAlignment, textLines: Iterable[str | None], context: QgsRenderContext, format: QgsTextFormat, part: Qgis.TextComponent, drawAsOutlines: bool = True)[source]¶

Draws a single component of rendered text using the specified settings.

Parameters:

rect (QRectF) – destination rectangle for text, in painter units
rotation (float) – text rotation
alignment (Qgis.TextHorizontalAlignment) – horizontal alignment
textLines (Iterable[Optional[str]]) – list of lines of text to draw
context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
part (Qgis.TextComponent) – component of text to draw. Note that Shadow parts cannot be drawn individually and instead are drawn with their associated part (e.g., drawn together with the text or background parts)
drawAsOutlines (bool = True) – set to False to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext.setTextRenderFormat() instead.

Deprecated since version 3.40: Private API only, will be removed in 4.0.

static drawPart(origin: QPointF | QPoint, rotation: float, alignment: Qgis.TextHorizontalAlignment, textLines: Iterable[str | None], context: QgsRenderContext, format: QgsTextFormat, part: Qgis.TextComponent, drawAsOutlines: bool = True)[source]

Draws a single component of rendered text using the specified settings.

Parameters:

origin (Union[QPointF, QPoint]) – origin for start of text, in painter units. Y coordinate will be used as baseline.
rotation (float) – text rotation
alignment (Qgis.TextHorizontalAlignment) – horizontal alignment
textLines (Iterable[Optional[str]]) – list of lines of text to draw
context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
part (Qgis.TextComponent) – component of text to draw. Note that Shadow parts cannot be drawn individually and instead are drawn with their associated part (e.g., drawn together with the text or background parts)
drawAsOutlines (bool = True) – set to False to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext.setTextRenderFormat() instead.

Deprecated since version 3.40: Private API only, will be removed in 4.0.

static drawText(rect: QRectF, rotation: float, alignment: Qgis.TextHorizontalAlignment, textLines: Iterable[str | None], context: QgsRenderContext, format: QgsTextFormat, drawAsOutlines: bool = True, vAlignment: Qgis.TextVerticalAlignment = Qgis.TextVerticalAlignment.Top, flags: Qgis.TextRendererFlags | Qgis.TextRendererFlag = Qgis.TextRendererFlags(), mode: Qgis.TextLayoutMode = Qgis.TextLayoutMode.Rectangle)[source]¶

Draws text within a rectangle using the specified settings.

Parameters:

rect (QRectF) – destination rectangle for text, in painter units
rotation (float) – text rotation
alignment (Qgis.TextHorizontalAlignment) – horizontal alignment
textLines (Iterable[Optional[str]]) – list of lines of text to draw
context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
drawAsOutlines (bool = True) – set to False to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext.setTextRenderFormat() instead.
vAlignment (Qgis.TextVerticalAlignment = Qgis.TextVerticalAlignment.Top) – vertical alignment (since QGIS 3.16)
flags (Union[Qgis.TextRendererFlags, Qgis.TextRendererFlag] = Qgis.TextRendererFlags()) – text rendering flags (since QGIS 3.24)
mode (Qgis.TextLayoutMode = Qgis.TextLayoutMode.Rectangle) – text layout mode. Only Qgis.TextLayoutMode.Rectangle, Qgis.TextLayoutMode.RectangleCapHeightBased and Qgis.TextLayoutMode.RectangleAscentBased are accepted (since QGIS 3.30)

See also

drawDocument() which is more efficient if the text document and metrics have already been calculated.

static drawText(point: QPointF | QPoint, rotation: float, alignment: Qgis.TextHorizontalAlignment, textLines: Iterable[str | None], context: QgsRenderContext, format: QgsTextFormat, drawAsOutlines: bool = True)[source]

Draws text at a point origin using the specified settings.

Parameters:

point (Union[QPointF, QPoint]) – origin of text, in painter units
rotation (float) – text rotation
alignment (Qgis.TextHorizontalAlignment) – horizontal alignment
textLines (Iterable[Optional[str]]) – list of lines of text to draw
context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
drawAsOutlines (bool = True) – set to False to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext.setTextRenderFormat() instead.

static drawTextOnLine(line: QPolygonF, text: str | None, context: QgsRenderContext, format: QgsTextFormat, offsetAlongLine: float = 0, offsetFromLine: float = 0)[source]¶

Draws text along a line using the specified settings.

Parameters:

line (QPolygonF) – line to render text along, in painter units
text (Optional[str]) – text to draw
context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
offsetAlongLine (float = 0) – offset along the line (in painter units) to start text at
offsetFromLine (float = 0) – offset from the line (in painter units). Negative values will shift the text to the left of the line, positive values will shift the text to the right.

Added in version 3.32.

static fontMetrics(context: QgsRenderContext, format: QgsTextFormat, scaleFactor: float = 1) → QFontMetricsF[source]¶

Returns the font metrics for the given text format, when rendered in the specified render context. The font metrics will take into account all scaling required by the render context.

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

Added in version 3.2.

Parameters:

context (QgsRenderContext)
format (QgsTextFormat)
scaleFactor (float = 1)

Return type:

QFontMetricsF

static sizeToPixel(size: float, c: QgsRenderContext, unit: Qgis.RenderUnit, mapUnitScale: QgsMapUnitScale = QgsMapUnitScale()) → int[source]¶

Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling)

Parameters:

size (float) – size to convert
c (QgsRenderContext) – rendercontext
unit (Qgis.RenderUnit) – size units
mapUnitScale (QgsMapUnitScale = QgsMapUnitScale()) – a mapUnitScale clamper

Return type:

int

Returns:

font pixel size

static textHeight(context: QgsRenderContext, format: QgsTextFormat, textLines: Iterable[str | None], mode: Qgis.TextLayoutMode = Qgis.TextLayoutMode.Point, fontMetrics: QFontMetricsF | None = None, flags: Qgis.TextRendererFlags | Qgis.TextRendererFlag = Qgis.TextRendererFlags(), maxLineWidth: float = 0) → float[source]¶

Returns the height of a text based on a given format.

Parameters:

context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
textLines (Iterable[Optional[str]]) – list of lines of text to calculate width from
mode (Qgis.TextLayoutMode = Qgis.TextLayoutMode.Point) – draw mode
fontMetrics (Optional[QFontMetricsF] = None) – font metrics
flags (Union[Qgis.TextRendererFlags, Qgis.TextRendererFlag] = Qgis.TextRendererFlags()) – text renderer flags (since QGIS 3.24)
maxLineWidth (float = 0) – maximum line width, in painter units. Used when the Qgis.TextRendererFlag.WrapLines flag is used (since QGIS 3.24)

Return type:

float

static textHeight(context: QgsRenderContext, format: QgsTextFormat, character: str, includeEffects: bool = False) → float[source]

Returns the height of a character when rendered with the specified text format.

Parameters:

context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
character (str) – character to determine height of. If character is invalid, then the maximum character height will be returned.
includeEffects (bool = False) – if True, then the size of formatting effects such as buffers and shadows will be considered in the returned height. If False, then the returned size considers the character only.

Added in version 3.16.

Return type:: float

static textRequiresWrapping(context: QgsRenderContext, text: str | None, width: float, format: QgsTextFormat) → bool[source]¶

Returns True if the specified text requires line wrapping in order to fit within the specified width (in painter units).

See also

wrappedText()

Added in version 3.24.

Parameters:

context (QgsRenderContext)
text (Optional[str])
width (float)
format (QgsTextFormat)

Return type:

bool

static textWidth(context: QgsRenderContext, format: QgsTextFormat, textLines: Iterable[str | None], fontMetrics: QFontMetricsF | None = None) → float[source]¶

Returns the width of a text based on a given format.

Parameters:

context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
textLines (Iterable[Optional[str]]) – list of lines of text to calculate width from
fontMetrics (Optional[QFontMetricsF] = None) – font metrics

Return type:

float

static wrappedText(context: QgsRenderContext, text: str | None, width: float, format: QgsTextFormat) → List[str][source]¶

Wraps a text string to multiple lines, such that each individual line will fit within the specified width (in painter units).

See also

textRequiresWrapping()

Added in version 3.24.

Parameters:

context (QgsRenderContext)
text (Optional[str])
width (float)
format (QgsTextFormat)

Return type:

List[str]