A cartoon talking bubble callout style. More...

#include <qgscallout.h>

Inheritance diagram for QgsBalloonCallout:

Public Member Functions
	QgsBalloonCallout ()

	QgsBalloonCallout (const QgsBalloonCallout &other)
	Copy constructor. More...

	~QgsBalloonCallout () override

QgsBalloonCallout *	clone () const override
	Duplicates a callout by creating a deep copy of the callout. More...

double	cornerRadius () const
	Returns the corner radius of the balloon shapes. More...

const QgsMapUnitScale &	cornerRadiusMapUnitScale () const
	Returns the map unit scale for the corner radius. More...

Qgis::RenderUnit	cornerRadiusUnit () const
	Returns the units for the corner radius. More...

QgsFillSymbol *	fillSymbol ()
	Returns the fill symbol used to render the callout. More...

const QgsMargins &	margins () const
	Returns the margins between the outside of the callout frame and the label's bounding rectangle. More...

Qgis::RenderUnit	marginsUnit () const
	Returns the units for the margins between the outside of the callout frame and the label's bounding rectangle. More...

double	offsetFromAnchor () const
	Returns the offset distance from the anchor point at which to start the line. More...

const QgsMapUnitScale &	offsetFromAnchorMapUnitScale () const
	Returns the map unit scale for the offset from anchor. More...

Qgis::RenderUnit	offsetFromAnchorUnit () const
	Returns the units for the offset from anchor point. More...

QgsBalloonCallout &	operator= (const QgsBalloonCallout &)=delete

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

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

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

void	setCornerRadius (double radius)
	Sets the radius of the corners for the balloon shapes. More...

void	setCornerRadiusMapUnitScale (const QgsMapUnitScale &scale)
	Sets the map unit scale for the corner radius. More...

void	setCornerRadiusUnit (Qgis::RenderUnit unit)
	Sets the unit for the corner radius. More...

void	setFillSymbol (QgsFillSymbol *symbol)
	Sets the fill symbol used to render the callout. More...

void	setMargins (const QgsMargins &margins)
	Sets the margins between the outside of the callout frame and the label's bounding rectangle. More...

void	setMarginsUnit (Qgis::RenderUnit unit)
	Sets the unit for the margins between the outside of the callout frame and the label's bounding rectangle. More...

void	setOffsetFromAnchor (double distance)
	Sets the offset distance from the anchor point at which to start the line. More...

void	setOffsetFromAnchorMapUnitScale (const QgsMapUnitScale &scale)
	Sets the map unit scale for the offset from anchor. More...

void	setOffsetFromAnchorUnit (Qgis::RenderUnit unit)
	Sets the unit for the offset from anchor distance. More...

void	setWedgeWidth (double width)
	Sets the width of the wedge shape at the side it connects with the label. More...

void	setWedgeWidthMapUnitScale (const QgsMapUnitScale &scale)
	Sets the map unit scale for the wedge width. More...

void	setWedgeWidthUnit (Qgis::RenderUnit unit)
	Sets the unit for the wedge width. More...

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

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

QString	type () const override
	Returns a unique string representing the callout type. More...

double	wedgeWidth () const
	Returns the width of the wedge shape at the side it connects with the label. More...

const QgsMapUnitScale &	wedgeWidthMapUnitScale () const
	Returns the map unit scale for the wedge width. More...

Qgis::RenderUnit	wedgeWidthUnit () const
	Returns the units for the wedge width. More...

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

virtual	~QgsCallout ()=default

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

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

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

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. 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, const 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	setBlendMode (QPainter::CompositionMode mode)
	Sets the blending mode used for drawing callouts. 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 *	create (const QVariantMap &properties=QVariantMap(), const QgsReadWriteContext &context=QgsReadWriteContext())
	Creates a new QgsBalloonCallout, using the settings serialized in the properties map (corresponding to the output from QgsBalloonCallout::properties() ). More...

Static Public Member Functions inherited from QgsCallout
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
void	draw (QgsRenderContext &context, const QRectF &bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCallout::QgsCalloutContext &calloutContext) override
	Performs the actual rendering of the callout implementation onto the specified render context. More...

