Abstract base class for callout renderers. More...

#include <qgscallout.h>

Inheritance diagram for QgsCallout:

[legend]

Classes
class	QgsCalloutContext
	Contains additional contextual information about the context in which a callout is being rendered. More...

Public Types
enum	AnchorPoint { PoleOfInaccessibility = 0 , PointOnExterior , PointOnSurface , Centroid }
	Feature's anchor point position. More...

enum	DrawOrder { OrderBelowAllLabels , OrderBelowIndividualLabels }
	Options for draw order (stacking) of callouts. More...

enum	LabelAnchorPoint { LabelPointOnExterior , LabelCentroid , LabelTopLeft , LabelTopMiddle , LabelTopRight , LabelMiddleLeft , LabelMiddleRight , LabelBottomLeft , LabelBottomMiddle , LabelBottomRight }
	Label's anchor point position. More...

enum class	Property : int { MinimumCalloutLength , OffsetFromAnchor , OffsetFromLabel , DrawCalloutToAllParts , AnchorPointPosition , LabelAnchorPointPosition , OriginX , OriginY , DestinationX , DestinationY , Curvature , Orientation , Margins , WedgeWidth , CornerRadius , BlendMode }
	Data definable properties. More...

Public Member Functions
	QgsCallout ()
	Constructor for QgsCallout.

virtual	~QgsCallout ()=default

AnchorPoint	anchorPoint () const
	Returns the feature's anchor point position.

QPainter::CompositionMode	blendMode () const
	Returns the blending mode used for drawing callouts.

virtual QgsCallout *	clone () const =0
	Duplicates a callout by creating a deep copy of the callout.

bool	containsAdvancedEffects () const
	Returns `true` if the callout requires advanced effects such as blend modes, which require output in raster formats to be fully respected.

QgsPropertyCollection &	dataDefinedProperties ()
	Returns a reference to the callout's property collection, used for data defined overrides.

const QgsPropertyCollection &	dataDefinedProperties () const
	Returns a reference to the callout's property collection, used for data defined overrides.

virtual DrawOrder	drawOrder () const
	Returns the desired drawing order (stacking) to use while rendering this callout.

bool	enabled () const
	Returns `true` if the the callout is enabled.

LabelAnchorPoint	labelAnchorPoint () const
	Returns the label's anchor point position.

virtual QVariantMap	properties (const QgsReadWriteContext &context) const
	Returns the properties describing the callout encoded in a string format.

virtual void	readProperties (const QVariantMap &props, const QgsReadWriteContext &context)
	Reads a string map of an callout's properties and restores the callout to the state described by the properties map.

virtual QSet< QString >	referencedFields (const QgsRenderContext &context) const
	Returns the set of attributes referenced by the callout.

void	render (QgsRenderContext &context, const QRectF &rect, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext)
	Renders the callout onto the specified render context.

virtual void	restoreProperties (const QDomElement &element, const QgsReadWriteContext &context)
	Restores the callout's properties from a DOM element.

virtual bool	saveProperties (QDomDocument &doc, QDomElement &element, const QgsReadWriteContext &context) const
	Saves the current state of the callout to a DOM element.

void	setAnchorPoint (AnchorPoint anchor)
	Sets the feature's anchor point position.

void	setBlendMode (QPainter::CompositionMode mode)
	Sets the blending mode used for drawing callouts.

void	setDataDefinedProperties (const QgsPropertyCollection &collection)
	Sets the callout's property collection, used for data defined overrides.

void	setEnabled (bool enabled)
	Sets whether the callout is enabled.

void	setLabelAnchorPoint (LabelAnchorPoint anchor)
	Sets the label's anchor point position.

virtual void	startRender (QgsRenderContext &context)
	Prepares the callout for rendering on the specified render context.

virtual void	stopRender (QgsRenderContext &context)
	Finalises the callout after a set of rendering operations on the specified render context.

virtual QString	type () const =0
	Returns a unique string representing the callout type.

Static Public Member Functions
static QgsCallout::AnchorPoint	decodeAnchorPoint (const QString &name, bool *ok=nullptr)
	Attempts to decode a string representation of an anchor point name to the corresponding anchor point.

static QgsCallout::LabelAnchorPoint	decodeLabelAnchorPoint (const QString &name, bool *ok=nullptr)
	Attempts to decode a string representation of a label anchor point name to the corresponding anchor point.

static QString	encodeAnchorPoint (AnchorPoint anchor)
	Encodes an anchor point to its string representation.

static QString	encodeLabelAnchorPoint (LabelAnchorPoint anchor)
	Encodes a label anchor point to its string representation.

