Class: QgsAnnotation

class qgis.core.QgsAnnotation

Bases: PyQt5.QtCore.QObject

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.

QgsAnnotation(parent: QObject = None) Constructor for QgsAnnotation.

Methods

accept

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

associatedFeature

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

childEvent

clone

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

connectNotify

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.

customEvent

disconnectNotify

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.

isSignalConnected

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.

minimumFrameSize

Returns the minimum frame size for the annotation.

readXml

Restores the annotation's state from a DOM element.

receivers

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.

renderAnnotation

Renders the annotation's contents to a target /a context at the specified /a size.

sender

senderSignalIndex

setAssociatedFeature

Sets the feature associated with the annotation.

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.

timerEvent

writeXml

Writes the annotation state to a DOM element.

Signals

appearanceChanged

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

mapLayerChanged

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

moved

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

accept(self, visitor: QgsStyleEntityVisitorInterface) 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.

New in version 3.10.

Parameters:

visitor (QgsStyleEntityVisitorInterface) –

Return type:

bool

appearanceChanged

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

associatedFeature(self) QgsFeature

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

Return type:

QgsFeature

childEvent(self, QChildEvent)
clone(self) QgsAnnotation

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

Return type:

QgsAnnotation

connectNotify(self, QMetaMethod)
contentsMargin(self) QgsMargins

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

Return type:

QgsMargins

copyCommonProperties(self, target: QgsAnnotation)

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

Parameters:

target (QgsAnnotation) –

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
fillSymbol(self) QgsFillSymbol

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

See also

setFillSymbol()

Return type:

QgsFillSymbol

frameOffsetFromReferencePoint(self) QPointF

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

Deprecated since version use: frameOffsetFromReferencePointMm() instead

Return type:

QPointF

frameOffsetFromReferencePointMm(self) QPointF

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

New 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 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()

New 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

mapPosition()

Return type:

bool

isSignalConnected(self, QMetaMethod) bool
isVisible(self) bool

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

See also

setVisible()

Return type:

bool

mapLayer(self) QgsMapLayer

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:

QgsMapLayer

mapLayerChanged

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

mapPosition(self) QgsPointXY

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

See also

setMapPosition()

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.

Return type:

QgsCoordinateReferenceSystem

markerSymbol(self) QgsMarkerSymbol

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

Return type:

QgsMarkerSymbol

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

moved

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

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:
receivers(self, PYQT_SIGNAL) int
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.

Return type:

QPointF

render(self, context: QgsRenderContext)

Renders the annotation to a target render context.

Parameters:

context (QgsRenderContext) –

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:
sender(self) QObject
senderSignalIndex(self) int
setAssociatedFeature(self, feature: QgsFeature)

Sets the feature associated with the annotation.

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)

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

See also

fillSymbol()

Parameters:

symbol (QgsFillSymbol) –

setFrameOffsetFromReferencePoint(self, offset: QPointF | QPoint | float)

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

Deprecated since version use: setFrameOffsetFromReferencePointMm() instead

Parameters:

offset (Union[QPointF) –

setFrameOffsetFromReferencePointMm(self, offset: QPointF | QPoint | float)

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

New in version 3.4.8.

Parameters:

offset (Union[QPointF) –

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

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

Parameters:

fixed (bool) –

setMapLayer(self, layer: QgsMapLayer)

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

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 (QgsMarkerSymbol) –

setRelativePosition(self, position: QPointF | QPoint | float)

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.

Parameters:

position (Union[QPointF) –

setVisible(self, visible: bool)

Sets whether the annotation is visible and should be rendered.

See also

isVisible()

Parameters:

visible (bool) –

timerEvent(self, QTimerEvent)
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: