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
Returns the feature’s anchor point position.
Duplicates a callout by creating a deep copy of the callout.
Returns a reference to the callout’s property collection, used for data defined overrides.
Attempts to decode a string representation of an anchor point name to the corresponding anchor point.
Performs the actual rendering of the callout implementation onto the specified render
context
.Returns the desired drawing order (stacking) to use while rendering this callout.
Returns
True
if the the callout is enabled.Encodes an
anchor
point to its string representation.Returns the properties describing the callout encoded in a string format.
Returns the definitions for data defined properties available for use in callouts.
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.
Renders the callout onto the specified render
context
.Restores the callout’s properties from a DOM element.
Saves the current state of the callout to a DOM
element
.Sets the feature’s
anchor
point position.Sets the callout’s property
collection
, used for data defined overrides.Sets whether the callout is
enabled
.Prepares the callout for rendering on the specified render
context
.Finalises the callout after a set of rendering operations on the specified render
context
.Returns a unique string representing the callout type.
Attributes
-
class
AnchorPoint
¶ Bases:
int
-
AnchorPointPosition
= 4¶
-
Centroid
= 3¶
-
DrawCalloutToAllParts
= 3¶
-
class
DrawOrder
¶ Bases:
int
-
MinimumCalloutLength
= 0¶
-
OffsetFromAnchor
= 1¶
-
OffsetFromLabel
= 2¶
-
OrderBelowAllLabels
= 0¶
-
OrderBelowIndividualLabels
= 1¶
-
PointOnExterior
= 1¶
-
PointOnSurface
= 2¶
-
PoleOfInaccessibility
= 0¶
-
class
Property
¶ Bases:
int
-
class
QgsCalloutContext
¶ Bases:
sip.wrapper
QgsCallout.QgsCalloutContext(QgsCallout.:py:class:.QgsCalloutContext)
-
allFeaturePartsLabeled
¶
-
-
anchorPoint
(self) → QgsCallout.AnchorPoint¶ Returns the feature’s anchor point position.
See also
- Return type
-
clone
(self) → QgsCallout¶ Duplicates a callout by creating a deep copy of the callout.
Caller takes ownership of the returned object.
- Return type
-
dataDefinedProperties
(self) → QgsPropertyCollection¶ Returns a reference to the callout’s property collection, used for data defined overrides.
See also
- Return type
-
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
See also
-
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). 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) –
-
drawOrder
(self) → QgsCallout.DrawOrder¶ Returns the desired drawing order (stacking) to use while rendering this callout.
The default order is QgsCallout.OrderBelowIndividualLabels.
- Return type
-
enabled
(self) → bool¶ Returns
True
if the the callout is enabled.See also
- Return type
bool
-
encodeAnchorPoint
(anchor: QgsCallout.AnchorPoint) → str¶ Encodes an
anchor
point to its string representation.- Return type
str
- Returns
encoded string
See also
- Parameters
anchor (QgsCallout.AnchorPoint) –
-
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
See also
- 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
- Parameters
props (Dict[str) –
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). 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 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
- 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
- Parameters
doc (QDomDocument) –
element (QDomElement) –
context (QgsReadWriteContext) –
-
setAnchorPoint
(self, anchor: QgsCallout.AnchorPoint)¶ Sets the feature’s
anchor
point position.See also
- 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
See also
Property
- Parameters
collection (QgsPropertyCollection) –
-
setEnabled
(self, enabled: bool)¶ Sets whether the callout is
enabled
.See also
- Parameters
enabled (bool) –
-
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
- 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
- Parameters
context (QgsRenderContext) –
-
type
(self) → str¶ Returns a unique string representing the callout type.
- Return type
str
-
class