Class used to render QgsLayout as an atlas, by iterating over the features from an associated vector layer. More...

#include <qgslayoutatlas.h>

Inheritance diagram for QgsLayoutAtlas:

[legend]

Public Slots
bool	first ()
	Seeks to the first feature, returning `false` if no feature was found. More...

bool	last ()
	Seeks to the last feature, returning `false` if no feature was found. More...

bool	next () override

bool	previous ()
	Iterates to the previous feature, returning `false` if no previous feature exists. More...

void	refreshCurrentFeature ()
	Refreshes the current atlas feature, by refetching its attributes from the vector layer provider. More...

bool	seekTo (const QgsFeature &feature)
	Seeks to the specified feature. More...

bool	seekTo (int feature)
	Seeks to the specified feature number. More...

Signals
void	changed ()
	Emitted when one of the atlas parameters changes. More...

void	coverageLayerChanged (QgsVectorLayer *layer)
	Emitted when the coverage layer for the atlas changes. More...

void	featureChanged (const QgsFeature &feature)
	Emitted when the current atlas feature changes. More...

void	messagePushed (const QString &message)
	Emitted when the atlas has an updated status bar message. More...

void	numberFeaturesChanged (int numFeatures)
	Emitted when the number of features for the atlas changes. More...

void	renderBegun ()
	Emitted when atlas rendering has begun. More...

void	renderEnded ()
	Emitted when atlas rendering has ended. More...

void	toggled (bool)
	Emitted when atlas is enabled or disabled. More...

Public Member Functions
	QgsLayoutAtlas (QgsLayout *layout)
	Constructor for new QgsLayoutAtlas. More...

bool	beginRender () override
	Called when rendering begins, before iteration commences. More...

int	count () const override
	Returns the number of features to iterate over. More...

QgsVectorLayer *	coverageLayer () const
	Returns the coverage layer used for the atlas features. More...

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

int	currentFeatureNumber () const
	Returns the current feature number, where a value of 0 corresponds to the first feature. More...

QString	currentFilename () const
	Returns the current feature filename. More...

bool	enabled () const
	Returns whether the atlas generation is enabled. More...

bool	endRender () override
	Ends the render, performing any required cleanup tasks. More...

QString	filenameExpression () const
	Returns the filename expression used for generating output filenames for each atlas page. More...

QString	filePath (const QString &baseFilePath, const QString &extension) override
	Returns the file path for the current feature, based on a specified base file path and extension. More...

QString	filterExpression () const
	Returns the expression used for filtering features in the coverage layer. More...

bool	filterFeatures () const
	Returns `true` if features should be filtered in the coverage layer. More...

bool	hideCoverage () const
	Returns `true` if the atlas is set to hide the coverage layer. More...

const QgsLayout *	layout () const
	Returns the atlas' layout. More...

QgsLayout *	layout () override
	Returns the layout associated with the iterator. More...

QString	nameForPage (int page) const
	Returns the calculated name for a specified atlas page number. More...

QString	pageNameExpression () const
	Returns the expression (or field name) used for calculating the page name. More...

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

void	setCoverageLayer (QgsVectorLayer *layer)
	Sets the coverage layer to use for the atlas features. More...

void	setEnabled (bool enabled)
	Sets whether the atlas is enabled. More...

bool	setFilenameExpression (const QString &expression, QString &errorString)
	Sets the filename expression used for generating output filenames for each atlas page. More...

bool	setFilterExpression (const QString &expression, QString &errorString)
	Sets the expression used for filtering features in the coverage layer. More...

void	setFilterFeatures (bool filtered)
	Sets whether features should be filtered in the coverage layer. More...

void	setHideCoverage (bool hide)
	Sets whether the coverage layer should be hidden in map items in the layouts. More...

void	setPageNameExpression (const QString &expression)
	Sets the expression (or field name) used for calculating the page name. More...

void	setSortAscending (bool ascending)
	Sets whether features should be sorted in an ascending order. More...

void	setSortExpression (const QString &expression)
	Sets the expression (or field name) to use for sorting features. More...

void	setSortFeatures (bool enabled)
	Sets whether features should be sorted in the atlas. More...

bool	sortAscending () const
	Returns `true` if features should be sorted in an ascending order. More...

QString	sortExpression () const
	Returns the expression (or field name) to use for sorting features. More...

bool	sortFeatures () const
	Returns `true` if features should be sorted in the atlas. More...

QString	stringType () const override
	Returns the object type as a string. More...

int	updateFeatures ()
	Requeries the current atlas coverage layer and applies filtering and sorting. More...

bool	writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const override
	Stores the objects's state in a DOM element. More...

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

virtual bool	next ()=0
	Iterates to next feature, returning `false` if no more features exist to iterate over. More...

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

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

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

Friends
class	AtlasFeatureSorter

Detailed Description

Class used to render QgsLayout as an atlas, by iterating over the features from an associated vector layer.

QgsLayoutAtlas implement the QgsAbstractLayoutIterator interface, allowing them to be used directly with QgsLayoutExporter to automatically output all pages from the atlas.

For QgsPrintLayout layouts, it is not necessary to manually construct a QgsLayoutAtlas object. Instead, the atlas attached to the print layout should be used. This can be retrieved by calling QgsPrintLayout::atlas().

Since: QGIS 3.0

Definition at line 41 of file qgslayoutatlas.h.

Constructor & Destructor Documentation

◆ QgsLayoutAtlas()

QgsLayoutAtlas::QgsLayoutAtlas ( QgsLayout * layout )

Constructor for new QgsLayoutAtlas.

Definition at line 29 of file qgslayoutatlas.cpp.

Member Function Documentation

◆ beginRender()

bool QgsLayoutAtlas::beginRender ( )

overridevirtual

Called when rendering begins, before iteration commences.

Returns true if successful, false if no iteration is available or required.

See also: endRender()

Implements QgsAbstractLayoutIterator.

Definition at line 376 of file qgslayoutatlas.cpp.

◆ changed

void QgsLayoutAtlas::changed ( )

signal

Emitted when one of the atlas parameters changes.

◆ count()

int QgsLayoutAtlas::count ( ) const

overridevirtual

Returns the number of features to iterate over.

Implements QgsAbstractLayoutIterator.

Definition at line 401 of file qgslayoutatlas.cpp.

◆ coverageLayer()

QgsVectorLayer* QgsLayoutAtlas::coverageLayer ( ) const

inline

Returns the coverage layer used for the atlas features.

See also: setCoverageLayer()

Definition at line 116 of file qgslayoutatlas.h.

◆ coverageLayerChanged

void QgsLayoutAtlas::coverageLayerChanged ( QgsVectorLayer * layer )

signal

Emitted when the coverage layer for the atlas changes.

◆ createExpressionContext()

QgsExpressionContext QgsLayoutAtlas::createExpressionContext ( ) const

overridevirtual

This method needs to be reimplemented in all classes which implement this interface and return an expression context.

Since: QGIS 3.0

Implements QgsExpressionContextGenerator.

Definition at line 508 of file qgslayoutatlas.cpp.

◆ currentFeatureNumber()

int QgsLayoutAtlas::currentFeatureNumber ( ) const

inline

Returns the current feature number, where a value of 0 corresponds to the first feature.

Definition at line 254 of file qgslayoutatlas.h.

◆ currentFilename()

QString QgsLayoutAtlas::currentFilename ( ) const

Returns the current feature filename.

See also: filenameExpression(); setFilenameExpression()

Definition at line 503 of file qgslayoutatlas.cpp.

◆ enabled()

bool QgsLayoutAtlas::enabled ( ) const

inline

Returns whether the atlas generation is enabled.

See also: setEnabled()

Definition at line 67 of file qgslayoutatlas.h.

◆ endRender()

bool QgsLayoutAtlas::endRender ( )

overridevirtual

Ends the render, performing any required cleanup tasks.

Implements QgsAbstractLayoutIterator.

