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

Added in version 3.10.

Class Hierarchy

Subclasses

QgsBalloonCallout	A cartoon talking bubble callout style.
QgsSimpleLineCallout	A simple direct line callout style.

Enums

Property

Data definable properties.

Methods

anchorPoint	Returns the feature's anchor point position.
blendMode	Returns the blending mode used for drawing callouts.
calloutLabelPoint	Returns the anchor point geometry for a label with the given bounding box and anchor point mode.
calloutLineToPart	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.
clone	Duplicates a callout by creating a deep copy of the callout.
containsAdvancedEffects	Returns True if the callout requires advanced effects such as blend modes, which require output in raster formats to be fully respected.
dataDefinedProperties	Returns a reference to the callout's property collection, used for data defined overrides.
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.
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.
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.
setBlendMode	Sets the blending mode used for drawing callouts.
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.

Static Methods

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.
encodeAnchorPoint	Encodes an anchor point to its string representation.
encodeLabelAnchorPoint	Encodes a label anchor point to its string representation.
propertyDefinitions	Returns the definitions for data defined properties available for use in callouts.

Attributes

Centroid
LabelBottomLeft
LabelBottomMiddle
LabelBottomRight
LabelCentroid
LabelMiddleLeft
LabelMiddleRight
LabelPointOnExterior
LabelTopLeft
LabelTopMiddle
LabelTopRight
OrderBelowAllLabels
OrderBelowIndividualLabels
PointOnExterior
PointOnSurface
PoleOfInaccessibility

class qgis.core.QgsCallout

Bases: object

__init__()

Constructor for QgsCallout.

__init__(a0: QgsCallout)

Parameters:

a0 (QgsCallout)

class AnchorPoint

Bases: int

Centroid = 3

class DrawOrder

Bases: int

class LabelAnchorPoint

Bases: int

LabelBottomLeft = 7

LabelBottomMiddle = 8

LabelBottomRight = 9

LabelCentroid = 1

LabelMiddleLeft = 5

LabelMiddleRight = 6

LabelPointOnExterior = 0

LabelTopLeft = 2

LabelTopMiddle = 3

LabelTopRight = 4

OrderBelowAllLabels = 0

OrderBelowIndividualLabels = 1

PointOnExterior = 1

PointOnSurface = 2

PoleOfInaccessibility = 0

class Property(*values)

Bases: IntEnum

Data definable properties.

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

  Added in version 3.20.

• OriginY: Y-coordinate of callout origin (label anchor)

  Added in version 3.20.

• DestinationX: X-coordinate of callout destination (feature anchor)

  Added in version 3.20.

• DestinationY: Y-coordinate of callout destination (feature anchor)

  Added in version 3.20.

• Curvature: Curvature of curved line callouts

  Added in version 3.20.

• Orientation: Orientation of curved line callouts

  Added in version 3.20.

• Margins: Margin from text

  Added in version 3.20.

• WedgeWidth: Balloon callout wedge width

  Added in version 3.20.

• CornerRadius: Balloon callout corner radius

  Added in version 3.20.

• BlendMode: Callout blend mode

  Added in version 3.20.

class QgsCalloutContext

Bases: object

Contains additional contextual information about the context in which a callout is being rendered.

Added in version 3.10.

addCalloutPosition(self, position: QgsCalloutPosition)

Adds a rendered callout position.

The position details such as the callout line origin and destination should be populated by the callout subclass during rendering operations.

Note

the feature ID, layer ID and provider ID of the QgsCalloutPosition will be automatically populated.

Added in version 3.20.

Parameters:

position (QgsCalloutPosition)

allFeaturePartsLabeled

True if all parts of associated feature were labeled

originalFeatureCrs

Contains the CRS of the original feature associated with this callout.

Added in version 3.20.

originalFeatureToMapTransform(self, renderContext: QgsRenderContext) → QgsCoordinateTransform

Returns the coordinate transform to convert from the original layer associated with the callout to the destination map CRS.

Added in version 3.20.

Parameters:

renderContext (QgsRenderContext)

Return type:

QgsCoordinateTransform

positions(self) → List[QgsCalloutPosition]

Returns the list of rendered callout positions.

Added in version 3.20.

Return type:

List[QgsCalloutPosition]

