QGIS API Documentation  3.0.2-Girona (307d082)
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( const 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( const 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, const bool ignoreLocked = false ) const;
308 
313  QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, const 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( const QgsLayoutMeasurement &measurement ) const;
337 
344  QSizeF convertToLayoutUnits( const QgsLayoutSize &size ) const;
345 
352  QPointF convertToLayoutUnits( const QgsLayoutPoint &point ) const;
353 
360  QgsLayoutMeasurement convertFromLayoutUnits( const double length, const QgsUnitTypes::LayoutUnit unit ) const;
361 
368  QgsLayoutSize convertFromLayoutUnits( const QSizeF &size, const QgsUnitTypes::LayoutUnit unit ) const;
369 
376  QgsLayoutPoint convertFromLayoutUnits( const QPointF &point, const 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 
492  QgsLayoutItemMap *referenceMap() const;
493 
500  void setReferenceMap( QgsLayoutItemMap *map );
501 
506  QgsLayoutPageCollection *pageCollection();
507 
512  SIP_SKIP const QgsLayoutPageCollection *pageCollection() const;
513 
523  QRectF layoutBounds( bool ignorePages = false, double margin = 0.0 ) const;
524 
535  QRectF pageItemBounds( int page, bool visibleOnly = false ) const;
536 
541  void addLayoutItem( QgsLayoutItem *item SIP_TRANSFER );
542 
548  void removeLayoutItem( QgsLayoutItem *item );
549 
555  void addMultiFrame( QgsLayoutMultiFrame *multiFrame SIP_TRANSFER );
556 
562  void removeMultiFrame( QgsLayoutMultiFrame *multiFrame );
563 
569  QList< QgsLayoutMultiFrame * > multiFrames() const;
570 
576  bool saveAsTemplate( const QString &path, const QgsReadWriteContext &context ) const;
577 
589  QList< QgsLayoutItem * > loadFromTemplate( const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting = true, bool *ok SIP_OUT = nullptr );
590 
595  virtual QDomElement writeXml( QDomDocument &document, const QgsReadWriteContext &context ) const;
596 
601  virtual bool readXml( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
602 
615  QList< QgsLayoutItem * > addItemsFromXml( const QDomElement &parentElement, const QDomDocument &document,
616  const QgsReadWriteContext &context,
617  QPointF *position = nullptr, bool pasteInPlace = false );
618 
623  QgsLayoutUndoStack *undoStack();
624 
629  SIP_SKIP const QgsLayoutUndoStack *undoStack() const;
630 
631  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id = 0, QUndoCommand *parent = nullptr ) SIP_FACTORY override;
632 
638  QgsLayoutItemGroup *groupItems( const QList<QgsLayoutItem *> &items );
639 
649  QList<QgsLayoutItem *> ungroupItems( QgsLayoutItemGroup *group );
650 
651  public slots:
652 
661  void refresh();
662 
666  void updateBounds();
667 
668  signals:
669 
675  void changed();
676 
680  void variablesChanged();
681 
686  void selectedItemChanged( QgsLayoutItem *selected );
687 
692  void refreshed();
693 
694  private:
695 
696  QgsProject *mProject = nullptr;
697  std::unique_ptr< QgsLayoutModel > mItemsModel;
698 
699  QgsObjectCustomProperties mCustomProperties;
700 
702  QgsLayoutRenderContext *mRenderContext = nullptr;
703  QgsLayoutReportContext *mReportContext = nullptr;
704  QgsLayoutSnapper mSnapper;
705  QgsLayoutGridSettings mGridSettings;
706 
707  std::unique_ptr< QgsLayoutPageCollection > mPageCollection;
708  std::unique_ptr< QgsLayoutUndoStack > mUndoStack;
709 
711  QList<QgsLayoutMultiFrame *> mMultiFrames;
712 
714  QString mWorldFileMapId;
715 
717  void writeXmlLayoutSettings( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
719  bool readXmlLayoutSettings( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
720 
724  void addLayoutItemPrivate( QgsLayoutItem *item );
725 
729  void removeLayoutItemPrivate( QgsLayoutItem *item );
730 
731  void deleteAndRemoveMultiFrames();
732 
734  QPointF minPointFromXml( const QDomElement &elem ) const;
735 
736  friend class QgsLayoutItemAddItemCommand;
737  friend class QgsLayoutItemDeleteUndoCommand;
738  friend class QgsLayoutItemUndoCommand;
739  friend class QgsLayoutUndoCommand;
740  friend class QgsLayoutItemGroupUndoCommand;
741  friend class QgsLayoutModel;
742  friend class QgsLayoutMultiFrame;
744 };
745 
746 #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
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:119
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.
Reads and writes project states.
Definition: qgsproject.h:82
#define SIP_FACTORY
Definition: qgis_sip.h:69
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:51
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:114
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