Base class for layouts, which can contain items such as maps, labels, scalebars, etc. More...

#include <qgslayout.h>

Inheritance diagram for QgsLayout:

[legend]

Public Types
enum	UndoCommand { UndoLayoutDpi , UndoNone = -1 }
	Layout undo commands, used for collapsing undo commands. More...

enum	ZValues { ZPage = 0 , ZItem = 1 , ZGrid = 9997 , ZGuide = 9998 , ZSmartGuide = 9999 , ZMouseHandles = 10000 , ZViewTool = 10001 , ZSnapIndicator = 10002 }
	Preset item z-values, to ensure correct stacking. More...

Public Slots
void	refresh ()
	Forces the layout, and all items contained within it, to refresh. More...

void	updateBounds ()
	Updates the scene bounds of the layout. More...

Signals
void	backgroundTaskCountChanged (int total)
	Emitted whenever the total number of background tasks running in items from the layout changes. More...

void	changed ()
	Emitted when properties of the layout change. More...

void	itemAdded (QgsLayoutItem *item)
	Emitted when an item was added to the layout. More...

void	refreshed ()
	Emitted when the layout has been refreshed and items should also be refreshed and updated. More...

void	selectedItemChanged (QgsLayoutItem *selected)
	Emitted whenever the selected item changes. More...

void	variablesChanged ()
	Emitted whenever the expression variables stored in the layout have been changed. More...

Public Member Functions
	QgsLayout (QgsProject *project)
	Construct a new layout linked to the specified project. More...

	~QgsLayout () override

bool	accept (QgsStyleEntityVisitorInterface *visitor) const
	Accepts the specified style entity visitor, causing it to visit all style entities associated with the layout. More...

QList< QgsLayoutItem * >	addItemsFromXml (const QDomElement &parentElement, const QDomDocument &document, const QgsReadWriteContext &context, QPointF *position=nullptr, bool pasteInPlace=false)
	Add items from an XML representation to the layout. More...

void	addLayoutItem (QgsLayoutItem *item)
	Adds an item to the layout. More...

void	addMultiFrame (QgsLayoutMultiFrame *multiFrame)
	Adds a multiFrame to the layout. More...

void	clear ()
	Clears the layout. More...

QgsLayout *	clone () const
	Creates a clone of the layout. More...

QgsLayoutMeasurement	convertFromLayoutUnits (double length, Qgis::LayoutUnit unit) const
	Converts a length measurement from the layout's native units to a specified target unit. More...

QgsLayoutPoint	convertFromLayoutUnits (QPointF point, Qgis::LayoutUnit unit) const
	Converts a point from the layout's native units to a specified target unit. More...

QgsLayoutSize	convertFromLayoutUnits (QSizeF size, Qgis::LayoutUnit unit) const
	Converts a size from the layout's native units to a specified target unit. More...

QPointF	convertToLayoutUnits (const QgsLayoutPoint &point) const
	Converts a point into the layout's native units. More...

QSizeF	convertToLayoutUnits (const QgsLayoutSize &size) const
	Converts a size into the layout's native units. More...

double	convertToLayoutUnits (QgsLayoutMeasurement measurement) const
	Converts a measurement into the layout's native units. More...

QgsAbstractLayoutUndoCommand *	createCommand (const QString &text, int id=0, QUndoCommand *parent=nullptr) override
	Creates a new layout undo command with the specified text and parent. More...

QgsExpressionContext	createExpressionContext () const override
	Creates an expression context relating to the layout's current state. More...

QStringList	customProperties () const
	Returns list of keys stored in custom properties for the layout. More...

QVariant	customProperty (const QString &key, const QVariant &defaultValue=QVariant()) const
	Read a custom property from the layout. More...

void	deselectAll ()
	Clears any selected items in the layout. More...

QgsLayoutGridSettings &	gridSettings ()
	Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets. More...

const QgsLayoutGridSettings &	gridSettings () const
	Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets. More...

QgsLayoutItemGroup *	groupItems (const QList< QgsLayoutItem * > &items)
	Creates a new group from a list of layout items and adds the group to the layout. More...

QgsLayoutGuideCollection &	guides ()
	Returns a reference to the layout's guide collection, which manages page snap guides. More...

const QgsLayoutGuideCollection &	guides () const
	Returns a reference to the layout's guide collection, which manages page snap guides. More...

void	initializeDefaults ()
	Initializes an empty layout, e.g. More...

QgsLayoutItem *	itemById (const QString &id) const
	Returns a layout item given its id. More...

QgsLayoutItem *	itemByTemplateUuid (const QString &uuid) const
	Returns the layout item with matching template uuid unique identifier, or `nullptr` if a matching item could not be found. More...

QgsLayoutItem *	itemByUuid (const QString &uuid, bool includeTemplateUuids=false) const
	Returns the layout item with matching uuid unique identifier, or `nullptr` if a matching item could not be found. More...

QgsLayoutModel *	itemsModel ()
	Returns the items model attached to the layout. More...

