QGIS API Documentation 3.39.0-Master (bca3cdb6021)
Loading...
Searching...
No Matches
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
48class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContextGenerator, public QgsLayoutUndoObjectInterface
49{
50 Q_OBJECT
51
52 public:
53
56 {
57 ZPage = 0,
58 ZItem = 1,
59 ZGrid = 9997,
60 ZGuide = 9998,
61 ZSmartGuide = 9999,
62 ZMouseHandles = 10000,
63 ZViewTool = 10001,
64 ZSnapIndicator = 10002,
65 };
66
69 {
71 UndoNone = -1,
72 };
73
81 QgsLayout( QgsProject *project );
82
83 ~QgsLayout() override;
84
89 QgsLayout *clone() const SIP_FACTORY;
90
95 void initializeDefaults();
96
102 void clear();
103
109 QgsProject *project() const;
110
114 QgsLayoutModel *itemsModel();
115
120 template<class T> void layoutItems( QList<T *> &itemList ) const SIP_SKIP
121 {
122 itemList.clear();
123 QList<QGraphicsItem *> graphicsItemList = items();
124 QList<QGraphicsItem *>::iterator itemIt = graphicsItemList.begin();
125 for ( ; itemIt != graphicsItemList.end(); ++itemIt )
126 {
127 T *item = dynamic_cast<T *>( *itemIt );
128 if ( item )
129 {
130 itemList.push_back( item );
131 }
132 }
133 }
134
139 template<class T> void layoutObjects( QList<T *> &objectList ) const SIP_SKIP
140 {
141 objectList.clear();
142 const QList<QGraphicsItem *> itemList( items() );
143 const QList<QgsLayoutMultiFrame *> frameList( multiFrames() );
144 for ( const auto &obj : itemList )
145 {
146 T *item = dynamic_cast<T *>( obj );
147 if ( item )
148 {
149 objectList.push_back( item );
150 }
151 }
152 for ( const auto &obj : frameList )
153 {
154 T *item = dynamic_cast<T *>( obj );
155 if ( item )
156 {
157 objectList.push_back( item );
158 }
159 }
160 }
161
168 QList<QgsLayoutItem *> selectedLayoutItems( bool includeLockedItems = true );
169
173 void setSelectedItem( QgsLayoutItem *item );
174
181 void deselectAll();
182
195 bool raiseItem( QgsLayoutItem *item, bool deferUpdate = false );
196
209 bool lowerItem( QgsLayoutItem *item, bool deferUpdate = false );
210
223 bool moveItemToTop( QgsLayoutItem *item, bool deferUpdate = false );
224
236 bool moveItemToBottom( QgsLayoutItem *item, bool deferUpdate = false );
237
243 void updateZValues( bool addUndoCommands = true );
244
260 QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
261
277 QgsLayoutItem *itemByTemplateUuid( const QString &uuid ) const;
278
285 QgsLayoutItem *itemById( const QString &id ) const;
286
300 QgsLayoutMultiFrame *multiFrameByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
301
307 QgsLayoutItem *layoutItemAt( QPointF position, bool ignoreLocked = false, double searchTolerance = 0 ) const;
308
314 QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked = false, double searchTolerance = 0 ) const;
315
322 void setUnits( Qgis::LayoutUnit units ) { mUnits = units; }
323
329 Qgis::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, Qgis::LayoutUnit unit ) const;
362
369 QgsLayoutSize convertFromLayoutUnits( QSizeF size, Qgis::LayoutUnit unit ) const;
370
377 QgsLayoutPoint convertFromLayoutUnits( QPointF point, Qgis::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
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
LayoutUnit
Layout measurement units.
Definition qgis.h:4839
@ Millimeters
Millimeters.
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...
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:49
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.
void setUnits(Qgis::LayoutUnit units)
Sets the native measurement units for the layout.
Definition qgslayout.h:322
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:139
static const QgsSettingsEntryStringList * settingsSearchPathForTemplates
Settings entry search path for templates.
Definition qgslayout.h:663
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:413
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:56
Qgis::LayoutUnit units() const
Returns the native units for the layout.
Definition qgslayout.h:329
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:69
@ UndoLayoutDpi
Change layout default DPI.
Definition qgslayout.h:70
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