QGIS API Documentation  3.8.0-Zanzibar (11aff65)
Signals | Public Member Functions | Protected Member Functions | Properties | List of all members
QgsAnnotation Class Referenceabstract

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

#include <qgsannotation.h>

Inheritance diagram for QgsAnnotation:
Inheritance graph
[legend]

Signals

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

Public Member Functions

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

Protected Member Functions

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

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 49 of file qgsannotation.h.

Constructor & Destructor Documentation

◆ QgsAnnotation()

QgsAnnotation::QgsAnnotation ( QObject *  parent = nullptr)

Constructor for QgsAnnotation.

Definition at line 28 of file qgsannotation.cpp.

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 417 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 372 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 301 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, QgsFormAnnotation, QgsSvgAnnotation, and QgsTextAnnotation.

◆ 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 231 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 517 of file qgsannotation.cpp.

◆ fillSymbol()

QgsFillSymbol* QgsAnnotation::fillSymbol ( ) const
inline

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

See also
setFillSymbol()

Definition at line 244 of file qgsannotation.h.

◆ 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 85 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 185 of file qgsannotation.h.

◆ frameSize()

Q_DECL_DEPRECATED 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

◆ 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 217 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 105 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 89 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 286 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 121 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 135 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 278 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 183 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, QgsFormAnnotation, QgsTextAnnotation, and QgsSvgAnnotation.

◆ 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 149 of file qgsannotation.h.

◆ render()

void QgsAnnotation::render ( QgsRenderContext context) const

Renders the annotation to a target render context.

Definition at line 131 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, QgsFormAnnotation, QgsTextAnnotation, and QgsSvgAnnotation.

◆ 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 178 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 119 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 125 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 79 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 90 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 99 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 110 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 51 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 172 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 61 of file qgsannotation.cpp.

◆ setMapPositionCrs()

void QgsAnnotation::setMapPositionCrs ( const QgsCoordinateReferenceSystem crs)

Sets the CRS of the map position.

See also
mapPositionCrs()

Definition at line 67 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 166 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 73 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 42 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, QgsFormAnnotation, QgsTextAnnotation, and QgsSvgAnnotation.

Property Documentation

◆ frameSize

QSizeF QgsAnnotation::frameSize
readwrite

Definition at line 70 of file qgsannotation.h.

◆ hasFixedMapPosition

bool QgsAnnotation::hasFixedMapPosition
readwrite

Definition at line 68 of file qgsannotation.h.

◆ mapPosition

QgsPointXY QgsAnnotation::mapPosition
readwrite

Definition at line 69 of file qgsannotation.h.

◆ visible

bool QgsAnnotation::visible
readwrite

Definition at line 67 of file qgsannotation.h.


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