QGIS API Documentation  2.5.0-Master
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Public Types | Signals | Public Member Functions | Private Member Functions | Private Attributes | 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]
Collaboration diagram for QgsAtlasComposition:
Collaboration graph
[legend]

Public Types

typedef QMap< QgsFeatureId,
QVariant > 
SorterKeys
 

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< double > & predefinedScales () const
 Returns the current list of predefined scales for the atlas. More...
 
void setPredefinedScales (const QVector< double > &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 (int i)
 Prepare the atlas map for the given feature. More...
 
bool prepareForFeature (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...
 
void nextFeature ()
 
void prevFeature ()
 
void lastFeature ()
 
void firstFeature ()
 
QgsFeaturecurrentFeature ()
 Returns the current atlas feature. More...
 
void prepareMap (QgsComposerMap *map)
 Recalculates the bounds of an atlas driven map. More...
 

Private Member Functions

bool updateFilenameExpression ()
 Updates the filename expression. More...
 
bool evalFeatureFilename ()
 Evaluates filename for current feature. More...
 
void updateAtlasMaps ()
 
void computeExtent (QgsComposerMap *map)
 

Private Attributes

QgsCompositionmComposition
 
bool mEnabled
 
bool mHideCoverage
 
QString mFilenamePattern
 
QgsVectorLayermCoverageLayer
 
bool mSingleFile
 
QgsCoordinateTransform mTransform
 
QString mCurrentFilename
 
bool mSortFeatures
 
bool mSortAscending
 
int mCurrentFeatureNo
 
SorterKeys mFeatureKeys
 
QString mSortKeyAttributeName
 
bool mFilterFeatures
 
QString mFeatureFilter
 
QVector< QgsFeatureIdmFeatureIds
 
QgsFeature mCurrentFeature
 
std::auto_ptr< QgsExpressionmFilenameExpr
 
QgsRectangle mTransformedFeatureBounds
 
QString mFilenameParserError
 
QString mFilterParserError
 
QVector< double > mPredefinedScales
 

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 40 of file qgsatlascomposition.h.

Member Typedef Documentation

typedef QMap< QgsFeatureId, QVariant > QgsAtlasComposition::SorterKeys

Definition at line 306 of file qgsatlascomposition.h.

Constructor & Destructor Documentation

QgsAtlasComposition::QgsAtlasComposition ( QgsComposition composition)

Definition at line 31 of file qgsatlascomposition.cpp.

References QgsExpression::setSpecialColumn().

QgsAtlasComposition::~QgsAtlasComposition ( )

Definition at line 52 of file qgsatlascomposition.cpp.

Member Function Documentation

bool QgsAtlasComposition::beginRender ( )

Begins the rendering.

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

Definition at line 245 of file qgsatlascomposition.cpp.

References mComposition, mCoverageLayer, mFeatureIds, QgsComposition::numPages(), renderBegun(), QgsExpression::setSpecialColumn(), and updateFeatures().

Referenced by QgsComposition::setAtlasMode().

QgsComposerMap * QgsAtlasComposition::composerMap ( ) const
QgsComposition* QgsAtlasComposition::composition ( )
inline

Definition at line 237 of file qgsatlascomposition.h.

Referenced by prepareMap().

void QgsAtlasComposition::computeExtent ( QgsComposerMap map)
private
QgsVectorLayer* QgsAtlasComposition::coverageLayer ( ) const
inline
void QgsAtlasComposition::coverageLayerChanged ( QgsVectorLayer layer)
signal

Is emitted when the coverage layer for an atlas changes.

Referenced by setCoverageLayer().

QgsFeature* QgsAtlasComposition::currentFeature ( )
inline
const QString & QgsAtlasComposition::currentFilename ( ) const

Returns the current filename.

Must be called after prepareForFeature( i )

Definition at line 566 of file qgsatlascomposition.cpp.

References mCurrentFilename.

bool QgsAtlasComposition::enabled ( ) const
inline
void QgsAtlasComposition::endRender ( )

Ends the rendering.

Restores original extent

Definition at line 268 of file qgsatlascomposition.cpp.

References featureChanged(), mCoverageLayer, renderEnded(), and updateAtlasMaps().

Referenced by QgsComposition::setAtlasMode().

bool QgsAtlasComposition::evalFeatureFilename ( )
private

Evaluates filename for current feature.

Returns
true if feature filename was successfully evaluated

Definition at line 748 of file qgsatlascomposition.cpp.

References QgsMessageLog::logMessage(), mCoverageLayer, mCurrentFeature, mCurrentFilename, mFilenameExpr, mFilenamePattern, QgsVectorLayer::pendingFields(), and tr.

Referenced by prepareForFeature(), and updateFilenameExpression().

void QgsAtlasComposition::featureChanged ( QgsFeature feature)
signal

Is emitted when the current atlas feature changes.

Referenced by endRender(), and prepareForFeature().

QString QgsAtlasComposition::featureFilter ( ) const
inline

Definition at line 164 of file qgsatlascomposition.h.

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 172 of file qgsatlascomposition.h.

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 108 of file qgsatlascomposition.h.

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 125 of file qgsatlascomposition.h.

bool QgsAtlasComposition::filterFeatures ( ) const
inline

Definition at line 161 of file qgsatlascomposition.h.

void QgsAtlasComposition::firstFeature ( )

Definition at line 326 of file qgsatlascomposition.cpp.

References prepareForFeature().

Referenced by updateFeatures().

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

Definition at line 773 of file qgsatlascomposition.cpp.

References QgsComposerMap::atlasFixedScale(), and composerMap().

Referenced by readXMLMapSettings().

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 73 of file qgsatlascomposition.h.

Referenced by QgsComposerMap::layersToRender().

void QgsAtlasComposition::lastFeature ( )

Definition at line 331 of file qgsatlascomposition.cpp.

References mFeatureIds, and prepareForFeature().

float QgsAtlasComposition::margin ( ) const

Returns the margin for the atlas map.

Deprecated:
Use QgsComposerMap::atlasMargin() instead

Definition at line 797 of file qgsatlascomposition.cpp.

References QgsComposerMap::atlasMargin(), and composerMap().

Referenced by readXMLMapSettings().

void QgsAtlasComposition::nextFeature ( )

Definition at line 304 of file qgsatlascomposition.cpp.

References mCurrentFeatureNo, mFeatureIds, and prepareForFeature().

int QgsAtlasComposition::numFeatures ( ) const

Returns the number of features in the coverage layer.

Definition at line 299 of file qgsatlascomposition.cpp.

References mFeatureIds.

void QgsAtlasComposition::parameterChanged ( )
signal

emitted when one of the parameters changes

Referenced by readXML().

const QVector<double>& 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 186 of file qgsatlascomposition.h.

bool QgsAtlasComposition::prepareForFeature ( int  i)
bool QgsAtlasComposition::prepareForFeature ( 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 336 of file qgsatlascomposition.cpp.

References QgsFeature::id(), mFeatureIds, and prepareForFeature().

void QgsAtlasComposition::prepareMap ( QgsComposerMap map)
void QgsAtlasComposition::prevFeature ( )

Definition at line 315 of file qgsatlascomposition.cpp.

References mCurrentFeatureNo, and prepareForFeature().

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 608 of file qgsatlascomposition.cpp.

References QgsFields::count(), QgsMapLayerRegistry::instance(), QgsMapLayerRegistry::mapLayers(), mCoverageLayer, mEnabled, mFeatureFilter, mFilenamePattern, mFilterFeatures, mHideCoverage, mSingleFile, mSortAscending, mSortFeatures, mSortKeyAttributeName, parameterChanged(), QgsVectorLayer::pendingFields(), and toggled().

Referenced by QgsComposition::loadFromTemplate().

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 663 of file qgsatlascomposition.cpp.

References QgsComposition::composerItems(), composerMap(), QgsComposerMap::Fixed, fixedScale(), margin(), mComposition, QgsComposerMap::setAtlasDriven(), QgsComposerMap::setAtlasMargin(), and QgsComposerMap::setAtlasScalingMode().

Referenced by QgsComposition::loadFromTemplate().

void QgsAtlasComposition::renderBegun ( )
signal

Is emitted when atlas rendering has begun.

Referenced by beginRender().

void QgsAtlasComposition::renderEnded ( )
signal

Is emitted when atlas rendering has ended.

Referenced by endRender().

void QgsAtlasComposition::setComposerMap ( QgsComposerMap map)

Sets the map used by the atlas.

Deprecated:
Use QgsComposerMap::setAtlasDriven( true ) instead

Definition at line 102 of file qgsatlascomposition.cpp.

References QgsComposerMap::setAtlasDriven().

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 63 of file qgsatlascomposition.cpp.

References coverageLayerChanged(), QgsFeature::geometry(), QgsVectorLayer::getFeatures(), QgsFeature::id(), mCoverageLayer, mFeatureIds, QgsFeatureIterator::nextFeature(), and QgsExpression::setSpecialColumn().

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.

References QgsComposition::AtlasOff, enabled(), mComposition, mEnabled, QgsComposition::setAtlasMode(), and toggled().

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

Definition at line 165 of file qgsatlascomposition.h.

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 710 of file qgsatlascomposition.cpp.

References mFilenamePattern, and updateFilenameExpression().

void QgsAtlasComposition::setFilterFeatures ( bool  doFilter)
inline

Definition at line 162 of file qgsatlascomposition.h.

void QgsAtlasComposition::setFixedScale ( bool  fixed)

Sets whether the atlas map should use a fixed scale.

Deprecated:
since 2.4 Use QgsComposerMap::setAtlasScalingMode() instead

Definition at line 785 of file qgsatlascomposition.cpp.

References QgsComposerMap::Auto, composerMap(), QgsComposerMap::Fixed, and QgsComposerMap::setAtlasScalingMode().

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 697 of file qgsatlascomposition.cpp.

References QgsComposition::atlasMode(), mComposition, mHideCoverage, QgsComposition::PreviewAtlas, and updateAtlasMaps().

void QgsAtlasComposition::setMargin ( float  margin)

Sets the margin for the atlas map.

Deprecated:
Use QgsComposerMap::setAtlasMargin( double ) instead

Definition at line 809 of file qgsatlascomposition.cpp.

References composerMap(), and QgsComposerMap::setAtlasMargin().

void QgsAtlasComposition::setPredefinedScales ( const QVector< double > &  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 765 of file qgsatlascomposition.cpp.

References mPredefinedScales.

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 153 of file qgsatlascomposition.h.

void QgsAtlasComposition::setSortAscending ( bool  ascending)
inline

Definition at line 159 of file qgsatlascomposition.h.

void QgsAtlasComposition::setSortFeatures ( bool  doSort)
inline

Definition at line 156 of file qgsatlascomposition.h.

void QgsAtlasComposition::setSortKeyAttributeIndex ( int  idx)
void QgsAtlasComposition::setSortKeyAttributeName ( QString  fieldName)
inline

Definition at line 175 of file qgsatlascomposition.h.

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 145 of file qgsatlascomposition.h.

bool QgsAtlasComposition::sortAscending ( ) const
inline

Definition at line 158 of file qgsatlascomposition.h.

bool QgsAtlasComposition::sortFeatures ( ) const
inline

Definition at line 155 of file qgsatlascomposition.h.

int QgsAtlasComposition::sortKeyAttributeIndex ( ) const
QString QgsAtlasComposition::sortKeyAttributeName ( ) const
inline

Definition at line 174 of file qgsatlascomposition.h.

void QgsAtlasComposition::statusMsgChanged ( QString  message)
signal

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

Referenced by prepareForFeature().

void QgsAtlasComposition::toggled ( bool  )
signal

emitted when atlas is enabled or disabled

Referenced by readXML(), and setEnabled().

void QgsAtlasComposition::updateAtlasMaps ( )
private
int QgsAtlasComposition::updateFeatures ( )
bool QgsAtlasComposition::updateFilenameExpression ( )
private

Updates the filename expression.

Returns
true if expression was successfully parsed, false if expression is invalid

Definition at line 716 of file qgsatlascomposition.cpp.

References QgsComposition::atlasMode(), evalFeatureFilename(), mComposition, mCoverageLayer, mFilenameExpr, mFilenameParserError, mFilenamePattern, QgsVectorLayer::pendingFields(), and QgsComposition::PreviewAtlas.

Referenced by setFilenamePattern(), and updateFeatures().

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

Member Data Documentation

QgsComposition* QgsAtlasComposition::mComposition
private
QgsVectorLayer* QgsAtlasComposition::mCoverageLayer
private
QgsFeature QgsAtlasComposition::mCurrentFeature
private

Definition at line 322 of file qgsatlascomposition.h.

Referenced by computeExtent(), evalFeatureFilename(), and prepareForFeature().

int QgsAtlasComposition::mCurrentFeatureNo
private

Definition at line 303 of file qgsatlascomposition.h.

Referenced by nextFeature(), prepareForFeature(), and prevFeature().

QString QgsAtlasComposition::mCurrentFilename
private

Definition at line 296 of file qgsatlascomposition.h.

Referenced by currentFilename(), and evalFeatureFilename().

bool QgsAtlasComposition::mEnabled
private

Definition at line 289 of file qgsatlascomposition.h.

Referenced by readXML(), setEnabled(), and writeXML().

QString QgsAtlasComposition::mFeatureFilter
private

Definition at line 317 of file qgsatlascomposition.h.

Referenced by readXML(), updateFeatures(), and writeXML().

QVector<QgsFeatureId> QgsAtlasComposition::mFeatureIds
private
SorterKeys QgsAtlasComposition::mFeatureKeys
private

Definition at line 310 of file qgsatlascomposition.h.

Referenced by updateFeatures().

std::auto_ptr<QgsExpression> QgsAtlasComposition::mFilenameExpr
private

Definition at line 324 of file qgsatlascomposition.h.

Referenced by evalFeatureFilename(), and updateFilenameExpression().

QString QgsAtlasComposition::mFilenameParserError
private

Definition at line 329 of file qgsatlascomposition.h.

Referenced by updateFilenameExpression().

QString QgsAtlasComposition::mFilenamePattern
private
bool QgsAtlasComposition::mFilterFeatures
private

Definition at line 315 of file qgsatlascomposition.h.

Referenced by readXML(), updateFeatures(), and writeXML().

QString QgsAtlasComposition::mFilterParserError
private

Definition at line 330 of file qgsatlascomposition.h.

Referenced by updateFeatures().

bool QgsAtlasComposition::mHideCoverage
private

Definition at line 290 of file qgsatlascomposition.h.

Referenced by readXML(), setHideCoverage(), and writeXML().

QVector<double> QgsAtlasComposition::mPredefinedScales
private

Definition at line 339 of file qgsatlascomposition.h.

Referenced by prepareMap(), and setPredefinedScales().

bool QgsAtlasComposition::mSingleFile
private

Definition at line 293 of file qgsatlascomposition.h.

Referenced by readXML(), and writeXML().

bool QgsAtlasComposition::mSortAscending
private

Definition at line 300 of file qgsatlascomposition.h.

Referenced by readXML(), updateFeatures(), and writeXML().

bool QgsAtlasComposition::mSortFeatures
private

Definition at line 298 of file qgsatlascomposition.h.

Referenced by readXML(), updateFeatures(), and writeXML().

QString QgsAtlasComposition::mSortKeyAttributeName
private
QgsCoordinateTransform QgsAtlasComposition::mTransform
private

Definition at line 295 of file qgsatlascomposition.h.

Referenced by computeExtent().

QgsRectangle QgsAtlasComposition::mTransformedFeatureBounds
private

Definition at line 327 of file qgsatlascomposition.h.

Referenced by computeExtent(), prepareForFeature(), and prepareMap().


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