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.
Note
This is an abstract class, with methods which must be implemented by a subclass.
The following methods must be implemented: clone()
, draw()
, type()
Class Hierarchy¶
Subclasses¶
A cartoon talking bubble callout style. |
|
A simple direct line callout style. |
Enums
Data definable properties. |
Abstract Methods
Duplicates a callout by creating a deep copy of the callout. |
|
Performs the actual rendering of the callout implementation onto the specified render context. |
|
Returns a unique string representing the callout type. |
Methods
Returns the feature's anchor point position. |
|
Returns the blending mode used for drawing callouts. |
|
Returns the anchor point geometry for a label with the given bounding box and anchor point mode. |
|
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 |
|
Returns a reference to the callout's property collection, used for data defined overrides. |
|
Returns |
|
Returns the anchor point geometry for a label with the given bounding box and anchor point mode. |
|
Returns the label's anchor point position. |
|
Renders the callout onto the specified render context. |
|
Sets the feature's anchor point position. |
|
Sets the blending mode used for drawing callouts. |
|
Sets the callout's property collection, used for data defined overrides. |
|
Sets whether the callout is enabled. |
|
Sets the label's anchor point position. |
Virtual Methods
In PyQGIS, only methods marked as virtual
can be safely overridden in a Python subclass of QgsCallout. See the FAQ for more details.
Returns the desired drawing order (stacking) to use while rendering this callout. |
|
Returns the properties describing the callout encoded in a string format. |
|
Reads a string map of an callout's properties and restores the callout to the state described by the properties map. |
|
Returns the set of attributes referenced by the callout. |
|
Restores the callout's properties from a DOM element. |
|
Saves the current state of the callout to a DOM element. |
|
Prepares the callout for rendering on the specified render context. |
|
Finalises the callout after a set of rendering operations on the specified render context. |
Static Methods
Attempts to decode a string representation of an anchor point name to the corresponding anchor point. |
|
Attempts to decode a string representation of a label anchor point name to the corresponding anchor point. |
|
Encodes an anchor point to its string representation. |
|
Encodes a label anchor point to its string representation. |
|
Returns the definitions for data defined properties available for use in callouts. |
Attributes
- class qgis.core.QgsCallout[source]¶
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 calloutsOffsetFromAnchor
: Distance to offset lines from anchor pointsOffsetFromLabel
: Distance to offset lines from label areaDrawCalloutToAllParts
: Whether callout lines should be drawn to all feature partsAnchorPointPosition
: Feature’s anchor point positionLabelAnchorPointPosition
: Label’s anchor point positionOriginX
: 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 calloutsAdded in version 3.20.
Orientation
: Orientation of curved line calloutsAdded in version 3.20.
Margins
: Margin from textAdded in version 3.20.
WedgeWidth
: Balloon callout wedge widthAdded in version 3.20.
CornerRadius
: Balloon callout corner radiusAdded in version 3.20.
BlendMode
: Callout blend modeAdded in version 3.20.
- class QgsCalloutContext[source]¶
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)[source]¶
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: bool¶
True
if all parts of associated feature were labeled
- originalFeatureCrs: QgsCoordinateReferenceSystem¶
Contains the CRS of the original feature associated with this callout.
Added in version 3.20.
- originalFeatureToMapTransform(self, renderContext: QgsRenderContext) QgsCoordinateTransform [source]¶
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:
- positions(self) List[QgsCalloutPosition] ¶
Returns the list of rendered callout positions.
Added in version 3.20.
- Return type:
List[QgsCalloutPosition]
- anchorPoint(self) QgsCallout.AnchorPoint [source]¶
Returns the feature’s anchor point position.
See also
- Return type:
- blendMode(self) QPainter.CompositionMode [source]¶
Returns the blending mode used for drawing callouts.
See also
Added in version 3.20.
- Return type:
QPainter.CompositionMode
- calloutLabelPoint(self, bodyBoundingBox: QRectF, angle: float, anchor: QgsCallout.LabelAnchorPoint, context: QgsRenderContext, calloutContext: QgsCallout.QgsCalloutContext)[source]¶
Returns the anchor point geometry for a label with the given bounding box and
anchor
point mode.The
pinned
argument will be set toTrue
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)[source]¶
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 toTrue
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)
- abstract clone(self) QgsCallout | None [source]¶
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 [source]¶
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
- Return type:
- static decodeAnchorPoint(name: str | None)[source]¶
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
- static decodeLabelAnchorPoint(name: str | None)[source]¶
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
Added in version 3.14.
- abstract draw(self, context: QgsRenderContext, bodyBoundingBox: QRectF, angle: float, anchor: QgsGeometry, calloutContext: QgsCallout.QgsCalloutContext)[source]¶
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). Theangle
argument specifies the rotation of the callout body (in degrees clockwise from horizontal). It is assumed that angle rotation specified viaangle
is applied around the center ofrect
.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 theanchor
, while another subclass may prefer to attach to the closest point onanchor
instead.Both
rect
andanchor
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)
- virtual drawOrder(self) QgsCallout.DrawOrder [source]¶
Returns the desired drawing order (stacking) to use while rendering this callout.
The default order is QgsCallout.OrderBelowIndividualLabels.
- Return type:
- static encodeAnchorPoint(anchor: QgsCallout.AnchorPoint) str [source]¶
Encodes an
anchor
point to its string representation.- Return type:
str
- Returns:
encoded string
See also
- Parameters:
anchor (QgsCallout.AnchorPoint)
- static encodeLabelAnchorPoint(anchor: QgsCallout.LabelAnchorPoint) str [source]¶
Encodes a label
anchor
point to its string representation.- Return type:
str
- Returns:
encoded string
See also
Added in version 3.14.
- Parameters:
anchor (QgsCallout.LabelAnchorPoint)
- labelAnchorGeometry(self, bodyBoundingBox: QRectF, angle: float, anchor: QgsCallout.LabelAnchorPoint) QgsGeometry [source]¶
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:
- labelAnchorPoint(self) QgsCallout.LabelAnchorPoint [source]¶
Returns the label’s anchor point position.
See also
Added in version 3.14.
- Return type:
- virtual properties(self, context: QgsReadWriteContext) Dict[str, Any] [source]¶
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
See also
- Parameters:
context (QgsReadWriteContext)
- Return type:
Dict[str, Any]
- static propertyDefinitions() Dict[int, QgsPropertyDefinition] [source]¶
Returns the definitions for data defined properties available for use in callouts.
- Return type:
Dict[int, QgsPropertyDefinition]
- virtual readProperties(self, props: Dict[str, Any], context: QgsReadWriteContext)[source]¶
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
- Parameters:
props (Dict[str, Any])
context (QgsReadWriteContext)
- virtual 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 rendercontext
.- Parameters:
context (QgsRenderContext)
- Return type:
Set[str]
- render(self, context: QgsRenderContext, rect: QRectF, angle: float, anchor: QgsGeometry, calloutContext: QgsCallout.QgsCalloutContext)[source]¶
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). Theangle
argument specifies the rotation of the callout body (in degrees clockwise from horizontal). It is assumed that angle rotation specified viaangle
is applied around the center ofrect
.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 theanchor
, while another subclass may prefer to attach to the closest point onanchor
instead.Both
rect
andanchor
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 allrender()
operations are complete a call tostopRender()
must be made.- Parameters:
context (QgsRenderContext)
rect (QRectF)
angle (float)
anchor (QgsGeometry)
calloutContext (QgsCallout.QgsCalloutContext)
- virtual restoreProperties(self, element: QDomElement, context: QgsReadWriteContext)[source]¶
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
- Parameters:
element (QDomElement)
context (QgsReadWriteContext)
- virtual saveProperties(self, doc: QDomDocument, element: QDomElement, context: QgsReadWriteContext) bool [source]¶
Saves the current state of the callout to a DOM
element
. The default behavior is to save the properties string map returned byproperties()
.- Return type:
bool
- Returns:
True
if save was successful
See also
- Parameters:
doc (QDomDocument)
element (QDomElement)
context (QgsReadWriteContext)
- setAnchorPoint(self, anchor: QgsCallout.AnchorPoint)[source]¶
Sets the feature’s
anchor
point position.See also
- Parameters:
anchor (QgsCallout.AnchorPoint)
- setBlendMode(self, mode: QPainter.CompositionMode)[source]¶
Sets the blending
mode
used for drawing callouts.See also
Added in version 3.20.
- Parameters:
mode (QPainter.CompositionMode)
- setDataDefinedProperties(self, collection: QgsPropertyCollection)[source]¶
Sets the callout’s property
collection
, used for data defined overrides.Any existing properties will be discarded.
See also
See also
Property
- Parameters:
collection (QgsPropertyCollection)
- setEnabled(self, enabled: bool)[source]¶
Sets whether the callout is
enabled
.See also
- Parameters:
enabled (bool)
- setLabelAnchorPoint(self, anchor: QgsCallout.LabelAnchorPoint)[source]¶
Sets the label’s
anchor
point position.See also
Added in version 3.14.
- Parameters:
anchor (QgsCallout.LabelAnchorPoint)
- virtual startRender(self, context: QgsRenderContext)[source]¶
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 tostopRender()
.See also
- Parameters:
context (QgsRenderContext)
- virtual stopRender(self, context: QgsRenderContext)[source]¶
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 tostartRender()
.See also
- Parameters:
context (QgsRenderContext)