static QgsPropertiesDefinition	propertyDefinitions ()
	Returns the definitions for data defined properties available for use in callouts.

Protected Member Functions
QgsGeometry	calloutLabelPoint (const QRectF &bodyBoundingBox, double angle, LabelAnchorPoint anchor, QgsRenderContext &context, const QgsCalloutContext &calloutContext, bool &pinned) const
	Returns the anchor point geometry for a label with the given bounding box and anchor point mode.

QgsGeometry	calloutLineToPart (const QgsGeometry &labelGeometry, const QgsAbstractGeometry *partGeometry, QgsRenderContext &context, const QgsCalloutContext &calloutContext, bool &pinned) const
	Calculates the direct line from a label geometry to an anchor geometry part, respecting the various callout settings which influence how the callout end should be placed in the anchor geometry.

virtual void	draw (QgsRenderContext &context, const QRectF &bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext)=0
	Performs the actual rendering of the callout implementation onto the specified render context.

Q_DECL_DEPRECATED QgsGeometry	labelAnchorGeometry (const QRectF &bodyBoundingBox, const double angle, LabelAnchorPoint anchor) const
	Returns the anchor point geometry for a label with the given bounding box and anchor point mode.

Detailed Description

Abstract base class for callout renderers.

Implementations of QgsCallout are responsible for performing the actual render of callouts, including determining the desired shape of the callout and using any relevant symbology elements to render them.

Since: QGIS 3.10

Definition at line 53 of file qgscallout.h.

Member Enumeration Documentation

◆ AnchorPoint

enum QgsCallout::AnchorPoint

Feature's anchor point position.

Enumerator
PoleOfInaccessibility	The surface's pole of inaccessibility used as anchor for polygon geometries.
PointOnExterior	A point on the surface's outline closest to the label is used as anchor for polygon geometries.
PointOnSurface	A point guaranteed to be on the surface is used as anchor for polygon geometries.
Centroid	The surface's centroid is used as anchor for polygon geometries.

Definition at line 114 of file qgscallout.h.

◆ DrawOrder

enum QgsCallout::DrawOrder

Options for draw order (stacking) of callouts.

Enumerator
OrderBelowAllLabels	Render callouts below all labels.
OrderBelowIndividualLabels	Render callouts below their individual associated labels, some callouts may be drawn over other labels.

Definition at line 107 of file qgscallout.h.

◆ LabelAnchorPoint

enum QgsCallout::LabelAnchorPoint

Label's anchor point position.

Since: QGIS 3.14

Enumerator
LabelPointOnExterior	The point on the label's boundary closest to the feature.
LabelCentroid	The labe's centroid.
LabelTopLeft	Top left corner of the label's boundary.
LabelTopMiddle	Top middle of the label's boundary.
LabelTopRight	Top right corner of the label's boundary.
LabelMiddleLeft	Middle left of the label's boundary.
LabelMiddleRight	Middle right of the label's boundary.
LabelBottomLeft	Bottom left corner of the label's boundary.
LabelBottomMiddle	Bottom middle of the label's boundary.
LabelBottomRight	Bottom right corner of the label's boundary.

Definition at line 126 of file qgscallout.h.

◆ Property

enum class QgsCallout::Property : int

strong

Data definable properties.

Enumerator
MinimumCalloutLength	Minimum length of callouts.
OffsetFromAnchor	Distance to offset lines from anchor points.
OffsetFromLabel	Distance to offset lines from label area.
DrawCalloutToAllParts	Whether callout lines should be drawn to all feature parts.
AnchorPointPosition	Feature's anchor point position.
LabelAnchorPointPosition	Label's anchor point position.
OriginX	X-coordinate of callout origin (label anchor) Since QGIS 3.20
OriginY	Y-coordinate of callout origin (label anchor) Since QGIS 3.20
DestinationX	X-coordinate of callout destination (feature anchor) Since QGIS 3.20
DestinationY	Y-coordinate of callout destination (feature anchor) Since QGIS 3.20
Curvature	Curvature of curved line callouts. Since QGIS 3.20
Orientation	Orientation of curved line callouts. Since QGIS 3.20
Margins	Margin from text. Since QGIS 3.20
WedgeWidth	Balloon callout wedge width. Since QGIS 3.20
CornerRadius	Balloon callout corner radius. Since QGIS 3.20
BlendMode	Callout blend mode. Since QGIS 3.20

Definition at line 85 of file qgscallout.h.

Constructor & Destructor Documentation

◆ QgsCallout()

QgsCallout::QgsCallout ( )

Constructor for QgsCallout.

Definition at line 77 of file qgscallout.cpp.

◆ ~QgsCallout()