QRectF	layoutBounds (bool ignorePages=false, double margin=0.0) const
	Calculates the bounds of all non-gui items in the layout. More...

QgsLayoutItem *	layoutItemAt (QPointF position, bool ignoreLocked=false) const
	Returns the topmost layout item at a specified position. More...

QgsLayoutItem *	layoutItemAt (QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked=false) const
	Returns the topmost layout item at a specified position which is below a specified item. More...

template<class T >
void	layoutItems (QList< T * > &itemList) const
	Returns a list of layout items of a specific type. More...

template<class T >
void	layoutObjects (QList< T * > &objectList) const
	Returns a list of layout objects (items and multiframes) of a specific type. More...

QList< QgsLayoutItem * >	loadFromTemplate (const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting=true, bool *ok=nullptr)
	Load a layout template document. More...

bool	lowerItem (QgsLayoutItem *item, bool deferUpdate=false)
	Lowers an item down the z-order. More...

bool	moveItemToBottom (QgsLayoutItem *item, bool deferUpdate=false)
	Lowers an item down to the bottom of the z-order. More...

bool	moveItemToTop (QgsLayoutItem *item, bool deferUpdate=false)
	Raises an item up to the top of the z-order. More...

QgsLayoutMultiFrame *	multiFrameByUuid (const QString &uuid, bool includeTemplateUuids=false) const
	Returns the layout multiframe with matching uuid unique identifier, or `nullptr` if a matching multiframe could not be found. More...

QList< QgsLayoutMultiFrame * >	multiFrames () const
	Returns a list of multi frames contained in the layout. More...

QgsLayoutPageCollection *	pageCollection ()
	Returns a pointer to the layout's page collection, which stores and manages page items in the layout. More...

const QgsLayoutPageCollection *	pageCollection () const
	Returns a pointer to the layout's page collection, which stores and manages page items in the layout. More...

QRectF	pageItemBounds (int page, bool visibleOnly=false) const
	Returns the bounding box of the items contained on a specified page. More...

QgsProject *	project () const
	The project associated with the layout. More...

bool	raiseItem (QgsLayoutItem *item, bool deferUpdate=false)
	Raises an item up the z-order. More...

virtual bool	readXml (const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context)
	Sets the collection's state from a DOM element. More...

QgsLayoutItemMap *	referenceMap () const
	Returns the map item which will be used to generate corresponding world files when the layout is exported. More...

void	reloadSettings ()
	Refreshes the layout when global layout related options change. More...

void	removeCustomProperty (const QString &key)
	Remove a custom property from the layout. More...

void	removeLayoutItem (QgsLayoutItem *item)
	Removes an item from the layout. More...

void	removeMultiFrame (QgsLayoutMultiFrame *multiFrame)
	Removes a multiFrame from the layout (but does not delete it). More...

QgsLayoutRenderContext &	renderContext ()
	Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout. More...

const QgsLayoutRenderContext &	renderContext () const
	Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout. More...

QgsLayoutReportContext &	reportContext ()
	Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout. More...

const QgsLayoutReportContext &	reportContext () const
	Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout. More...

bool	saveAsTemplate (const QString &path, const QgsReadWriteContext &context) const
	Saves the layout as a template at the given file path. More...

QList< QgsLayoutItem * >	selectedLayoutItems (bool includeLockedItems=true)
	Returns list of selected layout items. More...

void	setCustomProperty (const QString &key, const QVariant &value)
	Set a custom property for the layout. More...

void	setReferenceMap (QgsLayoutItemMap *map)
	Sets the map item which will be used to generate corresponding world files when the layout is exported. More...

void	setSelectedItem (QgsLayoutItem *item)
	Clears any selected items and sets item as the current selection. More...

void	setUnits (Qgis::LayoutUnit units)
	Sets the native measurement units for the layout. More...

QgsLayoutSnapper &	snapper ()
	Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point. More...

const QgsLayoutSnapper &	snapper () const
	Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point. More...

QgsLayoutUndoStack *	undoStack ()
	Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects. More...

const QgsLayoutUndoStack *	undoStack () const
	Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects. More...

QList< QgsLayoutItem * >	ungroupItems (QgsLayoutItemGroup *group)
	Ungroups items by removing them from an item group and removing the group from the layout. More...

Qgis::LayoutUnit	units () const
	Returns the native units for the layout. More...

void	updateZValues (bool addUndoCommands=true)
	Resets the z-values of items based on their position in the internal z order list. More...

virtual QDomElement	writeXml (QDomDocument &document, const QgsReadWriteContext &context) const
	Returns the layout's state encapsulated in a DOM element. More...

Public Member Functions inherited from QgsExpressionContextGenerator
virtual	~QgsExpressionContextGenerator ()=default

virtual QgsExpressionContext	createExpressionContext () const =0
	This method needs to be reimplemented in all classes which implement this interface and return an expression context. More...

Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual	~QgsLayoutUndoObjectInterface ()=default
	Destructor for QgsLayoutUndoObjectInterface. More...

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. More...

