QGIS API Documentation 3.27.0-Master (9c08adf5ef)
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"
24#include <QGraphicsItem> //for QGraphicsItem::UserType
25#include <QIcon>
26#include <functional>
27
28#include "qgslayoutitem.h" // temporary
29
30class QgsLayout;
31class QgsLayoutView;
32class 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
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
170typedef std::function<QAbstractGraphicsShapeItem *( QgsLayoutView * )> QgsLayoutNodeItemRubberBandFunc SIP_SKIP;
171
173typedef 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
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
316class 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
360class 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.
virtual QgsLayoutItemBaseWidget * createItemWidget(QgsLayoutItem *item)
Creates a configuration widget for an item of this type.
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.
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.
QgsLayoutItemAddedToLayoutFunc itemAddToLayoutFunction() const
Returns the classes' item added to layout function.
QgsLayoutItemWidgetFunc widgetFunction() const
Returns the classes' configuration widget creation function.
QAbstractGraphicsShapeItem * createNodeRubberBand(QgsLayoutView *view) override
Creates a rubber band for use when creating layout node based items of this type.
QgsLayoutViewRubberBand * createRubberBand(QgsLayoutView *view) override
Creates a rubber band for use when creating layout items of this type.
void setItemAddedToLayoutFunction(const QgsLayoutItemAddedToLayoutFunc &function)
Sets the classes' item creation function.
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.
QgsLayoutItemBaseWidget * createItemWidget(QgsLayoutItem *item) override
Creates a configuration widget for an item of this type.
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.