Class: QgsLayoutAtlas

class qgis.core.QgsLayoutAtlas

Bases: PyQt5.QtCore.QObject, QgsAbstractLayoutIterator, QgsLayoutSerializableObject, QgsExpressionContextGenerator

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

New in version 3.0.

QgsLayoutAtlas(layout: QgsLayout) Constructor for new QgsLayoutAtlas.

Methods

beginRender

rtype:

bool

childEvent

connectNotify

count

rtype:

int

coverageLayer

Returns the coverage layer used for the atlas features.

createExpressionContext

rtype:

QgsExpressionContext

currentFeatureNumber

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

currentFilename

Returns the current feature filename.

customEvent

disconnectNotify

enabled

Returns whether the atlas generation is enabled

endRender

rtype:

bool

filePath

param baseFilePath:

filenameExpression

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

filterExpression

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

filterFeatures

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

first

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

hideCoverage

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

isSignalConnected

last

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

layout

rtype:

QgsLayout

nameForPage

Returns the calculated name for a specified atlas page number.

next

rtype:

bool

pageNameExpression

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

previous

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

readXml

param element:

receivers

refreshCurrentFeature

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

seekTo

Seeks to the specified feature number.

sender

senderSignalIndex

setCoverageLayer

Sets the coverage layer to use for the atlas features.

setEnabled

Sets whether the atlas is enabled.

setFilenameExpression

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

setFilterExpression

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

setFilterFeatures

Sets whether features should be filtered in the coverage layer.

setHideCoverage

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

setPageNameExpression

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

setSortAscending

Sets whether features should be sorted in an ascending order.

setSortExpression

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

setSortFeatures

Sets whether features should be sorted in the atlas.

sortAscending

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

sortExpression

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

sortFeatures

Returns True if features should be sorted in the atlas.

stringType

rtype:

str

timerEvent

updateFeatures

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

writeXml

param parentElement:

Signals

changed

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

coverageLayerChanged

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

featureChanged

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

messagePushed

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

numberFeaturesChanged

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

renderBegun

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

renderEnded

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

toggled

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

beginRender(self) bool
Return type:

bool

changed

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

childEvent(self, QChildEvent)
connectNotify(self, QMetaMethod)
count(self) int
Return type:

int

coverageLayer(self) QgsVectorLayer

Returns the coverage layer used for the atlas features.

Return type:

QgsVectorLayer

coverageLayerChanged

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

createExpressionContext(self) QgsExpressionContext
Return type:

QgsExpressionContext

currentFeatureNumber(self) int

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

Return type:

int

currentFilename(self) str

Returns the current feature filename.

Return type:

str

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
enabled(self) bool

Returns whether the atlas generation is enabled

See also

setEnabled()

Return type:

bool

endRender(self) bool
Return type:

bool

featureChanged

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

filePath(self, baseFilePath: str, extension: str) str
Parameters:
  • baseFilePath (str) –

  • extension (str) –

Return type:

str

filenameExpression(self) str

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

Return type:

str

filterExpression(self) str

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

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

See also

filterFeatures()

Return type:

str

filterFeatures(self) bool

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

Return type:

bool

first(self) bool

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

See also

next()

See also

previous()

See also

last()

See also

seekTo()

Return type:

bool

hideCoverage(self) bool

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

Return type:

bool

isSignalConnected(self, QMetaMethod) bool
last(self) bool

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

See also

next()

See also

previous()

See also

first()

See also

seekTo()

Return type:

bool

layout(self) QgsLayout
Return type:

QgsLayout

messagePushed

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

nameForPage(self, page: int) str

Returns the calculated name for a specified atlas page number. Page numbers start at 0.

Parameters:

page (int) –

Return type:

str

next(self) bool
Return type:

bool

numberFeaturesChanged

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

pageNameExpression(self) str

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

See also

nameForPage()

Return type:

str

previous(self) bool

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

See also

next()

See also

last()

See also

first()

See also

seekTo()

Return type:

bool

readXml(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool

receivers(self, PYQT_SIGNAL) int
refreshCurrentFeature(self)

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

renderBegun

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

renderEnded

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

seekTo(self, feature: int) bool

Seeks to the specified feature number.

See also

first()

See also

previous()

See also

next()

See also

last()

seekTo(self, feature: QgsFeature) -> bool Seeks to the specified feature.

See also

first()

See also

previous()

See also

next()

See also

last()

Parameters:

feature (int) –

Return type:

bool

sender(self) QObject
senderSignalIndex(self) int
setCoverageLayer(self, layer: QgsVectorLayer)

Sets the coverage layer to use for the atlas features.

See also

coverageLayer()

Parameters:

layer (QgsVectorLayer) –

setEnabled(self, enabled: bool)

Sets whether the atlas is enabled.

See also

enabled()

Parameters:

enabled (bool) –

setFilenameExpression(self, expression: str) Tuple[bool, str]

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.

Parameters:

expression (str) –

Return type:

Tuple[bool, str]

setFilterExpression(self, expression: str) Tuple[bool, str]

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.

Parameters:

expression (str) –

Return type:

Tuple[bool, str]

setFilterFeatures(self, filtered: bool)

Sets whether features should be filtered in the coverage layer.

See also

filterFeatures()

Parameters:

filtered (bool) –

setHideCoverage(self, hide: bool)

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

See also

hideCoverage()

Parameters:

hide (bool) –

setPageNameExpression(self, expression: str)

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

Parameters:

expression (str) –

setSortAscending(self, ascending: bool)

Sets whether features should be sorted in an ascending order.

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

See also

sortAscending()

Parameters:

ascending (bool) –

setSortExpression(self, expression: str)

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

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

See also

sortExpression()

Parameters:

expression (str) –

setSortFeatures(self, enabled: bool)

Sets whether features should be sorted in the atlas.

See also

sortFeatures()

Parameters:

enabled (bool) –

sortAscending(self) bool

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

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

See also

sortFeatures()

See also

sortExpression()

Return type:

bool

sortExpression(self) str

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

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

See also

sortFeatures()

See also

sortAscending()

Return type:

str

sortFeatures(self) bool

Returns True if features should be sorted in the atlas.

See also

sortAscending()

See also

sortExpression()

Return type:

bool

stringType(self) str
Return type:

str

timerEvent(self, QTimerEvent)
toggled

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

updateFeatures(self) int

Requeries the current atlas coverage layer and applies filtering and sorting. Returns number of matching features.

Return type:

int

writeXml(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
  • parentElement (QDomElement) –

  • document (QDomDocument) –

  • context (QgsReadWriteContext) –

Return type:

bool