Static Public Attributes
static const QgsSettingsEntryStringList *	settingsSearchPathForTemplates = new QgsSettingsEntryStringList( QStringLiteral( "search-paths-for-templates" ), QgsSettingsTree::sTreeLayout, QStringList(), QObject::tr( "Search path for templates" ) )
	Settings entry search path for templates. More...

Friends
class	QgsCompositionConverter

class	QgsLayoutItemAddItemCommand

class	QgsLayoutItemDeleteUndoCommand

class	QgsLayoutItemGroupUndoCommand

class	QgsLayoutItemUndoCommand

class	QgsLayoutModel

class	QgsLayoutMultiFrame

class	QgsLayoutUndoCommand

Detailed Description

Base class for layouts, which can contain items such as maps, labels, scalebars, etc.

While the raw QGraphicsScene API can be used to render the contents of a QgsLayout to a QPainter, it is recommended to instead use a QgsLayoutExporter to handle rendering layouts instead. QgsLayoutExporter automatically takes care of the intracacies of preparing the layout and paint devices for correct exports, respecting various user settings such as the layout context DPI.

Since: QGIS 3.0

Definition at line 49 of file qgslayout.h.

Member Enumeration Documentation

◆ UndoCommand

enum QgsLayout::UndoCommand

Layout undo commands, used for collapsing undo commands.

Enumerator
UndoLayoutDpi	Change layout default DPI.
UndoNone	No command suppression.

Definition at line 69 of file qgslayout.h.

◆ ZValues

enum QgsLayout::ZValues

Preset item z-values, to ensure correct stacking.

Enumerator
ZPage	Z-value for page (paper) items.
ZItem	Minimum z value for items.
ZGrid	Z-value for page grids.
ZGuide	Z-value for page guides.
ZSmartGuide	Z-value for smart (item bounds based) guides.
ZMouseHandles	Z-value for mouse handles.
ZViewTool	Z-value for temporary view tool items.
ZSnapIndicator	Z-value for snapping indicator.

Definition at line 56 of file qgslayout.h.

Constructor & Destructor Documentation

◆ QgsLayout()

QgsLayout::QgsLayout ( QgsProject * project )

Construct a new layout linked to the specified project.

If the layout is a "new" layout (as opposed to a layout which will restore a previous state from XML) then initializeDefaults() should be called on the new layout.

Definition at line 44 of file qgslayout.cpp.

◆ ~QgsLayout()

QgsLayout::~QgsLayout ( )

override

Definition at line 58 of file qgslayout.cpp.

Member Function Documentation

◆ accept()

bool QgsLayout::accept ( QgsStyleEntityVisitorInterface * visitor ) const

Accepts the specified style entity visitor, causing it to visit all style entities associated with the layout.

Returns true if the visitor should continue visiting other objects, or false if visiting should be canceled.

Since: QGIS 3.10

Definition at line 798 of file qgslayout.cpp.

◆ addItemsFromXml()

QList< QgsLayoutItem * > QgsLayout::addItemsFromXml	(	const QDomElement &	parentElement,
		const QDomDocument &	document,
		const QgsReadWriteContext &	context,
		QPointF *	position = `nullptr`,
		bool	pasteInPlace = `false`
	)

Add items from an XML representation to the layout.

Used for project file reading and pasting items from clipboard.

The position argument is optional, and if it is not specified the items will be restored to their original position from the XML serialization. If specified, the items will be positioned such that the top-left bounds of all added items is located at this position.

The pasteInPlace argument determines whether the serialized position should be respected, but remapped to the origin of the page corresponding to the page at position.

A list of the newly added items is returned.

Definition at line 998 of file qgslayout.cpp.

◆ addLayoutItem()

void QgsLayout::addLayoutItem ( QgsLayoutItem * item )

Adds an item to the layout.

This should be called instead of the base class addItem() method. Ownership of the item is transferred to the layout.

Definition at line 548 of file qgslayout.cpp.

◆ addMultiFrame()

void QgsLayout::addMultiFrame ( QgsLayoutMultiFrame * multiFrame )

Adds a multiFrame to the layout.

The object is owned by the layout until removeMultiFrame() is called.

See also: removeMultiFrame(); multiFrames()

Definition at line 580 of file qgslayout.cpp.

◆ backgroundTaskCountChanged

void QgsLayout::backgroundTaskCountChanged ( int total )

signal

Emitted whenever the total number of background tasks running in items from the layout changes.

Since: QGIS 3.10

◆ changed

void QgsLayout::changed ( )

signal

Emitted when properties of the layout change.

This signal is only emitted for settings directly managed by the layout, and is not emitted when child items change.

◆ clear()

void QgsLayout::clear ( )

Clears the layout.

Calling this method removes all items and pages from the layout.

Definition at line 119 of file qgslayout.cpp.

◆ clone()

QgsLayout * QgsLayout::clone ( ) const

Creates a clone of the layout.

Ownership of the return layout is transferred to the caller.

Definition at line 91 of file qgslayout.cpp.

