/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/annotations/qgsannotationitem.h                             *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/





class QgsAnnotationItem
{
%Docstring(signature="appended")
Abstract base class for annotation items which are drawn with
:py:class:`QgsAnnotationLayers`.

.. versionadded:: 3.16
%End

%TypeHeaderCode
#include "qgsannotationitem.h"
%End
%ConvertToSubClassCode
    if ( sipCpp->type() == QLatin1String( "marker" ) )
    {
      sipType = sipType_QgsAnnotationMarkerItem;
    }
    else if ( sipCpp->type() == QLatin1String( "linestring" ) )
    {
      sipType = sipType_QgsAnnotationLineItem;
    }
    else if ( sipCpp->type() == QLatin1String( "polygon" ) )
    {
      sipType = sipType_QgsAnnotationPolygonItem;
    }
    else if ( sipCpp->type() == QLatin1String( "pointtext" ) )
    {
      sipType = sipType_QgsAnnotationPointTextItem;
    }
    else if ( sipCpp->type() == QLatin1String( "linetext" ) )
    {
      sipType = sipType_QgsAnnotationLineTextItem;
    }
    else if ( sipCpp->type() == QLatin1String( "recttext" ) )
    {
      sipType = sipType_QgsAnnotationRectangleTextItem;
    }
    else if ( sipCpp->type() == QLatin1String( "picture" ) )
    {
      sipType = sipType_QgsAnnotationPictureItem;
    }
    else
    {
      sipType = 0;
    }
%End
  public:

    QgsAnnotationItem();


    virtual ~QgsAnnotationItem();

    virtual Qgis::AnnotationItemFlags flags() const;
%Docstring
Returns item flags.

.. versionadded:: 3.22
%End

    virtual QgsAnnotationItem *clone() const = 0 /Factory/;
%Docstring
Returns a clone of the item. Ownership is transferred to the caller.

Implementations should include a call to
:py:func:`~QgsAnnotationItem.copyCommonProperties` to copy the base
class properties.

.. seealso:: :py:func:`copyCommonProperties`
%End

    virtual QString type() const = 0;
%Docstring
Returns a unique (untranslated) string identifying the type of item.
%End

    virtual QgsRectangle boundingBox() const = 0;
%Docstring
Returns the bounding box of the item's geographic location, in the
parent layer's coordinate reference system.
%End

    virtual QgsRectangle boundingBox( QgsRenderContext &context ) const;
%Docstring
Returns the bounding box of the item's geographic location, in the
parent layer's coordinate reference system.
%End

    virtual void render( QgsRenderContext &context, QgsFeedback *feedback ) = 0;
%Docstring
Renders the item to the specified render ``context``.

The ``feedback`` argument can be used to detect render cancellations
during expensive render operations.
%End

    virtual bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const = 0;
%Docstring
Writes the item's state into an XML ``element``.

Implementations should include a call to
:py:func:`~QgsAnnotationItem.writeCommonProperties` to store the base
class properties.

.. seealso:: :py:func:`readXml`

.. seealso:: :py:func:`writeCommonProperties`
%End

    virtual bool readXml( const QDomElement &element, const QgsReadWriteContext &context ) = 0;
%Docstring
Reads the item's state from the given DOM ``element``.

Implementations should include a call to
:py:func:`~QgsAnnotationItem.readCommonProperties` to read the base
class properties.

.. seealso:: :py:func:`writeXml`

.. seealso:: :py:func:`readCommonProperties`
%End

 virtual Qgis::AnnotationItemEditOperationResult applyEdit( QgsAbstractAnnotationItemEditOperation *operation ) /Deprecated/;
%Docstring
Applies an edit ``operation`` to the item.

.. deprecated:: 3.40

   Use :py:func:`~QgsAnnotationItem.applyEditV2` instead.
%End

    virtual Qgis::AnnotationItemEditOperationResult applyEditV2( QgsAbstractAnnotationItemEditOperation *operation, const QgsAnnotationItemEditContext &context );
%Docstring
Applies an edit ``operation`` to the item.

.. versionadded:: 3.40
%End

 virtual QgsAnnotationItemEditOperationTransientResults *transientEditResults( QgsAbstractAnnotationItemEditOperation *operation ) /Factory/;
%Docstring
Retrieves the results of a transient (in progress) edit ``operation`` on
the item.

.. deprecated:: 3.40

   Use :py:func:`~QgsAnnotationItem.transientEditResultsV2` instead.
%End

