Class: QgsTextRenderer¶
- class qgis.core.QgsTextRenderer¶
Bases:
sip.wrapper
Handles rendering text using rich formatting options, including drop shadows, buffers and background shapes.
New in version 3.0:
Methods
Converts a Qt horizontal
alignment
flag to a QgsTextRenderer.HAlignment value.Converts a Qt vertical
alignment
flag to a QgsTextRenderer.VAlignment value.Draws a single component of rendered text using the specified settings.
Draws text within a rectangle using the specified settings.
Returns the font metrics for the given text
format
, when rendered in the specified rendercontext
.Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling)
Returns the height of a text based on a given format.
Returns the width of a text based on a given format.
Attributes
- AlignBottom = 2¶
- AlignCenter = 1¶
- AlignJustify = 3¶
- AlignLeft = 0¶
- AlignRight = 2¶
- AlignTop = 0¶
- AlignVCenter = 1¶
- Background = 2¶
- Buffer = 1¶
- class DrawMode¶
Bases:
int
- FONT_WORKAROUND_SCALE = 10.0¶
- class HAlignment¶
Bases:
int
- Label = 2¶
- Point = 1¶
- Rect = 0¶
- Shadow = 3¶
- Text = 0¶
- class TextPart¶
Bases:
int
- class VAlignment¶
Bases:
int
- convertQtHAlignment(alignment: Qt.Alignment | Qt.AlignmentFlag) QgsTextRenderer.HAlignment ¶
Converts a Qt horizontal
alignment
flag to a QgsTextRenderer.HAlignment value.See also
New in version 3.16.
- Parameters:
alignment (Union[Qt.Alignment) –
- Return type:
- convertQtVAlignment(alignment: Qt.Alignment | Qt.AlignmentFlag) QgsTextRenderer.VAlignment ¶
Converts a Qt vertical
alignment
flag to a QgsTextRenderer.VAlignment value.See also
New in version 3.16.
- Parameters:
alignment (Union[Qt.Alignment) –
- Return type:
- drawPart(rect: QRectF, rotation: float, alignment: QgsTextRenderer.HAlignment, textLines: Iterable[str], context: QgsRenderContext, format: QgsTextFormat, part: QgsTextRenderer.TextPart, drawAsOutlines: bool = True)¶
Draws a single component of rendered text using the specified settings.
- Parameters:
rect (QRectF) – destination rectangle for text
rotation (float) – text rotation
alignment (QgsTextRenderer.HAlignment) – horizontal alignment
textLines (Iterable[str]) – list of lines of text to draw
context (QgsRenderContext) – render context
format (QgsTextFormat) – text format
part (QgsTextRenderer.TextPart) – 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 usingQgsRenderContext.setTextRenderFormat()
instead.
Deprecated since version Private: API only, will be removed in 4.0
drawPart(origin: Union[QPointF, QPoint], rotation: float, alignment: QgsTextRenderer.HAlignment, textLines: Iterable[str], context:
QgsRenderContext
, format:QgsTextFormat
, part: QgsTextRenderer.TextPart, drawAsOutlines: bool = True) Draws a single component of rendered text using the specified settings.- Parameters:
origin – origin for start of text. 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 usingQgsRenderContext.setTextRenderFormat()
instead.
Deprecated since version Private: API only, will be removed in 4.0
- drawText(rect: QRectF, rotation: float, alignment: QgsTextRenderer.HAlignment, textLines: Iterable[str], context: QgsRenderContext, format: QgsTextFormat, drawAsOutlines: bool = True, vAlignment: QgsTextRenderer.VAlignment = QgsTextRenderer.AlignTop)¶
Draws text within a rectangle using the specified settings.
- Parameters:
rect (QRectF) – destination rectangle for text
rotation (float) – text rotation
alignment (QgsTextRenderer.HAlignment) – 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 usingQgsRenderContext.setTextRenderFormat()
instead.vAlignment (QgsTextRenderer.VAlignment = QgsTextRenderer.AlignTop) – vertical alignment (since QGIS 3.16)
drawText(point: Union[QPointF, QPoint], rotation: float, alignment: QgsTextRenderer.HAlignment, 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
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 usingQgsRenderContext.setTextRenderFormat()
instead.
- fontMetrics(context: QgsRenderContext, format: QgsTextFormat, scaleFactor: float = 1) QFontMetricsF ¶
Returns the font metrics for the given text
format
, when rendered in the specified rendercontext
. 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:
context (QgsRenderContext) –
format (QgsTextFormat) –
scaleFactor (float = 1) –
- Return type:
QFontMetricsF
- sizeToPixel(size: float, c: QgsRenderContext, unit: QgsUnitTypes.RenderUnit, mapUnitScale: QgsMapUnitScale = QgsMapUnitScale()) int ¶
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 (QgsUnitTypes.RenderUnit) – size units
mapUnitScale (
QgsMapUnitScale
= QgsMapUnitScale()) – a mapUnitScale clamper
- Return type:
int
- Returns:
font pixel size
- textHeight(context: QgsRenderContext, format: QgsTextFormat, textLines: Iterable[str], mode: QgsTextRenderer.DrawMode = QgsTextRenderer.Point, fontMetrics: QFontMetricsF = None) 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 (QgsTextRenderer.DrawMode = QgsTextRenderer.Point) – draw mode
fontMetrics (QFontMetricsF = None) – font metrics
textHeight(context:
QgsRenderContext
, format:QgsTextFormat
, character: str, includeEffects: bool = False) -> float Returns the height of a character when rendered with the specified textformat
.- 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. IfFalse
, then the returned size considers the character only.
New in version 3.16.
- Return type:
float
- 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