Class: QgsCallout

class qgis.core.QgsCallout

Bases: sip.wrapper

Constructor for QgsCallout.

QgsCallout(QgsCallout)

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.

Methods

anchorPoint

Returns the feature’s anchor point position.

clone

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

dataDefinedProperties

Returns a reference to the callout’s property collection, used for data defined overrides.

decodeAnchorPoint

Attempts to decode a string representation of an anchor point name to the corresponding anchor point.

decodeLabelAnchorPoint

Attempts to decode a string representation of a label anchor point name to the corresponding anchor point.

draw

Performs the actual rendering of the callout implementation onto the specified render context.

drawOrder

Returns the desired drawing order (stacking) to use while rendering this callout.

enabled

Returns True if the the callout is enabled.

encodeAnchorPoint

Encodes an anchor point to its string representation.

encodeLabelAnchorPoint

Encodes a label anchor point to its string representation.

labelAnchorGeometry

Returns the anchor point geometry for a label with the given bounding box and anchor point mode.

labelAnchorPoint

Returns the label’s anchor point position.

properties

Returns the properties describing the callout encoded in a string format.

propertyDefinitions

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

readProperties

Reads a string map of an callout’s properties and restores the callout to the state described by the properties map.

referencedFields

Returns the set of attributes referenced by the callout.

render

Renders the callout onto the specified render context.

restoreProperties

Restores the callout’s properties from a DOM element.

saveProperties

Saves the current state of the callout to a DOM element.

setAnchorPoint

Sets the feature’s anchor point position.

setDataDefinedProperties

Sets the callout’s property collection, used for data defined overrides.

setEnabled

Sets whether the callout is enabled.

setLabelAnchorPoint

Sets the label’s anchor point position.

startRender

Prepares the callout for rendering on the specified render context.

stopRender

Finalises the callout after a set of rendering operations on the specified render context.

type

Returns a unique string representing the callout type.

Attributes

AnchorPointPosition

Centroid

DrawCalloutToAllParts

LabelAnchorPointPosition

LabelBottomLeft

LabelBottomMiddle

LabelBottomRight

LabelCentroid

LabelMiddleLeft

LabelMiddleRight

LabelPointOnExterior

LabelTopLeft

LabelTopMiddle

LabelTopRight

MinimumCalloutLength

OffsetFromAnchor

OffsetFromLabel

OrderBelowAllLabels

OrderBelowIndividualLabels

PointOnExterior

PointOnSurface

PoleOfInaccessibility

class AnchorPoint

Bases: int

AnchorPointPosition = 4
Centroid = 3
DrawCalloutToAllParts = 3
class DrawOrder

Bases: int

class LabelAnchorPoint

Bases: int

LabelAnchorPointPosition = 5
LabelBottomLeft = 7
LabelBottomMiddle = 8
LabelBottomRight = 9
LabelCentroid = 1
LabelMiddleLeft = 5
LabelMiddleRight = 6
LabelPointOnExterior = 0
LabelTopLeft = 2
LabelTopMiddle = 3
LabelTopRight = 4
MinimumCalloutLength = 0
OffsetFromAnchor = 1
OffsetFromLabel = 2
OrderBelowAllLabels = 0
OrderBelowIndividualLabels = 1
PointOnExterior = 1
PointOnSurface = 2
PoleOfInaccessibility = 0
class Property

Bases: int

class QgsCalloutContext
class QgsCalloutContext(QgsCallout.QgsCalloutContext)None

Bases: sip.wrapper

allFeaturePartsLabeled
anchorPoint(self)QgsCallout.AnchorPoint

Returns the feature’s anchor point position.

See also

setAnchorPoint()

Return type

QgsCallout.AnchorPoint

clone(self)QgsCallout

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

Caller takes ownership of the returned object.

Return type

QgsCallout

dataDefinedProperties(self)QgsPropertyCollection

Returns a reference to the callout’s property collection, used for data defined overrides.

Return type

QgsPropertyCollection

decodeAnchorPoint(name: str)Tuple[QgsCallout.AnchorPoint, bool]

Attempts to decode a string representation of an anchor point name to the corresponding anchor point.

Parameters
  • name (str) – encoded anchor point name

  • ok – if specified, will be set to True if the anchor point was successfully decoded

