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

#include <qgstextrenderer.h>

Static Public Member Functions
static double	calculateScaleFactorForFormat (const QgsRenderContext &context, const QgsTextFormat &format)
	Returns the scale factor used for upscaling font sizes and downscaling destination painter devices.

static Qgis::TextHorizontalAlignment	convertQtHAlignment (Qt::Alignment alignment)
	Converts a Qt horizontal alignment flag to a Qgis::TextHorizontalAlignment value.

static Qgis::TextVerticalAlignment	convertQtVAlignment (Qt::Alignment alignment)
	Converts a Qt vertical alignment flag to a Qgis::TextVerticalAlignment value.

static void	drawDocument (const QRectF &rect, const QgsTextFormat &format, const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics, QgsRenderContext &context, Qgis::TextHorizontalAlignment horizontalAlignment=Qgis::TextHorizontalAlignment::Left, Qgis::TextVerticalAlignment verticalAlignment=Qgis::TextVerticalAlignment::Top, double rotation=0, Qgis::TextLayoutMode mode=Qgis::TextLayoutMode::Rectangle, Qgis::TextRendererFlags flags=Qgis::TextRendererFlags())
	Draws a text document within a rectangle using the specified settings.

static void	drawDocument (QPointF point, const QgsTextFormat &format, const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics, QgsRenderContext &context, Qgis::TextHorizontalAlignment alignment, double rotation, Qgis::TextLayoutMode mode=Qgis::TextLayoutMode::Point)
	Draws a text document at a point origin using the specified settings.

static void	drawDocumentOnLine (const QPolygonF &line, const QgsTextFormat &format, const QgsTextDocument &document, QgsRenderContext &context, double offsetAlongLine=0, double offsetFromLine=0)
	Draws a text document along a line using the specified settings.

static Q_DECL_DEPRECATED void	drawPart (const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponent part, bool drawAsOutlines=true)
	Draws a single component of rendered text using the specified settings.

static Q_DECL_DEPRECATED void	drawPart (QPointF origin, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponent part, bool drawAsOutlines=true)
	Draws a single component of rendered text using the specified settings.

static void	drawText (const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, bool drawAsOutlines=true, Qgis::TextVerticalAlignment vAlignment=Qgis::TextVerticalAlignment::Top, Qgis::TextRendererFlags flags=Qgis::TextRendererFlags(), Qgis::TextLayoutMode mode=Qgis::TextLayoutMode::Rectangle)
	Draws text within a rectangle using the specified settings.

static void	drawText (QPointF point, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, bool drawAsOutlines=true)
	Draws text at a point origin using the specified settings.

static void	drawTextOnLine (const QPolygonF &line, const QString &text, QgsRenderContext &context, const QgsTextFormat &format, double offsetAlongLine=0, double offsetFromLine=0)
	Draws text along a line using the specified settings.

static QFontMetricsF	fontMetrics (QgsRenderContext &context, const QgsTextFormat &format, double scaleFactor=1.0)
	Returns the font metrics for the given text format, when rendered in the specified render context.

static int	sizeToPixel (double size, const QgsRenderContext &c, Qgis::RenderUnit unit, const QgsMapUnitScale &mapUnitScale=QgsMapUnitScale())
	Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling)

static double	textHeight (const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, Qgis::TextLayoutMode mode=Qgis::TextLayoutMode::Point, QFontMetricsF *fontMetrics=nullptr, Qgis::TextRendererFlags flags=Qgis::TextRendererFlags(), double maxLineWidth=0)
	Returns the height of a text based on a given format.

static double	textHeight (const QgsRenderContext &context, const QgsTextFormat &format, QChar character, bool includeEffects=false)
	Returns the height of a character when rendered with the specified text format.

static bool	textRequiresWrapping (const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format)
	Returns `true` if the specified text requires line wrapping in order to fit within the specified width (in painter units).

static double	textWidth (const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, QFontMetricsF *fontMetrics=nullptr)
	Returns the width of a text based on a given format.

static QStringList	wrappedText (const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format)
	Wraps a text string to multiple lines, such that each individual line will fit within the specified width (in painter units).

Static Public Attributes
static constexpr double	FONT_WORKAROUND_SCALE = 10
	Scale factor for upscaling font sizes and downscaling destination painter devices.

static constexpr double	SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR = 2.0 / 3.0
	Scale factor to use for super or subscript text which doesn't have an explicit font size set.

Friends
class	QgsLabelPreview

class	QgsVectorLayerLabelProvider

Detailed Description

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

Definition at line 41 of file qgstextrenderer.h.

Member Function Documentation

◆ calculateScaleFactorForFormat()

double QgsTextRenderer::calculateScaleFactorForFormat	(	const QgsRenderContext &	context,
		const QgsTextFormat &	format
	)

static

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.

Since: QGIS 3.40

Definition at line 2632 of file qgstextrenderer.cpp.

◆ convertQtHAlignment()

Qgis::TextHorizontalAlignment QgsTextRenderer::convertQtHAlignment ( Qt::Alignment alignment )

static

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

See also: convertQtVAlignment()