◆ convertFromLayoutUnits() [1/3]

QgsLayoutMeasurement QgsLayout::convertFromLayoutUnits	(	double	length,
		Qgis::LayoutUnit	unit
	)		const

Converts a length measurement from the layout's native units to a specified target unit.

Returns: length of measurement in specified units

See also: convertToLayoutUnits(); units()

Definition at line 352 of file qgslayout.cpp.

◆ convertFromLayoutUnits() [2/3]

QgsLayoutPoint QgsLayout::convertFromLayoutUnits	(	QPointF	point,
		Qgis::LayoutUnit	unit
	)		const

Converts a point from the layout's native units to a specified target unit.

Returns: point in specified units

See also: convertToLayoutUnits(); units()

Definition at line 362 of file qgslayout.cpp.

◆ convertFromLayoutUnits() [3/3]

QgsLayoutSize QgsLayout::convertFromLayoutUnits	(	QSizeF	size,
		Qgis::LayoutUnit	unit
	)		const

Converts a size from the layout's native units to a specified target unit.

Returns: size of measurement in specified units

See also: convertToLayoutUnits(); units()

Definition at line 357 of file qgslayout.cpp.

◆ convertToLayoutUnits() [1/3]

QPointF QgsLayout::convertToLayoutUnits ( const QgsLayoutPoint & point ) const

Converts a point into the layout's native units.

Returns: point in layout units

See also: convertFromLayoutUnits(); units()

Definition at line 347 of file qgslayout.cpp.

◆ convertToLayoutUnits() [2/3]

QSizeF QgsLayout::convertToLayoutUnits ( const QgsLayoutSize & size ) const

Converts a size into the layout's native units.

Returns: size of measurement in layout units

See also: convertFromLayoutUnits(); units()

Definition at line 342 of file qgslayout.cpp.

◆ convertToLayoutUnits() [3/3]

double QgsLayout::convertToLayoutUnits ( QgsLayoutMeasurement measurement ) const

Converts a measurement into the layout's native units.

Returns: length of measurement in layout units

See also: convertFromLayoutUnits(); units()

Definition at line 337 of file qgslayout.cpp.

◆ createCommand()

QgsAbstractLayoutUndoCommand * QgsLayout::createCommand	(	const QString &	text,
		int	id = `0`,
		QUndoCommand *	parent = `nullptr`
	)

overridevirtual

Creates a new layout undo command with the specified text and parent.

The id argument can be used to specify an id number for the source event - this is used to determine whether QUndoCommand command compression can apply to the command.

Implements QgsLayoutUndoObjectInterface.

Definition at line 741 of file qgslayout.cpp.

◆ createExpressionContext()

QgsExpressionContext QgsLayout::createExpressionContext ( ) const

overridevirtual

Creates an expression context relating to the layout's current state.

The context includes scopes for global, project, layout and layout context properties.

Implements QgsExpressionContextGenerator.

Reimplemented in QgsPrintLayout.

Definition at line 403 of file qgslayout.cpp.

◆ customProperties()

QStringList QgsLayout::customProperties ( ) const

Returns list of keys stored in custom properties for the layout.

See also: setCustomProperty(); customProperty(); removeCustomProperty()

Definition at line 433 of file qgslayout.cpp.

◆ customProperty()

QVariant QgsLayout::customProperty	(	const QString &	key,
		const QVariant &	defaultValue = `QVariant()`
	)		const

Read a custom property from the layout.

Parameters

key	property key
defaultValue	default value to return if property with matching key does not exist

Returns: value of matching property

See also: setCustomProperty(); removeCustomProperty(); customProperties()

Definition at line 423 of file qgslayout.cpp.

◆ deselectAll()

void QgsLayout::deselectAll ( )

Clears any selected items in the layout.

Call this method rather than QGraphicsScene::clearSelection, as the latter does not correctly emit signals to allow the layout's model to update.

Definition at line 177 of file qgslayout.cpp.

◆ gridSettings() [1/2]

QgsLayoutGridSettings & QgsLayout::gridSettings ( )

inline

Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets.

Definition at line 418 of file qgslayout.h.

◆ gridSettings() [2/2]

const QgsLayoutGridSettings & QgsLayout::gridSettings ( ) const

inline

Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets.

Definition at line 424 of file qgslayout.h.

◆ groupItems()

QgsLayoutItemGroup * QgsLayout::groupItems ( const QList< QgsLayoutItem * > & items )

Creates a new group from a list of layout items and adds the group to the layout.

If grouping was not possible, nullptr will be returned.

See also: ungroupItems()

Definition at line 746 of file qgslayout.cpp.

◆ guides() [1/2]

QgsLayoutGuideCollection & QgsLayout::guides ( )

Returns a reference to the layout's guide collection, which manages page snap guides.

Definition at line 393 of file qgslayout.cpp.

◆ guides() [2/2]

const QgsLayoutGuideCollection & QgsLayout::guides ( ) const

Returns a reference to the layout's guide collection, which manages page snap guides.

Definition at line 398 of file qgslayout.cpp.

◆ initializeDefaults()

void QgsLayout::initializeDefaults ( )

Initializes an empty layout, e.g.

by adding a default page to the layout. This should be called after creating a new layout.

Definition at line 110 of file qgslayout.cpp.

◆ itemAdded

void QgsLayout::itemAdded ( QgsLayoutItem * item )

signal

Emitted when an item was added to the layout.

Since: QGIS 3.20

◆ itemById()

QgsLayoutItem * QgsLayout::itemById ( const QString & id ) const

Returns a layout item given its id.

Since item IDs are not necessarely unique, this function returns the first matching item found.

See also: itemByUuid()

Definition at line 274 of file qgslayout.cpp.

◆ itemByTemplateUuid()

QgsLayoutItem * QgsLayout::itemByTemplateUuid ( const QString & uuid ) const

Returns the layout item with matching template uuid unique identifier, or nullptr if a matching item could not be found.

Unlike itemByUuid(), this method ONLY checks template UUIDs for a match.

Template UUIDs are valid only for items which have been added to an existing layout from a template. In this case the template UUID is the original item UUID at the time the template was created, vs the item's uuid() which returns the current instance of the item's unique identifier.

Note that template UUIDs are only available while a layout is being restored from XML.

See also: itemByUuid(); multiFrameByUuid(); itemById()

Definition at line 261 of file qgslayout.cpp.

◆ itemByUuid()

QgsLayoutItem * QgsLayout::itemByUuid	(	const QString &	uuid,
		bool	includeTemplateUuids = `false`
	)		const

Returns the layout item with matching uuid unique identifier, or nullptr if a matching item could not be found.

If includeTemplateUuids is true, then item's template UUID will also be tested when trying to match the uuid. This may differ from the item's UUID for items which have been added to an existing layout from a template. In this case the template UUID returns the original item UUID at the time the template was created, vs the item's uuid() which returns the current instance of the item's unique identifier. Note that template UUIDs are only available while a layout is being restored from XML.

See also: itemByTemplateUuid(); multiFrameByUuid(); itemById()

Definition at line 246 of file qgslayout.cpp.

◆ itemsModel()

QgsLayoutModel * QgsLayout::itemsModel ( )

Returns the items model attached to the layout.

Definition at line 145 of file qgslayout.cpp.

◆ layoutBounds()

QRectF QgsLayout::layoutBounds	(	bool	ignorePages = `false`,
		double	margin = `0.0`
	)		const

Calculates the bounds of all non-gui items in the layout.

Ignores snap lines, mouse handles and other cosmetic items.

Parameters

ignorePages	set to `true` to ignore page items
margin	optional marginal (in percent, e.g., 0.05 = 5% ) to add around items

Returns: layout bounds, in layout units.

See also: pageItemBounds()

Definition at line 477 of file qgslayout.cpp.

◆ layoutItemAt() [1/2]

QgsLayoutItem * QgsLayout::layoutItemAt	(	QPointF	position,
		bool	ignoreLocked = `false`
	)		const

Returns the topmost layout item at a specified position.

Ignores paper items. If ignoreLocked is set to true any locked items will be ignored.

Definition at line 301 of file qgslayout.cpp.

◆ layoutItemAt() [2/2]

QgsLayoutItem * QgsLayout::layoutItemAt	(	QPointF	position,
		const QgsLayoutItem *	belowItem,
		bool	ignoreLocked = `false`
	)		const

Returns the topmost layout item at a specified position which is below a specified item.

Ignores paper items. If ignoreLocked is set to true any locked items will be ignored.

Definition at line 306 of file qgslayout.cpp.

◆ layoutItems()

template<class T >

void QgsLayout::layoutItems ( QList< T * > & itemList ) const

inline

Returns a list of layout items of a specific type.

Note: not available in Python bindings

Definition at line 121 of file qgslayout.h.

◆ layoutObjects()

template<class T >

void QgsLayout::layoutObjects ( QList< T * > & objectList ) const

inline

Returns a list of layout objects (items and multiframes) of a specific type.

Note: not available in Python bindings

Definition at line 140 of file qgslayout.h.

◆ loadFromTemplate()

QList< QgsLayoutItem * > QgsLayout::loadFromTemplate	(	const QDomDocument &	document,
		const QgsReadWriteContext &	context,
		bool	clearExisting = `true`,
		bool *	ok = `nullptr`
	)

Load a layout template document.

By default this method will clear all items from the existing layout and real all layout settings from the template. Setting clearExisting to false will only add new items from the template, without overwriting the existing items or layout settings.

If ok is specified, it will be set to true if the load was successful.

Returns a list of loaded items.

Definition at line 617 of file qgslayout.cpp.

◆ lowerItem()

bool QgsLayout::lowerItem	(	QgsLayoutItem *	item,
		bool	deferUpdate = `false`
	)

Lowers an item down the z-order.

Returns true if the item was successfully lowered.

