Class: QgsAnnotation

Abstract base class for annotation items which are drawn over a map.

QgsAnnotation is an abstract base class for map annotation items. These annotations can be drawn within a map, and have either a fixed map position (retrieved using mapPosition()) or are placed relative to the map’s frame (retrieved using relativePosition()). Annotations with a fixed map position also have a corresponding QgsCoordinateReferenceSystem, which can be determined by calling mapPositionCrs().

Derived classes should implement their custom painting routines within a renderAnnotation() override.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: clone(), readXml(), renderAnnotation(), writeXml()

Class Hierarchy

Base classes

QObject

Subclasses

QgsHtmlAnnotation	An annotation item that embeds HTML content.
QgsSvgAnnotation	An annotation which renders the contents of an SVG file.
QgsTextAnnotation	An annotation item that displays formatted text from a QTextDocument document.
QgsFormAnnotation	An annotation item that embeds a designer form showing the feature attribute.

Abstract Methods

clone	Clones the annotation, returning a new copy of the annotation reflecting the annotation's current state.
readXml	Restores the annotation's state from a DOM element.
renderAnnotation	Renders the annotation's contents to a target /a context at the specified /a size.
writeXml	Writes the annotation state to a DOM element.

Methods

associatedFeature	Returns the feature associated with the annotation, or an invalid feature if none has been set.
contentsMargin	Returns the margins (in millimeters) between the outside of the frame and the annotation content.
copyCommonProperties	Copies common annotation properties to the targe annotation.
fillSymbol	Returns the symbol that is used for rendering the annotation frame.
frameOffsetFromReferencePoint	Returns the annotation's frame's offset (in pixels) from the mapPosition() reference point.
frameOffsetFromReferencePointMm	Returns the annotation's frame's offset (in millimeters) from the mapPosition() reference point.
frameSize	Returns the size (in pixels) of the annotation's frame (the main area in which the annotation's content is drawn).
frameSizeMm	Returns the size (in millimeters) of the annotation's frame (the main area in which the annotation's content is drawn).
hasFixedMapPosition	Returns True if the annotation is attached to a fixed map position, or False if the annotation uses a position relative to the current map extent.
isVisible	Returns True if the annotation is visible and should be rendered.
mapLayer	Returns the map layer associated with the annotation.
mapPosition	Returns the map position of the annotation, if it is attached to a fixed map position.
mapPositionCrs	Returns the CRS of the map position, or an invalid CRS if the annotation does not have a fixed map position.
markerSymbol	Returns the symbol that is drawn at the annotation's map position.
relativePosition	Returns the relative position of the annotation, if it is not attached to a fixed map position.
render	Renders the annotation to a target render context.
setContentsMargin	Sets the margins (in millimeters) between the outside of the frame and the annotation content.
setFillSymbol	Sets the fill symbol used for rendering the annotation frame.
setFrameOffsetFromReferencePoint	Sets the annotation's frame's offset (in pixels) from the mapPosition() reference point.
setFrameOffsetFromReferencePointMm	Sets the annotation's frame's offset (in millimeters) from the mapPosition() reference point.
setFrameSize	Sets the size (in pixels) of the annotation's frame (the main area in which the annotation's content is drawn).
setFrameSizeMm	Sets the size (in millimeters) of the annotation's frame (the main area in which the annotation's content is drawn).
setHasFixedMapPosition	Sets whether the annotation is attached to a fixed map position, or uses a position relative to the current map extent.
setMapLayer	Sets the map layer associated with the annotation.
setMapPosition	Sets the map position of the annotation, if it is attached to a fixed map position.
setMapPositionCrs	Sets the CRS of the map position.
setMarkerSymbol	Sets the symbol that is drawn at the annotation's map position.
setRelativePosition	Sets the relative position of the annotation, if it is not attached to a fixed map position.
setVisible	Sets whether the annotation is visible and should be rendered.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsAnnotation. See the FAQ for more details.

accept	Accepts the specified style entity visitor, causing it to visit all style entities associated within the annotation.
minimumFrameSize	Returns the minimum frame size for the annotation.
setAssociatedFeature	Sets the feature associated with the annotation.

Signals

appearanceChanged	Emitted whenever the annotation's appearance changes
mapLayerChanged	Emitted when the map layer associated with the annotation changes.
moved	Emitted when the annotation's position has changed and items need to be moved to reflect this.

class qgis.core.QgsAnnotation

Bases: QObject

__init__(parent: QObject | None = None)

Constructor for QgsAnnotation.