Protected Member Functions inherited from QgsCallout
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. More...

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

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

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

Additional Inherited Members
Public Types inherited from QgsCallout
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...

Detailed Description

A cartoon talking bubble callout style.

Since: QGIS 3.20

Definition at line 892 of file qgscallout.h.

Constructor & Destructor Documentation

◆ QgsBalloonCallout() [1/2]

QgsBalloonCallout::QgsBalloonCallout ( )

Definition at line 1035 of file qgscallout.cpp.

◆ ~QgsBalloonCallout()

QgsBalloonCallout::~QgsBalloonCallout ( )

overridedefault

◆ QgsBalloonCallout() [2/2]

QgsBalloonCallout::QgsBalloonCallout ( const QgsBalloonCallout & other )

Copy constructor.

Definition at line 1042 of file qgscallout.cpp.

Member Function Documentation

◆ clone()

QgsBalloonCallout * QgsBalloonCallout::clone ( ) const

overridevirtual

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

Caller takes ownership of the returned object.

Implements QgsCallout.

Definition at line 1072 of file qgscallout.cpp.

◆ cornerRadius()

double QgsBalloonCallout::cornerRadius ( ) const

inline

Returns the corner radius of the balloon shapes.

Units are specified through wedgeWidthUnit().

See also: setCornerRadius(); cornerRadiusUnit()

Definition at line 1086 of file qgscallout.h.

◆ cornerRadiusMapUnitScale()

const QgsMapUnitScale & QgsBalloonCallout::cornerRadiusMapUnitScale ( ) const

inline

Returns the map unit scale for the corner radius.

See also: setCornerRadiusMapUnitScale(); cornerRadiusUnit(); cornerRadius()

Definition at line 1130 of file qgscallout.h.

◆ cornerRadiusUnit()

Qgis::RenderUnit QgsBalloonCallout::cornerRadiusUnit ( ) const

inline

Returns the units for the corner radius.

See also: setCornerRadiusUnit(); cornerRadius()

Definition at line 1112 of file qgscallout.h.

◆ create()

QgsCallout * QgsBalloonCallout::create	(	const QVariantMap &	properties = `QVariantMap()`,
		const QgsReadWriteContext &	context = `QgsReadWriteContext()`
	)

static

Creates a new QgsBalloonCallout, using the settings serialized in the properties map (corresponding to the output from QgsBalloonCallout::properties() ).

Definition at line 1060 of file qgscallout.cpp.

◆ draw()

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

overrideprotectedvirtual

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.

Implements QgsCallout.

Definition at line 1164 of file qgscallout.cpp.

◆ fillSymbol()

QgsFillSymbol * QgsBalloonCallout::fillSymbol ( )

Returns the fill symbol used to render the callout.

Ownership is not transferred.

See also: setFillSymbol()

Definition at line 1154 of file qgscallout.cpp.

◆ margins()

const QgsMargins & QgsBalloonCallout::margins ( ) const

inline

Returns the margins between the outside of the callout frame and the label's bounding rectangle.

Units are retrieved via marginsUnit()

Note: Negative margins are acceptable.

See also: setMargins(); marginsUnit()

Definition at line 994 of file qgscallout.h.

◆ marginsUnit()

Qgis::RenderUnit QgsBalloonCallout::marginsUnit ( ) const

inline

Returns the units for the margins between the outside of the callout frame and the label's bounding rectangle.

See also: setMarginsUnit(); margins()

Definition at line 1022 of file qgscallout.h.

◆ offsetFromAnchor()

double QgsBalloonCallout::offsetFromAnchor ( ) const

inline

Returns the offset distance from the anchor point at which to start the line.

Units are specified through offsetFromAnchorUnit().

See also: setOffsetFromAnchor(); offsetFromAnchorUnit()

Definition at line 945 of file qgscallout.h.

◆ offsetFromAnchorMapUnitScale()

const QgsMapUnitScale & QgsBalloonCallout::offsetFromAnchorMapUnitScale ( ) const

inline

Returns the map unit scale for the offset from anchor.

See also: setOffsetFromAnchorMapUnitScale(); offsetFromAnchorUnit(); offsetFromAnchor()

Definition at line 982 of file qgscallout.h.

◆ offsetFromAnchorUnit()

Qgis::RenderUnit QgsBalloonCallout::offsetFromAnchorUnit ( ) const

inline

Returns the units for the offset from anchor point.

See also: setOffsetFromAnchorUnit(); offsetFromAnchor()

Definition at line 966 of file qgscallout.h.

◆ operator=()

QgsBalloonCallout & QgsBalloonCallout::operator= ( const QgsBalloonCallout & )

delete

◆ properties()

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

overridevirtual

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 from QgsCallout.

Definition at line 1077 of file qgscallout.cpp.

◆ readProperties()

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

overridevirtual

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 from QgsCallout.

Definition at line 1104 of file qgscallout.cpp.

◆ referencedFields()

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

overridevirtual

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 from QgsCallout.

Definition at line 1146 of file qgscallout.cpp.

◆ setCornerRadius()

void QgsBalloonCallout::setCornerRadius ( double radius )

inline

Sets the radius of the corners for the balloon shapes.

Units are specified through setCornerRadiusUnit().

See also: cornerRadius(); setCornerRadiusUnit()

Definition at line 1096 of file qgscallout.h.

◆ setCornerRadiusMapUnitScale()

void QgsBalloonCallout::setCornerRadiusMapUnitScale ( const QgsMapUnitScale & scale )

inline

Sets the map unit scale for the corner radius.

See also: cornerRadiusMapUnitScale(); setCornerRadiusUnit(); setCornerRadius()

Definition at line 1121 of file qgscallout.h.

◆ setCornerRadiusUnit()

void QgsBalloonCallout::setCornerRadiusUnit ( Qgis::RenderUnit unit )

inline

Sets the unit for the corner radius.

See also: cornerRadiusUnit(); setCornerRadius()

Definition at line 1104 of file qgscallout.h.

◆ setFillSymbol()

void QgsBalloonCallout::setFillSymbol ( QgsFillSymbol * symbol )

Sets the fill symbol used to render the callout.

Ownership of symbol is transferred to the callout.

See also: fillSymbol()

Definition at line 1159 of file qgscallout.cpp.

◆ setMargins()

void QgsBalloonCallout::setMargins ( const QgsMargins & margins )

inline

Sets the margins between the outside of the callout frame and the label's bounding rectangle.

Units are set via setMarginsUnit()

Note: Negative margins are acceptable.

See also: margins(); setMarginsUnit()

Definition at line 1006 of file qgscallout.h.

◆ setMarginsUnit()

void QgsBalloonCallout::setMarginsUnit ( Qgis::RenderUnit unit )

inline

Sets the unit for the margins between the outside of the callout frame and the label's bounding rectangle.

See also: margins(); marginsUnit()

Definition at line 1014 of file qgscallout.h.

◆ setOffsetFromAnchor()

void QgsBalloonCallout::setOffsetFromAnchor ( double distance )

inline

Sets the offset distance from the anchor point at which to start the line.

Units are specified through setOffsetFromAnchorUnit().

See also: offsetFromAnchor(); setOffsetFromAnchorUnit()

Definition at line 952 of file qgscallout.h.

◆ setOffsetFromAnchorMapUnitScale()

void QgsBalloonCallout::setOffsetFromAnchorMapUnitScale ( const QgsMapUnitScale & scale )

inline

Sets the map unit scale for the offset from anchor.

See also: offsetFromAnchorMapUnitScale(); setOffsetFromAnchorUnit(); setOffsetFromAnchor()

Definition at line 974 of file qgscallout.h.

◆ setOffsetFromAnchorUnit()

void QgsBalloonCallout::setOffsetFromAnchorUnit ( Qgis::RenderUnit unit )

inline

Sets the unit for the offset from anchor distance.

