Class: QgsAnnotationItem

Abstract base class for annotation items which are drawn with QgsAnnotationLayers.

Added in version 3.16.

Class Hierarchy

Subclasses

QgsAnnotationLineItem	An annotation item which renders a line symbol along a line geometry.
QgsAnnotationLineTextItem	An annotation item which renders text along a line geometry.
QgsAnnotationMarkerItem	An annotation item which renders a marker symbol at a point location.
QgsAnnotationRectItem	Abstract base class for annotation items which render annotations in a rectangular shape.
QgsAnnotationPointTextItem	An annotation item which renders a text string at a point location.
QgsAnnotationPolygonItem	An annotation item which renders a fill symbol for a polygon geometry.

Methods

applyEdit	Applies an edit operation to the item.
applyEditV2	Applies an edit operation to the item.
boundingBox	Returns the bounding box of the item's geographic location, in the parent layer's coordinate reference system.
callout	Returns the item's callout renderer, responsible for drawing item callouts.
calloutAnchor	Returns the callout's anchor geometry.
clone	Returns a clone of the item.
copyCommonProperties	Copies common properties from the base class from an other item.
enabled	Returns True if the item is enabled and will be rendered in the layer.
flags	Returns item flags.
nodes	Returns the nodes for the item, used for editing the item.
nodesV2	Returns the nodes for the item, used for editing the item.
offsetFromCallout	Returns the (optional) offset of the annotation item from the calloutAnchor().
offsetFromCalloutUnit	Returns the units for the offsetFromCallout().
readCommonProperties	Reads common properties from the base class from the given DOM element.
readXml	Reads the item's state from the given DOM element.
render	Renders the item to the specified render context.
renderCallout	Renders the item's callout.
setCallout	Sets the item's callout renderer, responsible for drawing item callouts.
setCalloutAnchor	Sets the callout's anchor geometry.
setEnabled	Sets if the item will be rendered or not in the layer.
setOffsetFromCallout	Sets the offset of the annotation item from the calloutAnchor().
setOffsetFromCalloutUnit	Sets the unit for the offsetFromCallout().
setSymbologyReferenceScale	Sets the annotation's symbology reference scale.
setUseSymbologyReferenceScale	Sets whether the annotation item uses a symbology reference scale.
setZIndex	Sets the item's z index, which controls the order in which annotation items are rendered in the layer.
symbologyReferenceScale	Returns the annotation's symbology reference scale.
transientEditResults	Retrieves the results of a transient (in progress) edit operation on the item.
transientEditResultsV2	Retrieves the results of a transient (in progress) edit operation on the item.
type	Returns a unique (untranslated) string identifying the type of item.
useSymbologyReferenceScale	Returns True if the annotation item uses a symbology reference scale.
writeCommonProperties	Writes common properties from the base class into an XML element.
writeXml	Writes the item's state into an XML element.
zIndex	Returns the item's z index, which controls the order in which annotation items are rendered in the layer.

class qgis.core.QgsAnnotationItem

Bases: object

applyEdit(self, operation: QgsAbstractAnnotationItemEditOperation | None) → Qgis.AnnotationItemEditOperationResult

Applies an edit operation to the item.

Deprecated since version 3.40: Use applyEditV2() instead.

Parameters:

operation (Optional[QgsAbstractAnnotationItemEditOperation])

Return type:

Qgis.AnnotationItemEditOperationResult

applyEditV2(self, operation: QgsAbstractAnnotationItemEditOperation | None, context: QgsAnnotationItemEditContext) → Qgis.AnnotationItemEditOperationResult

Applies an edit operation to the item.

Added in version 3.40.

Parameters:

• operation (Optional[QgsAbstractAnnotationItemEditOperation])

• context (QgsAnnotationItemEditContext)

Return type:

Qgis.AnnotationItemEditOperationResult

boundingBox(self) → QgsRectangle

Returns the bounding box of the item’s geographic location, in the parent layer’s coordinate reference system.

Return type:

QgsRectangle

boundingBox(self, context: QgsRenderContext) → QgsRectangle

Returns the bounding box of the item’s geographic location, in the parent layer’s coordinate reference system.

Parameters:

context (QgsRenderContext)

Return type:

QgsRectangle

callout(self) → QgsCallout | None

Returns the item’s callout renderer, responsible for drawing item callouts.

Ownership is not transferred.

By default items do not have a callout, and it is necessary to be explicitly set a callout style (via setCallout() ) and set the callout anchor geometry (via set setCalloutAnchor() ).

Note

Callouts are only supported by items which return Qgis.AnnotationItemFlag.SupportsCallouts from flags().

See also

setCallout()

See also

calloutAnchor()

Added in version 3.40.

Return type:

Optional[QgsCallout]

calloutAnchor(self) → QgsGeometry

Returns the callout’s anchor geometry.

The anchor dictates the geometry which the option item callout() should connect to. Depending on the callout subclass and anchor geometry type, the actual shape of the rendered callout may vary.

The callout anchor geometry is in the parent layer’s coordinate reference system.

See also

callout()

See also

setCalloutAnchor()

Added in version 3.40.

Return type:

QgsGeometry

clone(self) → QgsAnnotationItem | None

Returns a clone of the item. Ownership is transferred to the caller.

Implementations should include a call to copyCommonProperties() to copy the base class properties.

See also

copyCommonProperties()

Return type:

Optional[QgsAnnotationItem]

copyCommonProperties(self, other: QgsAnnotationItem | None)

Copies common properties from the base class from an other item.

Added in version 3.22.

Parameters:

other (Optional[QgsAnnotationItem])

enabled(self) → bool

Returns True if the item is enabled and will be rendered in the layer.

See also

setEnabled()

Added in version 3.36.

Return type:

bool

flags(self) → Qgis.AnnotationItemFlags

Returns item flags.

Added in version 3.22.

Return type:

Qgis.AnnotationItemFlags

nodes(self) → List[QgsAnnotationItemNode]

Returns the nodes for the item, used for editing the item.

Deprecated since version 3.40: Use nodesV2() instead.

Return type:

List[QgsAnnotationItemNode]

nodesV2(self, context: QgsAnnotationItemEditContext) → List[QgsAnnotationItemNode]

Returns the nodes for the item, used for editing the item.

Added in version 3.40.

Parameters:

context (QgsAnnotationItemEditContext)

Return type:

List[QgsAnnotationItemNode]

offsetFromCallout(self) → QSizeF

Returns the (optional) offset of the annotation item from the calloutAnchor().

Some annotation item subclasses support placement relative to the callout anchor. For these items, the offset from callout defines how far (in screen/page units) the item should be placed from the anchor point.

Units are defined by offsetFromCalloutUnit()

See also

setOffsetFromCallout()

Added in version 3.40.

Return type:

QSizeF

offsetFromCalloutUnit(self) → Qgis.RenderUnit

Returns the units for the offsetFromCallout().

See also

offsetFromCallout()

See also

setOffsetFromCalloutUnit()

Added in version 3.40.

Return type:

Qgis.RenderUnit

readCommonProperties(self, element: QDomElement, context: QgsReadWriteContext) → bool

Reads common properties from the base class from the given DOM element.

See also

readXml()

Added in version 3.22.

Parameters:

• element (QDomElement)

• context (QgsReadWriteContext)

Return type:

bool

readXml(self, element: QDomElement, context: QgsReadWriteContext) → bool

Reads the item’s state from the given DOM element.

Implementations should include a call to readCommonProperties() to read the base class properties.

See also

writeXml()

See also

readCommonProperties()

Parameters:

• element (QDomElement)

• context (QgsReadWriteContext)

Return type:

bool

render(self, context: QgsRenderContext, feedback: QgsFeedback | None)

Renders the item to the specified render context.

The feedback argument can be used to detect render cancellations during expensive render operations.

Parameters:

• context (QgsRenderContext)

• feedback (Optional[QgsFeedback])

renderCallout(self, context: QgsRenderContext, rect: QRectF, angle: float, calloutContext: QgsCallout.QgsCalloutContext, feedback: QgsFeedback | None)

Renders the item’s callout.

The item must have valid callout() set.

Added in version 3.40.

Parameters:

• context (QgsRenderContext)

• rect (QRectF)

• angle (float)

• calloutContext (QgsCallout.QgsCalloutContext)

• feedback (Optional[QgsFeedback])

setCallout(self, callout: QgsCallout | None)

Sets the item’s callout renderer, responsible for drawing item callouts.

Ownership of callout is transferred to the item.

Note

Callouts are only supported by items which return Qgis.AnnotationItemFlag.SupportsCallouts from flags().

See also

callout()

See also

setCalloutAnchor()

Added in version 3.40.

Parameters:

callout (Optional[QgsCallout])

setCalloutAnchor(self, anchor: QgsGeometry)

Sets the callout’s anchor geometry.

The anchor dictates the geometry which the option item callout() should connect to. Depending on the callout subclass and anchor geometry type, the actual shape of the rendered callout may vary.

The callout anchor geometry must be specified in the parent layer’s coordinate reference system.

See also

setCallout()

See also

calloutAnchor()

Added in version 3.40.

Parameters:

