QGIS API Documentation  2.5.0-Master
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
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 refreshFeature ()
 Refreshes the current atlas feature, by refetching its attributes from the vector layer provider. More...
 
void nextFeature ()
 
void prevFeature ()
 
void lastFeature ()
 
void firstFeature ()
 

Signals

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

Public Member Functions

 QgsAtlasComposition (QgsComposition *composition)
 
 ~QgsAtlasComposition ()
 
bool enabled () const
 Returns whether the atlas generation is enabled. More...
 
void setEnabled (bool enabled)
 Sets whether the atlas is enabled. More...
 
Q_DECL_DEPRECATED QgsComposerMapcomposerMap () const
 Returns the map used by the atlas. More...
 
Q_DECL_DEPRECATED void setComposerMap (QgsComposerMap *map)
 Sets the map used by the atlas. More...
 
bool hideCoverage () const
 Returns true if the atlas is set to hide the coverage layer. More...
 
void setHideCoverage (bool hide)
 Sets whether the coverage layer should be hidden in map items in the composition. More...
 
Q_DECL_DEPRECATED bool fixedScale () const
 Returns whether the atlas map uses a fixed scale. More...
 
Q_DECL_DEPRECATED void setFixedScale (bool fixed)
 Sets whether the atlas map should use a fixed scale. More...
 
Q_DECL_DEPRECATED float margin () const
 Returns the margin for the atlas map. More...
 
Q_DECL_DEPRECATED void setMargin (float margin)
 Sets the margin for the atlas map. More...
 
QString filenamePattern () const
 Returns the filename expression used for generating output filenames for each atlas page. More...
 
bool setFilenamePattern (const QString &pattern)
 Sets 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...
 
QgsVectorLayercoverageLayer () const
 Returns the coverage layer used for the atlas features. More...
 
void setCoverageLayer (QgsVectorLayer *layer)
 Sets the coverage layer to use for the atlas features. More...
 
bool singleFile () const
 Returns whether the atlas will be exported to a single file. More...
 
void setSingleFile (bool single)
 Sets whether the atlas should be exported to a single file. More...
 
bool sortFeatures () const
 
void setSortFeatures (bool doSort)
 
bool sortAscending () const
 
void setSortAscending (bool ascending)
 
bool filterFeatures () const
 
void setFilterFeatures (bool doFilter)
 
QString featureFilter () const
 
void setFeatureFilter (const QString &expression)
 
QString featureFilterErrorString () const
 Returns an error string from parsing the feature filter expression. More...
 
QString sortKeyAttributeName () const
 
void setSortKeyAttributeName (QString fieldName)
 
Q_DECL_DEPRECATED int sortKeyAttributeIndex () const
 
Q_DECL_DEPRECATED void setSortKeyAttributeIndex (int idx)
 
const QVector< qreal > & predefinedScales () const
 Returns the current list of predefined scales for the atlas. More...
 
void setPredefinedScales (const QVector< qreal > &scales)
 Sets the list of predefined scales for the atlas. More...
 
bool beginRender ()
 Begins the rendering. More...
 
void endRender ()
 Ends the rendering. More...
 
int numFeatures () const
 Returns the number of features in the coverage layer. 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...
 
const QString & currentFilename () const
 Returns the current filename. More...
 
void writeXML (QDomElement &elem, QDomDocument &doc) const
 
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...
 
QgsCompositioncomposition ()
 
int updateFeatures ()
 Requeries the current atlas coverage layer and applies filtering and sorting. More...
 
QgsFeaturecurrentFeature ()
 Returns the current atlas feature. More...
 
void prepareMap (QgsComposerMap *map)
 Recalculates the bounds of an atlas driven map. More...
 

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.

Member Typedef Documentation

typedef QMap< QgsFeatureId, QVariant > QgsAtlasComposition::SorterKeys

Constructor & Destructor Documentation

QgsAtlasComposition::QgsAtlasComposition ( QgsComposition composition)
QgsAtlasComposition::~QgsAtlasComposition ( )

Member Function Documentation

bool QgsAtlasComposition::beginRender ( )

Begins the rendering.

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

QgsComposerMap * QgsAtlasComposition::composerMap ( ) const

Returns the map used by the atlas.

Deprecated:
Use QgsComposerMap::atlasDriven() instead
QgsComposition* QgsAtlasComposition::composition ( )
inline
QgsVectorLayer* QgsAtlasComposition::coverageLayer ( ) const
inline

Returns the coverage layer used for the atlas features.

Returns
atlas coverage layer
See also
setCoverageLayer
void QgsAtlasComposition::coverageLayerChanged ( QgsVectorLayer layer)
signal

