Print layout, a QgsLayout subclass for static or atlas-based layouts. More...

#include <qgsprintlayout.h>

Inheritance diagram for QgsPrintLayout:

[legend]

Signals
void	nameChanged (const QString &name)
	Emitted when the layout's name is changed.

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

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

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

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

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

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

Public Member Functions
	QgsPrintLayout (QgsProject *project)
	Constructor for QgsPrintLayout.

QgsLayoutAtlas *	atlas ()
	Returns the print layout's atlas.

QgsPrintLayout *	clone () const override
	Creates a clone of the layout.

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

QIcon	icon () const override
	Returns an icon for the layout.

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

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

QgsMasterLayoutInterface::Type	layoutType () const override
	Returns the master layout type.

QString	name () const override
	Returns the layout's name.

bool	readLayoutXml (const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context) override
	Sets the layout's state from a DOM element.

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

void	setName (const QString &name) override
	Sets the layout's name.

void	updateSettings () override
	Refreshes the layout when global layout related options change.

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

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

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

	~QgsLayout () override

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

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.

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

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

void	clear ()
	Clears the layout.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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.

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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.

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.

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

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.

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

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

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

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

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

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

Properties
QString	name

Additional Inherited Members
Public Types inherited from QgsLayout
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 Types inherited from QgsMasterLayoutInterface
enum	Type { PrintLayout = 0 , Report = 1 }
	Master layout type. More...

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

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

Static Public Attributes inherited from QgsLayout
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.

Detailed Description

Print layout, a QgsLayout subclass for static or atlas-based layouts.

Definition at line 29 of file qgsprintlayout.h.

Constructor & Destructor Documentation

◆ QgsPrintLayout()

QgsPrintLayout::QgsPrintLayout ( QgsProject * project )

Constructor for QgsPrintLayout.

Definition at line 24 of file qgsprintlayout.cpp.

Member Function Documentation

◆ atlas()

QgsLayoutAtlas * QgsPrintLayout::atlas ( )

Returns the print layout's atlas.

Definition at line 59 of file qgsprintlayout.cpp.

◆ clone()

QgsPrintLayout * QgsPrintLayout::clone ( ) const

overridevirtual

Creates a clone of the layout.

Ownership of the returned layout is transferred to the caller.

Implements QgsMasterLayoutInterface.

Definition at line 30 of file qgsprintlayout.cpp.

◆ createExpressionContext()

QgsExpressionContext QgsPrintLayout::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.

Reimplemented from QgsLayout.

Definition at line 102 of file qgsprintlayout.cpp.

◆ icon()

QIcon QgsPrintLayout::icon ( ) const

overridevirtual

Returns an icon for the layout.

Implements QgsMasterLayoutInterface.

Definition at line 54 of file qgsprintlayout.cpp.

◆ layoutAccept()

bool QgsPrintLayout::layoutAccept ( QgsStyleEntityVisitorInterface * visitor ) const

overridevirtual

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

Reimplemented from QgsMasterLayoutInterface.

Definition at line 119 of file qgsprintlayout.cpp.

◆ layoutProject()

QgsProject * QgsPrintLayout::layoutProject ( ) const

overridevirtual

The project associated with the layout.

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

Implements QgsMasterLayoutInterface.

Definition at line 49 of file qgsprintlayout.cpp.

◆ layoutType()

QgsMasterLayoutInterface::Type QgsPrintLayout::layoutType ( ) const

overridevirtual

Returns the master layout type.

Implements QgsMasterLayoutInterface.

Definition at line 132 of file qgsprintlayout.cpp.

◆ name()

QString QgsPrintLayout::name ( ) const

inlineoverridevirtual

Returns the layout's name.

See also: setName()

Implements QgsMasterLayoutInterface.

Definition at line 51 of file qgsprintlayout.h.

◆ nameChanged

void QgsPrintLayout::nameChanged ( const QString & name )

signal

Emitted when the layout's name is changed.

See also: setName()

◆ readLayoutXml()

bool QgsPrintLayout::readLayoutXml	(	const QDomElement &	layoutElement,
		const QDomDocument &	document,
		const QgsReadWriteContext &	context
	)

overridevirtual

Sets the layout's state from a DOM element.

layoutElement is the DOM node corresponding to the layout.

See also: writeLayoutXml()

Implements QgsMasterLayoutInterface.

Definition at line 97 of file qgsprintlayout.cpp.

◆ readXml()

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

overridevirtual

Sets the collection's state from a DOM element.

layoutElement is the DOM node corresponding to the layout.

See also: writeXml()

Reimplemented from QgsLayout.

Definition at line 79 of file qgsprintlayout.cpp.

◆ setName()

void QgsPrintLayout::setName ( const QString & name )

overridevirtual

Sets the layout's name.

See also: name()

Implements QgsMasterLayoutInterface.

Definition at line 64 of file qgsprintlayout.cpp.

◆ updateSettings()

void QgsPrintLayout::updateSettings ( )

overridevirtual

Refreshes the layout when global layout related options change.

Implements QgsMasterLayoutInterface.

Definition at line 114 of file qgsprintlayout.cpp.

◆ writeLayoutXml()

QDomElement QgsPrintLayout::writeLayoutXml	(	QDomDocument &	document,
		const QgsReadWriteContext &	context
	)		const

overridevirtual

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

See also: readLayoutXml()

Implements QgsMasterLayoutInterface.

Definition at line 92 of file qgsprintlayout.cpp.

◆ writeXml()

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

overridevirtual

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

See also: readXml()

Reimplemented from QgsLayout.

Definition at line 71 of file qgsprintlayout.cpp.

Property Documentation

◆ name

QString QgsPrintLayout::name

readwrite

Definition at line 32 of file qgsprintlayout.h.

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

/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/layout/qgsprintlayout.h
/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/layout/qgsprintlayout.cpp

Signals

Public Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QgsPrintLayout()

Member Function Documentation

◆ atlas()

◆ clone()

◆ createExpressionContext()

◆ icon()

◆ layoutAccept()

◆ layoutProject()

◆ layoutType()

◆ name()

◆ nameChanged

◆ readLayoutXml()

◆ readXml()

◆ setName()

◆ updateSettings()

◆ writeLayoutXml()

◆ writeXml()

Property Documentation

◆ name