QGIS API Documentation  3.21.0-Master (5b68dc587e)
qgsannotationitemguiregistry.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsannotationitemguiregistry.h
3  --------------------------
4  begin : September 2021
5  copyright : (C) 2021 by Nyall Dawson
6  email : nyall dot dawson at gmail dot com
7  ***************************************************************************/
8 /***************************************************************************
9  * *
10  * This program is free software; you can redistribute it and/or modify *
11  * it under the terms of the GNU General Public License as published by *
12  * the Free Software Foundation; either version 2 of the License, or *
13  * (at your option) any later version. *
14  * *
15  ***************************************************************************/
16 #ifndef QGSANNOTATIONITEMGUIREGISTRY_H
17 #define QGSANNOTATIONITEMGUIREGISTRY_H
18 
19 #include "qgis_gui.h"
20 #include "qgis_sip.h"
21 #include "qgsapplication.h"
22 #include "qgspathresolver.h"
24 #include "qgis.h"
25 #include <QIcon>
26 #include <functional>
27 
28 class QgsAnnotationLayer;
29 class QgsAnnotationItem;
32 class QgsMapCanvas;
34 
46 {
47  public:
48 
56  QgsAnnotationItemAbstractGuiMetadata( const QString &type, const QString &visibleName, const QString &groupId = QString(), Qgis::AnnotationItemGuiFlags flags = Qgis::AnnotationItemGuiFlags() )
57  : mType( type )
58  , mGroupId( groupId )
59  , mName( visibleName )
60  , mFlags( flags )
61  {}
62 
64 
68  QString type() const { return mType; }
69 
73  Qgis::AnnotationItemGuiFlags flags() const { return mFlags; }
74 
78  QString groupId() const { return mGroupId; }
79 
83  QString visibleName() const { return mName; }
84 
88  virtual QIcon creationIcon() const;
89 
90  /*
91  * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
92  * the case.
93  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
94  *
95  * "
96  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
97  * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
98  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
99  * by Python so the /Factory/ on create() would be correct.)
100  *
101  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
102  * "
103  */
104 
108  virtual QgsAnnotationItemBaseWidget *createItemWidget( QgsAnnotationItem *item ) SIP_TRANSFERBACK;
109 
116 
120  virtual QgsAnnotationItem *createItem() SIP_TRANSFERBACK;
121 
128  virtual void newItemAddedToLayer( QgsAnnotationItem *item, QgsAnnotationLayer *layer );
129 
130  private:
131 
132  QString mType;
133  QString mGroupId;
134  QString mName;
135  Qgis::AnnotationItemGuiFlags mFlags;
136 
137 };
138 
141 
144 
147 
148 #ifndef SIP_RUN
149 
157 {
158  public:
159 
169  QgsAnnotationItemGuiMetadata( const QString &type, const QString &visibleName, const QIcon &creationIcon,
170  const QgsAnnotationItemWidgetFunc &pfWidget = nullptr,
171  const QString &groupId = QString(),
172  Qgis::AnnotationItemGuiFlags flags = Qgis::AnnotationItemGuiFlags(),
173  const QgsAnnotationItemCreateFunc &pfCreateFunc = nullptr,
174  const QgsCreateAnnotationItemMapToolFunc &pfCreateMapToolFunc = nullptr )
175  : QgsAnnotationItemAbstractGuiMetadata( type, visibleName, groupId, flags )
176  , mIcon( creationIcon )
177  , mWidgetFunc( pfWidget )
178  , mCreateFunc( pfCreateFunc )
179  , mCreateMapToolFunc( pfCreateMapToolFunc )
180  {}
181 
186  QgsAnnotationItemWidgetFunc widgetFunction() const { return mWidgetFunc; }
187 
192  void setWidgetFunction( const QgsAnnotationItemWidgetFunc &function ) { mWidgetFunc = function; }
193 
198  QgsCreateAnnotationItemMapToolFunc createMapToolFunction() const { return mCreateMapToolFunc; }
199 
204  void setCreateMapToolFunction( const QgsCreateAnnotationItemMapToolFunc &function ) { mCreateMapToolFunc = function; }
205 
210  QgsAnnotationItemCreateFunc itemCreationFunction() const { return mCreateFunc; }
211 
216  void setItemCreationFunction( const QgsAnnotationItemCreateFunc &function ) { mCreateFunc = function; }
217 
222  QgsAnnotationItemAddedToLayerFunc itemAddToLayerFunction() const { return mAddedToLayerFunc; }
223 
228  void setItemAddedToLayerFunction( const QgsAnnotationItemAddedToLayerFunc &function ) { mAddedToLayerFunc = function; }
229 
230  QIcon creationIcon() const override;
231  QgsAnnotationItemBaseWidget *createItemWidget( QgsAnnotationItem *item ) override;
232 
233  QgsAnnotationItem *createItem() override;
234  void newItemAddedToLayer( QgsAnnotationItem *item, QgsAnnotationLayer *layer ) override;
235  QgsCreateAnnotationItemMapToolInterface *createMapTool( QgsMapCanvas *canvas, QgsAdvancedDigitizingDockWidget *cadDockWidget ) override;
236 
237  protected:
238  QIcon mIcon;
239  QgsAnnotationItemWidgetFunc mWidgetFunc = nullptr;
240  QgsAnnotationItemCreateFunc mCreateFunc = nullptr;
241  QgsCreateAnnotationItemMapToolFunc mCreateMapToolFunc = nullptr;
242  QgsAnnotationItemAddedToLayerFunc mAddedToLayerFunc = nullptr;
243 
244 };
245 
246 #endif
247 
261 {
262  public:
263 
267  QgsAnnotationItemGuiGroup( const QString &id = QString(), const QString &name = QString(), const QIcon &icon = QIcon() )
268  : id( id )
269  , name( name )
270  , icon( icon )
271  {}
272 
276  QString id;
277 
281  QString name;
282 
286  QIcon icon;
287 
288 };
289 
290 
304 class GUI_EXPORT QgsAnnotationItemGuiRegistry : public QObject
305 {
306  Q_OBJECT
307 
308  public:
309 
316  QgsAnnotationItemGuiRegistry( QObject *parent = nullptr );
317 
318  ~QgsAnnotationItemGuiRegistry() override;
319 
324 
329  QgsAnnotationItemAbstractGuiMetadata *itemMetadata( int metadataId ) const;
330 
339  int metadataIdForItemType( const QString &type ) const;
340 
344  bool addAnnotationItemGuiMetadata( QgsAnnotationItemAbstractGuiMetadata *metadata SIP_TRANSFER );
345 
355  bool addItemGroup( const QgsAnnotationItemGuiGroup &group );
356 
361  const QgsAnnotationItemGuiGroup &itemGroup( const QString &id );
362 
363  /*
364  * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
365  * the case.
366  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
367  *
368  * "
369  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
370  * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
371  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
372  * by Python so the /Factory/ on create() would be correct.)
373  *
374  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
375  * "
376  */
377 
381  QgsAnnotationItem *createItem( int metadataId ) const SIP_TRANSFERBACK;
382 
389  void newItemAddedToLayer( int metadataId, QgsAnnotationItem *item, QgsAnnotationLayer *layer );
390 
391  /*
392  * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
393  * the case.
394  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
395  *
396  * "
397  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
398  * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
399  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
400  * by Python so the /Factory/ on create() would be correct.)
401  *
402  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
403  * "
404  */
405 
409  QgsAnnotationItemBaseWidget *createItemWidget( QgsAnnotationItem *item ) const SIP_TRANSFERBACK;
410 
414  QList< int > itemMetadataIds() const;
415 
419  void addDefaultItems();
420 
421  signals:
422 
427  void typeAdded( int metadataId );
428 
429  private:
430 #ifdef SIP_RUN
432 #endif
433 
434  QMap< int, QgsAnnotationItemAbstractGuiMetadata *> mMetadata;
435 
436  QMap< QString, QgsAnnotationItemGuiGroup > mItemGroups;
437 
438 };
439 
440 #endif //QGSANNOTATIONITEMGUIREGISTRY_H
441 
442 
443 
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:63
The QgsAdvancedDigitizingDockWidget class is a dockable widget used to handle the CAD tools on top of...
Stores GUI metadata about one annotation item class.
QString groupId() const
Returns the item group ID, if set.
virtual ~QgsAnnotationItemAbstractGuiMetadata()=default
QString type() const
Returns the unique item type code for the annotation item class.
QgsAnnotationItemAbstractGuiMetadata(const QString &type, const QString &visibleName, const QString &groupId=QString(), Qgis::AnnotationItemGuiFlags flags=Qgis::AnnotationItemGuiFlags())
Constructor for QgsAnnotationItemAbstractGuiMetadata with the specified class type.
QString visibleName() const
Returns a translated, user visible name identifying the corresponding annotation item.
Qgis::AnnotationItemGuiFlags flags() const
Returns item flags.
A base class for property widgets for annotation items.
Stores GUI metadata about a group of annotation item classes.
QgsAnnotationItemGuiGroup(const QString &id=QString(), const QString &name=QString(), const QIcon &icon=QIcon())
Constructor for QgsAnnotationItemGuiGroup.
QString name
Translated group name.
QString id
Unique (untranslated) group ID string.
Convenience metadata class that uses static functions to handle annotation item GUI behavior.
void setCreateMapToolFunction(const QgsCreateAnnotationItemMapToolFunc &function)
Sets the classes' create new item map tool creation function.
QgsAnnotationItemGuiMetadata(const QString &type, const QString &visibleName, const QIcon &creationIcon, const QgsAnnotationItemWidgetFunc &pfWidget=nullptr, const QString &groupId=QString(), Qgis::AnnotationItemGuiFlags flags=Qgis::AnnotationItemGuiFlags(), const QgsAnnotationItemCreateFunc &pfCreateFunc=nullptr, const QgsCreateAnnotationItemMapToolFunc &pfCreateMapToolFunc=nullptr)
Constructor for QgsAnnotationItemGuiMetadata with the specified class type and creationIcon,...
QgsAnnotationItemCreateFunc itemCreationFunction() const
Returns the classes' item creation function.
QgsCreateAnnotationItemMapToolFunc createMapToolFunction() const
Returns the classes' create new item map tool creation function.
QgsAnnotationItemWidgetFunc widgetFunction() const
Returns the classes' configuration widget creation function.
void setItemCreationFunction(const QgsAnnotationItemCreateFunc &function)
Sets the classes' item creation function.
void setWidgetFunction(const QgsAnnotationItemWidgetFunc &function)
Sets the classes' configuration widget creation function.
QgsAnnotationItemAddedToLayerFunc itemAddToLayerFunction() const
Returns the classes' item added to layer function.
void setItemAddedToLayerFunction(const QgsAnnotationItemAddedToLayerFunc &function)
Sets the classes' item creation function.
Registry of available annotation item GUI behavior.
QgsAnnotationItemGuiRegistry(const QgsAnnotationItemGuiRegistry &rh)=delete
QgsAnnotationItemGuiRegistry cannot be copied.
void typeAdded(int metadataId)
Emitted whenever a new item type is added to the registry, with the specified metadataId.
QgsAnnotationItemGuiRegistry & operator=(const QgsAnnotationItemGuiRegistry &rh)=delete
QgsAnnotationItemGuiRegistry cannot be copied.
Abstract base class for annotation items which are drawn with QgsAnnotationLayers.
Represents a map layer containing a set of georeferenced annotations, e.g.
An interface for map tools which create annotation items.
Map canvas is a class for displaying all GIS data types on a canvas.
Definition: qgsmapcanvas.h:88
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_TRANSFER
Definition: qgis_sip.h:36
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:48
std::function< QgsCreateAnnotationItemMapToolInterface *(QgsMapCanvas *, QgsAdvancedDigitizingDockWidget *)> QgsCreateAnnotationItemMapToolFunc
Create annotation map tool creation function.
std::function< void(QgsAnnotationItem *, QgsAnnotationLayer *layer)> QgsAnnotationItemAddedToLayerFunc
Annotation item added to layer callback.
std::function< QgsAnnotationItemBaseWidget *(QgsAnnotationItem *)> QgsAnnotationItemWidgetFunc
Annotation item configuration widget creation function.
std::function< QgsAnnotationItem *()> QgsAnnotationItemCreateFunc
Annotation item creation function.