Since: QGIS 3.16

Definition at line 40 of file qgstextrenderer.cpp.

◆ convertQtVAlignment()

Qgis::TextVerticalAlignment QgsTextRenderer::convertQtVAlignment ( Qt::Alignment alignment )

static

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

See also: convertQtHAlignment()

Since: QGIS 3.16

Definition at line 55 of file qgstextrenderer.cpp.

◆ drawDocument() [1/2]

void QgsTextRenderer::drawDocument	(	const QRectF &	rect,
		const QgsTextFormat &	format,
		const QgsTextDocument &	document,
		const QgsTextDocumentMetrics &	metrics,
		QgsRenderContext &	context,
		Qgis::TextHorizontalAlignment	horizontalAlignment = `Qgis::TextHorizontalAlignment::Left`,
		Qgis::TextVerticalAlignment	verticalAlignment = `Qgis::TextVerticalAlignment::Top`,
		double	rotation = `0`,
		Qgis::TextLayoutMode	mode = `Qgis::TextLayoutMode::Rectangle`,
		Qgis::TextRendererFlags	flags = `Qgis::TextRendererFlags()`
	)

static

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	destination rectangle for text, in painter units
format	base text format
document	text document to draw
metrics	precalculated text metrics
context	destination render context
horizontalAlignment	horizontal alignment
verticalAlignment	vertical alignment
rotation	text rotation
mode	text layout mode. Only Qgis::TextLayoutMode::Rectangle, Qgis::TextLayoutMode::RectangleCapHeightBased and Qgis::TextLayoutMode::RectangleAscentBased are accepted.
flags	text rendering flags

Since: QGIS 3.30

Definition at line 95 of file qgstextrenderer.cpp.

◆ drawDocument() [2/2]

void QgsTextRenderer::drawDocument	(	QPointF	point,
		const QgsTextFormat &	format,
		const QgsTextDocument &	document,
		const QgsTextDocumentMetrics &	metrics,
		QgsRenderContext &	context,
		Qgis::TextHorizontalAlignment	alignment,
		double	rotation,
		Qgis::TextLayoutMode	mode = `Qgis::TextLayoutMode::Point`
	)

static

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	origin of text, in painter units
format	base text format
document	text document to draw
metrics	precalculated text metrics
context	destination render context
alignment	horizontal alignment
rotation	text rotation
mode	optional layout mode (since QGIS 3.42)

Since: QGIS 3.40

Definition at line 133 of file qgstextrenderer.cpp.

◆ drawDocumentOnLine()

void QgsTextRenderer::drawDocumentOnLine	(	const QPolygonF &	line,
		const QgsTextFormat &	format,
		const QgsTextDocument &	document,
		QgsRenderContext &	context,
		double	offsetAlongLine = `0`,
		double	offsetFromLine = `0`
	)

static

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

Parameters

line	line to render text along, in painter units
format	text format
document	text document to draw
context	render context
offsetAlongLine	offset along the line (in painter units) to start text at
offsetFromLine	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.

Since: QGIS 3.32

Definition at line 169 of file qgstextrenderer.cpp.

◆ drawPart() [1/2]

void QgsTextRenderer::drawPart	(	const QRectF &	rect,
		double	rotation,
		Qgis::TextHorizontalAlignment	alignment,
		const QStringList &	textLines,
		QgsRenderContext &	context,
		const QgsTextFormat &	format,
		Qgis::TextComponent	part,
		bool	drawAsOutlines = `true`
	)

static

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

Parameters

rect	destination rectangle for text, in painter units
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:: QGIS 3.40. Private API only, will be removed in 4.0.

Definition at line 409 of file qgstextrenderer.cpp.

◆ drawPart() [2/2]

void QgsTextRenderer::drawPart	(	QPointF	origin,
		double	rotation,
		Qgis::TextHorizontalAlignment	alignment,
		const QStringList &	textLines,
		QgsRenderContext &	context,
		const QgsTextFormat &	format,
		Qgis::TextComponent	part,
		bool	drawAsOutlines = `true`
	)

static

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

Definition at line 481 of file qgstextrenderer.cpp.

◆ drawText() [1/2]

void QgsTextRenderer::drawText	(	const QRectF &	rect,
		double	rotation,
		Qgis::TextHorizontalAlignment	alignment,
		const QStringList &	textLines,
		QgsRenderContext &	context,
		const QgsTextFormat &	format,
		bool	drawAsOutlines = `true`,
		Qgis::TextVerticalAlignment	vAlignment = `Qgis::TextVerticalAlignment::Top`,
		Qgis::TextRendererFlags	flags = `Qgis::TextRendererFlags()`,
		Qgis::TextLayoutMode	mode = `Qgis::TextLayoutMode::Rectangle`
	)

static

Draws text within a rectangle using the specified settings.

Parameters

rect	destination rectangle for 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.
vAlignment	vertical alignment (since QGIS 3.16)
flags	text rendering flags (since QGIS 3.24)
mode	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.

Definition at line 75 of file qgstextrenderer.cpp.

◆ drawText() [2/2]

