QGIS API Documentation 3.37.0-Master (fdefdf9c27f)
Public Slots | Signals | Public Member Functions | Friends | List of all members
QgsLayoutAtlas Class Reference

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:
Inheritance graph
[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...
 
QgsVectorLayercoverageLayer () 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 QgsLayoutlayout () const
 Returns the atlas' layout. More...
 
QgsLayoutlayout () 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 beginRender ()=0
 Called when rendering begins, before iteration commences. More...
 
virtual int count () const =0
 Returns the number of features to iterate over. More...
 
virtual bool endRender ()=0
 Ends the render, performing any required cleanup tasks. More...
 
virtual QString filePath (const QString &baseFilePath, const QString &extension)=0
 Returns the file path for the current feature, based on a specified base file path and extension. More...
 
virtual QgsLayoutlayout ()=0
 Returns the layout associated with the iterator. More...
 
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
QgsAbstractLayoutUndoCommandcreateCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
 Creates a new layout undo command with the specified text and parent. More...
 
virtual QgsLayoutlayout ()=0
 Returns the layout the object belongs to. More...
 
virtual bool readXml (const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context)=0
 Sets the objects's state from a DOM element. More...
 
virtual QString stringType () const =0
 Returns the object type as a string. More...
 
virtual bool writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const =0
 Stores the objects's state in a DOM element. More...
 
- Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual ~QgsLayoutUndoObjectInterface ()=default
 Destructor for QgsLayoutUndoObjectInterface. More...
 
virtual QgsAbstractLayoutUndoCommandcreateCommand (const QString &text, int id=0, QUndoCommand *parent=nullptr)=0
 Creates a new layout undo command with the specified text and parent. 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...
 

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

Definition at line 40 of file qgslayoutatlas.h.

Constructor & Destructor Documentation

◆ QgsLayoutAtlas()

QgsLayoutAtlas::QgsLayoutAtlas ( QgsLayout layout)

Constructor for new QgsLayoutAtlas.

Definition at line 32 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 380 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 405 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 115 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.

Implements QgsExpressionContextGenerator.

Definition at line 512 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 253 of file qgslayoutatlas.h.

◆ currentFilename()

QString QgsLayoutAtlas::currentFilename ( ) const

Returns the current feature filename.

See also
filenameExpression()
setFilenameExpression()

Definition at line 507 of file qgslayoutatlas.cpp.

◆ enabled()

bool QgsLayoutAtlas::enabled ( ) const
inline

Returns whether the atlas generation is enabled.

See also
setEnabled()

Definition at line 66 of file qgslayoutatlas.h.

◆ endRender()

bool QgsLayoutAtlas::endRender ( )
overridevirtual

Ends the render, performing any required cleanup tasks.

Implements QgsAbstractLayoutIterator.

Definition at line 398 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 92 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 410 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 224 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 207 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 443 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 78 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 448 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 55 of file qgslayoutatlas.cpp.

◆ layout() [2/2]

QgsLayout * QgsLayoutAtlas::layout ( )
overridevirtual

Returns the layout associated with the iterator.

Implements QgsAbstractLayoutIterator.

Definition at line 50 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 181 of file qgslayoutatlas.cpp.

◆ next

bool QgsLayoutAtlas::next ( )
overrideslot

Definition at line 421 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 128 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 432 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 98 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 480 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 458 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 453 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 161 of file qgslayoutatlas.cpp.

◆ setEnabled()

void QgsLayoutAtlas::setEnabled ( bool  enabled)

Sets whether the atlas is enabled.

See also
enabled()

Definition at line 130 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 496 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 225 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 216 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 485 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 172 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 198 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 207 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 189 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 167 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 189 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 148 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 45 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 266 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 60 of file qgslayoutatlas.cpp.

Friends And Related Function Documentation

◆ AtlasFeatureSorter

friend class AtlasFeatureSorter
friend

Definition at line 396 of file qgslayoutatlas.h.


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