QGIS API Documentation  3.15.0-Master (a49cb7c9f3)
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 
28 class QgsLayoutItemMap;
29 class QgsLayoutModel;
32 class QgsLayoutUndoStack;
35 
49 class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContextGenerator, public QgsLayoutUndoObjectInterface
50 {
51  Q_OBJECT
52 
53  public:
54 
56  enum ZValues
57  {
58  ZPage = 0,
59  ZItem = 1,
60  ZGrid = 9997,
61  ZGuide = 9998,
62  ZSmartGuide = 9999,
63  ZMouseHandles = 10000,
64  ZViewTool = 10001,
65  ZSnapIndicator = 10002,
66  };
67 
70  {
72  UndoNone = -1,
73  };
74 
82  QgsLayout( QgsProject *project );
83 
84  ~QgsLayout() override;
85 
90  QgsLayout *clone() const SIP_FACTORY;
91 
96  void initializeDefaults();
97 
103  void clear();
104 
110  QgsProject *project() const;
111 
115  QgsLayoutModel *itemsModel();
116 
121  template<class T> void layoutItems( QList<T *> &itemList ) const SIP_SKIP
122  {
123  itemList.clear();
124  QList<QGraphicsItem *> graphicsItemList = items();
125  QList<QGraphicsItem *>::iterator itemIt = graphicsItemList.begin();
126  for ( ; itemIt != graphicsItemList.end(); ++itemIt )
127  {
128  T *item = dynamic_cast<T *>( *itemIt );
129  if ( item )
130  {
131  itemList.push_back( item );
132  }
133  }
134  }
135 
140  template<class T> void layoutObjects( QList<T *> &objectList ) const SIP_SKIP
141  {
142  objectList.clear();
143  const QList<QGraphicsItem *> itemList( items() );
144  const QList<QgsLayoutMultiFrame *> frameList( multiFrames() );
145  for ( const auto &obj : itemList )
146  {
147  T *item = dynamic_cast<T *>( obj );
148  if ( item )
149  {
150  objectList.push_back( item );
151  }
152  }
153  for ( const auto &obj : frameList )
154  {
155  T *item = dynamic_cast<T *>( obj );
156  if ( item )
157  {
158  objectList.push_back( item );
159  }
160  }
161  }
162 
169  QList<QgsLayoutItem *> selectedLayoutItems( bool includeLockedItems = true );
170 
174  void setSelectedItem( QgsLayoutItem *item );
175 
182  void deselectAll();
183 
196  bool raiseItem( QgsLayoutItem *item, bool deferUpdate = false );
197 
210  bool lowerItem( QgsLayoutItem *item, bool deferUpdate = false );
211 
224  bool moveItemToTop( QgsLayoutItem *item, bool deferUpdate = false );
225 
237  bool moveItemToBottom( QgsLayoutItem *item, bool deferUpdate = false );
238 
244  void updateZValues( bool addUndoCommands = true );
245 
261  QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
262 
278  QgsLayoutItem *itemByTemplateUuid( const QString &uuid ) const;
279 
286  QgsLayoutItem *itemById( const QString &id ) const;
287 
301  QgsLayoutMultiFrame *multiFrameByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
302 
307  QgsLayoutItem *layoutItemAt( QPointF position, bool ignoreLocked = false ) const;
308 
313  QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked = false ) const;
314 
321  void setUnits( QgsUnitTypes::LayoutUnit units ) { mUnits = units; }
322 
328  QgsUnitTypes::LayoutUnit units() const { return mUnits; }
329 
336  double convertToLayoutUnits( QgsLayoutMeasurement measurement ) const;
337 
344  QSizeF convertToLayoutUnits( const QgsLayoutSize &size ) const;
345 
352  QPointF convertToLayoutUnits( const QgsLayoutPoint &point ) const;
353 
360  QgsLayoutMeasurement convertFromLayoutUnits( double length, QgsUnitTypes::LayoutUnit unit ) const;
361 
368  QgsLayoutSize convertFromLayoutUnits( QSizeF size, QgsUnitTypes::LayoutUnit unit ) const;
369 
376  QgsLayoutPoint convertFromLayoutUnits( QPointF point, QgsUnitTypes::LayoutUnit unit ) const;
377 
382  QgsLayoutRenderContext &renderContext();
383 
388  SIP_SKIP const QgsLayoutRenderContext &renderContext() const;
389 
394  QgsLayoutReportContext &reportContext();
395 
400  SIP_SKIP const QgsLayoutReportContext &reportContext() const;
401 
406  QgsLayoutSnapper &snapper() { return mSnapper; }
407 
412  SIP_SKIP const QgsLayoutSnapper &snapper() const { return mSnapper; }
413 
418  QgsLayoutGridSettings &gridSettings() { return mGridSettings; }
419 
424  SIP_SKIP const QgsLayoutGridSettings &gridSettings() const { return mGridSettings; }
425 
429  void reloadSettings();
430 
434  QgsLayoutGuideCollection &guides();
435 
439  SIP_SKIP const QgsLayoutGuideCollection &guides() const;
440 
446 
455  void setCustomProperty( const QString &key, const QVariant &value );
456 
466  QVariant customProperty( const QString &key, const QVariant &defaultValue = QVariant() ) const;
467 
475  void removeCustomProperty( const QString &key );
476 
483  QStringList customProperties() const;
484 
491  QgsLayoutItemMap *referenceMap() const;
492 
498  void setReferenceMap( QgsLayoutItemMap *map );
499 
504  QgsLayoutPageCollection *pageCollection();
505 
510  SIP_SKIP const QgsLayoutPageCollection *pageCollection() const;
511 
521  QRectF layoutBounds( bool ignorePages = false, double margin = 0.0 ) const;
522 
533  QRectF pageItemBounds( int page, bool visibleOnly = false ) const;
534 
539  void addLayoutItem( QgsLayoutItem *item SIP_TRANSFER );
540 
546  void removeLayoutItem( QgsLayoutItem *item );
547 
553  void addMultiFrame( QgsLayoutMultiFrame *multiFrame SIP_TRANSFER );
554 
560  void removeMultiFrame( QgsLayoutMultiFrame *multiFrame );
561 
567  QList< QgsLayoutMultiFrame * > multiFrames() const;
568 
574  bool saveAsTemplate( const QString &path, const QgsReadWriteContext &context ) const;
575 
587  QList< QgsLayoutItem * > loadFromTemplate( const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting = true, bool *ok SIP_OUT = nullptr );
588 
593  virtual QDomElement writeXml( QDomDocument &document, const QgsReadWriteContext &context ) const;
594 
599  virtual bool readXml( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
600 
613  QList< QgsLayoutItem * > addItemsFromXml( const QDomElement &parentElement, const QDomDocument &document,
614  const QgsReadWriteContext &context,
615  QPointF *position = nullptr, bool pasteInPlace = false );
616 
621  QgsLayoutUndoStack *undoStack();
622 
627  SIP_SKIP const QgsLayoutUndoStack *undoStack() const;
628 
629  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id = 0, QUndoCommand *parent = nullptr ) SIP_FACTORY override;
630 
636  QgsLayoutItemGroup *groupItems( const QList<QgsLayoutItem *> &items );
637 
647  QList<QgsLayoutItem *> ungroupItems( QgsLayoutItemGroup *group );
648 
658  bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
659 
660  public slots:
661 
670  void refresh();
671 
675  void updateBounds();
676 
677  signals:
678 
684  void changed();
685 
689  void variablesChanged();
690 
695  void selectedItemChanged( QgsLayoutItem *selected );
696 
701  void refreshed();
702 
708  void backgroundTaskCountChanged( int total );
709 
710  private slots:
711  void itemBackgroundTaskCountChanged( int count );
712 
713  private:
714 
715  QgsProject *mProject = nullptr;
716  std::unique_ptr< QgsLayoutModel > mItemsModel;
717 
718  QgsObjectCustomProperties mCustomProperties;
719 
721  QgsLayoutRenderContext *mRenderContext = nullptr;
722  QgsLayoutReportContext *mReportContext = nullptr;
723  QgsLayoutSnapper mSnapper;
724  QgsLayoutGridSettings mGridSettings;
725 
726  std::unique_ptr< QgsLayoutPageCollection > mPageCollection;
727  std::unique_ptr< QgsLayoutUndoStack > mUndoStack;
728 
730  QList<QgsLayoutMultiFrame *> mMultiFrames;
731 
733  QString mWorldFileMapId;
734 
735  QHash< QgsLayoutItem *, int > mBackgroundTaskCount;
736 
738  void writeXmlLayoutSettings( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
740  bool readXmlLayoutSettings( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
741 
745  void addLayoutItemPrivate( QgsLayoutItem *item );
746 
750  void removeLayoutItemPrivate( QgsLayoutItem *item );
751 
752  void deleteAndRemoveMultiFrames();
753 
755  QPointF minPointFromXml( const QDomElement &elem ) const;
756 
757  QgsLayout( const QgsLayout & ) = delete;
758  QgsLayout &operator=( const QgsLayout & ) = delete;
759 
760  friend class QgsLayoutItemAddItemCommand;
761  friend class QgsLayoutItemDeleteUndoCommand;
762  friend class QgsLayoutItemUndoCommand;
763  friend class QgsLayoutUndoCommand;
764  friend class QgsLayoutItemGroupUndoCommand;
765  friend class QgsLayoutModel;
766  friend class QgsLayoutMultiFrame;
768 };
769 
770 #endif //QGSLAYOUT_H
The class is used as a container of context for various read/write operations on other objects...
Base class for graphical items within a QgsLayout.
void layoutObjects(QList< T *> &objectList) const
Returns a list of layout objects (items and multiframes) of a specific type.
Definition: qgslayout.h:140
Base class for commands to undo/redo layout and layout object changes.
Change layout default DPI.
Definition: qgslayout.h:71
Stores information relating to the current reporting context for a layout.
QgsUnitTypes::LayoutUnit units() const
Returns the native units for the layout.
Definition: qgslayout.h:328
An undo stack for QgsLayouts.
QgsLayoutSnapper & snapper()
Returns a reference to the layout&#39;s snapper, which stores handles layout snap grids and lines and sna...
Definition: qgslayout.h:406
A container for grouping several QgsLayoutItems.
void setUnits(QgsUnitTypes::LayoutUnit units)
Sets the native measurement units for the layout.
Definition: qgslayout.h:321
An interface for classes which can visit style entity (e.g.
const QgsLayoutGridSettings & gridSettings() const
Returns a reference to the layout&#39;s grid settings, which stores settings relating to grid appearance...
Definition: qgslayout.h:424
ZValues
Preset item z-values, to ensure correct stacking.
Definition: qgslayout.h:56
Abstract base class for layout items with the ability to distribute the content to several frames (Qg...
This class provides a method of storing points, consisting of an x and y coordinate, for use in QGIS layouts.
virtual QgsExpressionContext createExpressionContext() const =0
This method needs to be reimplemented in all classes which implement this interface and return an exp...
Layout graphical items for displaying a map.
const QgsLayoutSnapper & snapper() const
Returns a reference to the layout&#39;s snapper, which stores handles layout snap grids and lines and sna...
Definition: qgslayout.h:412
This class provides a method of storing measurements for use in QGIS layouts using a variety of diffe...
#define SIP_SKIP
Definition: qgis_sip.h:126
QgsLayoutGridSettings & gridSettings()
Returns a reference to the layout&#39;s grid settings, which stores settings relating to grid appearance...
Definition: qgslayout.h:418
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
#define SIP_TRANSFER
Definition: qgis_sip.h:36
Stores and manages the snap guides used by a layout.
Encapsulates a QGIS project, including sets of map layers and their styles, layouts, annotations, canvases, etc.
Definition: qgsproject.h:92
#define SIP_FACTORY
Definition: qgis_sip.h:76
Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
Definition: qgslayout.h:49
A manager for a collection of pages in a layout.
Contains settings relating to the appearance, spacing and offset for layout grids.
Abstract interface for generating an expression context.
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.
QgsCompositionConverter class converts a QGIS 2.x composition to a QGIS 3.x layout.
#define SIP_OUT
Definition: qgis_sip.h:58
Stores information relating to the current rendering settings for a layout.
Interface for layout objects which support undo/redo commands.
Simple key-value store (keys = strings, values = variants) that supports loading/saving to/from XML i...
UndoCommand
Layout undo commands, used for collapsing undo commands.
Definition: qgslayout.h:69
LayoutUnit
Layout measurement units.
Definition: qgsunittypes.h:180
A model for items attached to a layout.
Manages snapping grids and preset snap lines in a layout, and handles snapping points to the nearest ...
This class provides a method of storing sizes, consisting of a width and height, for use in QGIS layo...
Definition: qgslayoutsize.h:40