    virtual QgsAnnotationItemEditOperationTransientResults *transientEditResultsV2( QgsAbstractAnnotationItemEditOperation *operation, const QgsAnnotationItemEditContext &context ) /Factory/;
%Docstring
Retrieves the results of a transient (in progress) edit ``operation`` on
the item.

.. versionadded:: 3.40
%End

    int zIndex() const;
%Docstring
Returns the item's z index, which controls the order in which annotation
items are rendered in the layer.

.. seealso:: :py:func:`setZIndex`
%End

    void setZIndex( int index );
%Docstring
Sets the item's z ``index``, which controls the order in which
annotation items are rendered in the layer.

.. seealso:: :py:func:`zIndex`
%End

    bool enabled() const;
%Docstring
Returns ``True`` if the item is enabled and will be rendered in the
layer.

.. seealso:: :py:func:`setEnabled`

.. versionadded:: 3.36
%End

    void setEnabled( bool enabled );
%Docstring
Sets if the item will be rendered or not in the layer.

.. seealso:: :py:func:`enabled`

.. versionadded:: 3.36
%End

 virtual QList< QgsAnnotationItemNode > nodes() const /Deprecated/;
%Docstring
Returns the nodes for the item, used for editing the item.

.. deprecated:: 3.40

   Use :py:func:`~QgsAnnotationItem.nodesV2` instead.
%End

    virtual QList< QgsAnnotationItemNode > nodesV2( const QgsAnnotationItemEditContext &context ) const;
%Docstring
Returns the nodes for the item, used for editing the item.

.. versionadded:: 3.40
%End

    bool useSymbologyReferenceScale() const;
%Docstring
Returns ``True`` if the annotation item uses a symbology reference
scale.

.. seealso:: :py:func:`setUseSymbologyReferenceScale`

.. seealso:: :py:func:`symbologyReferenceScale`
%End

    void setUseSymbologyReferenceScale( bool enabled );
%Docstring
Sets whether the annotation item uses a symbology reference scale.

.. seealso:: :py:func:`useSymbologyReferenceScale`

.. seealso:: :py:func:`setSymbologyReferenceScale`
%End

    double symbologyReferenceScale() const;
%Docstring
Returns the annotation's symbology reference scale.

The reference scale will only be used if
:py:func:`~QgsAnnotationItem.useSymbologyReferenceScale` returns
``True``.

This represents the desired scale denominator for the rendered map, eg
1000.0 for a 1:1000 map render.

The symbology reference scale is an optional property which specifies
the reference scale at which symbology in paper units (such a
millimeters or points) is fixed to. For instance, if the scale is 1000
then a 2mm thick line will be rendered at exactly 2mm thick when a map
is rendered at 1:1000, or 1mm thick when rendered at 1:2000, or 4mm
thick at 1:500.

.. seealso:: :py:func:`setSymbologyReferenceScale`

.. seealso:: :py:func:`useSymbologyReferenceScale`
%End

    void setSymbologyReferenceScale( double scale );
%Docstring
Sets the annotation's symbology reference ``scale``.

The reference scale will only be used if
:py:func:`~QgsAnnotationItem.useSymbologyReferenceScale` returns
``True``.

This represents the desired scale denominator for the rendered map, eg
1000.0 for a 1:1000 map render.

The symbology reference scale is an optional property which specifies
the reference scale at which symbology in paper units (such a
millimeters or points) is fixed to. For instance, if the scale is 1000
then a 2mm thick line will be rendered at exactly 2mm thick when a map
is rendered at 1:1000, or 1mm thick when rendered at 1:2000, or 4mm
thick at 1:500.

.. seealso:: :py:func:`symbologyReferenceScale`

.. seealso:: :py:func:`setUseSymbologyReferenceScale`
%End

    QgsCallout *callout() const;
%Docstring
Returns the item's callout renderer, responsible for drawing item
callouts.

Ownership is not transferred.

By default items do not have a callout, and it is necessary to be
explicitly set a callout style (via
:py:func:`~QgsAnnotationItem.setCallout` ) and set the callout anchor
geometry (via set :py:func:`~QgsAnnotationItem.setCalloutAnchor` ).

.. note::

   Callouts are only supported by items which return :py:class:`Qgis`.AnnotationItemFlag.SupportsCallouts from :py:func:`~QgsAnnotationItem.flags`.

.. seealso:: :py:func:`setCallout`

.. seealso:: :py:func:`calloutAnchor`

.. versionadded:: 3.40
%End

    void setCallout( QgsCallout *callout /Transfer/ );
%Docstring
Sets the item's ``callout`` renderer, responsible for drawing item
callouts.

Ownership of ``callout`` is transferred to the item.

.. note::

   Callouts are only supported by items which return :py:class:`Qgis`.AnnotationItemFlag.SupportsCallouts from :py:func:`~QgsAnnotationItem.flags`.

.. seealso:: :py:func:`callout`

.. seealso:: :py:func:`setCalloutAnchor`

.. versionadded:: 3.40
%End

    QgsGeometry calloutAnchor() const;
%Docstring
Returns the callout's anchor geometry.

The anchor dictates the geometry which the option item
:py:func:`~QgsAnnotationItem.callout` should connect to. Depending on
the callout subclass and anchor geometry type, the actual shape of the
rendered callout may vary.

The callout anchor geometry is in the parent layer's coordinate
reference system.

.. seealso:: :py:func:`callout`

.. seealso:: :py:func:`setCalloutAnchor`

.. versionadded:: 3.40
%End

    void setCalloutAnchor( const QgsGeometry &anchor );
%Docstring
Sets the callout's ``anchor`` geometry.

The anchor dictates the geometry which the option item
:py:func:`~QgsAnnotationItem.callout` should connect to. Depending on
the callout subclass and anchor geometry type, the actual shape of the
rendered callout may vary.

The callout ``anchor`` geometry must be specified in the parent layer's
coordinate reference system.

.. seealso:: :py:func:`setCallout`

.. seealso:: :py:func:`calloutAnchor`

.. versionadded:: 3.40
%End

    QSizeF offsetFromCallout() const;
%Docstring
Returns the (optional) offset of the annotation item from the
:py:func:`~QgsAnnotationItem.calloutAnchor`.

Some annotation item subclasses support placement relative to the
callout anchor. For these items, the offset from callout defines how far
(in screen/page units) the item should be placed from the anchor point.

Units are defined by :py:func:`~QgsAnnotationItem.offsetFromCalloutUnit`

.. seealso:: :py:func:`setOffsetFromCallout`

.. versionadded:: 3.40
%End

    void setOffsetFromCallout( const QSizeF &offset );
%Docstring
Sets the offset of the annotation item from the
:py:func:`~QgsAnnotationItem.calloutAnchor`.

Some annotation item subclasses support placement relative to the
callout anchor. For these items, the offset from callout defines how far
(in screen/page units) the item should be placed from the anchor point.

Units are defined by :py:func:`~QgsAnnotationItem.offsetFromCalloutUnit`

.. seealso:: :py:func:`offsetFromCallout`

.. versionadded:: 3.40
%End

    Qgis::RenderUnit offsetFromCalloutUnit() const;
%Docstring
Returns the units for the
:py:func:`~QgsAnnotationItem.offsetFromCallout`.

.. seealso:: :py:func:`offsetFromCallout`

.. seealso:: :py:func:`setOffsetFromCalloutUnit`

.. versionadded:: 3.40
%End

    void setOffsetFromCalloutUnit( Qgis::RenderUnit unit );
%Docstring
Sets the ``unit`` for the
:py:func:`~QgsAnnotationItem.offsetFromCallout`.

.. seealso:: :py:func:`setOffsetFromCallout`

.. seealso:: :py:func:`offsetFromCalloutUnit`

.. versionadded:: 3.40
%End

  protected:

    virtual void copyCommonProperties( const QgsAnnotationItem *other );
%Docstring
Copies common properties from the base class from an ``other`` item.

.. versionadded:: 3.22
%End

    virtual bool writeCommonProperties( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
%Docstring
Writes common properties from the base class into an XML ``element``.

.. seealso:: :py:func:`writeXml`

.. versionadded:: 3.22
%End

    virtual bool readCommonProperties( const QDomElement &element, const QgsReadWriteContext &context );
%Docstring
Reads common properties from the base class from the given DOM
``element``.

.. seealso:: :py:func:`readXml`

.. versionadded:: 3.22
%End

    void renderCallout( QgsRenderContext &context, const QRectF &rect, double angle, QgsCallout::QgsCalloutContext &calloutContext, QgsFeedback *feedback );
%Docstring
Renders the item's callout.

The item must have valid :py:func:`~QgsAnnotationItem.callout` set.

.. versionadded:: 3.40
%End

  private:
    QgsAnnotationItem( const QgsAnnotationItem &other );
};

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/annotations/qgsannotationitem.h                             *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/