Utility functions for text rendering. More...

#include <qgstextrendererutils.h>

Classes
class	CurvedGraphemePlacement
	Contains placement information for a single grapheme in a curved text layout. More...
class	CurvePlacementProperties
	Contains placement information for a curved text layout. More...

Public Types
enum	LabelLineDirection { RespectPainterOrientation , FollowLineDirection }
	Controls behavior of curved text with respect to line directions. More...

Static Public Member Functions
static Qgis::RenderUnit	convertFromOldLabelUnit (int val)
	Converts a unit from an old (pre 3.0) label unit.
static QgsTextBackgroundSettings::RotationType	decodeBackgroundRotationType (const QString &string)
	Decodes a string representation of a background rotation type to a type.
static QgsTextBackgroundSettings::SizeType	decodeBackgroundSizeType (const QString &string)
	Decodes a string representation of a background size type to a type.
static QgsTextShadowSettings::ShadowPlacement	decodeShadowPlacementType (const QString &string)
	Decodes a string representation of a shadow placement type to a type.
static QgsTextBackgroundSettings::ShapeType	decodeShapeType (const QString &string)
	Decodes a string representation of a background shape type to a type.
static Qgis::TextOrientation	decodeTextOrientation (const QString &name, bool *ok=nullptr)
	Attempts to decode a string representation of a text orientation.
static QString	encodeTextOrientation (Qgis::TextOrientation orientation)
	Encodes a text orientation.
static std::unique_ptr< CurvePlacementProperties >	generateCurvedTextPlacement (const QgsPrecalculatedTextMetrics &metrics, const double x, const double y, int numPoints, const std::vector< double > &pathDistances, double offsetAlongLine, LabelLineDirection direction=RespectPainterOrientation, double maxConcaveAngle=-1, double maxConvexAngle=-1, Qgis::CurvedTextFlags flags=Qgis::CurvedTextFlags(), double additionalCharacterSpacing=0.0, double additionalWordSpacing=0.0, Qgis::TextAnchorPoint textAnchor=Qgis::TextAnchorPoint::StartOfText)
	Calculates curved text placement properties.
static std::unique_ptr< CurvePlacementProperties >	generateCurvedTextPlacement (const QgsPrecalculatedTextMetrics &metrics, const QPolygonF &line, double offsetAlongLine, LabelLineDirection direction=RespectPainterOrientation, double maxConcaveAngle=-1, double maxConvexAngle=-1, Qgis::CurvedTextFlags flags=Qgis::CurvedTextFlags(), Qgis::TextAnchorPoint textAnchor=Qgis::TextAnchorPoint::StartOfText)
	Calculates curved text placement properties.
static QColor	readColor (QgsVectorLayer *layer, const QString &property, const QColor &defaultColor=Qt::black, bool withAlpha=true)
	Converts an encoded color value from a layer property.

Detailed Description

Utility functions for text rendering.

Since: QGIS 3.10

Definition at line 31 of file qgstextrendererutils.h.

Member Enumeration Documentation

◆ LabelLineDirection

enum QgsTextRendererUtils::LabelLineDirection

Controls behavior of curved text with respect to line directions.

Enumerator
RespectPainterOrientation	Curved text will be placed respecting the painter orientation, and the actual line direction will be ignored.
FollowLineDirection	Curved text placement will respect the line direction and ignore painter orientation.

Definition at line 137 of file qgstextrendererutils.h.

Member Function Documentation

◆ convertFromOldLabelUnit()

Qgis::RenderUnit QgsTextRendererUtils::convertFromOldLabelUnit ( int val )

static

Converts a unit from an old (pre 3.0) label unit.

Note: Not available in Python bindings.

Since: QGIS 3.14

Definition at line 137 of file qgstextrendererutils.cpp.

◆ decodeBackgroundRotationType()

QgsTextBackgroundSettings::RotationType QgsTextRendererUtils::decodeBackgroundRotationType ( const QString & string )

static

Decodes a string representation of a background rotation type to a type.

Definition at line 66 of file qgstextrendererutils.cpp.

◆ decodeBackgroundSizeType()

QgsTextBackgroundSettings::SizeType QgsTextRendererUtils::decodeBackgroundSizeType ( const QString & string )

static

Decodes a string representation of a background size type to a type.

Definition at line 53 of file qgstextrendererutils.cpp.

◆ decodeShadowPlacementType()

QgsTextShadowSettings::ShadowPlacement QgsTextRendererUtils::decodeShadowPlacementType ( const QString & string )

static

Decodes a string representation of a shadow placement type to a type.

Definition at line 83 of file qgstextrendererutils.cpp.

◆ decodeShapeType()

QgsTextBackgroundSettings::ShapeType QgsTextRendererUtils::decodeShapeType ( const QString & string )

static

Decodes a string representation of a background shape type to a type.

Definition at line 25 of file qgstextrendererutils.cpp.

◆ decodeTextOrientation()

Qgis::TextOrientation QgsTextRendererUtils::decodeTextOrientation	(	const QString &	name,
		bool *	ok = nullptr )

static

Attempts to decode a string representation of a text orientation.

Parameters

name	encoded text orientation name
ok	if specified, will be set to `true` if the name was successfully decoded

Returns: decoded text orientation

See also: encodeTextOrientation()

Definition at line 118 of file qgstextrendererutils.cpp.