void QgsTextRenderer::drawText	(	QPointF	point,
		double	rotation,
		Qgis::TextHorizontalAlignment	alignment,
		const QStringList &	textLines,
		QgsRenderContext &	context,
		const QgsTextFormat &	format,
		bool	drawAsOutlines = `true`
	)

static

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.

Definition at line 118 of file qgstextrenderer.cpp.

◆ drawTextOnLine()

void QgsTextRenderer::drawTextOnLine	(	const QPolygonF &	line,
		const QString &	text,
		QgsRenderContext &	context,
		const QgsTextFormat &	format,
		double	offsetAlongLine = `0`,
		double	offsetFromLine = `0`
	)

static

Draws text along a line using the specified settings.

Parameters

line	line to render text along, in painter units
text	text to draw
context	render context
format	text format
offsetAlongLine	offset along the line (in painter units) to start text at
offsetFromLine	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.

Since: QGIS 3.32

Definition at line 154 of file qgstextrenderer.cpp.

◆ fontMetrics()

QFontMetricsF QgsTextRenderer::fontMetrics	(	QgsRenderContext &	context,
		const QgsTextFormat &	format,
		double	scaleFactor = `1.0`
	)

static

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.

Since: QGIS 3.2

Definition at line 523 of file qgstextrenderer.cpp.

◆ sizeToPixel()

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

static

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

Definition at line 70 of file qgstextrenderer.cpp.

◆ textHeight() [1/2]

double QgsTextRenderer::textHeight	(	const QgsRenderContext &	context,
		const QgsTextFormat &	format,
		const QStringList &	textLines,
		Qgis::TextLayoutMode	mode = `Qgis::TextLayoutMode::Point`,
		QFontMetricsF *	fontMetrics = `nullptr`,
		Qgis::TextRendererFlags	flags = `Qgis::TextRendererFlags()`,
		double	maxLineWidth = `0`
	)

static

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
flags	text renderer flags (since QGIS 3.24)
maxLineWidth	maximum line width, in painter units. Used when the Qgis::TextRendererFlag::WrapLines flag is used (since QGIS 3.24)

Definition at line 809 of file qgstextrenderer.cpp.

◆ textHeight() [2/2]

double QgsTextRenderer::textHeight	(	const QgsRenderContext &	context,
		const QgsTextFormat &	format,
		QChar	character,
		bool	includeEffects = `false`
	)

static

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.

Since: QGIS 3.16

Definition at line 828 of file qgstextrenderer.cpp.

◆ textRequiresWrapping()

bool QgsTextRenderer::textRequiresWrapping	(	const QgsRenderContext &	context,
		const QString &	text,
		double	width,
		const QgsTextFormat &	format
	)

static

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

See also: wrappedText()

Since: QGIS 3.24

Definition at line 875 of file qgstextrenderer.cpp.

◆ textWidth()

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

static

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

Definition at line 789 of file qgstextrenderer.cpp.

◆ wrappedText()

QStringList QgsTextRenderer::wrappedText	(	const QgsRenderContext &	context,
		const QString &	text,
		double	width,
		const QgsTextFormat &	format
	)

static

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

See also: textRequiresWrapping()

Since: QGIS 3.24

Definition at line 885 of file qgstextrenderer.cpp.

Friends And Related Symbol Documentation

◆ QgsLabelPreview

friend class QgsLabelPreview

friend

Definition at line 556 of file qgstextrenderer.h.

◆ QgsVectorLayerLabelProvider

friend class QgsVectorLayerLabelProvider

friend

Definition at line 555 of file qgstextrenderer.h.

Member Data Documentation

◆ FONT_WORKAROUND_SCALE

constexpr double QgsTextRenderer::FONT_WORKAROUND_SCALE = 10

staticconstexpr

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.

Since: QGIS 3.16

Definition at line 331 of file qgstextrenderer.h.

◆ SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR

constexpr double QgsTextRenderer::SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR = 2.0 / 3.0

staticconstexpr

Scale factor to use for super or subscript text which doesn't have an explicit font size set.

Since: QGIS 3.32

Definition at line 350 of file qgstextrenderer.h.

The documentation for this class was generated from the following files:

/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/textrenderer/qgstextrenderer.h
/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/textrenderer/qgstextrenderer.cpp

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Function Documentation

◆ calculateScaleFactorForFormat()

◆ convertQtHAlignment()

◆ convertQtVAlignment()

◆ drawDocument() [1/2]

◆ drawDocument() [2/2]

◆ drawDocumentOnLine()

◆ drawPart() [1/2]

◆ drawPart() [2/2]

◆ drawText() [1/2]

◆ drawText() [2/2]

◆ drawTextOnLine()

◆ fontMetrics()

◆ sizeToPixel()

◆ textHeight() [1/2]

◆ textHeight() [2/2]

◆ textRequiresWrapping()

◆ textWidth()

◆ wrappedText()

Friends And Related Symbol Documentation

◆ QgsLabelPreview

◆ QgsVectorLayerLabelProvider

Member Data Documentation

◆ FONT_WORKAROUND_SCALE

◆ SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR