QGIS API Documentation  3.19.0-Master (f616be29d3)
qgslayout.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgslayout.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 QGSLAYOUT_H
17 #define QGSLAYOUT_H
18 
19 #include "qgis_core.h"
20 #include <QGraphicsScene>
21 #include "qgslayoutsnapper.h"
23 #include "qgslayoutgridsettings.h"
25 #include "qgslayoutexporter.h"
27 #include "qgssettingsentry.h"
28 
29 class QgsLayoutItemMap;
30 class QgsLayoutModel;
33 class QgsLayoutUndoStack;
36 
50 class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContextGenerator, public QgsLayoutUndoObjectInterface
51 {
52  Q_OBJECT
53 
54  public:
55 
57  enum ZValues
58  {
59  ZPage = 0,
60  ZItem = 1,
61  ZGrid = 9997,
62  ZGuide = 9998,
63  ZSmartGuide = 9999,
64  ZMouseHandles = 10000,
65  ZViewTool = 10001,
66  ZSnapIndicator = 10002,
67  };
68 
71  {
73  UndoNone = -1,
74  };
75 
83  QgsLayout( QgsProject *project );
84 
85  ~QgsLayout() override;
86 
91  QgsLayout *clone() const SIP_FACTORY;
92 
97  void initializeDefaults();
98 
104  void clear();
105 
111  QgsProject *project() const;
112 
116  QgsLayoutModel *itemsModel();
117 
122  template<class T> void layoutItems( QList<T *> &itemList ) const SIP_SKIP
123  {
124  itemList.clear();
125  QList<QGraphicsItem *> graphicsItemList = items();
126  QList<QGraphicsItem *>::iterator itemIt = graphicsItemList.begin();
127  for ( ; itemIt != graphicsItemList.end(); ++itemIt )
128  {
129  T *item = dynamic_cast<T *>( *itemIt );
130  if ( item )
131  {
132  itemList.push_back( item );
133  }
134  }
135  }
136 
141  template<class T> void layoutObjects( QList<T *> &objectList ) const SIP_SKIP
142  {
143  objectList.clear();
144  const QList<QGraphicsItem *> itemList( items() );
145  const QList<QgsLayoutMultiFrame *> frameList( multiFrames() );
146  for ( const auto &obj : itemList )
147  {
148  T *item = dynamic_cast<T *>( obj );
149  if ( item )
150  {
151  objectList.push_back( item );
152  }
153  }
154  for ( const auto &obj : frameList )
155  {
156  T *item = dynamic_cast<T *>( obj );
157  if ( item )
158  {
159  objectList.push_back( item );
160  }
161  }
162  }
163 
170  QList<QgsLayoutItem *> selectedLayoutItems( bool includeLockedItems = true );
171 
175  void setSelectedItem( QgsLayoutItem *item );
176 
183  void deselectAll();
184 
197  bool raiseItem( QgsLayoutItem *item, bool deferUpdate = false );
198 
211  bool lowerItem( QgsLayoutItem *item, bool deferUpdate = false );
212 
225  bool moveItemToTop( QgsLayoutItem *item, bool deferUpdate = false );
226 
238  bool moveItemToBottom( QgsLayoutItem *item, bool deferUpdate = false );
239 
245  void updateZValues( bool addUndoCommands = true );
246 
262  QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
263 
279  QgsLayoutItem *itemByTemplateUuid( const QString &uuid ) const;
280 
287  QgsLayoutItem *itemById( const QString &id ) const;
288 
302  QgsLayoutMultiFrame *multiFrameByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
303 
308  QgsLayoutItem *layoutItemAt( QPointF position, bool ignoreLocked = false ) const;
309 
314  QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked = false ) const;
315 
322  void setUnits( QgsUnitTypes::LayoutUnit units ) { mUnits = units; }
323 
329  QgsUnitTypes::LayoutUnit units() const { return mUnits; }
330 
337  double convertToLayoutUnits( QgsLayoutMeasurement measurement ) const;
338 
345  QSizeF convertToLayoutUnits( const QgsLayoutSize &size ) const;
346 
353  QPointF convertToLayoutUnits( const QgsLayoutPoint &point ) const;
354 
361  QgsLayoutMeasurement convertFromLayoutUnits( double length, QgsUnitTypes::LayoutUnit unit ) const;
362 
369  QgsLayoutSize convertFromLayoutUnits( QSizeF size, QgsUnitTypes::LayoutUnit unit ) const;
370 
377  QgsLayoutPoint convertFromLayoutUnits( QPointF point, QgsUnitTypes::LayoutUnit unit ) const;
378 
383  QgsLayoutRenderContext &renderContext();
384 
389  SIP_SKIP const QgsLayoutRenderContext &renderContext() const;
390 
395  QgsLayoutReportContext &reportContext();
396 
401  SIP_SKIP const QgsLayoutReportContext &reportContext() const;
402 
407  QgsLayoutSnapper &snapper() { return mSnapper; }
408 
413  SIP_SKIP const QgsLayoutSnapper &snapper() const { return mSnapper; }
414 
419  QgsLayoutGridSettings &gridSettings() { return mGridSettings; }
420 
425  SIP_SKIP const QgsLayoutGridSettings &gridSettings() const { return mGridSettings; }
426 
430  void reloadSettings();
431 
435  QgsLayoutGuideCollection &guides();
436 
440  SIP_SKIP const QgsLayoutGuideCollection &guides() const;
441 
447 
456  void setCustomProperty( const QString &key, const QVariant &value );
457 
467  QVariant customProperty( const QString &key, const QVariant &defaultValue = QVariant() ) const;
468 
476  void removeCustomProperty( const QString &key );
477 
484  QStringList customProperties() const;
485 
492  QgsLayoutItemMap *referenceMap() const;
493 
499  void setReferenceMap( QgsLayoutItemMap *map );
500 
505  QgsLayoutPageCollection *pageCollection();
506 
511  SIP_SKIP const QgsLayoutPageCollection *pageCollection() const;
512 
522  QRectF layoutBounds( bool ignorePages = false, double margin = 0.0 ) const;
523 
534  QRectF pageItemBounds( int page, bool visibleOnly = false ) const;
535 
540  void addLayoutItem( QgsLayoutItem *item SIP_TRANSFER );
541 
547  void removeLayoutItem( QgsLayoutItem *item );
548 
554  void addMultiFrame( QgsLayoutMultiFrame *multiFrame SIP_TRANSFER );
555 
561  void removeMultiFrame( QgsLayoutMultiFrame *multiFrame );
562 
568  QList< QgsLayoutMultiFrame * > multiFrames() const;
569 
575  bool saveAsTemplate( const QString &path, const QgsReadWriteContext &context ) const;
576 
588  QList< QgsLayoutItem * > loadFromTemplate( const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting = true, bool *ok SIP_OUT = nullptr );
589 
594  virtual QDomElement writeXml( QDomDocument &document, const QgsReadWriteContext &context ) const;
595 
600  virtual bool readXml( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
601 
614  QList< QgsLayoutItem * > addItemsFromXml( const QDomElement &parentElement, const QDomDocument &document,
615  const QgsReadWriteContext &context,
616  QPointF *position = nullptr, bool pasteInPlace = false );
617 
622  QgsLayoutUndoStack *undoStack();
623 
628  SIP_SKIP const QgsLayoutUndoStack *undoStack() const;
629 
630  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id = 0, QUndoCommand *parent = nullptr ) SIP_FACTORY override;
631 
637  QgsLayoutItemGroup *groupItems( const QList<QgsLayoutItem *> &items );
638 
648  QList<QgsLayoutItem *> ungroupItems( QgsLayoutItemGroup *group );
649 
659  bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
660 
661 #ifndef SIP_RUN
663  static const inline QgsSettingsEntryStringList settingsSearchPathForTemplates = QgsSettingsEntryStringList( QStringLiteral( "Layout/searchPathsForTemplates" ), QgsSettings::Core, QStringList(), QObject::tr( "Search path for templates" ) );
664 #endif
665 
666  public slots:
667 
676  void refresh();
677 
681  void updateBounds();
682 
683  signals:
684 
690  void changed();
691 
696 
702 
707  void refreshed();
708 
714  void backgroundTaskCountChanged( int total );
715 
716  private slots:
717  void itemBackgroundTaskCountChanged( int count );
718 
719  private:
720 
721  QgsProject *mProject = nullptr;
722  std::unique_ptr< QgsLayoutModel > mItemsModel;
723 
724  QgsObjectCustomProperties mCustomProperties;
725 
727  QgsLayoutRenderContext *mRenderContext = nullptr;
728  QgsLayoutReportContext *mReportContext = nullptr;
729  QgsLayoutSnapper mSnapper;
730  QgsLayoutGridSettings mGridSettings;
731 
732  std::unique_ptr< QgsLayoutPageCollection > mPageCollection;
733  std::unique_ptr< QgsLayoutUndoStack > mUndoStack;
734 
736  QList<QgsLayoutMultiFrame *> mMultiFrames;
737 
739  QString mWorldFileMapId;
740 
741  QHash< QgsLayoutItem *, int > mBackgroundTaskCount;
742 
744  void writeXmlLayoutSettings( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
746  bool readXmlLayoutSettings( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
747 
751  void addLayoutItemPrivate( QgsLayoutItem *item );
752 
756  void removeLayoutItemPrivate( QgsLayoutItem *item );
757 
758  void deleteAndRemoveMultiFrames();
759 
761  QPointF minPointFromXml( const QDomElement &elem ) const;
762 
763  QgsLayout( const QgsLayout & ) = delete;
764  QgsLayout &operator=( const QgsLayout & ) = delete;
765 
766  friend class QgsLayoutItemAddItemCommand;
767  friend class QgsLayoutItemDeleteUndoCommand;
768  friend class QgsLayoutItemUndoCommand;
769  friend class QgsLayoutUndoCommand;
770  friend class QgsLayoutItemGroupUndoCommand;
771  friend class QgsLayoutModel;
772  friend class QgsLayoutMultiFrame;
774 };
775 
776 #endif //QGSLAYOUT_H
Base class for commands to undo/redo layout and layout object changes.
QgsCompositionConverter class converts a QGIS 2.x composition to a QGIS 3.x layout.
Abstract interface for generating an expression context.
virtual QgsExpressionContext createExpressionContext() const =0
This method needs to be reimplemented in all classes which implement this interface and return an exp...
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
Contains settings relating to the appearance, spacing and offset for layout grids.
Stores and manages the snap guides used by a layout.
A container for grouping several QgsLayoutItems.
Layout graphical items for displaying a map.
Base class for graphical items within a QgsLayout.
This class provides a method of storing measurements for use in QGIS layouts using a variety of diffe...
A model for items attached to a layout.
Abstract base class for layout items with the ability to distribute the content to several frames (Qg...
A manager for a collection of pages in a layout.
This class provides a method of storing points, consisting of an x and y coordinate,...
Stores information relating to the current rendering settings for a layout.
Stores information relating to the current reporting context for a layout.
This class provides a method of storing sizes, consisting of a width and height, for use in QGIS layo...
Definition: qgslayoutsize.h:41
Manages snapping grids and preset snap lines in a layout, and handles snapping points to the nearest ...
Interface for layout objects which support undo/redo commands.
virtual QgsAbstractLayoutUndoCommand * createCommand(const QString &text, int id=0, QUndoCommand *parent=nullptr)=0
Creates a new layout undo command with the specified text and parent.
An undo stack for QgsLayouts.
Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
Definition: qgslayout.h:51
QgsLayoutGridSettings & gridSettings()
Returns a reference to the layout's grid settings, which stores settings relating to grid appearance,...
Definition: qgslayout.h:419
const QgsLayoutSnapper & snapper() const
Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and sna...
Definition: qgslayout.h:413
void variablesChanged()
Emitted whenever the expression variables stored in the layout have been changed.
void changed()
Emitted when properties of the layout change.
void layoutObjects(QList< T * > &objectList) const
Returns a list of layout objects (items and multiframes) of a specific type.
Definition: qgslayout.h:141
void selectedItemChanged(QgsLayoutItem *selected)
Emitted whenever the selected item changes.
QgsUnitTypes::LayoutUnit units() const
Returns the native units for the layout.
Definition: qgslayout.h:329
QgsLayoutSnapper & snapper()
Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and sna...
Definition: qgslayout.h:407
void setUnits(QgsUnitTypes::LayoutUnit units)
Sets the native measurement units for the layout.
Definition: qgslayout.h:322
void backgroundTaskCountChanged(int total)
Emitted whenever the total number of background tasks running in items from the layout changes.
void refreshed()
Emitted when the layout has been refreshed and items should also be refreshed and updated.
const QgsLayoutGridSettings & gridSettings() const
Returns a reference to the layout's grid settings, which stores settings relating to grid appearance,...
Definition: qgslayout.h:425
ZValues
Preset item z-values, to ensure correct stacking.
Definition: qgslayout.h:58
UndoCommand
Layout undo commands, used for collapsing undo commands.
Definition: qgslayout.h:71
@ UndoLayoutDpi
Change layout default DPI.
Definition: qgslayout.h:72
Simple key-value store (keys = strings, values = variants) that supports loading/saving to/from XML i...
Encapsulates a QGIS project, including sets of map layers and their styles, layouts,...
Definition: qgsproject.h:99
The class is used as a container of context for various read/write operations on other objects.
An interface for classes which can visit style entity (e.g.
LayoutUnit
Layout measurement units.
Definition: qgsunittypes.h:182
@ LayoutMillimeters
Millimeters.
Definition: qgsunittypes.h:183
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_TRANSFER
Definition: qgis_sip.h:36
#define SIP_OUT
Definition: qgis_sip.h:58
#define SIP_FACTORY
Definition: qgis_sip.h:76