QGIS API Documentation 3.32.0-Lima (311a8cb8a6)
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"
26
28class QgsLayoutModel;
35
49class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContextGenerator, public QgsLayoutUndoObjectInterface
50{
51 Q_OBJECT
52
53 public:
54
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( Qgis::LayoutUnit units ) { mUnits = units; }
322
328 Qgis::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, Qgis::LayoutUnit unit ) const;
361
368 QgsLayoutSize convertFromLayoutUnits( QSizeF size, Qgis::LayoutUnit unit ) const;
369
376 QgsLayoutPoint convertFromLayoutUnits( QPointF point, Qgis::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#ifndef SIP_RUN
663#endif
664
665 public slots:
666
675 void refresh();
676
680 void updateBounds();
681
682 signals:
683
689 void changed();
690
695
701
706 void refreshed();
707
713 void backgroundTaskCountChanged( int total );
714
721
722 private slots:
723 void itemBackgroundTaskCountChanged( int count );
724
725 private:
726
727 QgsProject *mProject = nullptr;
728 std::unique_ptr< QgsLayoutModel > mItemsModel;
729
730 QgsObjectCustomProperties mCustomProperties;
731
732 Qgis::LayoutUnit mUnits = Qgis::LayoutUnit::Millimeters;
733 QgsLayoutRenderContext *mRenderContext = nullptr;
734 QgsLayoutReportContext *mReportContext = nullptr;
735 QgsLayoutSnapper mSnapper;
736 QgsLayoutGridSettings mGridSettings;
737
738 std::unique_ptr< QgsLayoutPageCollection > mPageCollection;
739 std::unique_ptr< QgsLayoutUndoStack > mUndoStack;
740
742 QList<QgsLayoutMultiFrame *> mMultiFrames;
743
745 QString mWorldFileMapId;
746
747 QHash< QgsLayoutItem *, int > mBackgroundTaskCount;
748
750 void writeXmlLayoutSettings( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
752 bool readXmlLayoutSettings( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
753
757 void addLayoutItemPrivate( QgsLayoutItem *item );
758
762 void removeLayoutItemPrivate( QgsLayoutItem *item );
763
764 void deleteAndRemoveMultiFrames();
765
767 QPointF minPointFromXml( const QDomElement &elem ) const;
768
769 QgsLayout( const QgsLayout & ) = delete;
770 QgsLayout &operator=( const QgsLayout & ) = delete;
771
772 friend class QgsLayoutItemAddItemCommand;
773 friend class QgsLayoutItemDeleteUndoCommand;
774 friend class QgsLayoutItemUndoCommand;
775 friend class QgsLayoutUndoCommand;
776 friend class QgsLayoutItemGroupUndoCommand;
777 friend class QgsLayoutModel;
780};
781
782#endif //QGSLAYOUT_H
LayoutUnit
Layout measurement units.
Definition: qgis.h:3461
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:50
QgsLayoutSnapper & snapper()
Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and sna...
Definition: qgslayout.h:406
void variablesChanged()
Emitted whenever the expression variables stored in the layout have been changed.
void setUnits(Qgis::LayoutUnit units)
Sets the native measurement units for the layout.
Definition: qgslayout.h:321
const QgsLayoutGridSettings & gridSettings() const
Returns a reference to the layout's grid settings, which stores settings relating to grid appearance,...
Definition: qgslayout.h:424
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:140
static const QgsSettingsEntryStringList * settingsSearchPathForTemplates
Settings entry search path for templates.
Definition: qgslayout.h:662
void selectedItemChanged(QgsLayoutItem *selected)
Emitted whenever the selected item changes.
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:412
QgsLayoutGridSettings & gridSettings()
Returns a reference to the layout's grid settings, which stores settings relating to grid appearance,...
Definition: qgslayout.h:418
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.
ZValues
Preset item z-values, to ensure correct stacking.
Definition: qgslayout.h:57
Qgis::LayoutUnit units() const
Returns the native units for the layout.
Definition: qgslayout.h:328
void itemAdded(QgsLayoutItem *item)
Emitted when an item was added to the layout.
UndoCommand
Layout undo commands, used for collapsing undo commands.
Definition: qgslayout.h:70
@ UndoLayoutDpi
Change layout default DPI.
Definition: qgslayout.h:71
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:107
The class is used as a container of context for various read/write operations on other objects.
A string list settings entry.
An interface for classes which can visit style entity (e.g.
#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