If deferUpdate is true, the scene will not be visibly updated to reflect the new stacking order. This allows multiple raiseItem() calls to be made in sequence without the cost of updating the scene for each one.

See also: raiseItem(); updateZValues()

Definition at line 207 of file qgslayout.cpp.

◆ moveItemToBottom()

bool QgsLayout::moveItemToBottom	(	QgsLayoutItem *	item,
		bool	deferUpdate = `false`
	)

Lowers an item down to the bottom of the z-order.

Returns true if the item was successfully lowered. If deferUpdate is true, the scene will not be visibly updated to reflect the new stacking order. This allows multiple raiseItem() calls to be made in sequence without the cost of updating the scene for each one.

See also: moveItemToTop(); updateZValues()

Definition at line 233 of file qgslayout.cpp.

◆ moveItemToTop()

bool QgsLayout::moveItemToTop	(	QgsLayoutItem *	item,
		bool	deferUpdate = `false`
	)

Raises an item up to the top of the z-order.

Returns true if the item was successfully raised.

If deferUpdate is true, the scene will not be visibly updated to reflect the new stacking order. This allows multiple raiseItem() calls to be made in sequence without the cost of updating the scene for each one.

See also: moveItemToBottom(); updateZValues()

Definition at line 220 of file qgslayout.cpp.

◆ multiFrameByUuid()

QgsLayoutMultiFrame * QgsLayout::multiFrameByUuid	(	const QString &	uuid,
		bool	includeTemplateUuids = `false`
	)		const

Returns the layout multiframe with matching uuid unique identifier, or nullptr if a matching multiframe could not be found.

If includeTemplateUuids is true, then the multiframe's QgsLayoutMultiFrame::templateUuid() will also be tested when trying to match the uuid. Template UUIDs are valid only for items which have been added to an existing layout from a template. In this case the template UUID is the original item UUID at the time the template was created, vs the item's uuid() which returns the current instance of the item's unique identifier. Note that template UUIDs are only available while a layout is being restored from XML.

See also: itemByUuid()

Definition at line 288 of file qgslayout.cpp.

◆ multiFrames()

QList< QgsLayoutMultiFrame * > QgsLayout::multiFrames ( ) const

Returns a list of multi frames contained in the layout.

See also: addMultiFrame(); removeMultiFrame()

Definition at line 594 of file qgslayout.cpp.

◆ pageCollection() [1/2]

QgsLayoutPageCollection * QgsLayout::pageCollection ( )

Returns a pointer to the layout's page collection, which stores and manages page items in the layout.

Definition at line 467 of file qgslayout.cpp.

◆ pageCollection() [2/2]

const QgsLayoutPageCollection * QgsLayout::pageCollection ( ) const

Returns a pointer to the layout's page collection, which stores and manages page items in the layout.

Definition at line 472 of file qgslayout.cpp.

◆ pageItemBounds()

QRectF QgsLayout::pageItemBounds	(	int	page,
		bool	visibleOnly = `false`
	)		const

Returns the bounding box of the items contained on a specified page.

A page number of 0 represents the first page in the layout.

Set visibleOnly to true to only include visible items.

The returned bounds are in layout units.

See also: layoutBounds()

Definition at line 522 of file qgslayout.cpp.

◆ project()

QgsProject * QgsLayout::project ( ) const

The project associated with the layout.

Used to get access to layers, map themes, relations and various other bits. It is never nullptr.

Definition at line 140 of file qgslayout.cpp.

◆ raiseItem()

bool QgsLayout::raiseItem	(	QgsLayoutItem *	item,
		bool	deferUpdate = `false`
	)

Raises an item up the z-order.

Returns true if the item was successfully raised.

If deferUpdate is true, the scene will not be visibly updated to reflect the new stacking order. This allows multiple raiseItem() calls to be made in sequence without the cost of updating the scene for each one.

See also: lowerItem(); updateZValues()

Definition at line 194 of file qgslayout.cpp.

◆ readXml()

bool QgsLayout::readXml	(	const QDomElement &	layoutElement,
		const QDomDocument &	document,
		const QgsReadWriteContext &	context
	)

virtual

Sets the collection's state from a DOM element.

layoutElement is the DOM node corresponding to the layout.

See also: writeXml()

Reimplemented in QgsPrintLayout.

Definition at line 959 of file qgslayout.cpp.

◆ referenceMap()

QgsLayoutItemMap * QgsLayout::referenceMap ( ) const

Returns the map item which will be used to generate corresponding world files when the layout is exported.

If no map was explicitly set via setReferenceMap(), the largest map in the layout will be returned (or nullptr if there are no maps in the layout).

See also: setReferenceMap()

Definition at line 438 of file qgslayout.cpp.

◆ refresh

void QgsLayout::refresh ( )

slot

Forces the layout, and all items contained within it, to refresh.

For instance, this causes maps to redraw and rebuild cached images, html items to reload their source url, and attribute tables to refresh their contents. Calling this also triggers a recalculation of all data defined attributes within the layout.

See also: refreshed()

Definition at line 813 of file qgslayout.cpp.

