[api] Create annotation item gui registry

This registry is attached to QgsGui and handles registration of
functions which create widgets for modifying QgsAnnotationItems

Modeled heavily off the print layout API

python/core/auto_additions/qgis.py

@@ -663,6 +663,11 @@
 # --
 Qgis.AnnotationItemFlag.baseClass = Qgis
 # monkey patching scoped based enum
+Qgis.AnnotationItemGuiFlag.FlagNoCreationTools.__doc__ = "Do not show item creation tools for the item type"
+Qgis.AnnotationItemGuiFlag.__doc__ = 'Flags for controlling how an annotation item behaves in the GUI.\n\n.. versionadded:: 3.22\n\n' + '* ``FlagNoCreationTools``: ' + Qgis.AnnotationItemGuiFlag.FlagNoCreationTools.__doc__
+# --
+Qgis.AnnotationItemGuiFlag.baseClass = Qgis
+# monkey patching scoped based enum
 Qgis.AnnotationItemNodeType.VertexHandle.__doc__ = "Node is a handle for manipulating vertices"
 Qgis.AnnotationItemNodeType.__doc__ = 'Annotation item node types.\n\n.. versionadded:: 3.22\n\n' + '* ``VertexHandle``: ' + Qgis.AnnotationItemNodeType.VertexHandle.__doc__
 # --

python/core/auto_generated/qgis.sip.in

@@ -480,6 +480,13 @@ The development version
     typedef QFlags<Qgis::AnnotationItemFlag> AnnotationItemFlags;
 
 