Return type

Tuple[QgsCallout.AnchorPoint, bool]

Returns

decoded name

decodeLabelAnchorPoint(name: str)Tuple[QgsCallout.LabelAnchorPoint, bool]

Attempts to decode a string representation of a label anchor point name to the corresponding anchor point.

Parameters
  • name (str) – encoded label anchor point name

  • ok – if specified, will be set to True if the anchor point was successfully decoded

Return type

Tuple[QgsCallout.LabelAnchorPoint, bool]

Returns

decoded name

New in version 3.14.

draw(self, context: QgsRenderContext, bodyBoundingBox: QRectF, angle: float, anchor: QgsGeometry, calloutContext: QgsCallout.QgsCalloutContext)

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.

Parameters
drawOrder(self)QgsCallout.DrawOrder

Returns the desired drawing order (stacking) to use while rendering this callout.

The default order is QgsCallout.OrderBelowIndividualLabels.

Return type

QgsCallout.DrawOrder

enabled(self)bool

Returns True if the the callout is enabled.

See also

setEnabled()

Return type

bool

encodeAnchorPoint(anchor: QgsCallout.AnchorPoint)str

Encodes an anchor point to its string representation.

Return type

str

Returns

encoded string

Parameters

anchor (QgsCallout.AnchorPoint) –

encodeLabelAnchorPoint(anchor: QgsCallout.LabelAnchorPoint)str

Encodes a label anchor point to its string representation.

Return type

str

Returns

encoded string

New in version 3.14.

Parameters

anchor (QgsCallout.LabelAnchorPoint) –

labelAnchorGeometry(self, bodyBoundingBox: QRectF, angle: float, anchor: QgsCallout.LabelAnchorPoint)QgsGeometry

Returns the anchor point geometry for a label with the given bounding box and anchor point mode.

New in version 3.14.

Parameters
Return type

QgsGeometry

labelAnchorPoint(self)QgsCallout.LabelAnchorPoint

Returns the label’s anchor point position.

New in version 3.14.

Return type

QgsCallout.LabelAnchorPoint

properties(self, context: QgsReadWriteContext)Dict[str, Any]

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()

See also

saveProperties()

Parameters

context (QgsReadWriteContext) –

Return type

Dict[str, Any]

propertyDefinitions()Dict[int, QgsPropertyDefinition]

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

Return type

Dict[int, QgsPropertyDefinition]

readProperties(self, props: Dict[str, Any], context: QgsReadWriteContext)

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()

Parameters
referencedFields(self, context: QgsRenderContext)Set[str]

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.

Parameters

context (QgsRenderContext) –

Return type

Set[str]

render(self, context: QgsRenderContext, rect: QRectF, angle: float, anchor: QgsGeometry, calloutContext: QgsCallout.QgsCalloutContext)

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.

Parameters
restoreProperties(self, element: QDomElement, context: QgsReadWriteContext)

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()

Parameters
saveProperties(self, doc: QDomDocument, element: QDomElement, context: QgsReadWriteContext)bool

Saves the current state of the callout to a DOM element. The default behavior is to save the properties string map returned by properties().

Return type

bool

Returns

True if save was successful

See also

readProperties()

Parameters
setAnchorPoint(self, anchor: QgsCallout.AnchorPoint)

Sets the feature’s anchor point position.

See also

anchorPoint()

Parameters

anchor (QgsCallout.AnchorPoint) –

setDataDefinedProperties(self, collection: QgsPropertyCollection)

Sets the callout’s property collection, used for data defined overrides.

Any existing properties will be discarded.

See also

Property

Parameters

collection (QgsPropertyCollection) –

setEnabled(self, enabled: bool)

Sets whether the callout is enabled.

See also

enabled()

Parameters

enabled (bool) –

setLabelAnchorPoint(self, anchor: QgsCallout.LabelAnchorPoint)

Sets the label’s anchor point position.

New in version 3.14.

Parameters

anchor (QgsCallout.LabelAnchorPoint) –

startRender(self, context: QgsRenderContext)

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()

Parameters

context (QgsRenderContext) –

stopRender(self, context: QgsRenderContext)

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()

Parameters

context (QgsRenderContext) –

type(self)str

Returns a unique string representing the callout type.

Return type

str