QGIS API Documentation  3.21.0-Master (5b68dc587e)
qgslayoutitemguiregistry.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgslayoutitemguiregistry.h
3  --------------------------
4  begin : June 2017
5  copyright : (C) 2017 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 QGSLAYOUTITEMGUIREGISTRY_H
17 #define QGSLAYOUTITEMGUIREGISTRY_H
18 
19 #include "qgis_gui.h"
20 #include "qgis_sip.h"
21 #include "qgsapplication.h"
22 #include "qgspathresolver.h"
23 #include "qgslayoutitemregistry.h"
24 #include <QGraphicsItem> //for QGraphicsItem::UserType
25 #include <QIcon>
26 #include <functional>
27 
28 #include "qgslayoutitem.h" // temporary
29 
30 class QgsLayout;
31 class QgsLayoutView;
32 class QgsLayoutItem;
35 
47 {
48  public:
49 
51  enum Flag
52  {
53  FlagNoCreationTools = 1 << 1,
54  };
55  Q_DECLARE_FLAGS( Flags, Flag )
56 
57 
66  QgsLayoutItemAbstractGuiMetadata( int type, const QString &visibleName, const QString &groupId = QString(), bool isNodeBased = false, Flags flags = QgsLayoutItemAbstractGuiMetadata::Flags() )
67  : mType( type )
68  , mGroupId( groupId )
69  , mIsNodeBased( isNodeBased )
70  , mName( visibleName )
71  , mFlags( flags )
72  {}
73 
74  virtual ~QgsLayoutItemAbstractGuiMetadata() = default;
75 
79  int type() const { return mType; }
80 
84  Flags flags() const { return mFlags; }
85 
89  QString groupId() const { return mGroupId; }
90 
94  bool isNodeBased() const { return mIsNodeBased; }
95 
99  QString visibleName() const { return mName; }
100 
104  virtual QIcon creationIcon() const { return QgsApplication::getThemeIcon( QStringLiteral( "/mActionAddBasicRectangle.svg" ) ); }
105 
106  /*
107  * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
108  * the case.
109  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
110  *
111  * "
112  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
113  * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
114  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
115  * by Python so the /Factory/ on create() would be correct.)
116  *
117  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
118  * "
119  */
120 
124  virtual QgsLayoutItemBaseWidget *createItemWidget( QgsLayoutItem *item ) SIP_TRANSFERBACK { Q_UNUSED( item ) return nullptr; }
125 
131  virtual QgsLayoutViewRubberBand *createRubberBand( QgsLayoutView *view ) SIP_TRANSFERBACK;
132 
138  virtual QAbstractGraphicsShapeItem *createNodeRubberBand( QgsLayoutView *view ) SIP_TRANSFERBACK;
139 
143  virtual QgsLayoutItem *createItem( QgsLayout *layout ) SIP_TRANSFERBACK;
144 
151  virtual void newItemAddedToLayout( QgsLayoutItem *item );
152 
153  private:
154 
155  int mType = -1;
156  QString mGroupId;
157  bool mIsNodeBased = false;
158  QString mName;
159  Flags mFlags;
160 
161 };
162 
165 
168 
170 typedef std::function<QAbstractGraphicsShapeItem *( QgsLayoutView * )> QgsLayoutNodeItemRubberBandFunc SIP_SKIP;
171 
173 typedef std::function<void ( QgsLayoutItem *, const QVariantMap & )> QgsLayoutItemAddedToLayoutFunc SIP_SKIP;
174 
175 #ifndef SIP_RUN
176 
184 {
185  public:
186 
198  QgsLayoutItemGuiMetadata( int type, const QString &visibleName, const QIcon &creationIcon,
199  const QgsLayoutItemWidgetFunc &pfWidget = nullptr,
200  const QgsLayoutItemRubberBandFunc &pfRubberBand = nullptr, const QString &groupId = QString(),
201  bool isNodeBased = false,
202  QgsLayoutItemAbstractGuiMetadata::Flags flags = QgsLayoutItemAbstractGuiMetadata::Flags(),
203  const QgsLayoutItemCreateFunc &pfCreateFunc = nullptr )
204  : QgsLayoutItemAbstractGuiMetadata( type, visibleName, groupId, isNodeBased, flags )
205  , mIcon( creationIcon )
206  , mWidgetFunc( pfWidget )
207  , mRubberBandFunc( pfRubberBand )
208  , mCreateFunc( pfCreateFunc )
209  {}
210 
215  QgsLayoutItemWidgetFunc widgetFunction() const { return mWidgetFunc; }
216 
221  void setWidgetFunction( const QgsLayoutItemWidgetFunc &function ) { mWidgetFunc = function; }
222 
227  QgsLayoutItemRubberBandFunc rubberBandCreationFunction() const { return mRubberBandFunc; }
228 
233  void setRubberBandCreationFunction( const QgsLayoutItemRubberBandFunc &function ) { mRubberBandFunc = function; }
234 
239  QgsLayoutNodeItemRubberBandFunc nodeRubberBandCreationFunction() const { return mNodeRubberBandFunc; }
240 
245  void setNodeRubberBandCreationFunction( const QgsLayoutNodeItemRubberBandFunc &function ) { mNodeRubberBandFunc = function; }
246 
251  QgsLayoutItemCreateFunc itemCreationFunction() const { return mCreateFunc; }
252 
257  void setItemCreationFunction( const QgsLayoutItemCreateFunc &function ) { mCreateFunc = function; }
258 
263  QgsLayoutItemAddedToLayoutFunc itemAddToLayoutFunction() const { return mAddedToLayoutFunc; }
264 
269  void setItemAddedToLayoutFunction( const QgsLayoutItemAddedToLayoutFunc &function ) { mAddedToLayoutFunc = function; }
270 
271  QIcon creationIcon() const override { return mIcon.isNull() ? QgsLayoutItemAbstractGuiMetadata::creationIcon() : mIcon; }
272  QgsLayoutItemBaseWidget *createItemWidget( QgsLayoutItem *item ) override { return mWidgetFunc ? mWidgetFunc( item ) : nullptr; }
273  QgsLayoutViewRubberBand *createRubberBand( QgsLayoutView *view ) override { return mRubberBandFunc ? mRubberBandFunc( view ) : nullptr; }
274  QAbstractGraphicsShapeItem *createNodeRubberBand( QgsLayoutView *view ) override { return mNodeRubberBandFunc ? mNodeRubberBandFunc( view ) : nullptr; }
275 
276  QgsLayoutItem *createItem( QgsLayout *layout ) override;
277  void newItemAddedToLayout( QgsLayoutItem *item ) override;
278 
290  void newItemAddedToLayout( QgsLayoutItem *item, const QVariantMap &properties );
291 
292  protected:
293  QIcon mIcon;
294  QgsLayoutItemWidgetFunc mWidgetFunc = nullptr;
295  QgsLayoutItemRubberBandFunc mRubberBandFunc = nullptr;
296  QgsLayoutNodeItemRubberBandFunc mNodeRubberBandFunc = nullptr;
297  QgsLayoutItemCreateFunc mCreateFunc = nullptr;
298  QgsLayoutItemAddedToLayoutFunc mAddedToLayoutFunc = nullptr;
299 
300 };
301 
302 #endif
303 
316 class GUI_EXPORT QgsLayoutItemGuiGroup
317 {
318  public:
319 
323  QgsLayoutItemGuiGroup( const QString &id = QString(), const QString &name = QString(), const QIcon &icon = QIcon() )
324  : id( id )
325  , name( name )
326  , icon( icon )
327  {}
328 
332  QString id;
333 
337  QString name;
338 
342  QIcon icon;
343 
344 };
345 
346 
360 class GUI_EXPORT QgsLayoutItemGuiRegistry : public QObject
361 {
362  Q_OBJECT
363 
364  public:
365 
372  QgsLayoutItemGuiRegistry( QObject *parent = nullptr );
373 
374  ~QgsLayoutItemGuiRegistry() override;
375 
380 
385  QgsLayoutItemAbstractGuiMetadata *itemMetadata( int metadataId ) const;
386 
397  int metadataIdForItemType( int type ) const;
398 
402  bool addLayoutItemGuiMetadata( QgsLayoutItemAbstractGuiMetadata *metadata SIP_TRANSFER );
403 
413  bool addItemGroup( const QgsLayoutItemGuiGroup &group );
414 
419  const QgsLayoutItemGuiGroup &itemGroup( const QString &id );
420 
421  /*
422  * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
423  * the case.
424  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
425  *
426  * "
427  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
428  * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
429  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
430  * by Python so the /Factory/ on create() would be correct.)
431  *
432  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
433  * "
434  */
435 
439  QgsLayoutItem *createItem( int metadataId, QgsLayout *layout ) const SIP_TRANSFERBACK;
440 
450  void newItemAddedToLayout( int metadataId, QgsLayoutItem *item, const QVariantMap &properties = QVariantMap() );
451 
452  /*
453  * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
454  * the case.
455  * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
456  *
457  * "
458  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
459  * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
460  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
461  * by Python so the /Factory/ on create() would be correct.)
462  *
463  * You might try using /TransferBack/ on create() instead - that might be the best compromise.
464  * "
465  */
466 
470  QgsLayoutItemBaseWidget *createItemWidget( QgsLayoutItem *item ) const SIP_TRANSFERBACK;
471 
477  QgsLayoutViewRubberBand *createItemRubberBand( int metadataId, QgsLayoutView *view ) const SIP_SKIP;
478 
485  QAbstractGraphicsShapeItem *createNodeItemRubberBand( int metadataId, QgsLayoutView *view ) SIP_SKIP;
486 
490  QList< int > itemMetadataIds() const;
491 
492  signals:
493 
498  void typeAdded( int metadataId );
499 
500  private:
501 #ifdef SIP_RUN
503 #endif
504 
505  QMap< int, QgsLayoutItemAbstractGuiMetadata *> mMetadata;
506 
507  QMap< QString, QgsLayoutItemGuiGroup > mItemGroups;
508 
509 };
510 
511 #endif //QGSLAYOUTITEMGUIREGISTRY_H
512 
513 
514 
static QIcon getThemeIcon(const QString &name, const QColor &fillColor=QColor(), const QColor &strokeColor=QColor())
Helper to get a theme icon.
Stores GUI metadata about one layout item class.
virtual ~QgsLayoutItemAbstractGuiMetadata()=default
QString groupId() const
Returns the item group ID, if set.
bool isNodeBased() const
Returns true if the associated item is a node based item.
int type() const
Returns the unique item type code for the layout item class.
QString visibleName() const
Returns a translated, user visible name identifying the corresponding layout item.
virtual QIcon creationIcon() const
Returns an icon representing creation of the layout item type.
Flags flags() const
Returns item flags.
Flag
Flags for controlling how a items behave in the GUI.
virtual QgsLayoutItemBaseWidget * createItemWidget(QgsLayoutItem *item)
Creates a configuration widget for an item of this type.
A base class for property widgets for layout items.
Stores GUI metadata about a group of layout item classes.
QString id
Unique (untranslated) group ID string.
QgsLayoutItemGuiGroup(const QString &id=QString(), const QString &name=QString(), const QIcon &icon=QIcon())
Constructor for QgsLayoutItemGuiGroup.
QString name
Translated group name.
Convenience metadata class that uses static functions to handle layout item GUI behavior.
QgsLayoutItemCreateFunc itemCreationFunction() const
Returns the classes' item creation function.
QgsLayoutViewRubberBand * createRubberBand(QgsLayoutView *view) override
Creates a rubber band for use when creating layout items of this type.
QgsLayoutItemAddedToLayoutFunc itemAddToLayoutFunction() const
Returns the classes' item added to layout function.
QgsLayoutItemWidgetFunc widgetFunction() const
Returns the classes' configuration widget creation function.
QgsLayoutItemBaseWidget * createItemWidget(QgsLayoutItem *item) override
Creates a configuration widget for an item of this type.
void setItemAddedToLayoutFunction(const QgsLayoutItemAddedToLayoutFunc &function)
Sets the classes' item creation function.
QAbstractGraphicsShapeItem * createNodeRubberBand(QgsLayoutView *view) override
Creates a rubber band for use when creating layout node based items of this type.
QgsLayoutItemGuiMetadata(int type, const QString &visibleName, const QIcon &creationIcon, const QgsLayoutItemWidgetFunc &pfWidget=nullptr, const QgsLayoutItemRubberBandFunc &pfRubberBand=nullptr, const QString &groupId=QString(), bool isNodeBased=false, QgsLayoutItemAbstractGuiMetadata::Flags flags=QgsLayoutItemAbstractGuiMetadata::Flags(), const QgsLayoutItemCreateFunc &pfCreateFunc=nullptr)
Constructor for QgsLayoutItemGuiMetadata with the specified class type and creationIcon,...
void setItemCreationFunction(const QgsLayoutItemCreateFunc &function)
Sets the classes' item creation function.
QgsLayoutNodeItemRubberBandFunc nodeRubberBandCreationFunction() const
Returns the classes' node based rubber band creation function.
QgsLayoutItemRubberBandFunc rubberBandCreationFunction() const
Returns the classes' rubber band creation function.
void setWidgetFunction(const QgsLayoutItemWidgetFunc &function)
Sets the classes' configuration widget creation function.
QIcon creationIcon() const override
Returns an icon representing creation of the layout item type.
void setRubberBandCreationFunction(const QgsLayoutItemRubberBandFunc &function)
Sets the classes' rubber band creation function.
void setNodeRubberBandCreationFunction(const QgsLayoutNodeItemRubberBandFunc &function)
Sets the classes' node based rubber band creation function.
Registry of available layout item GUI behavior.
QgsLayoutItemGuiRegistry & operator=(const QgsLayoutItemGuiRegistry &rh)=delete
QgsLayoutItemGuiRegistry cannot be copied.
QgsLayoutItemGuiRegistry(const QgsLayoutItemGuiRegistry &rh)=delete
QgsLayoutItemGuiRegistry cannot be copied.
void typeAdded(int metadataId)
Emitted whenever a new item type is added to the registry, with the specified metadataId.
Base class for graphical items within a QgsLayout.
QgsLayoutViewRubberBand is an abstract base class for temporary rubber band items in various shapes,...
A graphical widget to display and interact with QgsLayouts.
Definition: qgslayoutview.h:50
Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
Definition: qgslayout.h:51
#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< void(QgsLayoutItem *, const QVariantMap &)> QgsLayoutItemAddedToLayoutFunc
Layout item added to layout callback.
std::function< QgsLayoutViewRubberBand *(QgsLayoutView *)> QgsLayoutItemRubberBandFunc
Layout rubber band creation function.
std::function< QAbstractGraphicsShapeItem *(QgsLayoutView *)> QgsLayoutNodeItemRubberBandFunc
Layout node based rubber band creation function.
std::function< QgsLayoutItemBaseWidget *(QgsLayoutItem *)> QgsLayoutItemWidgetFunc
Layout item configuration widget creation function.
std::function< QgsLayoutItem *(QgsLayout *)> QgsLayoutItemCreateFunc
Layout item creation function.