QGIS API Documentation  3.13.0-Master (7f54853aae)
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

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  Property {
  MinimumCalloutLength, OffsetFromAnchor, OffsetFromLabel, DrawCalloutToAllParts,
  AnchorPointPosition
}
 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 QgsCalloutclone () const =0
 Duplicates a callout by creating a deep copy of the callout. 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...
 
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...
 
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 QString encodeAnchorPoint (AnchorPoint anchor)
 Encodes an 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...
 

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

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

Definition at line 69 of file qgscallout.h.

Constructor & Destructor Documentation

◆ QgsCallout()

QgsCallout::QgsCallout ( )

Constructor for QgsCallout.

Definition at line 46 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 270 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 240 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 248 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 151 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 104 of file qgscallout.cpp.

◆ enabled()

bool QgsCallout::enabled ( ) const
inline

Returns true if the the callout is enabled.

See also
setEnabled()

Definition at line 228 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 171 of file qgscallout.cpp.

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

◆ propertyDefinitions()

QgsPropertiesDefinition QgsCallout::propertyDefinitions ( )
static

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

Definition at line 141 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 59 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 98 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 109 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 83 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 66 of file qgscallout.cpp.

◆ setAnchorPoint()

void QgsCallout::setAnchorPoint ( AnchorPoint  anchor)
inline

Sets the feature's anchor point position.

See also
anchorPoint()

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

◆ setEnabled()

void QgsCallout::setEnabled ( bool  enabled)

Sets whether the callout is enabled.

See also
enabled()

Definition at line 136 of file qgscallout.cpp.

◆ 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 89 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 93 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: