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

#include <qgsannotation.h>

Inheritance diagram for QgsAnnotation:

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.

Public Member Functions
	QgsAnnotation (QObject *parent=nullptr)
	Constructor for QgsAnnotation.

	~QgsAnnotation () override

virtual bool	accept (QgsStyleEntityVisitorInterface *visitor) const
	Accepts the specified style entity visitor, causing it to visit all style entities associated within the annotation.

QgsFeature	associatedFeature () const
	Returns the feature associated with the annotation, or an invalid feature if none has been set.

virtual QgsAnnotation *	clone () const =0
	Clones the annotation, returning a new copy of the annotation reflecting the annotation's current state.

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

QgsFillSymbol *	fillSymbol () const
	Returns the symbol that is used for rendering the annotation frame.

Q_DECL_DEPRECATED QPointF	frameOffsetFromReferencePoint () const
	Returns the annotation's frame's offset (in pixels) from the mapPosition() reference point.

QPointF	frameOffsetFromReferencePointMm () const
	Returns the annotation's frame's offset (in millimeters) from the mapPosition() reference point.

Q_DECL_DEPRECATED QSizeF	frameSize () const
	Returns the size (in pixels) of the annotation's frame (the main area in which the annotation's content is drawn).

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

bool	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	isVisible () const
	Returns `true` if the annotation is visible and should be rendered.

QgsMapLayer *	mapLayer () const
	Returns the map layer associated with the annotation.

QgsPointXY	mapPosition () const
	Returns the map position of the annotation, if it is attached to a fixed map position.

QgsCoordinateReferenceSystem	mapPositionCrs () const
	Returns the CRS of the map position, or an invalid CRS if the annotation does not have a fixed map position.

QgsMarkerSymbol *	markerSymbol () const
	Returns the symbol that is drawn at the annotation's map position.

virtual void	readXml (const QDomElement &itemElem, const QgsReadWriteContext &context)=0
	Restores the annotation's state from a DOM element.

QPointF	relativePosition () const
	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.

virtual void	setAssociatedFeature (const QgsFeature &feature)
	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.

Q_DECL_DEPRECATED void	setFrameOffsetFromReferencePoint (QPointF offset)
	Sets the annotation's frame's offset (in pixels) from the mapPosition() reference point.

void	setFrameOffsetFromReferencePointMm (QPointF offset)
	Sets the annotation's frame's offset (in millimeters) from the mapPosition() reference point.

Q_DECL_DEPRECATED void	setFrameSize (QSizeF size)
	Sets the size (in pixels) of the annotation's frame (the main area in which the annotation's content is drawn).

void	setFrameSizeMm (QSizeF size)
	Sets the size (in millimeters) 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.

virtual void	writeXml (QDomElement &elem, QDomDocument &doc, const QgsReadWriteContext &context) const =0
	Writes the annotation state to a DOM element.

Protected Member 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.

virtual QSizeF	minimumFrameSize () const
	Returns the minimum frame size for the annotation.

virtual void	renderAnnotation (QgsRenderContext &context, QSizeF size) const =0
	Renders the annotation's contents to a target /a context at the specified /a size.

Properties
QSizeF	frameSize

bool	hasFixedMapPosition

QgsPointXY	mapPosition

bool	visible

Detailed Description

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.

Since: QGIS 3.0

Definition at line 53 of file qgsannotation.h.

Constructor & Destructor Documentation

◆ QgsAnnotation()

QgsAnnotation::QgsAnnotation ( QObject * parent = nullptr )

Constructor for QgsAnnotation.

Definition at line 33 of file qgsannotation.cpp.

◆ ~QgsAnnotation()

QgsAnnotation::~QgsAnnotation ( )

overridedefault

Member Function Documentation

◆ _readXml()

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.

See also: readXml(); _writeXml()

Definition at line 308 of file qgsannotation.cpp.

◆ _writeXml()

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.

See also: writeXml(); _readXml()

Definition at line 263 of file qgsannotation.cpp.

◆ accept()

bool QgsAnnotation::accept ( QgsStyleEntityVisitorInterface * visitor ) const

virtual

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.

Since: QGIS 3.10

Definition at line 193 of file qgsannotation.cpp.

◆ appearanceChanged

void QgsAnnotation::appearanceChanged ( )

signal

Emitted whenever the annotation's appearance changes.

◆ associatedFeature()

QgsFeature QgsAnnotation::associatedFeature ( ) const

inline

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

See also: setAssociatedFeature()

Definition at line 307 of file qgsannotation.h.

◆ clone()

virtual QgsAnnotation * QgsAnnotation::clone ( ) const

pure virtual

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

Implemented in QgsHtmlAnnotation, QgsSvgAnnotation, QgsTextAnnotation, and QgsFormAnnotation.

