Class: QgsTextRenderer

class qgis.core.QgsTextRenderer

Bases: sip.wrapper

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

Methods

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

SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR

DrawMode

alias of TextLayoutMode

FONT_WORKAROUND_SCALE = 10.0
HAlignment

alias of TextHorizontalAlignment

SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR = 0.6666666666666666
TextPart

alias of TextComponent

VAlignment

alias of TextVerticalAlignment

convertQtHAlignment(alignment: Qt.Alignment | Qt.AlignmentFlag) Qgis.TextHorizontalAlignment

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

New in version 3.16.

Parameters:

alignment (Union[Qt.Alignment) –

Return type:

Qgis.TextHorizontalAlignment

convertQtVAlignment(alignment: Qt.Alignment | Qt.AlignmentFlag) Qgis.TextVerticalAlignment

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

New in version 3.16.

Parameters:

alignment (Union[Qt.Alignment) –

Return type:

Qgis.TextVerticalAlignment

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())

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) – text rendering flags

New in version 3.30.

drawDocumentOnLine(line: QPolygonF, format: QgsTextFormat, document: QgsTextDocument, context: QgsRenderContext, offsetAlongLine: float = 0, offsetFromLine: float = 0)

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.

New in version 3.32.

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

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[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 Private: API only, will be removed in 4.0

drawPart(origin: Union[QPointF, QPoint], rotation: float, alignment: Qgis.TextHorizontalAlignment, textLines: Iterable[str], context: QgsRenderContext, format: QgsTextFormat, part: Qgis.TextComponent, drawAsOutlines: bool = True) Draws a single component of rendered text using the specified settings.

Parameters:
  • origin – origin for start of text, in painter units. Y coordinate will be used as baseline.

  • rotation – text rotation

  • alignment – horizontal alignment

  • textLines – list of lines of text to draw

  • context – render context

  • format – text format

  • part – 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 – 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 Private: API only, will be removed in 4.0

drawText(rect: QRectF, rotation: float, alignment: Qgis.TextHorizontalAlignment, textLines: Iterable[str], 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)

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[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) – 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()

drawText(point: Union[QPointF, QPoint], rotation: float, alignment: Qgis.TextHorizontalAlignment, textLines: Iterable[str], context: QgsRenderContext, format: QgsTextFormat, drawAsOutlines: bool = True) Draws text at a point origin using the specified settings.

Parameters:
  • point – origin of text, in painter units

  • rotation – text rotation

  • alignment – horizontal alignment

  • textLines – list of lines of text to draw

  • context – render context

  • format – text format

  • drawAsOutlines – 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.

drawTextOnLine(line: QPolygonF, text: str, context: QgsRenderContext, format: QgsTextFormat, offsetAlongLine: float = 0, offsetFromLine: float = 0)

Draws text along a line using the specified settings.

Parameters:
  • line (QPolygonF) – line to render text along, in painter units

  • text (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.

New in version 3.32.

fontMetrics(context: QgsRenderContext, format: QgsTextFormat, scaleFactor: float = 1) QFontMetricsF

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

New in version 3.2.

Parameters:
Return type:

QFontMetricsF

sizeToPixel(size: float, c: QgsRenderContext, unit: Qgis.RenderUnit, mapUnitScale: QgsMapUnitScale = QgsMapUnitScale()) int

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

Parameters:
Return type:

int

Returns:

font pixel size

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

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

Parameters:
  • context (QgsRenderContext) – render context

  • format (QgsTextFormat) – text format

  • textLines (Iterable[str]) – list of lines of text to calculate width from

  • mode (Qgis.TextLayoutMode = Qgis.TextLayoutMode.Point) – draw mode

  • fontMetrics (QFontMetricsF = None) – font metrics

  • flags (Union[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)

textHeight(context: QgsRenderContext, format: QgsTextFormat, character: str, includeEffects: bool = False) -> float Returns the height of a character when rendered with the specified text format.

Parameters:
  • context – render context

  • format – text format

  • character – character to determine height of. If character is invalid, then the maximum character height will be returned.

  • includeEffects – 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.

New in version 3.16.

Return type:

float

textRequiresWrapping(context: QgsRenderContext, text: str, width: float, format: QgsTextFormat) bool

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

See also

wrappedText()

New in version 3.24.

Parameters:
Return type:

bool

textWidth(context: QgsRenderContext, format: QgsTextFormat, textLines: Iterable[str], fontMetrics: QFontMetricsF = None) float

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

Parameters:
  • context (QgsRenderContext) – render context

  • format (QgsTextFormat) – text format

  • textLines (Iterable[str]) – list of lines of text to calculate width from

  • fontMetrics (QFontMetricsF = None) – font metrics

Return type:

float

wrappedText(context: QgsRenderContext, text: str, width: float, format: QgsTextFormat) List[str]

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

New in version 3.24.

Parameters:
Return type:

List[str]