+    enum class AnnotationItemGuiFlag
+    {
+      FlagNoCreationTools,
+    };
+    typedef QFlags<Qgis::AnnotationItemGuiFlag> AnnotationItemGuiFlags;
+
+
     enum class AnnotationItemNodeType
     {
       VertexHandle,
@@ -574,6 +581,8 @@ QFlags<Qgis::FileOperationFlag> operator|(Qgis::FileOperationFlag f1, QFlags<Qgi
 
 QFlags<Qgis::AnnotationItemFlag> operator|(Qgis::AnnotationItemFlag f1, QFlags<Qgis::AnnotationItemFlag> f2);
 
+QFlags<Qgis::AnnotationItemGuiFlag> operator|(Qgis::AnnotationItemGuiFlag f1, QFlags<Qgis::AnnotationItemGuiFlag> f2);
+
 
 
 

python/gui/auto_generated/annotations/qgsannotationitemguiregistry.sip.in

@@ -0,0 +1,244 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/annotations/qgsannotationitemguiregistry.h                   *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+class QgsAnnotationItemAbstractGuiMetadata
+{
+%Docstring(signature="appended")
+Stores GUI metadata about one annotation item class.
+
+This is a companion to :py:class:`QgsAnnotationItemAbstractMetadata`, storing only
+the components related to the GUI behavior of an annotation item.
+
+.. note::
+
+   In C++ you can use :py:class:`QgsAnnotationItemGuiMetadata` convenience class.
+
+.. versionadded:: 3.22
+%End
+
+%TypeHeaderCode
+#include "qgsannotationitemguiregistry.h"
+%End
+  public:
+
+    QgsAnnotationItemAbstractGuiMetadata( const QString &type, const QString &visibleName, const QString &groupId = QString(), Qgis::AnnotationItemGuiFlags flags = Qgis::AnnotationItemGuiFlags() );
+%Docstring
+Constructor for QgsAnnotationItemAbstractGuiMetadata with the specified class ``type``.
+
+``visibleName`` should be set to a translated, user visible name identifying the corresponding annotation item.
+
+An optional ``groupId`` can be set, which allows grouping of related annotation item classes. See :py:class:`QgsAnnotationItemGuiMetadata` for details.
+%End
+
+    virtual ~QgsAnnotationItemAbstractGuiMetadata();
+
+    QString type() const;
+%Docstring
+Returns the unique item type code for the annotation item class.
+%End
+
+    Qgis::AnnotationItemGuiFlags flags() const;
+%Docstring
+Returns item flags.
+%End
+
+    QString groupId() const;
+%Docstring
+Returns the item group ID, if set.
+%End
+
+    QString visibleName() const;
+%Docstring
+Returns a translated, user visible name identifying the corresponding annotation item.
+%End
+
+    virtual QIcon creationIcon() const;
+%Docstring
+Returns an icon representing creation of the annotation item type.
+%End
+
+
+    virtual QgsAnnotationItemBaseWidget *createItemWidget( QgsAnnotationItem *item ) /TransferBack/;
+%Docstring
+Creates a configuration widget for an ``item`` of this type. Can return ``None`` if no configuration GUI is required.
+%End
+
+    virtual QgsAnnotationItem *createItem() /TransferBack/;
+%Docstring
+Creates an instance of the corresponding item type.
+%End
+
+    virtual void newItemAddedToLayer( QgsAnnotationItem *item, QgsAnnotationLayer *layer );
+%Docstring
+Called when a newly created item of the associated type has been added to a ``layer``.
+
+This is only called for additions which result from GUI operations - i.e. it is not
+called for items added programmatically.
+%End
+
+};
+
+
+
+
+class QgsAnnotationItemGuiGroup
+{
+%Docstring(signature="appended")
+Stores GUI metadata about a group of annotation item classes.
+
+:py:class:`QgsAnnotationItemGuiGroup` stores settings about groups of related annotation item classes
+which should be presented to users grouped together.
+
+For instance, the various basic shape creation tools would use :py:class:`QgsAnnotationItemGuiGroup`
+to display grouped within toolbars.
+
+.. versionadded:: 3.22
+%End
+
+%TypeHeaderCode
+#include "qgsannotationitemguiregistry.h"
+%End
+  public:
+
+    QgsAnnotationItemGuiGroup( const QString &id = QString(), const QString &name = QString(), const QIcon &icon = QIcon() );
+%Docstring
+Constructor for QgsAnnotationItemGuiGroup.
+%End
+
+    QString id;
+
+    QString name;
+
+    QIcon icon;
+
+};
+
+
+class QgsAnnotationItemGuiRegistry : QObject
+{
+%Docstring(signature="appended")
+Registry of available annotation item GUI behavior.
+
+:py:class:`QgsAnnotationItemGuiRegistry` is not usually directly created, but rather accessed through
+:py:func:`QgsGui.annotationItemGuiRegistry()`.
+
+This acts as a companion to :py:class:`QgsAnnotationItemRegistry`, handling only
+the components related to the GUI behavior of annotation items.
+
+.. versionadded:: 3.22
+%End
+
+%TypeHeaderCode
+#include "qgsannotationitemguiregistry.h"
+%End
+  public:
+
+    QgsAnnotationItemGuiRegistry( QObject *parent = 0 );
+%Docstring
+Creates a new empty item GUI registry.
+
+QgsAnnotationItemGuiRegistry is not usually directly created, but rather accessed through
+:py:func:`QgsGui.annotationItemGuiRegistry()`.
+%End
+
+    ~QgsAnnotationItemGuiRegistry();
+
+
+    QgsAnnotationItemAbstractGuiMetadata *itemMetadata( int metadataId ) const;
+%Docstring
+Returns the metadata for the specified item ``metadataId``. Returns ``None`` if
+a corresponding ``metadataId`` was not found in the registry.
+%End
+
+    int metadataIdForItemType( const QString &type ) const;
+%Docstring
+Returns the GUI item metadata ID which corresponds to the specified annotation item ``type``.
+
+In the case that multiple GUI metadata classes exist for a single annotation item ``type`` then
+only the first encountered GUI metadata ID will be returned.
+
+Returns -1 if no matching metadata is found in the GUI registry.
+%End
+
+    bool addAnnotationItemGuiMetadata( QgsAnnotationItemAbstractGuiMetadata *metadata /Transfer/ );
+%Docstring
+Registers the gui metadata for a new annotation item type. Takes ownership of the metadata instance.
+%End
+
+    bool addItemGroup( const QgsAnnotationItemGuiGroup &group );
+%Docstring
+Registers a new item group with the registry. This must be done before calling
+:py:func:`~QgsAnnotationItemGuiRegistry.addAnnotationItemGuiMetadata` for any item types associated with the group.
+
+Returns ``True`` if group was added, or ``False`` if group could not be added (e.g. due to
+duplicate id value).
+
+.. seealso:: :py:func:`itemGroup`
+%End
+
+    const QgsAnnotationItemGuiGroup &itemGroup( const QString &id );
+%Docstring
+Returns a reference to the item group with matching ``id``.
+
+.. seealso:: :py:func:`addItemGroup`
+%End
+
+
+    QgsAnnotationItem *createItem( int metadataId ) const /TransferBack/;
+%Docstring
+Creates a new instance of an annotation item given the item metadata ``metadataId``.
+%End
+
+    void newItemAddedToLayer( int metadataId, QgsAnnotationItem *item, QgsAnnotationLayer *layer );
+%Docstring
+Called when a newly created item of the associated metadata ``metadataId`` has been added to a ``layer``.
+
+This is only called for additions which result from GUI operations - i.e. it is not
+called for items added programmatically.
+%End
+
+
+    QgsAnnotationItemBaseWidget *createItemWidget( QgsAnnotationItem *item ) const /TransferBack/;
+%Docstring
+Creates a new instance of an annotation item configuration widget for the specified ``item``.
+%End
+
+    QList< int > itemMetadataIds() const;
+%Docstring
+Returns a list of available item metadata ids handled by the registry.
+%End
+
+    void addDefaultItems();
+%Docstring
+Populates the registry with default items.
+%End
+
+  signals:
+
+    void typeAdded( int metadataId );
+%Docstring
+Emitted whenever a new item type is added to the registry, with the specified
+``metadataId``.
+%End
+
+  private:
+    QgsAnnotationItemGuiRegistry( const QgsAnnotationItemGuiRegistry &rh );
+};
+
+
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/annotations/qgsannotationitemguiregistry.h                   *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/gui/auto_generated/annotations/qgsannotationitemwidget.sip.in

@@ -0,0 +1,76 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/annotations/qgsannotationitemwidget.h                        *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+class QgsAnnotationItemBaseWidget: QgsPanelWidget
+{
+%Docstring(signature="appended")
+
+A base class for property widgets for annotation items.
+
+All annotation item widgets should inherit from this base class.
+
+.. versionadded:: 3.22
+%End
+
+%TypeHeaderCode
+#include "qgsannotationitemwidget.h"
+%End
+  public:
+
+    QgsAnnotationItemBaseWidget( QWidget *parent /TransferThis/ );
+%Docstring
+Constructor for QgsAnnotationItemBaseWidget, linked with the specified annotation ``item``.
+%End
+
+    virtual QgsAnnotationItem *createItem() = 0 /Factory/;
+%Docstring
+Creates a new item matching the settings defined in the widget.
+%End
+
+    bool setItem( QgsAnnotationItem *item );
+%Docstring
+Sets the current ``item`` to show in the widget. If ``True`` is returned, ``item``
+was an acceptable type for display in this widget and the widget has been
+updated to match ``item``'s properties.
+
+If ``False`` is returned, then the widget could not be successfully updated
+to show the properties of ``item``.
+%End
+
+
+  signals:
+
+    void itemChanged();
+%Docstring
+Emitted when the annotation item definition in the widget is changed by the user.
+%End
+
+  protected:
+
+    virtual bool setNewItem( QgsAnnotationItem *item );
+%Docstring
+Attempts to update the widget to show the properties
+for the specified ``item``.
+
+Subclasses can override this if they support changing items in place.
+
+Implementations must return ``True`` if the item was accepted and
+the widget was updated.
+%End
+
+};
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/annotations/qgsannotationitemwidget.h                        *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/gui/auto_generated/qgsgui.sip.in

@@ -73,6 +73,13 @@ Returns the global map layer action registry, used for registering map layer act
     static QgsLayoutItemGuiRegistry *layoutItemGuiRegistry() /KeepReference/;
 %Docstring
 Returns the global layout item GUI registry, used for registering the GUI behavior of layout items.
+%End
+
+    static QgsAnnotationItemGuiRegistry *annotationItemGuiRegistry() /KeepReference/;
+%Docstring
+Returns the global annotation item GUI registry, used for registering the GUI behavior of annotation items.
+
+.. versionadded:: 3.22
 %End
 
     static QgsProcessingGuiRegistry *processingGuiRegistry() /KeepReference/;

python/gui/gui_auto.sip

@@ -224,6 +224,8 @@
 %Include auto_generated/qgsvertexmarker.sip
 %Include auto_generated/qgsvscrollarea.sip
 %Include auto_generated/qgswindowmanagerinterface.sip
+%Include auto_generated/annotations/qgsannotationitemguiregistry.sip
+%Include auto_generated/annotations/qgsannotationitemwidget.sip
 %Include auto_generated/annotations/qgsmaptoolmodifyannotation.sip
 %Include auto_generated/attributetable/qgsattributetabledelegate.sip
 %Include auto_generated/attributetable/qgsattributetablefiltermodel.sip