virtual QgsCallout::~QgsCallout ( )

virtualdefault

Member Function Documentation

◆ anchorPoint()

AnchorPoint QgsCallout::anchorPoint ( ) const

inline

Returns the feature's anchor point position.

See also: setAnchorPoint()

Definition at line 364 of file qgscallout.h.

◆ blendMode()

QPainter::CompositionMode QgsCallout::blendMode ( ) const

inline

Returns the blending mode used for drawing callouts.

See also: setBlendMode()

Since: QGIS 3.20

Definition at line 431 of file qgscallout.h.

◆ calloutLabelPoint()

QgsGeometry QgsCallout::calloutLabelPoint	(	const QRectF &	bodyBoundingBox,
		double	angle,
		QgsCallout::LabelAnchorPoint	anchor,
		QgsRenderContext &	context,
		const QgsCalloutContext &	calloutContext,
		bool &	pinned
	)		const

protected

Returns the anchor point geometry for a label with the given bounding box and anchor point mode.

The pinned argument will be set to true if the callout label point is pinned (manually placed).

Since: QGIS 3.20

Definition at line 351 of file qgscallout.cpp.

◆ calloutLineToPart()

QgsGeometry QgsCallout::calloutLineToPart	(	const QgsGeometry &	labelGeometry,
		const QgsAbstractGeometry *	partGeometry,
		QgsRenderContext &	context,
		const QgsCalloutContext &	calloutContext,
		bool &	pinned
	)		const

protected

Calculates the direct line from a label geometry to an anchor geometry part, respecting the various callout settings which influence how the callout end should be placed in the anchor geometry.

Returns a null geometry if the callout line cannot be calculated.

The pinned argument will be set to true if the callout anchor point is pinned (manually placed).

Since: QGIS 3.20

Definition at line 428 of file qgscallout.cpp.

◆ clone()

virtual QgsCallout * QgsCallout::clone ( ) const

pure virtual

Duplicates a callout by creating a deep copy of the callout.

Caller takes ownership of the returned object.

Implemented in QgsSimpleLineCallout, QgsManhattanLineCallout, QgsCurvedLineCallout, and QgsBalloonCallout.

◆ containsAdvancedEffects()

bool QgsCallout::containsAdvancedEffects ( ) const

Returns true if the callout requires advanced effects such as blend modes, which require output in raster formats to be fully respected.

Since: QGIS 3.20

Definition at line 134 of file qgscallout.cpp.

◆ dataDefinedProperties() [1/2]

QgsPropertyCollection & QgsCallout::dataDefinedProperties ( )

inline

Returns a reference to the callout's property collection, used for data defined overrides.

See also: setDataDefinedProperties()

Definition at line 334 of file qgscallout.h.

◆ dataDefinedProperties() [2/2]

const QgsPropertyCollection & QgsCallout::dataDefinedProperties ( ) const

inline

Returns a reference to the callout's property collection, used for data defined overrides.

See also: setDataDefinedProperties(); Property

Note: not available in Python bindings

Definition at line 342 of file qgscallout.h.

◆ decodeAnchorPoint()

QgsCallout::AnchorPoint QgsCallout::decodeAnchorPoint	(	const QString &	name,
		bool *	ok = `nullptr`
	)

static

Attempts to decode a string representation of an anchor point name to the corresponding anchor point.

Parameters

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

Returns: decoded name

See also: encodeAnchorPoint()

Definition at line 204 of file qgscallout.cpp.

◆ decodeLabelAnchorPoint()

QgsCallout::LabelAnchorPoint QgsCallout::decodeLabelAnchorPoint	(	const QString &	name,
		bool *	ok = `nullptr`
	)

static

Attempts to decode a string representation of a label anchor point name to the corresponding anchor point.

Parameters

name	encoded label anchor point name
ok	if specified, will be set to `true` if the anchor point was successfully decoded

Returns: decoded name

See also: encodeLabelAnchorPoint()

Since: QGIS 3.14

Definition at line 269 of file qgscallout.cpp.

◆ draw()

virtual void QgsCallout::draw	(	QgsRenderContext &	context,
		const QRectF &	bodyBoundingBox,
		const double	angle,
		const QgsGeometry &	anchor,
		QgsCalloutContext &	calloutContext
	)

protectedpure virtual

Performs the actual rendering of the callout implementation onto the specified render context.

The bodyBoundingBox argument gives the desired size and position of the body of the callout (e.g. the actual label geometry). The angle argument specifies the rotation of the callout body (in degrees clockwise from horizontal). It is assumed that angle rotation specified via angle is applied around the center of rect.

