QgsLayoutAtlas class

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

Contents

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().

Base classes

class QgsAbstractLayoutIterator
An abstract base class for QgsLayout based classes which can be exported by QgsLayoutExporter.
class QgsLayoutSerializableObject
An interface for layout objects which can be stored and read from DOM elements.

Constructors, destructors, conversion operators

QgsLayoutAtlas(QgsLayout* layout)
Constructor for new QgsLayoutAtlas.

Public functions

auto beginRender() -> bool override
Called when rendering begins, before iteration commences.
auto count() -> int override
Returns the number of features to iterate over.
auto coverageLayer() const -> QgsVectorLayer*
Returns the coverage layer used for the atlas features.
auto currentFeatureNumber() const -> int
Returns the current feature number, where a value of 0 corresponds to the first feature.
auto currentFilename() const -> QString
Returns the current feature filename.
auto enabled() const -> bool
Returns whether the atlas generation is enabled.
auto endRender() -> bool override
Ends the render, performing any required cleanup tasks.
auto filenameExpression() const -> QString
Returns the filename expression used for generating output filenames for each atlas page.
auto filePath(const QString& baseFilePath, const QString& extension) -> QString override
Returns the file path for the current feature, based on a specified base file path and extension.
auto filterExpression() const -> QString
Returns the expression used for filtering features in the coverage layer.
auto filterFeatures() const -> bool
Returns true if features should be filtered in the coverage layer.
auto hideCoverage() const -> bool
Returns true if the atlas is set to hide the coverage layer.
auto layout() -> QgsLayout* override
Returns the layout associated with the iterator.
auto layout() const -> const QgsLayout*
Returns the atlas' layout.
auto nameForPage(int page) const -> QString
Returns the calculated name for a specified atlas page number.
auto pageNameExpression() const -> QString
Returns the expression (or field name) used for calculating the page name.
auto readXml(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override
Sets the objects's state from a DOM element.
void setCoverageLayer(QgsVectorLayer* layer)
Sets the coverage layer to use for the atlas features.
void setEnabled(bool enabled)
Sets whether the atlas is enabled.
auto setFilenameExpression(const QString& expression, QString& errorString) -> bool
Sets the filename expression used for generating output filenames for each atlas page.
auto setFilterExpression(const QString& expression, QString& errorString) -> bool
Sets the expression used for filtering features in the coverage layer.
void setFilterFeatures(bool filtered)
Sets whether features should be filtered in the coverage layer.
void setHideCoverage(bool hide)
Sets whether the coverage layer should be hidden in map items in the layouts.
void setPageNameExpression(const QString& expression)
Sets the expression (or field name) used for calculating the page name.
void setSortAscending(bool ascending)
Sets whether features should be sorted in an ascending order.
void setSortExpression(const QString& expression)
Sets the expression (or field name) to use for sorting features.
void setSortFeatures(bool enabled)
Sets whether features should be sorted in the atlas.
auto sortAscending() const -> bool
Returns true if features should be sorted in an ascending order.
auto sortExpression() const -> QString
Returns the expression (or field name) to use for sorting features.
auto sortFeatures() const -> bool
Returns true if features should be sorted in the atlas.
auto stringType() const -> QString override
Returns the object type as a string.
auto updateFeatures() -> int
Requeries the current atlas coverage layer and applies filtering and sorting.
auto writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override
Stores the objects's state in a DOM element.

Signals

void changed()
Emitted when one of the atlas parameters changes.
void coverageLayerChanged(QgsVectorLayer* layer)
Emitted when the coverage layer for the atlas changes.
void featureChanged(const QgsFeature& feature)
Is emitted when the current atlas feature changes.
void messagePushed(const QString& message)
Is emitted when the atlas has an updated status bar message.
void numberFeaturesChanged(int numFeatures)
Emitted when the number of features for the atlas changes.
void renderBegun()
Emitted when atlas rendering has begun.
void renderEnded()
Emitted when atlas rendering has ended.
void toggled(bool)
Emitted when atlas is enabled or disabled.

Public slots

auto first() -> bool
Seeks to the first feature, returning false if no feature was found.
auto last() -> bool
Seeks to the last feature, returning false if no feature was found.
auto previous() -> bool
Iterates to the previous feature, returning false if no previous feature exists.
void refreshCurrentFeature()
Refreshes the current atlas feature, by refetching its attributes from the vector layer provider.
auto seekTo(int feature) -> bool
Seeks to the specified feature number.
auto seekTo(const QgsFeature& feature) -> bool
Seeks to the specified feature.

Function documentation

bool QgsLayoutAtlas::beginRender() override

Called when rendering begins, before iteration commences.

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

QgsVectorLayer* QgsLayoutAtlas::coverageLayer() const

Returns the coverage layer used for the atlas features.

QString QgsLayoutAtlas::currentFilename() const

Returns the current feature filename.

bool QgsLayoutAtlas::enabled() const

Returns whether the atlas generation is enabled.

QString QgsLayoutAtlas::filenameExpression() const

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

QString QgsLayoutAtlas::filterExpression() const

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

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

bool QgsLayoutAtlas::filterFeatures() const

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

bool QgsLayoutAtlas::hideCoverage() const

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

const QgsLayout* QgsLayoutAtlas::layout() const

Returns the atlas' layout.

QString QgsLayoutAtlas::nameForPage(int page) const

Returns the calculated name for a specified atlas page number.

Page numbers start at 0.

QString QgsLayoutAtlas::pageNameExpression() const

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

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

Sets the objects's state from a DOM element.

element is the DOM node corresponding to the object.

void QgsLayoutAtlas::setCoverageLayer(QgsVectorLayer* layer)

Sets the coverage layer to use for the atlas features.

void QgsLayoutAtlas::setEnabled(bool enabled)

Sets whether the atlas is enabled.

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.

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.

void QgsLayoutAtlas::setFilterFeatures(bool filtered)

Sets whether features should be filtered in the coverage layer.

void QgsLayoutAtlas::setHideCoverage(bool hide)

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

void QgsLayoutAtlas::setPageNameExpression(const QString& expression)

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

void QgsLayoutAtlas::setSortAscending(bool ascending)

Sets whether features should be sorted in an ascending order.

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

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.

void QgsLayoutAtlas::setSortFeatures(bool enabled)

Sets whether features should be sorted in the atlas.

bool QgsLayoutAtlas::sortAscending() const

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

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

QString QgsLayoutAtlas::sortExpression() const

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

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

bool QgsLayoutAtlas::sortFeatures() const

Returns true if features should be sorted in the atlas.

QString QgsLayoutAtlas::stringType() const override

Returns the object type as a string.

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

int QgsLayoutAtlas::updateFeatures()

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

Returns number of matching features.

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

Stores the objects's state in a DOM element.

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

bool QgsLayoutAtlas::first() public slot

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

bool QgsLayoutAtlas::last() public slot

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

bool QgsLayoutAtlas::previous() public slot

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

bool QgsLayoutAtlas::seekTo(int feature) public slot

Seeks to the specified feature number.

bool QgsLayoutAtlas::seekTo(const QgsFeature& feature) public slot

Seeks to the specified feature.