QgsAnnotation class

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

Reference

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.

Derived classes

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

Constructors, destructors, conversion operators

QgsAnnotation(QObject* parent = nullptr): Constructor for QgsAnnotation.

Public functions

auto associatedFeature() const -> QgsFeature: Returns the feature associated with the annotation, or an invalid feature if none has been set.
auto clone() const -> QgsAnnotation* pure virtual: Clones the annotation, returning a new copy of the annotation reflecting the annotation's current state.
auto contentsMargin() const -> QgsMargins: Returns the margins (in millimeters) between the outside of the frame and the annotation content.
auto fillSymbol() const -> QgsFillSymbol*: Returns the symbol that is used for rendering the annotation frame.
auto frameOffsetFromReferencePoint() const -> QPointF: Returns the annotation's frame's offset from the mapPosition() reference point.
auto frameSize() const -> QSizeF: Returns the size of the annotation's frame (the main area in which the annotation's content is drawn).
auto hasFixedMapPosition() const -> 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.
auto isVisible() const -> bool: Returns true if the annotation is visible and should be rendered.
auto mapLayer() const -> QgsMapLayer*: Returns the map layer associated with the annotation.
auto mapPosition() const -> QgsPointXY: Returns the map position of the annotation, if it is attached to a fixed map position.
auto mapPositionCrs() const -> QgsCoordinateReferenceSystem: Returns the CRS of the map position, or an invalid CRS if the annotation does not have a fixed map position.
auto markerSymbol() const -> QgsMarkerSymbol*: Returns the symbol that is drawn at the annotation's map position.
void readXml(const QDomElement& itemElem, const QgsReadWriteContext& context) pure virtual: Restores the annotation's state from a DOM element.
auto relativePosition() const -> QPointF: Returns the relative position of the annotation, if it is not attached to a fixed map position.
void render(QgsRenderContext& context) const: Renders the annotation to a target render context.
void setAssociatedFeature(const QgsFeature& feature) virtual: Sets the feature associated with the annotation.
void setContentsMargin(const QgsMargins& margins): Sets the margins (in millimeters) between the outside of the frame and the annotation content.
void setFillSymbol(QgsFillSymbol* symbol): Sets the fill symbol used for rendering the annotation frame.
void setFrameOffsetFromReferencePoint(QPointF offset): Sets the annotation's frame's offset from the mapPosition() reference point.
void setFrameSize(QSizeF size): Sets the size of the annotation's frame (the main area in which the annotation's content is drawn).
void setHasFixedMapPosition(bool fixed): Sets whether the annotation is attached to a fixed map position, or uses a position relative to the current map extent.
void setMapLayer(QgsMapLayer* layer): Sets the map layer associated with the annotation.
void setMapPosition(const QgsPointXY& position): Sets the map position of the annotation, if it is attached to a fixed map position.
void setMapPositionCrs(const QgsCoordinateReferenceSystem& crs): Sets the CRS of the map position.
void setMarkerSymbol(QgsMarkerSymbol* symbol): Sets the symbol that is drawn at the annotation's map position.
void setRelativePosition(QPointF position): Sets the relative position of the annotation, if it is not attached to a fixed map position.
void setVisible(bool visible): Sets whether the annotation is visible and should be rendered.
void writeXml(QDomElement& elem, QDomDocument& doc, const QgsReadWriteContext& context) const pure virtual: Writes the annotation state to a DOM element.

Signals

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

Protected functions

void _readXml(const QDomElement& annotationElem, const QgsReadWriteContext& context): Reads common annotation properties from a DOM element.
void _writeXml(QDomElement& itemElem, QDomDocument& doc, const QgsReadWriteContext& context) const: Writes common annotation properties to a DOM element.
void copyCommonProperties(QgsAnnotation* target) const: Copies common annotation properties to the targe annotation.
auto minimumFrameSize() const -> QSizeF virtual: Returns the minimum frame size for the annotation.
void renderAnnotation(QgsRenderContext& context, QSizeF size) const pure virtual: Renders the annotation's contents to a target /a context at the specified /a size.

Function documentation

QgsFeature QgsAnnotation::associatedFeature() const

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

QgsMargins QgsAnnotation::contentsMargin() const

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

QgsFillSymbol* QgsAnnotation::fillSymbol() const

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

QPointF QgsAnnotation::frameOffsetFromReferencePoint() const

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

QSizeF QgsAnnotation::frameSize() const

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

bool QgsAnnotation::hasFixedMapPosition() const

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.

bool QgsAnnotation::isVisible() const

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

QgsMapLayer* QgsAnnotation::mapLayer() const

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.

QgsPointXY QgsAnnotation::mapPosition() const

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

QgsCoordinateReferenceSystem QgsAnnotation::mapPositionCrs() const

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

QgsMarkerSymbol* QgsAnnotation::markerSymbol() const

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

void QgsAnnotation::readXml(const QDomElement& itemElem, const QgsReadWriteContext& context) pure virtual

Restores the annotation's state from a DOM element.

Derived classes should call _readXml() within their implementation of this method.

QPointF QgsAnnotation::relativePosition() const

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.

void QgsAnnotation::setAssociatedFeature(const QgsFeature& feature) virtual

Sets the feature associated with the annotation.

void QgsAnnotation::setContentsMargin(const QgsMargins& margins)

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

void QgsAnnotation::setFillSymbol(QgsFillSymbol* symbol)

Sets the fill symbol used for rendering the annotation frame.

Ownership of the symbol is transferred to the annotation.

void QgsAnnotation::setFrameOffsetFromReferencePoint(QPointF offset)

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

void QgsAnnotation::setFrameSize(QSizeF size)

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

void QgsAnnotation::setHasFixedMapPosition(bool fixed)

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

void QgsAnnotation::setMapLayer(QgsMapLayer* layer)

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.

void QgsAnnotation::setMapPosition(const QgsPointXY& position)

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

void QgsAnnotation::setMapPositionCrs(const QgsCoordinateReferenceSystem& crs)

Sets the CRS of the map position.

void QgsAnnotation::setMarkerSymbol(QgsMarkerSymbol* symbol)

Sets the symbol that is drawn at the annotation's map position.

Ownership of the symbol is transferred to the annotation.

void QgsAnnotation::setRelativePosition(QPointF position)

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.

void QgsAnnotation::setVisible(bool visible)

Sets whether the annotation is visible and should be rendered.

void QgsAnnotation::writeXml(QDomElement& elem, QDomDocument& doc, const QgsReadWriteContext& context) const pure virtual

Writes the annotation state to a DOM element.

Derived classes should call _writeXml() within their implementation of this method.

void QgsAnnotation::_readXml(const QDomElement& annotationElem, const QgsReadWriteContext& context) protected

Reads common annotation properties from a DOM element.

This method should be called from subclasses in their readXml method.

void QgsAnnotation::_writeXml(QDomElement& itemElem, QDomDocument& doc, const QgsReadWriteContext& context) const protected

Writes common annotation properties to a DOM element.

This method should be called from subclasses in their writeXml method.

void QgsAnnotation::copyCommonProperties(QgsAnnotation* target) const protected

Copies common annotation properties to the targe annotation.

Can be used within QgsAnnotation::clone() implementations to assist with creating copies.

QSizeF QgsAnnotation::minimumFrameSize() const virtual protected

Returns the minimum frame size for the annotation.

Subclasses should implement this if they cannot be resized smaller than a certain minimum size.

void QgsAnnotation::renderAnnotation(QgsRenderContext& context, QSizeF size) const pure virtual protected

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.