Subgroup: Annotation

Class: QgsAnnotation

class qgis.core.QgsAnnotation(parent: QObject = None)

Bases: PyQt5.QtCore.QObject

Constructor for 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.

New in version 3.0: Methods

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 from the mapPosition() reference point.
frameSize Returns the size 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 from the mapPosition() reference point.
setFrameSize Sets the size 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 Emitted whenever the annotation’s appearance changes [signal]
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.

Attributes

appearanceChanged

Emitted whenever the annotation’s appearance changes [signal]

associatedFeature(self) → QgsFeature

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

childEvent()
clone(self) → QgsAnnotation

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

connectNotify()
contentsMargin(self) → QgsMargins

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

copyCommonProperties(self, target: QgsAnnotation)

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

customEvent()
disconnectNotify()
fillSymbol(self) → QgsFillSymbol

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

See also

setFillSymbol()

frameOffsetFromReferencePoint(self) → QPointF

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

frameSize(self) → QSizeF

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

See also

setFrameSize()

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

isSignalConnected()
isVisible(self) → bool

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

See also

setVisible()

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

mapLayerChanged

Emitted when the map layer associated with the annotation changes. [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()

mapPositionCrs(self) → QgsCoordinateReferenceSystem

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

markerSymbol(self) → QgsMarkerSymbol

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

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.

moved

Emitted when the annotation’s position has changed and items need to be moved to reflect this. [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

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

render(self, context: QgsRenderContext)

Renders the annotation to a target render context.

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.

sender()
senderSignalIndex()
setAssociatedFeature(self, feature: QgsFeature)

Sets the feature associated with the annotation.

setContentsMargin(self, margins: QgsMargins)

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

See also

contentsMargin()

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

setFrameOffsetFromReferencePoint(self, offset: Union[QPointF, QPoint])

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

setFrameSize(self, size: QSizeF)

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

See also

frameSize()

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.

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

setMapPosition(self, position: QgsPointXY)

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

See also

mapPosition()

setMapPositionCrs(self, crs: QgsCoordinateReferenceSystem)

Sets the CRS of the map position.

See also

mapPositionCrs()

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

setRelativePosition(self, position: Union[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.

setVisible(self, visible: bool)

Sets whether the annotation is visible and should be rendered.

See also

isVisible()

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