See also: offsetFromAnchor(); setOffsetFromAnchor()

Definition at line 959 of file qgscallout.h.

◆ setWedgeWidth()

void QgsBalloonCallout::setWedgeWidth ( double width )

inline

Sets the width of the wedge shape at the side it connects with the label.

Units are specified through setWedgeWidthUnit().

See also: wedgeWidth(); setWedgeWidthUnit()

Definition at line 1042 of file qgscallout.h.

◆ setWedgeWidthMapUnitScale()

void QgsBalloonCallout::setWedgeWidthMapUnitScale ( const QgsMapUnitScale & scale )

inline

Sets the map unit scale for the wedge width.

See also: wedgeWidthMapUnitScale(); setWedgeWidthUnit(); setWedgeWidth()

Definition at line 1067 of file qgscallout.h.

◆ setWedgeWidthUnit()

void QgsBalloonCallout::setWedgeWidthUnit ( Qgis::RenderUnit unit )

inline

Sets the unit for the wedge width.

See also: wedgeWidthUnit(); setWedgeWidth()

Definition at line 1050 of file qgscallout.h.

◆ startRender()

void QgsBalloonCallout::startRender ( QgsRenderContext & context )

overridevirtual

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 from QgsCallout.

Definition at line 1132 of file qgscallout.cpp.

◆ stopRender()

void QgsBalloonCallout::stopRender ( QgsRenderContext & context )

overridevirtual

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 from QgsCallout.

Definition at line 1139 of file qgscallout.cpp.

◆ type()

QString QgsBalloonCallout::type ( ) const

overridevirtual

Returns a unique string representing the callout type.

Implements QgsCallout.

Definition at line 1067 of file qgscallout.cpp.

◆ wedgeWidth()

double QgsBalloonCallout::wedgeWidth ( ) const

inline

Returns the width of the wedge shape at the side it connects with the label.

Units are specified through wedgeWidthUnit().

See also: setWedgeWidth(); wedgeWidthUnit()

Definition at line 1032 of file qgscallout.h.

◆ wedgeWidthMapUnitScale()

const QgsMapUnitScale & QgsBalloonCallout::wedgeWidthMapUnitScale ( ) const

inline

Returns the map unit scale for the wedge width.

See also: setWedgeWidthMapUnitScale(); wedgeWidthUnit(); wedgeWidth()

Definition at line 1076 of file qgscallout.h.

◆ wedgeWidthUnit()

Qgis::RenderUnit QgsBalloonCallout::wedgeWidthUnit ( ) const

inline

Returns the units for the wedge width.

See also: setWedgeWidthUnit(); wedgeWidth()

Definition at line 1058 of file qgscallout.h.

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

/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/callouts/qgscallout.h
/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/callouts/qgscallout.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QgsBalloonCallout() [1/2]

◆ ~QgsBalloonCallout()

◆ QgsBalloonCallout() [2/2]

Member Function Documentation

◆ clone()

◆ cornerRadius()

◆ cornerRadiusMapUnitScale()

◆ cornerRadiusUnit()

◆ create()

◆ draw()

◆ fillSymbol()

◆ margins()

◆ marginsUnit()

◆ offsetFromAnchor()

◆ offsetFromAnchorMapUnitScale()

◆ offsetFromAnchorUnit()

◆ operator=()

◆ properties()

◆ readProperties()

◆ referencedFields()

◆ setCornerRadius()

◆ setCornerRadiusMapUnitScale()

◆ setCornerRadiusUnit()

◆ setFillSymbol()

◆ setMargins()

◆ setMarginsUnit()

◆ setOffsetFromAnchor()

◆ setOffsetFromAnchorMapUnitScale()

◆ setOffsetFromAnchorUnit()

◆ setWedgeWidth()

◆ setWedgeWidthMapUnitScale()

◆ setWedgeWidthUnit()

◆ startRender()

◆ stopRender()

◆ type()

◆ wedgeWidth()

◆ wedgeWidthMapUnitScale()

◆ wedgeWidthUnit()