Abstract base class for callout renderers. More...

#include <qgscallout.h>

Inheritance diagram for QgsCallout:

Classes
struct	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	Property { MinimumCalloutLength, OffsetFromAnchor, OffsetFromLabel, DrawCalloutToAllParts, AnchorPointPosition, LabelAnchorPointPosition }
	Data definable properties. More...

Public Member Functions
	QgsCallout ()
	Constructor for QgsCallout. More...

virtual	~QgsCallout ()=default

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

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

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

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

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

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

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

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

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. More...

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

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

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

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

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

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

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

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

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

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

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

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. More...

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. More...

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

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

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

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

QgsGeometry	labelAnchorGeometry (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. More...

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 46 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 87 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 80 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 99 of file qgscallout.h.

◆ Property

enum QgsCallout::Property

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.

Definition at line 69 of file qgscallout.h.

Constructor & Destructor Documentation

◆ QgsCallout()

QgsCallout::QgsCallout ( )

Constructor for QgsCallout.

Definition at line 53 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 289 of file qgscallout.h.

◆ 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 QgsManhattanLineCallout, and QgsSimpleLineCallout.

◆ 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 259 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 267 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 160 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 225 of file qgscallout.cpp.

◆ draw()

virtual void QgsCallout::draw	(	QgsRenderContext &	context,
		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 QgsManhattanLineCallout, and QgsSimpleLineCallout.

◆ 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 113 of file qgscallout.cpp.

◆ enabled()

bool QgsCallout::enabled ( ) const

inline

Returns true if the the callout is enabled.

See also: setEnabled()

Definition at line 247 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 180 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 196 of file qgscallout.cpp.

◆ labelAnchorGeometry()

QgsGeometry QgsCallout::labelAnchorGeometry	(	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.

Since: QGIS 3.14

Definition at line 257 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 322 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.

Definition at line 57 of file qgscallout.cpp.

◆ propertyDefinitions()

QgsPropertiesDefinition QgsCallout::propertyDefinitions ( )

static

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

Definition at line 150 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.

Definition at line 67 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.

Definition at line 107 of file qgscallout.cpp.

◆ render()

void QgsCallout::render	(	QgsRenderContext &	context,
		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 118 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 92 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 75 of file qgscallout.cpp.

◆ setAnchorPoint()

void QgsCallout::setAnchorPoint ( AnchorPoint anchor )

inline

Sets the feature's anchor point position.

See also: anchorPoint()

Definition at line 296 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 277 of file qgscallout.h.

◆ setEnabled()

void QgsCallout::setEnabled ( bool enabled )

Sets whether the callout is enabled.

See also: enabled()

Definition at line 145 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 330 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.

Definition at line 98 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.

Definition at line 102 of file qgscallout.cpp.

◆ type()

virtual QString QgsCallout::type ( ) const

pure virtual

Returns a unique string representing the callout type.

Implemented in QgsManhattanLineCallout, and QgsSimpleLineCallout.

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

/build/qgis-3.16.0+99unstable/src/core/callouts/qgscallout.h
/build/qgis-3.16.0+99unstable/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()

◆ clone()

◆ dataDefinedProperties() [1/2]

◆ dataDefinedProperties() [2/2]

◆ decodeAnchorPoint()

◆ decodeLabelAnchorPoint()

◆ draw()

◆ drawOrder()

◆ enabled()

◆ encodeAnchorPoint()

◆ encodeLabelAnchorPoint()

◆ labelAnchorGeometry()

◆ labelAnchorPoint()

◆ properties()

◆ propertyDefinitions()

◆ readProperties()

◆ referencedFields()

◆ render()

◆ restoreProperties()

◆ saveProperties()

◆ setAnchorPoint()

◆ setDataDefinedProperties()

◆ setEnabled()

◆ setLabelAnchorPoint()

◆ startRender()

◆ stopRender()

◆ type()