QGIS API Documentation  2.99.0-Master (37c43df)
Public Types | Public Slots | Signals | Public Member Functions | List of all members
QgsAtlasComposition Class Reference

Class used to render an Atlas, iterating over geometry features. More...

#include <qgsatlascomposition.h>

Inheritance diagram for QgsAtlasComposition:
Inheritance graph
[legend]

Public Types

typedef QMap< QgsFeatureId, QVariant > SorterKeys
 

Public Slots

void firstFeature ()
 
void lastFeature ()
 
void nextFeature ()
 
void prevFeature ()
 
void refreshFeature ()
 Refreshes the current atlas feature, by refetching its attributes from the vector layer provider. More...
 

Signals

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

Public Member Functions

 QgsAtlasComposition (QgsComposition *composition)
 
 ~QgsAtlasComposition ()
 
bool beginRender ()
 Begins the rendering. More...
 
QgsCompositioncomposition ()
 
QgsVectorLayercoverageLayer () const
 Returns the coverage layer used for the atlas features. 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 filename. Must be called after prepareForFeature() More...
 
QgsGeometry currentGeometry (const QgsCoordinateReferenceSystem &projectedTo=QgsCoordinateReferenceSystem()) const
 Returns the current atlas geometry in the given projection system (default to the coverage layer's CRS) More...
 
QString currentPageName () const
 Returns the name of the page for the current atlas feature. More...
 
bool enabled () const
 Returns whether the atlas generation is enabled. More...
 
void endRender ()
 Ends the rendering. Restores original extent. More...
 
QgsFeature feature () const
 Returns the current atlas feature. More...
 
QString featureFilter () const
 
QString featureFilterErrorString () const
 Returns an error string from parsing the feature filter expression. More...
 
QString filenamePattern () const
 Returns the filename expression used for generating output filenames for each atlas page. More...
 
QString filenamePatternErrorString () const
 Returns an error string from parsing the filename expression. More...
 
bool filterFeatures () const
 
bool hideCoverage () const
 Returns true if the atlas is set to hide the coverage layer. More...
 
QString nameForPage (int pageNumber) const
 Returns the calculated name for a specified atlas page number. More...
 
int numFeatures () const
 Returns the number of features in the coverage layer. More...
 
QString pageNameExpression () const
 Returns the expression used for calculating the page name. More...
 
const QVector< qreal > & predefinedScales () const
 Returns the current list of predefined scales for the atlas. More...
 
bool prepareForFeature (const int i, const bool updateMaps=true)
 Prepare the atlas map for the given feature. More...
 
bool prepareForFeature (const QgsFeature *feat)
 Prepare the atlas map for the given feature. More...
 
void prepareMap (QgsComposerMap *map)
 Recalculates the bounds of an atlas driven map. More...
 
void readXml (const QDomElement &elem, const QDomDocument &doc)
 Reads general atlas settings from xml. More...
 
void readXmlMapSettings (const QDomElement &elem, const QDomDocument &doc)
 Reads old (pre 2.2) map related atlas settings from xml. 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...
 
void setFeatureFilter (const QString &expression)
 
bool setFilenamePattern (const QString &pattern)
 Sets the filename expression used for generating output filenames for each atlas page. More...
 
void setFilterFeatures (bool doFilter)
 
void setHideCoverage (bool hide)
 Sets whether the coverage layer should be hidden in map items in the composition. More...
 
void setPageNameExpression (const QString &pageNameExpression)
 Sets the expression used for calculating the page name. More...
 
void setPredefinedScales (const QVector< qreal > &scales)
 Sets the list of predefined scales for the atlas. More...
 
void setSingleFile (bool single)
 Sets whether the atlas should be exported to a single file. More...
 
void setSortAscending (bool ascending)
 
void setSortFeatures (bool doSort)
 
void setSortKeyAttributeName (const QString &fieldName)
 
bool singleFile () const
 Returns whether the atlas will be exported to a single file. More...
 
bool sortAscending () const
 
bool sortFeatures () const
 
QString sortKeyAttributeName () const
 
int updateFeatures ()
 Requeries the current atlas coverage layer and applies filtering and sorting. More...
 
void writeXml (QDomElement &elem, QDomDocument &doc) const
 

Detailed Description

Class used to render an Atlas, iterating over geometry features.

prepareForFeature() modifies the atlas map's extent to zoom on the given feature. This class is used for printing, exporting to PDF and images.

Note
This class should not be created directly. For the atlas to function correctly the atlasComposition() property for QgsComposition should be used to retrieve a QgsAtlasComposition which is automatically created and attached to the composition.

Definition at line 43 of file qgsatlascomposition.h.

Member Typedef Documentation

§ SorterKeys

typedef QMap< QgsFeatureId, QVariant > QgsAtlasComposition::SorterKeys

Definition at line 329 of file qgsatlascomposition.h.

Constructor & Destructor Documentation

§ QgsAtlasComposition()

QgsAtlasComposition::QgsAtlasComposition ( QgsComposition composition)

Definition at line 35 of file qgsatlascomposition.cpp.

§ ~QgsAtlasComposition()

QgsAtlasComposition::~QgsAtlasComposition ( )

Definition at line 52 of file qgsatlascomposition.cpp.

Member Function Documentation

§ beginRender()

bool QgsAtlasComposition::beginRender ( )

Begins the rendering.

Returns true if successful, false if no matching atlas features found.

Definition at line 230 of file qgsatlascomposition.cpp.

§ composition()

QgsComposition* QgsAtlasComposition::composition ( )
inline

Definition at line 232 of file qgsatlascomposition.h.

§ coverageLayer()

QgsVectorLayer* QgsAtlasComposition::coverageLayer ( ) const
inline

Returns the coverage layer used for the atlas features.

Returns
atlas coverage layer
See also
setCoverageLayer

Definition at line 104 of file qgsatlascomposition.h.

§ coverageLayerChanged

void QgsAtlasComposition::coverageLayerChanged ( QgsVectorLayer layer)
signal

Is emitted when the coverage layer for an atlas changes.

§ currentFeatureNumber()

int QgsAtlasComposition::currentFeatureNumber ( ) const
inline

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

Note
added in QGIS 2.12

Definition at line 252 of file qgsatlascomposition.h.

§ currentFilename()

QString QgsAtlasComposition::currentFilename ( ) const

Returns the current filename. Must be called after prepareForFeature()

Definition at line 578 of file qgsatlascomposition.cpp.

§ currentGeometry()

QgsGeometry QgsAtlasComposition::currentGeometry ( const QgsCoordinateReferenceSystem projectedTo = QgsCoordinateReferenceSystem()) const

Returns the current atlas geometry in the given projection system (default to the coverage layer's CRS)

Definition at line 803 of file qgsatlascomposition.cpp.

§ currentPageName()

QString QgsAtlasComposition::currentPageName ( ) const

Returns the name of the page for the current atlas feature.

Must be called after prepareForFeature().

Note
added in QGIS 2.12

Definition at line 225 of file qgsatlascomposition.cpp.

§ enabled()

bool QgsAtlasComposition::enabled ( ) const
inline

Returns whether the atlas generation is enabled.

Returns
true if atlas is enabled
See also
setEnabled

Definition at line 54 of file qgsatlascomposition.h.

§ endRender()

void QgsAtlasComposition::endRender ( )

Ends the rendering. Restores original extent.

Definition at line 249 of file qgsatlascomposition.cpp.

§ feature()

QgsFeature QgsAtlasComposition::feature ( ) const
inline

Returns the current atlas feature.

Must be called after prepareForFeature().

Note
added in QGIS 2.12

Definition at line 242 of file qgsatlascomposition.h.

§ featureChanged

void QgsAtlasComposition::featureChanged ( QgsFeature feature)
signal

Is emitted when the current atlas feature changes.

§ featureFilter()

QString QgsAtlasComposition::featureFilter ( ) const
inline

Definition at line 160 of file qgsatlascomposition.h.

§ featureFilterErrorString()

QString QgsAtlasComposition::featureFilterErrorString ( ) const
inline

Returns an error string from parsing the feature filter expression.

Returns
filename pattern parser error
See also
setFilenamePattern
filenamePattern

Definition at line 168 of file qgsatlascomposition.h.

§ filenamePattern()

QString QgsAtlasComposition::filenamePattern ( ) const
inline

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

Returns
filename pattern
See also
setFilenamePattern
filenamePatternErrorString
Note
This property has no effect when exporting to PDF if singleFile() is true

Definition at line 81 of file qgsatlascomposition.h.

§ filenamePatternErrorString()

QString QgsAtlasComposition::filenamePatternErrorString ( ) const
inline

Returns an error string from parsing the filename expression.

Returns
filename pattern parser error
See also
setFilenamePattern
filenamePattern

Definition at line 98 of file qgsatlascomposition.h.

§ filterFeatures()

bool QgsAtlasComposition::filterFeatures ( ) const
inline

Definition at line 157 of file qgsatlascomposition.h.

§ firstFeature

void QgsAtlasComposition::firstFeature ( )
slot

Definition at line 307 of file qgsatlascomposition.cpp.

§ hideCoverage()

bool QgsAtlasComposition::hideCoverage ( ) const
inline

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

Returns
true if coverage layer is hidden
See also
setHideCoverage

Definition at line 66 of file qgsatlascomposition.h.

§ lastFeature

void QgsAtlasComposition::lastFeature ( )
slot

Definition at line 312 of file qgsatlascomposition.cpp.

§ nameForPage()

QString QgsAtlasComposition::nameForPage ( int  pageNumber) const

Returns the calculated name for a specified atlas page number.

Parameters
pageNumbernumber of page, where 0 = first page
Returns
page name
See also
pageNameExpression
Note
added in QGIS 2.12

Definition at line 99 of file qgsatlascomposition.cpp.

§ nextFeature

void QgsAtlasComposition::nextFeature ( )
slot

Definition at line 285 of file qgsatlascomposition.cpp.

§ numberFeaturesChanged

void QgsAtlasComposition::numberFeaturesChanged ( int  numFeatures)
signal

Is emitted when the number of features for the atlas changes.

Note
added in QGIS 2.12

§ numFeatures()

int QgsAtlasComposition::numFeatures ( ) const

Returns the number of features in the coverage layer.

Definition at line 280 of file qgsatlascomposition.cpp.

§ pageNameExpression()

QString QgsAtlasComposition::pageNameExpression ( ) const
inline

Returns the expression used for calculating the page name.

Returns
expression string, or field name from coverage layer
See also
setPageNameExpression
nameForPage
Note
added in QGIS 2.12

Definition at line 118 of file qgsatlascomposition.h.

§ parameterChanged

void QgsAtlasComposition::parameterChanged ( )
signal

Emitted when one of the parameters changes.

§ predefinedScales()

const QVector<qreal>& QgsAtlasComposition::predefinedScales ( ) const
inline

Returns the current list of predefined scales for the atlas.

This is used for maps which are set to the predefined atlas scaling mode.

Returns
a vector of doubles representing predefined scales
See also
setPredefinedScales
QgsComposerMap::atlasScalingMode

Definition at line 179 of file qgsatlascomposition.h.

§ prepareForFeature() [1/2]

bool QgsAtlasComposition::prepareForFeature ( const int  i,
const bool  updateMaps = true 
)

Prepare the atlas map for the given feature.

Sets the extent and context variables

Parameters
ifeature number
updateMapsset to true to redraw maps and recalculate their extent
Returns
true if feature was successfully prepared

Definition at line 345 of file qgsatlascomposition.cpp.

§ prepareForFeature() [2/2]

bool QgsAtlasComposition::prepareForFeature ( const QgsFeature feat)

Prepare the atlas map for the given feature.

Sets the extent and context variables

Returns
true if feature was successfully prepared

Definition at line 317 of file qgsatlascomposition.cpp.

§ prepareMap()

void QgsAtlasComposition::prepareMap ( QgsComposerMap map)

Recalculates the bounds of an atlas driven map.

Definition at line 450 of file qgsatlascomposition.cpp.

§ prevFeature

void QgsAtlasComposition::prevFeature ( )
slot

Definition at line 296 of file qgsatlascomposition.cpp.

§ readXml()

void QgsAtlasComposition::readXml ( const QDomElement &  elem,
const QDomDocument &  doc 
)

Reads general atlas settings from xml.

Parameters
elema QDomElement holding the atlas properties.
docQDomDocument for the source xml.
See also
readXMLMapSettings
Note
This method should be called before restoring composer item properties

Definition at line 621 of file qgsatlascomposition.cpp.

§ readXmlMapSettings()

void QgsAtlasComposition::readXmlMapSettings ( const QDomElement &  elem,
const QDomDocument &  doc 
)

Reads old (pre 2.2) map related atlas settings from xml.

Parameters
elema QDomElement holding the atlas map properties.
docQDomDocument for the source xml.
See also
readXMLMapSettings
Note
This method should be called after restoring composer item properties
added in version 2.5

Definition at line 677 of file qgsatlascomposition.cpp.

§ refreshFeature

void QgsAtlasComposition::refreshFeature ( )
slot

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

Note
added in QGIS 2.5

Definition at line 340 of file qgsatlascomposition.cpp.

§ renderBegun

void QgsAtlasComposition::renderBegun ( )
signal

Is emitted when atlas rendering has begun.

§ renderEnded

void QgsAtlasComposition::renderEnded ( )
signal

Is emitted when atlas rendering has ended.

§ setCoverageLayer()

void QgsAtlasComposition::setCoverageLayer ( QgsVectorLayer layer)

Sets the coverage layer to use for the atlas features.

Parameters
layervector coverage layer
See also
coverageLayer

Definition at line 88 of file qgsatlascomposition.cpp.

§ setEnabled()

void QgsAtlasComposition::setEnabled ( bool  enabled)

Sets whether the atlas is enabled.

Parameters
enabledset to true to enable to atlas
See also
enabled

Definition at line 56 of file qgsatlascomposition.cpp.

§ setFeatureFilter()

void QgsAtlasComposition::setFeatureFilter ( const QString &  expression)
inline

Definition at line 161 of file qgsatlascomposition.h.

§ setFilenamePattern()

bool QgsAtlasComposition::setFilenamePattern ( const QString &  pattern)

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

Returns
true if filename expression could be successful set, false if expression is invalid
Parameters
patternexpression to use for output filenames
See also
filenamePattern
filenamePatternErrorString
Note
This method has no effect when exporting to PDF if singleFile() is true

Definition at line 724 of file qgsatlascomposition.cpp.

§ setFilterFeatures()

void QgsAtlasComposition::setFilterFeatures ( bool  doFilter)
inline

Definition at line 158 of file qgsatlascomposition.h.

§ setHideCoverage()

void QgsAtlasComposition::setHideCoverage ( bool  hide)

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

Parameters
hideset to true to hide the coverage layer
See also
hideCoverage

Definition at line 711 of file qgsatlascomposition.cpp.

§ setPageNameExpression()

void QgsAtlasComposition::setPageNameExpression ( const QString &  pageNameExpression)
inline

Sets the expression used for calculating the page name.

Parameters
pageNameExpressionexpression string, or field name from coverage layer
See also
pageNameExpression
Note
added in QGIS 2.12

Definition at line 125 of file qgsatlascomposition.h.

§ setPredefinedScales()

void QgsAtlasComposition::setPredefinedScales ( const QVector< qreal > &  scales)

Sets the list of predefined scales for the atlas.

This is used for maps which are set to the predefined atlas scaling mode.

Parameters
scalesa vector of doubles representing predefined scales
See also
predefinedScales
QgsComposerMap::atlasScalingMode

Definition at line 796 of file qgsatlascomposition.cpp.

§ setSingleFile()

void QgsAtlasComposition::setSingleFile ( bool  single)
inline

Sets whether the atlas should be exported to a single file.

This is only applicable for PDF exports.

Parameters
singleset to true to export atlas to a single file.
See also
singleFile
Note
This method is only used for PDF exports.

Definition at line 149 of file qgsatlascomposition.h.

§ setSortAscending()

void QgsAtlasComposition::setSortAscending ( bool  ascending)
inline

Definition at line 155 of file qgsatlascomposition.h.

§ setSortFeatures()

void QgsAtlasComposition::setSortFeatures ( bool  doSort)
inline

Definition at line 152 of file qgsatlascomposition.h.

§ setSortKeyAttributeName()

void QgsAtlasComposition::setSortKeyAttributeName ( const QString &  fieldName)
inline

Definition at line 171 of file qgsatlascomposition.h.

§ singleFile()

bool QgsAtlasComposition::singleFile ( ) const
inline

Returns whether the atlas will be exported to a single file.

This is only applicable for PDF exports.

Returns
true if atlas will be exported to a single file
See also
setSingleFile
Note
This property is only used for PDF exports.

Definition at line 141 of file qgsatlascomposition.h.

§ sortAscending()

bool QgsAtlasComposition::sortAscending ( ) const
inline

Definition at line 154 of file qgsatlascomposition.h.

§ sortFeatures()

bool QgsAtlasComposition::sortFeatures ( ) const
inline

Definition at line 151 of file qgsatlascomposition.h.

§ sortKeyAttributeName()

QString QgsAtlasComposition::sortKeyAttributeName ( ) const
inline

Definition at line 170 of file qgsatlascomposition.h.

§ statusMsgChanged

void QgsAtlasComposition::statusMsgChanged ( const QString &  message)
signal

Is emitted when the atlas has an updated status bar message for the composer window.

§ toggled

void QgsAtlasComposition::toggled ( bool  )
signal

Emitted when atlas is enabled or disabled.

§ updateFeatures()

int QgsAtlasComposition::updateFeatures ( )

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

Returns number of matching features. Must be called after prepareForFeature()

Definition at line 129 of file qgsatlascomposition.cpp.

§ writeXml()

void QgsAtlasComposition::writeXml ( QDomElement &  elem,
QDomDocument &  doc 
) const

Definition at line 583 of file qgsatlascomposition.cpp.


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