Is emitted when the coverage layer for an atlas changes.

QgsFeature* QgsAtlasComposition::currentFeature ( )
inline

Returns the current atlas feature.

Must be called after prepareForFeature( i ).

const QString & QgsAtlasComposition::currentFilename ( ) const

Returns the current filename.

Must be called after prepareForFeature( i )

bool QgsAtlasComposition::enabled ( ) const
inline

Returns whether the atlas generation is enabled.

Returns
true if atlas is enabled
See also
setEnabled
void QgsAtlasComposition::endRender ( )

Ends the rendering.

Restores original extent

void QgsAtlasComposition::featureChanged ( QgsFeature feature)
signal

Is emitted when the current atlas feature changes.

QString QgsAtlasComposition::featureFilter ( ) const
inline
QString QgsAtlasComposition::featureFilterErrorString ( ) const
inline

Returns an error string from parsing the feature filter expression.

Returns
filename pattern parser error
See also
setFilenamePattern
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
QString QgsAtlasComposition::filenamePatternErrorString ( ) const
inline

Returns an error string from parsing the filename expression.

Returns
filename pattern parser error
See also
setFilenamePattern
filenamePattern
bool QgsAtlasComposition::filterFeatures ( ) const
inline
void QgsAtlasComposition::firstFeature ( )
slot
Q_NOWARN_DEPRECATED_PUSH bool QgsAtlasComposition::fixedScale ( ) const

Returns whether the atlas map uses a fixed scale.

Deprecated:
since 2.4 Use QgsComposerMap::atlasScalingMode() instead
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
void QgsAtlasComposition::lastFeature ( )
slot
float QgsAtlasComposition::margin ( ) const

Returns the margin for the atlas map.

Deprecated:
Use QgsComposerMap::atlasMargin() instead
void QgsAtlasComposition::nextFeature ( )
slot
int QgsAtlasComposition::numFeatures ( ) const

Returns the number of features in the coverage layer.

void QgsAtlasComposition::parameterChanged ( )
signal

emitted when one of the parameters changes

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
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
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
void QgsAtlasComposition::prepareMap ( QgsComposerMap map)

Recalculates the bounds of an atlas driven map.

void QgsAtlasComposition::prevFeature ( )
slot
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
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
void QgsAtlasComposition::refreshFeature ( )
slot

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

Note
added in QGIS 2.5
void QgsAtlasComposition::renderBegun ( )
signal

Is emitted when atlas rendering has begun.

void QgsAtlasComposition::renderEnded ( )
signal

Is emitted when atlas rendering has ended.

void QgsAtlasComposition::setComposerMap ( QgsComposerMap map)

Sets the map used by the atlas.

Deprecated:
Use QgsComposerMap::setAtlasDriven( true ) instead
void QgsAtlasComposition::setCoverageLayer ( QgsVectorLayer layer)

Sets the coverage layer to use for the atlas features.

Parameters
layervector coverage layer
See also
coverageLayer
void QgsAtlasComposition::setEnabled ( bool  enabled)

Sets whether the atlas is enabled.

Parameters
enabledset to true to enable to atlas
See also
enabled
void QgsAtlasComposition::setFeatureFilter ( const QString &  expression)
inline
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
void QgsAtlasComposition::setFilterFeatures ( bool  doFilter)
inline
void QgsAtlasComposition::setFixedScale ( bool  fixed)

Sets whether the atlas map should use a fixed scale.

Deprecated:
since 2.4 Use QgsComposerMap::setAtlasScalingMode() instead
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
void QgsAtlasComposition::setMargin ( float  margin)

Sets the margin for the atlas map.

Deprecated:
Use QgsComposerMap::setAtlasMargin( double ) instead
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
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.
void QgsAtlasComposition::setSortAscending ( bool  ascending)
inline
void QgsAtlasComposition::setSortFeatures ( bool  doSort)
inline
void QgsAtlasComposition::setSortKeyAttributeIndex ( int  idx)
void QgsAtlasComposition::setSortKeyAttributeName ( QString  fieldName)
inline
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.
bool QgsAtlasComposition::sortAscending ( ) const
inline
bool QgsAtlasComposition::sortFeatures ( ) const
inline
int QgsAtlasComposition::sortKeyAttributeIndex ( ) const
QString QgsAtlasComposition::sortKeyAttributeName ( ) const
inline
void QgsAtlasComposition::statusMsgChanged ( QString  message)
signal

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

void QgsAtlasComposition::toggled ( bool  )
signal

emitted when atlas is enabled or disabled

int QgsAtlasComposition::updateFeatures ( )

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

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

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

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