◆ refreshed

void QgsLayout::refreshed ( )

signal

Emitted when the layout has been refreshed and items should also be refreshed and updated.

◆ reloadSettings()

void QgsLayout::reloadSettings ( )

Refreshes the layout when global layout related options change.

Definition at line 387 of file qgslayout.cpp.

◆ removeCustomProperty()

void QgsLayout::removeCustomProperty ( const QString & key )

Remove a custom property from the layout.

Parameters

key	property key

See also: setCustomProperty(); customProperty(); customProperties()

Definition at line 428 of file qgslayout.cpp.

◆ removeLayoutItem()

void QgsLayout::removeLayoutItem ( QgsLayoutItem * item )

Removes an item from the layout.

This should be called instead of the base class removeItem() method. The item will also be deleted.

Definition at line 564 of file qgslayout.cpp.

◆ removeMultiFrame()

void QgsLayout::removeMultiFrame ( QgsLayoutMultiFrame * multiFrame )

Removes a multiFrame from the layout (but does not delete it).

See also: addMultiFrame(); multiFrames()

Definition at line 589 of file qgslayout.cpp.

◆ renderContext() [1/2]

QgsLayoutRenderContext & QgsLayout::renderContext ( )

Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout.

Definition at line 367 of file qgslayout.cpp.

◆ renderContext() [2/2]

const QgsLayoutRenderContext & QgsLayout::renderContext ( ) const

Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout.

Definition at line 372 of file qgslayout.cpp.

◆ reportContext() [1/2]

QgsLayoutReportContext & QgsLayout::reportContext ( )

Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout.

Definition at line 377 of file qgslayout.cpp.

◆ reportContext() [2/2]

const QgsLayoutReportContext & QgsLayout::reportContext ( ) const

Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout.

Definition at line 382 of file qgslayout.cpp.

◆ saveAsTemplate()

bool QgsLayout::saveAsTemplate	(	const QString &	path,
		const QgsReadWriteContext &	context
	)		const

Saves the layout as a template at the given file path.

Returns true if save was successful.

See also: loadFromTemplate()

Definition at line 599 of file qgslayout.cpp.

◆ selectedItemChanged

void QgsLayout::selectedItemChanged ( QgsLayoutItem * selected )

signal

Emitted whenever the selected item changes.

If nullptr, no item is selected.

◆ selectedLayoutItems()

QList< QgsLayoutItem * > QgsLayout::selectedLayoutItems ( bool includeLockedItems = true )

Returns list of selected layout items.

If includeLockedItems is set to true, then locked items will also be included in the returned list.

Definition at line 150 of file qgslayout.cpp.

◆ setCustomProperty()

void QgsLayout::setCustomProperty	(	const QString &	key,
		const QVariant &	value
	)

Set a custom property for the layout.

Parameters

key	property key. If a property with the same key already exists it will be overwritten.
value	property value

See also: customProperty(); removeCustomProperty(); customProperties()

Definition at line 415 of file qgslayout.cpp.

◆ setReferenceMap()

void QgsLayout::setReferenceMap ( QgsLayoutItemMap * map )

Sets the map item which will be used to generate corresponding world files when the layout is exported.

See also: referenceMap()

Definition at line 461 of file qgslayout.cpp.

◆ setSelectedItem()

void QgsLayout::setSelectedItem ( QgsLayoutItem * item )

Clears any selected items and sets item as the current selection.

Definition at line 167 of file qgslayout.cpp.

◆ setUnits()

void QgsLayout::setUnits ( Qgis::LayoutUnit units )

inline

Sets the native measurement units for the layout.

These also form the default unit for measurements for the layout.

See also: units(); convertToLayoutUnits()

Definition at line 321 of file qgslayout.h.

◆ snapper() [1/2]

QgsLayoutSnapper & QgsLayout::snapper ( )

inline

Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point.

Definition at line 406 of file qgslayout.h.

◆ snapper() [2/2]

const QgsLayoutSnapper & QgsLayout::snapper ( ) const

inline

Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point.

Definition at line 412 of file qgslayout.h.

◆ undoStack() [1/2]

QgsLayoutUndoStack * QgsLayout::undoStack ( )

Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects.

Definition at line 694 of file qgslayout.cpp.

◆ undoStack() [2/2]

const QgsLayoutUndoStack * QgsLayout::undoStack ( ) const

Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects.

Definition at line 699 of file qgslayout.cpp.

◆ ungroupItems()

QList< QgsLayoutItem * > QgsLayout::ungroupItems ( QgsLayoutItemGroup * group )

Ungroups items by removing them from an item group and removing the group from the layout.

Child items will remain in the layout and will not be deleted.

Returns a list of the items removed from the group, or an empty list if ungrouping was not successful.

See also: groupItems()

Definition at line 773 of file qgslayout.cpp.

◆ units()

Qgis::LayoutUnit QgsLayout::units ( ) const

inline

Returns the native units for the layout.

See also: setUnits(); convertToLayoutUnits()

Definition at line 328 of file qgslayout.h.

