QGIS API Documentation  2.12.0-Lyon
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, QVariantSorterKeys
 

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 (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...
 
Q_DECL_DEPRECATED QgsComposerMapcomposerMap () const
 Returns the map used by the atlas. More...
 
QgsCompositioncomposition ()
 
QgsVectorLayercoverageLayer () const
 Returns the coverage layer used for the atlas features. More...
 
Q_DECL_DEPRECATED QgsFeaturecurrentFeature ()
 Returns the current atlas feature. More...
 
int currentFeatureNumber () const
 Returns the current feature number, where a value of 0 corresponds to the first feature. More...
 
const QStringcurrentFilename () const
 Returns the current filename. 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. 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
 
Q_DECL_DEPRECATED bool fixedScale () const
 Returns whether the atlas map uses a fixed scale. More...
 
bool hideCoverage () const
 Returns true if the atlas is set to hide the coverage layer. More...
 
Q_DECL_DEPRECATED float margin () const
 Returns the margin for the atlas map. 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...
 
Q_DECL_DEPRECATED void setComposerMap (QgsComposerMap *map)
 Sets the map used by the atlas. 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)
 
Q_DECL_DEPRECATED void setFixedScale (bool fixed)
 Sets whether the atlas map should use a fixed scale. More...
 
void setHideCoverage (bool hide)
 Sets whether the coverage layer should be hidden in map items in the composition. More...
 
Q_DECL_DEPRECATED void setMargin (float margin)
 Sets the margin for the atlas map. 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)
 
Q_DECL_DEPRECATED void setSortKeyAttributeIndex (int idx)
 
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
 
Q_DECL_DEPRECATED int sortKeyAttributeIndex () 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
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
 QObject (QObject *parent, const char *name)
 
virtual  ~QObject ()
 
bool blockSignals (bool block)
 
QObjectchild (const char *objName, const char *inheritsClass, bool recursiveSearch) const
 
const QObjectList & children () const
 
const char * className () const
 
bool connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const QObject *receiver, const char *method)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method)
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QByteArraydynamicPropertyNames () const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name) const
 
QList< T > findChildren (const QRegExp &regExp) const
 
QList< T > findChildren (const QString &name) const
 
bool inherits (const char *className) const
 
void insertChild (QObject *object)
 
void installEventFilter (QObject *filterObj)
 
bool isA (const char *className) const
 
bool isWidgetType () const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
const char * name () const
 
const char * name (const char *defaultName) const
 
QString objectName () const
 
QObjectparent () const
 
QVariant property (const char *name) const
 
void removeChild (QObject *object)
 
void removeEventFilter (QObject *obj)
 
void setName (const char *name)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval)
 
QThreadthread () const
 

Additional Inherited Members

- Static Public Member Functions inherited from QObject
bool connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
bool connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Protected Member Functions inherited from QObject
bool checkConnectArgs (const char *signal, const QObject *object, const char *method)
 
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const char *signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const char *signal)
 
int receivers (const char *signal) const
 
QObjectsender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 
- Static Protected Member Functions inherited from QObject
QByteArray normalizeSignalSlot (const char *signalSlot)
 
- Properties inherited from QObject
 objectName
 

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

Member Typedef Documentation

Definition at line 363 of file qgsatlascomposition.h.

Constructor & Destructor Documentation

QgsAtlasComposition::QgsAtlasComposition ( QgsComposition composition)

Definition at line 32 of file qgsatlascomposition.cpp.

QgsAtlasComposition::~QgsAtlasComposition ( )

Definition at line 49 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 288 of file qgsatlascomposition.cpp.

QgsComposerMap * QgsAtlasComposition::composerMap ( ) const

Returns the map used by the atlas.

Deprecated:
Use QgsComposerMap::atlasDriven() instead

Definition at line 104 of file qgsatlascomposition.cpp.

QgsComposition* QgsAtlasComposition::composition ( )
inline

Definition at line 231 of file qgsatlascomposition.h.

QgsVectorLayer* QgsAtlasComposition::coverageLayer ( ) const
inline

Returns the coverage layer used for the atlas features.

Returns
atlas coverage layer
See also
setCoverageLayer

Definition at line 103 of file qgsatlascomposition.h.

void QgsAtlasComposition::coverageLayerChanged ( QgsVectorLayer layer)
signal

Is emitted when the coverage layer for an atlas changes.

Q_DECL_DEPRECATED QgsFeature* QgsAtlasComposition::currentFeature ( )
inline

Returns the current atlas feature.