◆ encodeTextOrientation()

QString QgsTextRendererUtils::encodeTextOrientation ( Qgis::TextOrientation orientation )

static

Encodes a text orientation.

Returns: encoded string

See also: decodeTextOrientation()

Definition at line 104 of file qgstextrendererutils.cpp.

◆ generateCurvedTextPlacement() [1/2]

std::unique_ptr< QgsTextRendererUtils::CurvePlacementProperties > QgsTextRendererUtils::generateCurvedTextPlacement	(	const QgsPrecalculatedTextMetrics &	metrics,
		const double *	x,
		const double *	y,
		int	numPoints,
		const std::vector< double > &	pathDistances,
		double	offsetAlongLine,
		LabelLineDirection	direction = RespectPainterOrientation,
		double	maxConcaveAngle = -1,
		double	maxConvexAngle = -1,
		Qgis::CurvedTextFlags	flags = Qgis::CurvedTextFlags(),
		double	additionalCharacterSpacing = 0.0,
		double	additionalWordSpacing = 0.0,
		Qgis::TextAnchorPoint	textAnchor = Qgis::TextAnchorPoint::StartOfText )

static

Calculates curved text placement properties.

Parameters

metrics	precalculated text metrics for text to render
x	array of linestring x coordinates
y	array of linestring y coordinates
numPoints	number of points in x, y arrays
pathDistances	vector of precalculated distances between vertices in x, y arrays
offsetAlongLine	offset along line at which to start the curved text placement. Only applies when textAnchor is Qgis::TextAnchorPoint::StartOfText.
direction	controls placement of text with respect to painter orientation or line direction
maxConcaveAngle	maximum angle between characters for concave text, or -1 if not set
maxConvexAngle	maximum angle between characters for convex text, or -1 if not set
flags	flags controlling behavior of curved text generation
additionalCharacterSpacing	additional spacing to apply between every character (grapheme). Can be negative to constrict text placement. (since QGIS 4.0)
additionalWordSpacing	additional spacing to apply after every word (space character). Can be negative to constrict text placement. (since QGIS 4.0)
textAnchor	dictates where on the line the text should be anchored to. If the anchor point is the start of the text, the text will always start at the start of the line (and potential extend past the end of the line). If the anchor point is the end of the text, then the text will always end at the end of the line and potential extend past the start of the line. (since QGIS 4.4)

Returns: calculated placement properties, or nullptr if placement could not be calculated. Caller takes ownership of the returned placement.

Since: QGIS 3.20

Definition at line 203 of file qgstextrendererutils.cpp.

◆ generateCurvedTextPlacement() [2/2]

std::unique_ptr< QgsTextRendererUtils::CurvePlacementProperties > QgsTextRendererUtils::generateCurvedTextPlacement	(	const QgsPrecalculatedTextMetrics &	metrics,
		const QPolygonF &	line,
		double	offsetAlongLine,
		LabelLineDirection	direction = RespectPainterOrientation,
		double	maxConcaveAngle = -1,
		double	maxConvexAngle = -1,
		Qgis::CurvedTextFlags	flags = Qgis::CurvedTextFlags(),
		Qgis::TextAnchorPoint	textAnchor = Qgis::TextAnchorPoint::StartOfText )

static

Calculates curved text placement properties.

Parameters

metrics	precalculated text metrics for text to render
line	line to render text along
offsetAlongLine	offset along line at which to start the curved text placement. Only applies when textAnchor is Qgis::TextAnchorPoint::StartOfText.
direction	controls placement of text with respect to painter orientation or line direction
maxConcaveAngle	maximum angle between characters for concave text, or -1 if not set
maxConvexAngle	maximum angle between characters for convex text, or -1 if not set
flags	flags controlling behavior of curved text generation
textAnchor	dictates where on the line the text should be anchored to. If the anchor point is the start of the text, the text will always start at the start of the line (and potential extend past the end of the line). If the anchor point is the end of the text, then the text will always end at the end of the line and potential extend past the start of the line. (since QGIS 4.4)

Returns: calculated placement properties, or nullptr if placement could not be calculated. Caller takes ownership of the returned placement.

Since: QGIS 3.20

Definition at line 160 of file qgstextrendererutils.cpp.

◆ readColor()

QColor QgsTextRendererUtils::readColor	(	QgsVectorLayer *	layer,
		const QString &	property,
		const QColor &	defaultColor = Qt::black,
		bool	withAlpha = true )

static

Converts an encoded color value from a layer property.

Note: Not available in Python bindings.

Since: QGIS 3.14

Definition at line 151 of file qgstextrendererutils.cpp.

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

/build/qgis-4.3.0+git20260731+0978c174f8e+99sid/src/core/textrenderer/qgstextrendererutils.h
/build/qgis-4.3.0+git20260731+0978c174f8e+99sid/src/core/textrenderer/qgstextrendererutils.cpp

Classes

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ LabelLineDirection

Member Function Documentation

◆ convertFromOldLabelUnit()

◆ decodeBackgroundRotationType()

◆ decodeBackgroundSizeType()

◆ decodeShadowPlacementType()

◆ decodeShapeType()

◆ decodeTextOrientation()

◆ encodeTextOrientation()

◆ generateCurvedTextPlacement() [1/2]

◆ generateCurvedTextPlacement() [2/2]

◆ readColor()