The anchor argument dictates the geometry which the callout should connect to. Depending on the callout subclass and anchor geometry type, the actual shape of the rendered callout may vary. E.g. a subclass may prefer to attach to the centroid of the anchor, while another subclass may prefer to attach to the closest point on anchor instead.

Both rect and anchor are specified in painter coordinates (i.e. pixels).

The calloutContext argument is used to specify additional contextual information about how a callout is being rendered.

Implemented in QgsSimpleLineCallout, and QgsBalloonCallout.

◆ drawOrder()

QgsCallout::DrawOrder QgsCallout::drawOrder ( ) const

virtual

Returns the desired drawing order (stacking) to use while rendering this callout.

The default order is QgsCallout::OrderBelowIndividualLabels.

Definition at line 145 of file qgscallout.cpp.

◆ enabled()

bool QgsCallout::enabled ( ) const

inline

Returns true if the the callout is enabled.

See also: setEnabled()

Definition at line 322 of file qgscallout.h.

◆ encodeAnchorPoint()

QString QgsCallout::encodeAnchorPoint ( AnchorPoint anchor )

static

Encodes an anchor point to its string representation.

Returns: encoded string

See also: decodeAnchorPoint()

Definition at line 224 of file qgscallout.cpp.

◆ encodeLabelAnchorPoint()

QString QgsCallout::encodeLabelAnchorPoint ( QgsCallout::LabelAnchorPoint anchor )

static

Encodes a label anchor point to its string representation.

Returns: encoded string

See also: decodeLabelAnchorPoint()

Since: QGIS 3.14

Definition at line 240 of file qgscallout.cpp.

◆ labelAnchorGeometry()

QgsGeometry QgsCallout::labelAnchorGeometry	(	const QRectF &	bodyBoundingBox,
		const double	angle,
		LabelAnchorPoint	anchor
	)		const

protected

Returns the anchor point geometry for a label with the given bounding box and anchor point mode.

Deprecated:: QGIS 3.20. Use calloutLabelPoint() instead.

Definition at line 301 of file qgscallout.cpp.

◆ labelAnchorPoint()

LabelAnchorPoint QgsCallout::labelAnchorPoint ( ) const

inline

Returns the label's anchor point position.

See also: setLabelAnchorPoint()

Since: QGIS 3.14

Definition at line 397 of file qgscallout.h.

◆ properties()

QVariantMap QgsCallout::properties ( const QgsReadWriteContext & context ) const

virtual

Returns the properties describing the callout encoded in a string format.

Subclasses must ensure that they include the base class' properties() in their returned value.

See also: readProperties(); saveProperties()

Reimplemented in QgsSimpleLineCallout, QgsCurvedLineCallout, and QgsBalloonCallout.

Definition at line 81 of file qgscallout.cpp.

◆ propertyDefinitions()

QgsPropertiesDefinition QgsCallout::propertyDefinitions ( )

static

Returns the definitions for data defined properties available for use in callouts.

Definition at line 194 of file qgscallout.cpp.

◆ readProperties()

void QgsCallout::readProperties	(	const QVariantMap &	props,
		const QgsReadWriteContext &	context
	)

virtual

Reads a string map of an callout's properties and restores the callout to the state described by the properties map.

Subclasses must ensure that they call the base class' readProperties() method.

See also: properties()

Reimplemented in QgsSimpleLineCallout, and QgsBalloonCallout.

Definition at line 92 of file qgscallout.cpp.

◆ referencedFields()

QSet< QString > QgsCallout::referencedFields ( const QgsRenderContext & context ) const

virtual

Returns the set of attributes referenced by the callout.

This includes attributes required by any data defined properties associated with the callout.

Warning: This must only be called after a corresponding call to startRender() with the same render context.

Reimplemented in QgsSimpleLineCallout, and QgsBalloonCallout.

Definition at line 139 of file qgscallout.cpp.

◆ render()

void QgsCallout::render	(	QgsRenderContext &	context,
		const QRectF &	rect,
		const double	angle,
		const QgsGeometry &	anchor,
		QgsCalloutContext &	calloutContext
	)

Renders the callout onto the specified render context.

The rect argument gives the desired size and position of the body of the callout (e.g. the actual label geometry). The angle argument specifies the rotation of the callout body (in degrees clockwise from horizontal). It is assumed that angle rotation specified via angle is applied around the center of rect.

The anchor argument dictates the geometry which the callout should connect to. Depending on the callout subclass and anchor geometry type, the actual shape of the rendered callout may vary. E.g. a subclass may prefer to attach to the centroid of the anchor, while another subclass may prefer to attach to the closest point on anchor instead.

Both rect and anchor must be specified in painter coordinates (i.e. pixels).