Definition at line 394 of file qgslayoutatlas.cpp.

◆ featureChanged

void QgsLayoutAtlas::featureChanged ( const QgsFeature & feature )

signal

Emitted when the current atlas feature changes.

◆ filenameExpression()

QString QgsLayoutAtlas::filenameExpression ( ) const

inline

Returns the filename expression used for generating output filenames for each atlas page.

See also: setFilenameExpression(); currentFilename()

Definition at line 93 of file qgslayoutatlas.h.

◆ filePath()

QString QgsLayoutAtlas::filePath	(	const QString &	baseFilePath,
		const QString &	extension
	)

overridevirtual

Returns the file path for the current feature, based on a specified base file path and extension.

Implements QgsAbstractLayoutIterator.

Definition at line 406 of file qgslayoutatlas.cpp.

◆ filterExpression()

QString QgsLayoutAtlas::filterExpression ( ) const

inline

Returns the expression used for filtering features in the coverage layer.

This property has no effect is filterFeatures() is false.

See also: setFilterExpression(); filterFeatures()

Definition at line 225 of file qgslayoutatlas.h.

◆ filterFeatures()

bool QgsLayoutAtlas::filterFeatures ( ) const

inline

Returns true if features should be filtered in the coverage layer.

See also: filterExpression(); setFilterExpression()

Definition at line 208 of file qgslayoutatlas.h.

◆ first

bool QgsLayoutAtlas::first ( )

slot

Seeks to the first feature, returning false if no feature was found.

See also: next(); previous(); last(); seekTo()

Definition at line 439 of file qgslayoutatlas.cpp.

◆ hideCoverage()

bool QgsLayoutAtlas::hideCoverage ( ) const

inline

Returns true if the atlas is set to hide the coverage layer.

See also: setHideCoverage()

Definition at line 79 of file qgslayoutatlas.h.

◆ last

bool QgsLayoutAtlas::last ( )

slot

Seeks to the last feature, returning false if no feature was found.

See also: next(); previous(); first(); seekTo()

Definition at line 444 of file qgslayoutatlas.cpp.

◆ layout() [1/2]

const QgsLayout * QgsLayoutAtlas::layout ( ) const

Returns the atlas' layout.

Note: Not available in Python bindings.

Definition at line 52 of file qgslayoutatlas.cpp.

◆ layout() [2/2]

QgsLayout * QgsLayoutAtlas::layout ( )

overridevirtual

Returns the layout associated with the iterator.

Implements QgsAbstractLayoutIterator.

Definition at line 47 of file qgslayoutatlas.cpp.

◆ messagePushed

void QgsLayoutAtlas::messagePushed ( const QString & message )

signal

Emitted when the atlas has an updated status bar message.

◆ nameForPage()

QString QgsLayoutAtlas::nameForPage ( int page ) const

Returns the calculated name for a specified atlas page number.

Page numbers start at 0.

See also: pageNameExpression()

Definition at line 177 of file qgslayoutatlas.cpp.

◆ next

bool QgsLayoutAtlas::next ( )

overrideslot

Definition at line 417 of file qgslayoutatlas.cpp.

◆ numberFeaturesChanged

void QgsLayoutAtlas::numberFeaturesChanged ( int numFeatures )

signal

Emitted when the number of features for the atlas changes.

◆ pageNameExpression()

QString QgsLayoutAtlas::pageNameExpression ( ) const

inline

Returns the expression (or field name) used for calculating the page name.

See also: setPageNameExpression(); nameForPage()

Definition at line 129 of file qgslayoutatlas.h.

◆ previous

bool QgsLayoutAtlas::previous ( )

slot

Iterates to the previous feature, returning false if no previous feature exists.

See also: next(); last(); first(); seekTo()

Definition at line 428 of file qgslayoutatlas.cpp.

◆ readXml()

bool QgsLayoutAtlas::readXml	(	const QDomElement &	element,
		const QDomDocument &	document,
		const QgsReadWriteContext &	context
	)

overridevirtual

