QGIS API Documentation  3.21.0-Master (5b68dc587e)
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QgsCallout Class Referenceabstract

Abstract base class for callout renderers. More...

#include <qgscallout.h>

Inheritance diagram for QgsCallout:
Inheritance graph
[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  Property {
  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. 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 QgsCalloutclone () 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...
 
QgsPropertyCollectiondataDefinedProperties ()
 Returns a reference to the callout's property collection, used for data defined overrides. More...
 
const QgsPropertyCollectiondataDefinedProperties () 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::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

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

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 52 of file qgscallout.h.

Member Enumeration Documentation

◆ 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 111 of file qgscallout.h.

◆ 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 104 of file qgscallout.h.

◆ 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 123 of file qgscallout.h.

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

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 83 of file qgscallout.h.

Constructor & Destructor Documentation

◆ QgsCallout()

QgsCallout::QgsCallout ( )

Constructor for QgsCallout.

Definition at line 75 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 361 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 428 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 349 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 426 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 QgsBalloonCallout, QgsCurvedLineCallout, QgsManhattanLineCallout, and QgsSimpleLineCallout.

◆ 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 132 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 331 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 339 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
nameencoded anchor point name
okif specified, will be set to true if the anchor point was successfully decoded
Returns
decoded name
See also
encodeAnchorPoint()

Definition at line 202 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
nameencoded label anchor point name
okif 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 267 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 QgsBalloonCallout, 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 143 of file qgscallout.cpp.

◆ enabled()

bool QgsCallout::enabled ( ) const
inline

Returns true if the the callout is enabled.

See also
setEnabled()

Definition at line 319 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 222 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 238 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 299 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 394 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 QgsBalloonCallout, QgsCurvedLineCallout, and QgsSimpleLineCallout.

Definition at line 79 of file qgscallout.cpp.

◆ propertyDefinitions()

QgsPropertiesDefinition QgsCallout::propertyDefinitions ( )
static

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

Definition at line 192 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 QgsBalloonCallout, and QgsSimpleLineCallout.

Definition at line 90 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 QgsBalloonCallout, and QgsSimpleLineCallout.

Definition at line 137 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 148 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 117 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 100 of file qgscallout.cpp.

◆ setAnchorPoint()

void QgsCallout::setAnchorPoint ( AnchorPoint  anchor)
inline

Sets the feature's anchor point position.

See also
anchorPoint()

Definition at line 368 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 435 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 349 of file qgscallout.h.

◆ setEnabled()

void QgsCallout::setEnabled ( bool  enabled)

Sets whether the callout is enabled.

See also
enabled()

Definition at line 187 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 402 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 QgsBalloonCallout, and QgsSimpleLineCallout.

Definition at line 123 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 QgsBalloonCallout, and QgsSimpleLineCallout.

Definition at line 127 of file qgscallout.cpp.

◆ type()

virtual QString QgsCallout::type ( ) const
pure virtual

Returns a unique string representing the callout type.

Implemented in QgsBalloonCallout, QgsCurvedLineCallout, QgsManhattanLineCallout, and QgsSimpleLineCallout.


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