The calloutContext argument is used to specify additional contextual information about how a callout is being rendered.

Warning: A prior call to startRender() must have been made before calling this method, and after all render() operations are complete a call to stopRender() must be made.

Definition at line 150 of file qgscallout.cpp.

◆ restoreProperties()

void QgsCallout::restoreProperties	(	const QDomElement &	element,
		const QgsReadWriteContext &	context
	)

virtual

Restores the callout's properties from a DOM element.

The default behavior is the read the DOM contents and call readProperties() on the subclass.

See also: readProperties()

Definition at line 119 of file qgscallout.cpp.

◆ saveProperties()

bool QgsCallout::saveProperties	(	QDomDocument &	doc,
		QDomElement &	element,
		const QgsReadWriteContext &	context
	)		const

virtual

Saves the current state of the callout to a DOM element.

The default behavior is to save the properties string map returned by properties().

Returns: true if save was successful

See also: readProperties()

Definition at line 102 of file qgscallout.cpp.

◆ setAnchorPoint()

void QgsCallout::setAnchorPoint ( AnchorPoint anchor )

inline

Sets the feature's anchor point position.

See also: anchorPoint()

Definition at line 371 of file qgscallout.h.

◆ setBlendMode()

void QgsCallout::setBlendMode ( QPainter::CompositionMode mode )

inline

Sets the blending mode used for drawing callouts.

See also: blendMode()

Since: QGIS 3.20

Definition at line 438 of file qgscallout.h.

◆ setDataDefinedProperties()

void QgsCallout::setDataDefinedProperties ( const QgsPropertyCollection & collection )

inline

Sets the callout's property collection, used for data defined overrides.

Any existing properties will be discarded.

See also: dataDefinedProperties(); Property

Definition at line 352 of file qgscallout.h.

◆ setEnabled()

void QgsCallout::setEnabled ( bool enabled )

Sets whether the callout is enabled.

See also: enabled()

Definition at line 189 of file qgscallout.cpp.

◆ setLabelAnchorPoint()

void QgsCallout::setLabelAnchorPoint ( LabelAnchorPoint anchor )

inline

Sets the label's anchor point position.

See also: labelAnchorPoint()

Since: QGIS 3.14

Definition at line 405 of file qgscallout.h.

◆ startRender()

void QgsCallout::startRender ( QgsRenderContext & context )

virtual

Prepares the callout for rendering on the specified render context.

Warning: This MUST be called prior to calling render() on the callout, and must always be accompanied by a corresponding call to stopRender().

See also: stopRender()

Reimplemented in QgsSimpleLineCallout, and QgsBalloonCallout.

Definition at line 125 of file qgscallout.cpp.

◆ stopRender()

void QgsCallout::stopRender ( QgsRenderContext & context )

virtual

Finalises the callout after a set of rendering operations on the specified render context.

Warning: This MUST be called after to after render() operations on the callout, and must always be accompanied by a corresponding prior call to startRender().

See also: startRender()

Reimplemented in QgsSimpleLineCallout, and QgsBalloonCallout.

Definition at line 129 of file qgscallout.cpp.

◆ type()

virtual QString QgsCallout::type ( ) const

pure virtual

Returns a unique string representing the callout type.

Implemented in QgsSimpleLineCallout, QgsManhattanLineCallout, QgsCurvedLineCallout, and QgsBalloonCallout.

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

/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/callouts/qgscallout.h
/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/callouts/qgscallout.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ AnchorPoint

◆ DrawOrder

◆ LabelAnchorPoint

◆ Property

Constructor & Destructor Documentation

◆ QgsCallout()

◆ ~QgsCallout()

Member Function Documentation

◆ anchorPoint()

◆ blendMode()

◆ calloutLabelPoint()

◆ calloutLineToPart()

◆ clone()

◆ containsAdvancedEffects()

◆ dataDefinedProperties() [1/2]

◆ dataDefinedProperties() [2/2]

◆ decodeAnchorPoint()

◆ decodeLabelAnchorPoint()

◆ draw()

◆ drawOrder()

◆ enabled()

◆ encodeAnchorPoint()

◆ encodeLabelAnchorPoint()

◆ labelAnchorGeometry()

◆ labelAnchorPoint()

◆ properties()

◆ propertyDefinitions()

◆ readProperties()

◆ referencedFields()

◆ render()

◆ restoreProperties()

◆ saveProperties()

◆ setAnchorPoint()

◆ setBlendMode()

◆ setDataDefinedProperties()

◆ setEnabled()

◆ setLabelAnchorPoint()

◆ startRender()

◆ stopRender()

◆ type()