Sets the objects's state from a DOM element.

element is the DOM node corresponding to the object.

See also: writeXml()

Implements QgsLayoutSerializableObject.

Definition at line 95 of file qgslayoutatlas.cpp.

◆ refreshCurrentFeature

void QgsLayoutAtlas::refreshCurrentFeature ( )

slot

Refreshes the current atlas feature, by refetching its attributes from the vector layer provider.

Definition at line 476 of file qgslayoutatlas.cpp.

◆ renderBegun

void QgsLayoutAtlas::renderBegun ( )

signal

Emitted when atlas rendering has begun.

◆ renderEnded

void QgsLayoutAtlas::renderEnded ( )

signal

Emitted when atlas rendering has ended.

◆ seekTo [1/2]

bool QgsLayoutAtlas::seekTo ( const QgsFeature & feature )

slot

Seeks to the specified feature.

See also: first(); previous(); next(); last()

Definition at line 454 of file qgslayoutatlas.cpp.

◆ seekTo [2/2]

bool QgsLayoutAtlas::seekTo ( int feature )

slot

Seeks to the specified feature number.

See also: first(); previous(); next(); last()

Definition at line 449 of file qgslayoutatlas.cpp.

◆ setCoverageLayer()

void QgsLayoutAtlas::setCoverageLayer ( QgsVectorLayer * layer )

Sets the coverage layer to use for the atlas features.

See also: coverageLayer()

Definition at line 157 of file qgslayoutatlas.cpp.

◆ setEnabled()

void QgsLayoutAtlas::setEnabled ( bool enabled )

Sets whether the atlas is enabled.

See also: enabled()

Definition at line 126 of file qgslayoutatlas.cpp.

◆ setFilenameExpression()

bool QgsLayoutAtlas::setFilenameExpression	(	const QString &	expression,
		QString &	errorString
	)

Sets the filename expression used for generating output filenames for each atlas page.

If an invalid expression is passed, false will be returned and errorString will be set to the expression error.

See also: filenameExpression(); currentFilename()

Definition at line 492 of file qgslayoutatlas.cpp.

◆ setFilterExpression()

bool QgsLayoutAtlas::setFilterExpression	(	const QString &	expression,
		QString &	errorString
	)

Sets the expression used for filtering features in the coverage layer.

This property has no effect is filterFeatures() is false.

If an invalid expression is passed, false will be returned and errorString will be set to the expression error.

See also: filterExpression(); setFilterFeatures()

Definition at line 221 of file qgslayoutatlas.cpp.

◆ setFilterFeatures()

void QgsLayoutAtlas::setFilterFeatures ( bool filtered )

Sets whether features should be filtered in the coverage layer.

See also: filterFeatures(); setFilterExpression()

Definition at line 212 of file qgslayoutatlas.cpp.

◆ setHideCoverage()

void QgsLayoutAtlas::setHideCoverage ( bool hide )

Sets whether the coverage layer should be hidden in map items in the layouts.

See also: hideCoverage()

Definition at line 481 of file qgslayoutatlas.cpp.

◆ setPageNameExpression()

void QgsLayoutAtlas::setPageNameExpression ( const QString & expression )

Sets the expression (or field name) used for calculating the page name.

See also: pageNameExpression()

Definition at line 168 of file qgslayoutatlas.cpp.

◆ setSortAscending()

void QgsLayoutAtlas::setSortAscending ( bool ascending )

Sets whether features should be sorted in an ascending order.

This property has no effect is sortFeatures() is false.

See also: setSortFeatures(); sortAscending(); setSortExpression()

Definition at line 194 of file qgslayoutatlas.cpp.

◆ setSortExpression()

void QgsLayoutAtlas::setSortExpression ( const QString & expression )

Sets the expression (or field name) to use for sorting features.

This property has no effect is sortFeatures() is false.

See also: setSortFeatures(); setSortAscending(); sortExpression()

Definition at line 203 of file qgslayoutatlas.cpp.

◆ setSortFeatures()

void QgsLayoutAtlas::setSortFeatures ( bool enabled )

