QGIS API Documentation  3.14.0-Pi (9f7028fd23)
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  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 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...
 
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

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

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

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

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