QgsTextRenderer class

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

Reference
- Public types
- Public static functions

Public types

enum DrawMode { Rect = 0, Point, Label }: Draw mode to calculate width and height.
enum HAlignment { AlignLeft = 0, AlignCenter, AlignRight }: Horizontal alignment.
enum TextPart { Text = 0, Buffer, Background, Shadow }: Components of text.

Public static functions

static void drawPart(const QRectF& rect, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, TextPart part, bool drawAsOutlines = true): Draws a single component of rendered text using the specified settings.
static void drawPart(QPointF origin, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, TextPart part, bool drawAsOutlines = true): Draws a single component of rendered text using the specified settings.
static void drawText(const QRectF& rect, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, bool drawAsOutlines = true): Draws text within a rectangle using the specified settings.
static void drawText(QPointF point, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, bool drawAsOutlines = true): Draws text at a point origin using the specified settings.
static auto fontMetrics(QgsRenderContext& context, const QgsTextFormat& format) -> QFontMetricsF: Returns the font metrics for the given text format, when rendered in the specified render context.
static auto sizeToPixel(double size, const QgsRenderContext& c, QgsUnitTypes::RenderUnit unit, const QgsMapUnitScale& mapUnitScale = QgsMapUnitScale()) -> int: Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling)
static auto textHeight(const QgsRenderContext& context, const QgsTextFormat& format, const QStringList& textLines, DrawMode mode, QFontMetricsF* fontMetrics = nullptr) -> double: Returns the height of a text based on a given format.
static auto textWidth(const QgsRenderContext& context, const QgsTextFormat& format, const QStringList& textLines, QFontMetricsF* fontMetrics = nullptr) -> double: Returns the width of a text based on a given format.

Enum documentation

enum QgsTextRenderer::DrawMode

Draw mode to calculate width and height.

Enumerators
Rect	Text within rectangle draw mode.
Point	Text at point of origin draw mode.
Label	Label-specific draw mode.

enum QgsTextRenderer::HAlignment

Horizontal alignment.

Enumerators
AlignLeft	Left align.
AlignCenter	Center align.
AlignRight	Right align.

enum QgsTextRenderer::TextPart

Components of text.

Enumerators
Text	Text component.
Buffer	Buffer component.
Background	Background shape.
Shadow	Drop shadow.

Function documentation

static void QgsTextRenderer::drawPart(const QRectF& rect, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, TextPart part, bool drawAsOutlines = true)

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

Parameters
rect	destination rectangle for text
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.

static void QgsTextRenderer::drawPart(QPointF origin, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, TextPart part, bool drawAsOutlines = 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 using QgsRenderContext::setTextRenderFormat() instead.

static void QgsTextRenderer::drawText(const QRectF& rect, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, bool drawAsOutlines = true)

Draws text within a rectangle using the specified settings.

Parameters
rect	destination rectangle for 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 using QgsRenderContext::setTextRenderFormat() instead.

static void QgsTextRenderer::drawText(QPointF point, double rotation, HAlignment alignment, const QStringList& textLines, QgsRenderContext& context, const QgsTextFormat& format, bool drawAsOutlines = 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 using QgsRenderContext::setTextRenderFormat() instead.

static QFontMetricsF QgsTextRenderer::fontMetrics(QgsRenderContext& context, const QgsTextFormat& format)

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.

static int QgsTextRenderer::sizeToPixel(double size, const QgsRenderContext& c, QgsUnitTypes::RenderUnit unit, const QgsMapUnitScale& mapUnitScale = QgsMapUnitScale())

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

Parameters
size	size to convert
c	rendercontext
unit	size units
mapUnitScale	a mapUnitScale clamper
Returns	font pixel size

static double QgsTextRenderer::textHeight(const QgsRenderContext& context, const QgsTextFormat& format, const QStringList& textLines, DrawMode mode, QFontMetricsF* fontMetrics = nullptr)

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

Parameters
context	render context
format	text format
textLines	list of lines of text to calculate width from
mode	draw mode
fontMetrics	font metrics

static double QgsTextRenderer::textWidth(const QgsRenderContext& context, const QgsTextFormat& format, const QStringList& textLines, QFontMetricsF* fontMetrics = nullptr)

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

Parameters
context	render context
format	text format
textLines	list of lines of text to calculate width from
fontMetrics	font metrics