QGIS API Documentation 3.27.0-Master (0a97e3138f)
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"
25#include "qgslayoutexporter.h"
27#include "qgssettingsentry.h"
28
30class QgsLayoutModel;
36
50class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContextGenerator, public QgsLayoutUndoObjectInterface
51{
52 Q_OBJECT
53
54 public:
55
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( "searchPathsForTemplates" ), QgsSettings::Prefix::CORE_LAYOUT, 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
722
723 private slots:
724 void itemBackgroundTaskCountChanged( int count );
725
726 private:
727
728 QgsProject *mProject = nullptr;
729 std::unique_ptr< QgsLayoutModel > mItemsModel;
730
731 QgsObjectCustomProperties mCustomProperties;
732
734 QgsLayoutRenderContext *mRenderContext = nullptr;
735 QgsLayoutReportContext *mReportContext = nullptr;
736 QgsLayoutSnapper mSnapper;
737 QgsLayoutGridSettings mGridSettings;
738
739 std::unique_ptr< QgsLayoutPageCollection > mPageCollection;
740 std::unique_ptr< QgsLayoutUndoStack > mUndoStack;
741
743 QList<QgsLayoutMultiFrame *> mMultiFrames;
744
746 QString mWorldFileMapId;
747
748 QHash< QgsLayoutItem *, int > mBackgroundTaskCount;
749
751 void writeXmlLayoutSettings( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
753 bool readXmlLayoutSettings( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
754
758 void addLayoutItemPrivate( QgsLayoutItem *item );
759
763 void removeLayoutItemPrivate( QgsLayoutItem *item );
764
765 void deleteAndRemoveMultiFrames();
766
768 QPointF minPointFromXml( const QDomElement &elem ) const;
769
770 QgsLayout( const QgsLayout & ) = delete;
771 QgsLayout &operator=( const QgsLayout & ) = delete;
772
773 friend class QgsLayoutItemAddItemCommand;
774 friend class QgsLayoutItemDeleteUndoCommand;
775 friend class QgsLayoutItemUndoCommand;
776 friend class QgsLayoutUndoCommand;
777 friend class QgsLayoutItemGroupUndoCommand;
778 friend class QgsLayoutModel;
781};
782
783#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
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 variablesChanged()
Emitted whenever the expression variables stored in the layout have been changed.
const QgsLayoutGridSettings & gridSettings() const
Returns a reference to the layout's grid settings, which stores settings relating to grid appearance,...
Definition: qgslayout.h:425
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
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 setUnits(QgsUnitTypes::LayoutUnit units)
Sets the native measurement units for the layout.
Definition: qgslayout.h:322
QgsLayoutGridSettings & gridSettings()
Returns a reference to the layout's grid settings, which stores settings relating to grid appearance,...
Definition: qgslayout.h:419
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:58
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: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:104
The class is used as a container of context for various read/write operations on other objects.
A string list settings entry.
static const char * CORE_LAYOUT
Definition: qgssettings.h:92
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