Parameters:

parent (Optional[QObject] = None)

virtual accept(self, visitor: QgsStyleEntityVisitorInterface | None) → bool

Accepts the specified style entity visitor, causing it to visit all style entities associated within the annotation.

Returns True if the visitor should continue visiting other objects, or False if visiting should be canceled.

Added in version 3.10.

Parameters:

visitor (Optional[QgsStyleEntityVisitorInterface])

Return type:

bool

signal appearanceChanged

Emitted whenever the annotation’s appearance changes

associatedFeature(self) → QgsFeature

Returns the feature associated with the annotation, or an invalid feature if none has been set.

See also

setAssociatedFeature()

Return type:

QgsFeature

abstract clone(self) → QgsAnnotation | None

Clones the annotation, returning a new copy of the annotation reflecting the annotation’s current state.

Return type:

Optional[QgsAnnotation]

contentsMargin(self) → QgsMargins

Returns the margins (in millimeters) between the outside of the frame and the annotation content.

See also

setContentsMargin()

Return type:

QgsMargins

copyCommonProperties(self, target: QgsAnnotation | None)

Copies common annotation properties to the targe annotation. Can be used within QgsAnnotation.clone() implementations to assist with creating copies.

Parameters:

target (Optional[QgsAnnotation])

fillSymbol(self) → QgsFillSymbol | None

Returns the symbol that is used for rendering the annotation frame.

See also

setFillSymbol()

Return type:

Optional[QgsFillSymbol]

frameOffsetFromReferencePoint(self) → QPointF

Returns the annotation’s frame’s offset (in pixels) from the mapPosition() reference point.

See also

setFrameOffsetFromReferencePoint()

Deprecated since version 3.40: Use frameOffsetFromReferencePointMm() instead.

Return type:

QPointF

frameOffsetFromReferencePointMm(self) → QPointF

Returns the annotation’s frame’s offset (in millimeters) from the mapPosition() reference point.

See also

setFrameOffsetFromReferencePointMm()

Added in version 3.4.8.

Return type:

QPointF

frameSize(self) → QSizeF

Returns the size (in pixels) of the annotation’s frame (the main area in which the annotation’s content is drawn).

See also

setFrameSize()

Deprecated since version 3.40: Use frameSizeMm() instead.

Return type:

QSizeF

frameSizeMm(self) → QSizeF

Returns the size (in millimeters) of the annotation’s frame (the main area in which the annotation’s content is drawn).

See also

setFrameSizeMm()

Added in version 3.4.8.

Return type:

QSizeF

hasFixedMapPosition(self) → bool

Returns True if the annotation is attached to a fixed map position, or False if the annotation uses a position relative to the current map extent.

See also

setHasFixedMapPosition()

See also

mapPosition()

See also

relativePosition()

Return type:

bool

isVisible(self) → bool

Returns True if the annotation is visible and should be rendered.

See also

setVisible()

Return type:

bool

mapLayer(self) → QgsMapLayer | None

Returns the map layer associated with the annotation. Annotations can be associated with a map layer if their visibility should be synchronized with the layer’s visibility.

See also

setMapLayer()

Return type:

Optional[QgsMapLayer]

signal mapLayerChanged

Emitted when the map layer associated with the annotation changes.

mapPosition(self) → QgsPointXY

Returns the map position of the annotation, if it is attached to a fixed map position.

See also

setMapPosition()

See also

hasFixedMapPosition()

See also

mapPositionCrs()

Return type:

QgsPointXY

mapPositionCrs(self) → QgsCoordinateReferenceSystem

Returns the CRS of the map position, or an invalid CRS if the annotation does not have a fixed map position.

See also

setMapPositionCrs()

Return type:

QgsCoordinateReferenceSystem

markerSymbol(self) → QgsMarkerSymbol | None

Returns the symbol that is drawn at the annotation’s map position.

See also

setMarkerSymbol()

Return type:

Optional[QgsMarkerSymbol]

virtual minimumFrameSize(self) → QSizeF

Returns the minimum frame size for the annotation. Subclasses should implement this if they cannot be resized smaller than a certain minimum size.

Return type:

QSizeF

signal moved

Emitted when the annotation’s position has changed and items need to be moved to reflect this.

abstract readXml(self, itemElem: QDomElement, context: QgsReadWriteContext)

Restores the annotation’s state from a DOM element. Derived classes should call _readXml() within their implementation of this method.

See also

writeXml()

See also

_readXml

Parameters:

• itemElem (QDomElement)

• context (QgsReadWriteContext)

relativePosition(self) → QPointF

Returns the relative position of the annotation, if it is not attached to a fixed map position. The coordinates in the return point should be between 0 and 1, and represent the relative percentage for the position compared to the map width and height.

See also

setRelativePosition()

Return type:

QPointF

render(self, context: QgsRenderContext)

Renders the annotation to a target render context.

Parameters:

context (QgsRenderContext)

abstract renderAnnotation(self, context: QgsRenderContext, size: QSizeF)

Renders the annotation’s contents to a target /a context at the specified /a size. Derived classes should implement their custom annotation drawing logic here.

Parameters:

• context (QgsRenderContext)

• size (QSizeF)

virtual setAssociatedFeature(self, feature: QgsFeature)

Sets the feature associated with the annotation.

See also

associatedFeature()

Parameters:

feature (QgsFeature)

setContentsMargin(self, margins: QgsMargins)

Sets the margins (in millimeters) between the outside of the frame and the annotation content.

See also

contentsMargin()

Parameters:

margins (QgsMargins)

setFillSymbol(self, symbol: QgsFillSymbol | None)

Sets the fill symbol used for rendering the annotation frame. Ownership of the symbol is transferred to the annotation.

See also

fillSymbol()

Parameters:

symbol (Optional[QgsFillSymbol])

setFrameOffsetFromReferencePoint(self, offset: QPointF | QPoint)

Sets the annotation’s frame’s offset (in pixels) from the mapPosition() reference point.

See also

frameOffsetFromReferencePoint()

Deprecated since version 3.40: Use setFrameOffsetFromReferencePointMm() instead.

Parameters:

offset (Union[QPointF, QPoint])

setFrameOffsetFromReferencePointMm(self, offset: QPointF | QPoint)

Sets the annotation’s frame’s offset (in millimeters) from the mapPosition() reference point.

See also

frameOffsetFromReferencePointMm()

Added in version 3.4.8.

Parameters:

offset (Union[QPointF, QPoint])

setFrameSize(self, size: QSizeF)

Sets the size (in pixels) of the annotation’s frame (the main area in which the annotation’s content is drawn).

See also

frameSize()

Deprecated since version 3.40: Use setFrameSizeMm() instead.

Parameters:

size (QSizeF)

setFrameSizeMm(self, size: QSizeF)

Sets the size (in millimeters) of the annotation’s frame (the main area in which the annotation’s content is drawn).

See also

frameSizeMm()

Added in version 3.4.8.

Parameters:

size (QSizeF)

setHasFixedMapPosition(self, fixed: bool)

Sets whether the annotation is attached to a fixed map position, or uses a position relative to the current map extent.

See also

hasFixedMapPosition()

Parameters:

fixed (bool)

setMapLayer(self, layer: QgsMapLayer | None)

Sets the map layer associated with the annotation. Annotations can be associated with a map layer if their visibility should be synchronized with the layer’s visibility.

See also

mapLayer()

Parameters:

layer (Optional[QgsMapLayer])

setMapPosition(self, position: QgsPointXY)

Sets the map position of the annotation, if it is attached to a fixed map position.

See also

mapPosition()

Parameters:

position (QgsPointXY)

setMapPositionCrs(self, crs: QgsCoordinateReferenceSystem)

Sets the CRS of the map position.

See also

mapPositionCrs()

Parameters:

crs (QgsCoordinateReferenceSystem)

setMarkerSymbol(self, symbol: QgsMarkerSymbol | None)

Sets the symbol that is drawn at the annotation’s map position. Ownership of the symbol is transferred to the annotation.

See also

markerSymbol()

Parameters:

symbol (Optional[QgsMarkerSymbol])

setRelativePosition(self, position: QPointF | QPoint)

Sets the relative position of the annotation, if it is not attached to a fixed map position. The coordinates in the return point should be between 0 and 1, and represent the relative percentage for the position compared to the map width and height.

See also

relativePosition()

Parameters:

position (Union[QPointF, QPoint])

setVisible(self, visible: bool)

Sets whether the annotation is visible and should be rendered.

See also

isVisible()

Parameters:

visible (bool)

abstract writeXml(self, elem: QDomElement, doc: QDomDocument, context: QgsReadWriteContext)

Writes the annotation state to a DOM element. Derived classes should call _writeXml() within their implementation of this method.

See also

readXml()

See also

_writeXml

Parameters:

• elem (QDomElement)

• doc (QDomDocument)

• context (QgsReadWriteContext)