◆ contentsMargin()

QgsMargins QgsAnnotation::contentsMargin ( ) const

inline

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

See also: setContentsMargin()

Definition at line 237 of file qgsannotation.h.

◆ copyCommonProperties()

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.

Definition at line 409 of file qgsannotation.cpp.

◆ fillSymbol()

QgsFillSymbol * QgsAnnotation::fillSymbol ( ) const

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

See also: setFillSymbol()

Definition at line 135 of file qgsannotation.cpp.

◆ frameOffsetFromReferencePoint()

QPointF QgsAnnotation::frameOffsetFromReferencePoint ( ) const

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

See also: setFrameOffsetFromReferencePoint()

Deprecated:: use frameOffsetFromReferencePointMm() instead

Definition at line 91 of file qgsannotation.cpp.

◆ frameOffsetFromReferencePointMm()

QPointF QgsAnnotation::frameOffsetFromReferencePointMm ( ) const

inline

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

See also: setFrameOffsetFromReferencePointMm()

Since: QGIS 3.4.8

Definition at line 191 of file qgsannotation.h.

◆ frameSize()

QSizeF QgsAnnotation::frameSize ( ) const

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:: use frameSizeMm() instead

Definition at line 110 of file qgsannotation.cpp.

◆ frameSizeMm()

QSizeF QgsAnnotation::frameSizeMm ( ) const

inline

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

See also: setFrameSizeMm()

Since: QGIS 3.4.8

Definition at line 223 of file qgsannotation.h.

◆ hasFixedMapPosition()

bool QgsAnnotation::hasFixedMapPosition ( ) const

inline

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(); mapPosition(); relativePosition()

Definition at line 111 of file qgsannotation.h.

◆ isVisible()

bool QgsAnnotation::isVisible ( ) const

inline

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

See also: setVisible()

Definition at line 95 of file qgsannotation.h.

◆ mapLayer()

QgsMapLayer * QgsAnnotation::mapLayer ( ) const

inline

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

Definition at line 292 of file qgsannotation.h.

◆ mapLayerChanged

void QgsAnnotation::mapLayerChanged ( )

signal

Emitted when the map layer associated with the annotation changes.

◆ mapPosition()

QgsPointXY QgsAnnotation::mapPosition ( ) const

inline

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

See also: setMapPosition(); hasFixedMapPosition(); mapPositionCrs()

Definition at line 127 of file qgsannotation.h.

◆ mapPositionCrs()

QgsCoordinateReferenceSystem QgsAnnotation::mapPositionCrs ( ) const

inline

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

See also: setMapPositionCrs()

Definition at line 141 of file qgsannotation.h.

◆ markerSymbol()

QgsMarkerSymbol * QgsAnnotation::markerSymbol ( ) const

inline

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

See also: setMarkerSymbol()

Definition at line 284 of file qgsannotation.h.

◆ minimumFrameSize()

QSizeF QgsAnnotation::minimumFrameSize ( ) const

protectedvirtual

Returns the minimum frame size for the annotation.

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

Reimplemented in QgsHtmlAnnotation, and QgsFormAnnotation.

Definition at line 219 of file qgsannotation.cpp.

◆ moved

void QgsAnnotation::moved ( )

signal

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

◆ readXml()

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

See also: writeXml(); _readXml()

Implemented in QgsHtmlAnnotation, QgsSvgAnnotation, QgsTextAnnotation, and QgsFormAnnotation.

◆ relativePosition()

QPointF QgsAnnotation::relativePosition ( ) const

inline

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

Definition at line 155 of file qgsannotation.h.

◆ render()

void QgsAnnotation::render ( QgsRenderContext & context ) const

Renders the annotation to a target render context.

Definition at line 140 of file qgsannotation.cpp.

◆ renderAnnotation()

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

protectedpure virtual

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.

Implemented in QgsHtmlAnnotation, QgsSvgAnnotation, QgsTextAnnotation, and QgsFormAnnotation.

◆ setAssociatedFeature()

void QgsAnnotation::setAssociatedFeature ( const QgsFeature & feature )

virtual

Sets the feature associated with the annotation.

See also: associatedFeature()

Reimplemented in QgsHtmlAnnotation, and QgsFormAnnotation.

Definition at line 188 of file qgsannotation.cpp.

◆ setContentsMargin()

void QgsAnnotation::setContentsMargin ( const QgsMargins & margins )

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

See also: contentsMargin()

Definition at line 123 of file qgsannotation.cpp.

◆ setFillSymbol()

void QgsAnnotation::setFillSymbol ( QgsFillSymbol * symbol )

Sets the fill symbol used for rendering the annotation frame.

Ownership of the symbol is transferred to the annotation.

See also: fillSymbol()

Definition at line 129 of file qgsannotation.cpp.

◆ setFrameOffsetFromReferencePoint()

void QgsAnnotation::setFrameOffsetFromReferencePoint ( QPointF offset )

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

See also: frameOffsetFromReferencePoint()

Deprecated:: use setFrameOffsetFromReferencePointMm() instead

Definition at line 85 of file qgsannotation.cpp.

◆ setFrameOffsetFromReferencePointMm()

void QgsAnnotation::setFrameOffsetFromReferencePointMm ( QPointF offset )

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

See also: frameOffsetFromReferencePointMm()

Since: QGIS 3.4.8

Definition at line 96 of file qgsannotation.cpp.

◆ setFrameSize()

void QgsAnnotation::setFrameSize ( QSizeF size )

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:: use setFrameSizeMm() instead

Definition at line 104 of file qgsannotation.cpp.

◆ setFrameSizeMm()

void QgsAnnotation::setFrameSizeMm ( QSizeF size )

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

See also: frameSizeMm()

Since: QGIS 3.4.8

Definition at line 115 of file qgsannotation.cpp.

◆ setHasFixedMapPosition()

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.

See also: hasFixedMapPosition()

Definition at line 58 of file qgsannotation.cpp.

◆ setMapLayer()

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.

See also: mapLayer()

Definition at line 182 of file qgsannotation.cpp.

◆ setMapPosition()

void QgsAnnotation::setMapPosition ( const QgsPointXY & position )

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

See also: mapPosition()

Definition at line 67 of file qgsannotation.cpp.

◆ setMapPositionCrs()

void QgsAnnotation::setMapPositionCrs ( const QgsCoordinateReferenceSystem & crs )

Sets the CRS of the map position.

See also: mapPositionCrs()

Definition at line 73 of file qgsannotation.cpp.

◆ setMarkerSymbol()

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.

See also: markerSymbol()

Definition at line 176 of file qgsannotation.cpp.

◆ setRelativePosition()

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.

See also: relativePosition()

Definition at line 79 of file qgsannotation.cpp.

◆ setVisible()

void QgsAnnotation::setVisible ( bool visible )

Sets whether the annotation is visible and should be rendered.

See also: isVisible()

Definition at line 49 of file qgsannotation.cpp.

◆ writeXml()

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

See also: readXml(); _writeXml()

Implemented in QgsHtmlAnnotation, QgsSvgAnnotation, QgsTextAnnotation, and QgsFormAnnotation.

Property Documentation

◆ frameSize

QSizeF QgsAnnotation::frameSize

readwrite

Definition at line 74 of file qgsannotation.h.

◆ hasFixedMapPosition

bool QgsAnnotation::hasFixedMapPosition

readwrite

Definition at line 72 of file qgsannotation.h.

◆ mapPosition

QgsPointXY QgsAnnotation::mapPosition

readwrite

Definition at line 73 of file qgsannotation.h.

◆ visible

bool QgsAnnotation::visible

readwrite

Definition at line 71 of file qgsannotation.h.

The documentation for this class was generated from the following files:

/build/qgis-3.34.0+99sid/src/core/annotations/qgsannotation.h
/build/qgis-3.34.0+99sid/src/core/annotations/qgsannotation.cpp

Signals

Public Member Functions

Protected Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ QgsAnnotation()

◆ ~QgsAnnotation()

Member Function Documentation

◆ _readXml()

◆ _writeXml()

◆ accept()

◆ appearanceChanged

◆ associatedFeature()

◆ clone()

◆ contentsMargin()

◆ copyCommonProperties()

◆ fillSymbol()

◆ frameOffsetFromReferencePoint()

◆ frameOffsetFromReferencePointMm()

◆ frameSize()

◆ frameSizeMm()

◆ hasFixedMapPosition()

◆ isVisible()

◆ mapLayer()

◆ mapLayerChanged

◆ mapPosition()

◆ mapPositionCrs()

◆ markerSymbol()

◆ minimumFrameSize()

◆ moved

◆ readXml()

◆ relativePosition()

◆ render()

◆ renderAnnotation()

◆ setAssociatedFeature()

◆ setContentsMargin()

◆ setFillSymbol()

◆ setFrameOffsetFromReferencePoint()

◆ setFrameOffsetFromReferencePointMm()

◆ setFrameSize()

◆ setFrameSizeMm()

◆ setHasFixedMapPosition()

◆ setMapLayer()

◆ setMapPosition()

◆ setMapPositionCrs()

◆ setMarkerSymbol()

◆ setRelativePosition()

◆ setVisible()

◆ writeXml()

Property Documentation

◆ frameSize

◆ hasFixedMapPosition

◆ mapPosition

◆ visible