Must be called after prepareForFeature( i ).

Definition at line 292 of file qgsatlascomposition.h.

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

const QString & QgsAtlasComposition::currentFilename ( ) const

Returns the current filename.

Must be called after prepareForFeature()

Definition at line 647 of file qgsatlascomposition.cpp.

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

bool QgsAtlasComposition::enabled ( ) const
inline

Returns whether the atlas generation is enabled.

Returns
true if atlas is enabled
See also
setEnabled

Definition at line 53 of file qgsatlascomposition.h.

void QgsAtlasComposition::endRender ( )

Ends the rendering.

Restores original extent

Definition at line 307 of file qgsatlascomposition.cpp.

QgsFeature QgsAtlasComposition::feature ( ) const
inline

Returns the current atlas feature.

Must be called after prepareForFeature().

Note
added in QGIS 2.12

Definition at line 240 of file qgsatlascomposition.h.

void QgsAtlasComposition::featureChanged ( QgsFeature feature)
signal

Is emitted when the current atlas feature changes.

QString QgsAtlasComposition::featureFilter ( ) const
inline

Definition at line 159 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 167 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 80 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 97 of file qgsatlascomposition.h.

bool QgsAtlasComposition::filterFeatures ( ) const
inline

Definition at line 156 of file qgsatlascomposition.h.

void QgsAtlasComposition::firstFeature ( )
slot

Definition at line 365 of file qgsatlascomposition.cpp.

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

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

void QgsAtlasComposition::lastFeature ( )
slot

Definition at line 370 of file qgsatlascomposition.cpp.

float QgsAtlasComposition::margin ( ) const

Returns the margin for the atlas map.

Deprecated:
Use QgsComposerMap::atlasMargin() instead

Definition at line 897 of file qgsatlascomposition.cpp.

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

void QgsAtlasComposition::nextFeature ( )
slot

Definition at line 343 of file qgsatlascomposition.cpp.

void QgsAtlasComposition::numberFeaturesChanged ( int  numFeatures)
signal

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

Note
added in QGIS 2.12
int QgsAtlasComposition::numFeatures ( ) const

Returns the number of features in the coverage layer.

Definition at line 338 of file qgsatlascomposition.cpp.

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

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

Definition at line 178 of file qgsatlascomposition.h.

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

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

void QgsAtlasComposition::prepareMap ( QgsComposerMap map)

Recalculates the bounds of an atlas driven map.

Definition at line 519 of file qgsatlascomposition.cpp.

void QgsAtlasComposition::prevFeature ( )
slot

Definition at line 354 of file qgsatlascomposition.cpp.

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

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

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

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

Definition at line 123 of file qgsatlascomposition.cpp.

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

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

void QgsAtlasComposition::setFeatureFilter ( const QString expression)
inline

Definition at line 160 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 793 of file qgsatlascomposition.cpp.

void QgsAtlasComposition::setFilterFeatures ( bool  doFilter)
inline

Definition at line 157 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 885 of file qgsatlascomposition.cpp.

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

void QgsAtlasComposition::setMargin ( float  margin)

Sets the margin for the atlas map.

Deprecated:
Use QgsComposerMap::setAtlasMargin( double ) instead

Definition at line 909 of file qgsatlascomposition.cpp.

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

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

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

void QgsAtlasComposition::setSortAscending ( bool  ascending)
inline

Definition at line 154 of file qgsatlascomposition.h.

void QgsAtlasComposition::setSortFeatures ( bool  doSort)
inline

Definition at line 151 of file qgsatlascomposition.h.

void QgsAtlasComposition::setSortKeyAttributeIndex ( int  idx)

Definition at line 145 of file qgsatlascomposition.cpp.

void QgsAtlasComposition::setSortKeyAttributeName ( const QString fieldName)
inline

Definition at line 170 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 140 of file qgsatlascomposition.h.

bool QgsAtlasComposition::sortAscending ( ) const
inline

Definition at line 153 of file qgsatlascomposition.h.

bool QgsAtlasComposition::sortFeatures ( ) const
inline

Definition at line 150 of file qgsatlascomposition.h.

int QgsAtlasComposition::sortKeyAttributeIndex ( ) const

Definition at line 136 of file qgsatlascomposition.cpp.

QString QgsAtlasComposition::sortKeyAttributeName ( ) const
inline

Definition at line 169 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.

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

Definition at line 190 of file qgsatlascomposition.cpp.

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

Definition at line 652 of file qgsatlascomposition.cpp.


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