anchorPoint(self) → QgsCallout.AnchorPoint

Returns the feature’s anchor point position.

See also

setAnchorPoint()

Return type:

QgsCallout.AnchorPoint

blendMode(self) → QPainter.CompositionMode

Returns the blending mode used for drawing callouts.

See also

setBlendMode()

Added in version 3.20.

Return type:

QPainter.CompositionMode

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

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

Added in version 3.20.

Parameters:

• bodyBoundingBox (QRectF)

• angle (float)

• anchor (QgsCallout.LabelAnchorPoint)

• context (QgsRenderContext)

• calloutContext (QgsCallout.:py:class:.QgsCalloutContext) -> (QgsGeometry)

calloutLineToPart(self, labelGeometry: QgsGeometry, partGeometry: QgsAbstractGeometry | None, context: QgsRenderContext, calloutContext: QgsCallout.QgsCalloutContext)

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

Added in version 3.20.

Parameters:

• labelGeometry (QgsGeometry)

• partGeometry (Optional[QgsAbstractGeometry])

• context (QgsRenderContext)

• calloutContext (QgsCallout.:py:class:.QgsCalloutContext) -> (QgsGeometry)

clone(self) → QgsCallout | None

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

Caller takes ownership of the returned object.

Return type:

Optional[QgsCallout]

containsAdvancedEffects(self) → bool

Returns True if the callout requires advanced effects such as blend modes, which require output in raster formats to be fully respected.

Added in version 3.20.

Return type:

bool

dataDefinedProperties(self) → QgsPropertyCollection

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

See also

setDataDefinedProperties()

Return type:

QgsPropertyCollection

static decodeAnchorPoint(name: str | None)

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

Parameters:

• name (Optional[str]) -> (QgsCallout.AnchorPoint) – encoded anchor point name

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

Returns:

decoded name

See also

encodeAnchorPoint()

static decodeLabelAnchorPoint(name: str | None)

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

Parameters:

• name (Optional[str]) -> (QgsCallout.LabelAnchorPoint) – encoded label anchor point name

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

Returns:

decoded name

See also

encodeLabelAnchorPoint()

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

• context (QgsRenderContext)

• bodyBoundingBox (QRectF)

• angle (float)

• anchor (QgsGeometry)

• calloutContext (QgsCallout.QgsCalloutContext)

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

static encodeAnchorPoint(anchor: QgsCallout.AnchorPoint) → str

Encodes an anchor point to its string representation.

Return type:

str

Returns:

encoded string

See also

decodeAnchorPoint()

Parameters:

anchor (QgsCallout.AnchorPoint)

static encodeLabelAnchorPoint(anchor: QgsCallout.LabelAnchorPoint) → str

Encodes a label anchor point to its string representation.

Return type:

str

Returns:

encoded string

See also

decodeLabelAnchorPoint()

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

Deprecated since version 3.20: Use calloutLabelPoint() instead.

Parameters:

• bodyBoundingBox (QRectF)

• angle (float)

• anchor (QgsCallout.LabelAnchorPoint)

Return type:

QgsGeometry

labelAnchorPoint(self) → QgsCallout.LabelAnchorPoint

Returns the label’s anchor point position.

See also

setLabelAnchorPoint()

Added 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]

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

• props (Dict[str, Any])

• context (QgsReadWriteContext)

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:

• context (QgsRenderContext)

• rect (QRectF)

• angle (float)

• anchor (QgsGeometry)

• calloutContext (QgsCallout.QgsCalloutContext)

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:

• element (QDomElement)

• context (QgsReadWriteContext)

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:

• doc (QDomDocument)

• element (QDomElement)

• context (QgsReadWriteContext)

setAnchorPoint(self, anchor: QgsCallout.AnchorPoint)

Sets the feature’s anchor point position.

See also

anchorPoint()

Parameters:

anchor (QgsCallout.AnchorPoint)

setBlendMode(self, mode: QPainter.CompositionMode)

Sets the blending mode used for drawing callouts.

See also

blendMode()

Added in version 3.20.

Parameters:

mode (QPainter.CompositionMode)

setDataDefinedProperties(self, collection: QgsPropertyCollection)

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

Any existing properties will be discarded.

See also

dataDefinedProperties()

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.

See also

labelAnchorPoint()

Added 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