◆ updateBounds

void QgsLayout::updateBounds ( )

slot

Updates the scene bounds of the layout.

Definition at line 1178 of file qgslayout.cpp.

◆ updateZValues()

void QgsLayout::updateZValues ( bool addUndoCommands = true )

Resets the z-values of items based on their position in the internal z order list.

This should be called after any stacking changes which deferred z-order updates.

Definition at line 928 of file qgslayout.cpp.

◆ variablesChanged

void QgsLayout::variablesChanged ( )

signal

Emitted whenever the expression variables stored in the layout have been changed.

◆ writeXml()

QDomElement QgsLayout::writeXml	(	QDomDocument &	document,
		const QgsReadWriteContext &	context
	)		const

virtual

Returns the layout's state encapsulated in a DOM element.

See also: readXml()

Reimplemented in QgsPrintLayout.

Definition at line 832 of file qgslayout.cpp.

Friends And Related Function Documentation

◆ QgsCompositionConverter

friend class QgsCompositionConverter

friend

Definition at line 779 of file qgslayout.h.

◆ QgsLayoutItemAddItemCommand

friend class QgsLayoutItemAddItemCommand

friend

Definition at line 772 of file qgslayout.h.

◆ QgsLayoutItemDeleteUndoCommand

friend class QgsLayoutItemDeleteUndoCommand

friend

Definition at line 773 of file qgslayout.h.

◆ QgsLayoutItemGroupUndoCommand

friend class QgsLayoutItemGroupUndoCommand

friend

Definition at line 776 of file qgslayout.h.

◆ QgsLayoutItemUndoCommand

friend class QgsLayoutItemUndoCommand

friend

Definition at line 774 of file qgslayout.h.

◆ QgsLayoutModel

friend class QgsLayoutModel

friend

Definition at line 777 of file qgslayout.h.

◆ QgsLayoutMultiFrame

friend class QgsLayoutMultiFrame

friend

Definition at line 778 of file qgslayout.h.

◆ QgsLayoutUndoCommand

friend class QgsLayoutUndoCommand

friend

Definition at line 775 of file qgslayout.h.

Member Data Documentation

◆ settingsSearchPathForTemplates

const QgsSettingsEntryStringList * QgsLayout::settingsSearchPathForTemplates = new QgsSettingsEntryStringList( QStringLiteral( "search-paths-for-templates" ), QgsSettingsTree::sTreeLayout, QStringList(), QObject::tr( "Search path for templates" ) )

static

Settings entry search path for templates.

Definition at line 662 of file qgslayout.h.

The documentation for this class was generated from the following files:

/build/qgis-3.32.0+99sid/src/core/layout/qgslayout.h
/build/qgis-3.32.0+99sid/src/core/layout/qgslayout.cpp

Public Types

Public Slots

Signals

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ UndoCommand

◆ ZValues

Constructor & Destructor Documentation

◆ QgsLayout()

◆ ~QgsLayout()

Member Function Documentation

◆ accept()

◆ addItemsFromXml()

◆ addLayoutItem()

◆ addMultiFrame()

◆ backgroundTaskCountChanged

◆ changed

◆ clear()

◆ clone()

◆ convertFromLayoutUnits() [1/3]

◆ convertFromLayoutUnits() [2/3]

◆ convertFromLayoutUnits() [3/3]

◆ convertToLayoutUnits() [1/3]

◆ convertToLayoutUnits() [2/3]

◆ convertToLayoutUnits() [3/3]

◆ createCommand()

◆ createExpressionContext()

◆ customProperties()

◆ customProperty()

◆ deselectAll()

◆ gridSettings() [1/2]

◆ gridSettings() [2/2]

◆ groupItems()

◆ guides() [1/2]

◆ guides() [2/2]

◆ initializeDefaults()

◆ itemAdded

◆ itemById()

◆ itemByTemplateUuid()

◆ itemByUuid()

◆ itemsModel()

◆ layoutBounds()

◆ layoutItemAt() [1/2]

◆ layoutItemAt() [2/2]

◆ layoutItems()

◆ layoutObjects()

◆ loadFromTemplate()

◆ lowerItem()

◆ moveItemToBottom()

◆ moveItemToTop()

◆ multiFrameByUuid()

◆ multiFrames()

◆ pageCollection() [1/2]

◆ pageCollection() [2/2]

◆ pageItemBounds()

◆ project()

◆ raiseItem()

◆ readXml()

◆ referenceMap()

◆ refresh

◆ refreshed

◆ reloadSettings()

◆ removeCustomProperty()

◆ removeLayoutItem()

◆ removeMultiFrame()

◆ renderContext() [1/2]

◆ renderContext() [2/2]

◆ reportContext() [1/2]

◆ reportContext() [2/2]

◆ saveAsTemplate()

◆ selectedItemChanged

◆ selectedLayoutItems()

◆ setCustomProperty()

◆ setReferenceMap()

◆ setSelectedItem()

◆ setUnits()

◆ snapper() [1/2]