Sets whether features should be sorted in the atlas.

See also: sortFeatures(); setSortAscending(); setSortExpression()

Definition at line 185 of file qgslayoutatlas.cpp.

◆ sortAscending()

bool QgsLayoutAtlas::sortAscending ( ) const

inline

Returns true if features should be sorted in an ascending order.

This property has no effect is sortFeatures() is false.

See also: sortFeatures(); setSortAscending(); sortExpression()

Definition at line 168 of file qgslayoutatlas.h.

◆ sortExpression()

QString QgsLayoutAtlas::sortExpression ( ) const

inline

Returns the expression (or field name) to use for sorting features.

This property has no effect is sortFeatures() is false.

See also: sortFeatures(); sortAscending(); setSortExpression()

Definition at line 190 of file qgslayoutatlas.h.

◆ sortFeatures()

bool QgsLayoutAtlas::sortFeatures ( ) const

inline

Returns true if features should be sorted in the atlas.

See also: setSortFeatures(); sortAscending(); sortExpression()

Definition at line 149 of file qgslayoutatlas.h.

◆ stringType()

QString QgsLayoutAtlas::stringType ( ) const

overridevirtual

Returns the object type as a string.

This string must be a unique, single word, character only representation of the item type, eg "LayoutScaleBar"

Implements QgsLayoutSerializableObject.

Definition at line 42 of file qgslayoutatlas.cpp.

◆ toggled

void QgsLayoutAtlas::toggled ( bool )

signal

Emitted when atlas is enabled or disabled.

◆ updateFeatures()

int QgsLayoutAtlas::updateFeatures ( )

Requeries the current atlas coverage layer and applies filtering and sorting.

Returns number of matching features.

Definition at line 262 of file qgslayoutatlas.cpp.

◆ writeXml()

bool QgsLayoutAtlas::writeXml	(	QDomElement &	parentElement,
		QDomDocument &	document,
		const QgsReadWriteContext &	context
	)		const

overridevirtual

Stores the objects's state in a DOM element.

The parentElement should refer to the parent layout's DOM element.

See also: readXml()

Implements QgsLayoutSerializableObject.

Definition at line 57 of file qgslayoutatlas.cpp.

Friends And Related Function Documentation

◆ AtlasFeatureSorter

friend class AtlasFeatureSorter

friend

Definition at line 397 of file qgslayoutatlas.h.

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

/build/qgis-3.22.4+99unstable/src/core/layout/qgslayoutatlas.h
/build/qgis-3.22.4+99unstable/src/core/layout/qgslayoutatlas.cpp

Public Slots

Signals

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ QgsLayoutAtlas()

Member Function Documentation

◆ beginRender()

◆ changed

◆ count()

◆ coverageLayer()

◆ coverageLayerChanged

◆ createExpressionContext()

◆ currentFeatureNumber()

◆ currentFilename()

◆ enabled()

◆ endRender()

◆ featureChanged

◆ filenameExpression()

◆ filePath()

◆ filterExpression()

◆ filterFeatures()

◆ first

◆ hideCoverage()

◆ last

◆ layout() [1/2]

◆ layout() [2/2]

◆ messagePushed

◆ nameForPage()

◆ next

◆ numberFeaturesChanged

◆ pageNameExpression()

◆ previous

◆ readXml()

◆ refreshCurrentFeature

◆ renderBegun

◆ renderEnded

◆ seekTo [1/2]

◆ seekTo [2/2]

◆ setCoverageLayer()

◆ setEnabled()

◆ setFilenameExpression()

◆ setFilterExpression()

◆ setFilterFeatures()

◆ setHideCoverage()

◆ setPageNameExpression()

◆ setSortAscending()

◆ setSortExpression()

◆ setSortFeatures()

◆ sortAscending()

◆ sortExpression()

◆ sortFeatures()

◆ stringType()

◆ toggled

◆ updateFeatures()

◆ writeXml()

Friends And Related Function Documentation

◆ AtlasFeatureSorter