anchor (QgsGeometry)

setEnabled(self, enabled: bool)

Sets if the item will be rendered or not in the layer.

See also

enabled()

Added in version 3.36.

Parameters:

enabled (bool)

setOffsetFromCallout(self, offset: QSizeF)

Sets the offset of the annotation item from the calloutAnchor().

Some annotation item subclasses support placement relative to the callout anchor. For these items, the offset from callout defines how far (in screen/page units) the item should be placed from the anchor point.

Units are defined by offsetFromCalloutUnit()

See also

offsetFromCallout()

Added in version 3.40.

Parameters:

offset (QSizeF)

setOffsetFromCalloutUnit(self, unit: Qgis.RenderUnit)

Sets the unit for the offsetFromCallout().

See also

setOffsetFromCallout()

See also

offsetFromCalloutUnit()

Added in version 3.40.

Parameters:

unit (Qgis.RenderUnit)

setSymbologyReferenceScale(self, scale: float)

Sets the annotation’s symbology reference scale.

The reference scale will only be used if useSymbologyReferenceScale() returns True.

This represents the desired scale denominator for the rendered map, eg 1000.0 for a 1:1000 map render.

The symbology reference scale is an optional property which specifies the reference scale at which symbology in paper units (such a millimeters or points) is fixed to. For instance, if the scale is 1000 then a 2mm thick line will be rendered at exactly 2mm thick when a map is rendered at 1:1000, or 1mm thick when rendered at 1:2000, or 4mm thick at 1:500.

See also

symbologyReferenceScale()

See also

setUseSymbologyReferenceScale()

Parameters:

scale (float)

setUseSymbologyReferenceScale(self, enabled: bool)

Sets whether the annotation item uses a symbology reference scale.

See also

useSymbologyReferenceScale()

See also

setSymbologyReferenceScale()

Parameters:

enabled (bool)

setZIndex(self, index: int)

Sets the item’s z index, which controls the order in which annotation items are rendered in the layer.

See also

zIndex()

Parameters:

index (int)

symbologyReferenceScale(self) → float

Returns the annotation’s symbology reference scale.

The reference scale will only be used if useSymbologyReferenceScale() returns True.

This represents the desired scale denominator for the rendered map, eg 1000.0 for a 1:1000 map render.

The symbology reference scale is an optional property which specifies the reference scale at which symbology in paper units (such a millimeters or points) is fixed to. For instance, if the scale is 1000 then a 2mm thick line will be rendered at exactly 2mm thick when a map is rendered at 1:1000, or 1mm thick when rendered at 1:2000, or 4mm thick at 1:500.

See also

setSymbologyReferenceScale()

See also

useSymbologyReferenceScale()

Return type:

float

transientEditResults(self, operation: QgsAbstractAnnotationItemEditOperation | None) → QgsAnnotationItemEditOperationTransientResults | None

Retrieves the results of a transient (in progress) edit operation on the item.

Deprecated since version 3.40: Use transientEditResultsV2() instead.

Parameters:

operation (Optional[QgsAbstractAnnotationItemEditOperation])

Return type:

Optional[QgsAnnotationItemEditOperationTransientResults]

transientEditResultsV2(self, operation: QgsAbstractAnnotationItemEditOperation | None, context: QgsAnnotationItemEditContext) → QgsAnnotationItemEditOperationTransientResults | None

Retrieves the results of a transient (in progress) edit operation on the item.

Added in version 3.40.

Parameters:

• operation (Optional[QgsAbstractAnnotationItemEditOperation])

• context (QgsAnnotationItemEditContext)

Return type:

Optional[QgsAnnotationItemEditOperationTransientResults]

type(self) → str

Returns a unique (untranslated) string identifying the type of item.

Return type:

str

useSymbologyReferenceScale(self) → bool

Returns True if the annotation item uses a symbology reference scale.

See also

setUseSymbologyReferenceScale()

See also

symbologyReferenceScale()

Return type:

bool

writeCommonProperties(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool

Writes common properties from the base class into an XML element.

See also

writeXml()

Added in version 3.22.

Parameters:

• element (QDomElement)

• document (QDomDocument)

• context (QgsReadWriteContext)

Return type:

bool

writeXml(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool

Writes the item’s state into an XML element.

Implementations should include a call to writeCommonProperties() to store the base class properties.

See also

readXml()

See also

writeCommonProperties()

Parameters:

• element (QDomElement)

• document (QDomDocument)

• context (QgsReadWriteContext)

Return type:

bool

zIndex(self) → int

Returns the item’s z index, which controls the order in which annotation items are rendered in the layer.

See also

setZIndex()

Return type:

int