QGIS API Documentation  2.11.0-Master
Classes | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QgsProject Class Reference

Reads and writes project states. More...

#include <qgsproject.h>

Inheritance diagram for QgsProject:
Inheritance graph
[legend]

Classes

struct  Imp
 

Signals

void layerLoaded (int i, int n)
 emitted when a layer from a projects was read More...
 
void loadingLayer (QString)
 
void oldProjectVersionWarning (QString)
 emitted when an old project file is read. More...
 
void projectSaved ()
 emitted when the project file has been written and closed More...
 
void readMapLayer (QgsMapLayer *mapLayer, const QDomElement &layerNode)
 Emitted, after the basic initialisation of a layer from the project file is done. More...
 
void readProject (const QDomDocument &)
 emitted when project is being read More...
 
void snapSettingsChanged ()
 
void writeMapLayer (QgsMapLayer *mapLayer, QDomElement &layerElem, QDomDocument &doc)
 Emitted, when a layer is being saved. More...
 
void writeProject (QDomDocument &)
 emitted when project is being written More...
 

Public Member Functions

 ~QgsProject ()
 
void clear ()
 Clear the project. More...
 
void clearProperties ()
 removes all project properties More...
 
QgsLayerTreeGroupcreateEmbeddedGroup (const QString &groupName, const QString &projectFilePath, const QStringList &invisibleLayers)
 Create layer group instance defined in an arbitrary project file. More...
 
bool createEmbeddedLayer (const QString &layerId, const QString &projectFilePath, QList< QDomNode > &brokenNodes, QList< QPair< QgsVectorLayer *, QDomElement > > &vectorLayerList, bool saveFlag=true)
 Creates a maplayer instance defined in an arbitrary project file. More...
 
void dumpProperties () const
 Dump out current project properties to stderr. More...
 
QStringList entryList (const QString &scope, const QString &key) const
 Return keys with values – do not return keys that contain other keys. More...
 
QString error () const
 Return error message from previous read/write. More...
 
QFileInfo fileInfo () const
 Returns QFileInfo object for the project's associated file. More...
 
QString homePath () const
 Return project's home path. More...
 
QString layerIsEmbedded (const QString &id) const
 Returns project file path if layer is embedded from other project file. More...
 
QgsLayerTreeRegistryBridgelayerTreeRegistryBridge () const
 Return pointer to the helper class that synchronizes map layer registry with layer tree. More...
 
QgsLayerTreeGrouplayerTreeRoot () const
 Return pointer to the root (invisible) node of the project's layer tree. More...
 
bool read (QDomNode &layerNode)
 Read the layer described in the associated Dom node. More...
 
QString readPath (QString filename) const
 Turn filename read from the project file to an absolute path. More...
 
QgsRelationManagerrelationManager () const
 
bool removeEntry (const QString &scope, const QString &key)
 Remove the given key. More...
 
void setBadLayerHandler (QgsProjectBadLayerHandler *handler)
 Change handler for missing layers. More...
 
void setSnapSettingsForLayer (const QString &layerId, bool enabled, QgsSnapper::SnappingType type, QgsTolerance::UnitType unit, double tolerance, bool avoidIntersection)
 Convenience function to set snap settings per layer. More...
 
void setTopologicalEditing (bool enabled)
 Convenience function to set topological editing. More...
 
bool snapSettingsForLayer (const QString &layerId, bool &enabled, QgsSnapper::SnappingType &type, QgsTolerance::UnitType &units, double &tolerance, bool &avoidIntersection) const
 Convenience function to query snap settings of a layer. More...
 
QStringList subkeyList (const QString &scope, const QString &key) const
 Return keys with keys – do not return keys that contain only values. More...
 
bool topologicalEditing () const
 Convenience function to query topological editing status. More...
 
QgsVisibilityPresetCollectionvisibilityPresetCollection ()
 Returns pointer to the project's visibility preset collection. More...
 
QString writePath (QString filename, QString relativeBasePath=QString::null) const
 Prepare a filename to save it to the project file. More...
 
Q_DECL_DEPRECATED void title (const QString &title)
 Every project has an associated title string. More...
 
void setTitle (const QString &title)
 Set project title. More...
 
const QStringtitle () const
 Returns title. More...
 
bool isDirty () const
 the dirty flag is true if the project has been modified since the last write() More...
 
void dirty (bool b)
 
void setDirty (bool b)
 Set project as dirty (modified). More...
 
void setFileName (const QString &name)
 Every project has an associated file that contains its XML. More...
 
QString fileName () const
 Returns file name. More...
 
bool read (const QFileInfo &file)
 Read project file. More...
 
bool read ()
 presuming that the caller has already reset the map canvas, map registry, and legend More...
 
bool write (const QFileInfo &file)
 Write project file. More...
 
bool write ()
 
bool writeEntry (const QString &scope, const QString &key, bool value)
 
bool writeEntry (const QString &scope, const QString &key, double value)
 
bool writeEntry (const QString &scope, const QString &key, int value)
 
bool writeEntry (const QString &scope, const QString &key, const QString &value)
 
bool writeEntry (const QString &scope, const QString &key, const QStringList &value)
 
QStringList readListEntry (const QString &scope, const QString &key, QStringList def=QStringList(), bool *ok=0) const
 Key value accessors. More...
 
QString readEntry (const QString &scope, const QString &key, const QString &def=QString::null, bool *ok=0) const
 
int readNumEntry (const QString &scope, const QString &key, int def=0, bool *ok=0) const
 
double readDoubleEntry (const QString &scope, const QString &key, double def=0, bool *ok=0) const
 
bool readBoolEntry (const QString &scope, const QString &key, bool def=false, bool *ok=0) 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
 

Static Public Member Functions

static QgsProjectinstance ()
 access to canonical QgsProject instance More...
 
- 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

bool addLayer (const QDomElement &layerElem, QList< QDomNode > &brokenNodes, QList< QPair< QgsVectorLayer *, QDomElement > > &vectorLayerList)
 
void clearError ()
 Clear error message. More...
 
void initializeEmbeddedSubtree (const QString &projectFilePath, QgsLayerTreeGroup *group)
 
void loadEmbeddedNodes (QgsLayerTreeGroup *group)
 
void setError (QString errorMessage)
 Set error message from read/write operation. More...
 
- 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)
 

Additional Inherited Members

- Static Protected Member Functions inherited from QObject
QByteArray normalizeSignalSlot (const char *signalSlot)
 
- Properties inherited from QObject
 objectName
 

Detailed Description

Reads and writes project states.

Note

Has two general kinds of state to make persistent. (I.e., to read and write.) First, Qgis proprietary information. Second plug-in information.

A singleton since there shall only be one active project at a time; and provides canonical location for plug-ins and main app to find/set properties.

Might want to consider moving from Singleton; i.e., allowing more than one project. Just as the GIMP can have simultaneous multiple images, perhaps qgis can one day have simultaneous multiple projects.

Definition at line 69 of file qgsproject.h.

Constructor & Destructor Documentation

QgsProject::~QgsProject ( )
Todo:
XXX Should have semantics for saving project if dirty as last gasp?

Definition at line 341 of file qgsproject.cpp.

Member Function Documentation

bool QgsProject::addLayer ( const QDomElement layerElem,
QList< QDomNode > &  brokenNodes,
QList< QPair< QgsVectorLayer *, QDomElement > > &  vectorLayerList 
)
protected
Note
not available in python bindings

Definition at line 701 of file qgsproject.cpp.

void QgsProject::clear ( )

Clear the project.

Note
added in 2.4

Definition at line 412 of file qgsproject.cpp.

void QgsProject::clearError ( )
protected

Clear error message.

Definition at line 1585 of file qgsproject.cpp.

void QgsProject::clearProperties ( )

removes all project properties

QGIS 3: remove in favor of clear()

Definition at line 1133 of file qgsproject.cpp.

QgsLayerTreeGroup * QgsProject::createEmbeddedGroup ( const QString groupName,
const QString projectFilePath,
const QStringList invisibleLayers 
)

Create layer group instance defined in an arbitrary project file.

Note
: added in version 2.4

Definition at line 1714 of file qgsproject.cpp.

bool QgsProject::createEmbeddedLayer ( const QString layerId,
const QString projectFilePath,
QList< QDomNode > &  brokenNodes,
QList< QPair< QgsVectorLayer *, QDomElement > > &  vectorLayerList,
bool  saveFlag = true 
)

Creates a maplayer instance defined in an arbitrary project file.

Caller takes ownership

Returns
the layer or 0 in case of error

Definition at line 1606 of file qgsproject.cpp.

void QgsProject::dirty ( bool  b)

Definition at line 381 of file qgsproject.cpp.

void QgsProject::dumpProperties ( ) const

Dump out current project properties to stderr.

Todo:
XXX Now slightly broken since re-factoring. Won't print out top-level key and redundantly prints sub-keys.

Definition at line 1365 of file qgsproject.cpp.

QStringList QgsProject::entryList ( const QString scope,
const QString key 
) const

Return keys with values – do not return keys that contain other keys.

Note
equivalent to QSettings entryList()

Definition at line 1327 of file qgsproject.cpp.

QString QgsProject::error ( ) const

Return error message from previous read/write.

Definition at line 1580 of file qgsproject.cpp.

QFileInfo QgsProject::fileInfo ( ) const

Returns QFileInfo object for the project's associated file.

Note
added in QGIS 2.9

Definition at line 407 of file qgsproject.cpp.

QString QgsProject::fileName ( ) const

Returns file name.

Definition at line 402 of file qgsproject.cpp.

QString QgsProject::homePath ( ) const

Return project's home path.

Returns
home path of project (or QString::null if not set)

Definition at line 1959 of file qgsproject.cpp.

void QgsProject::initializeEmbeddedSubtree ( const QString projectFilePath,
QgsLayerTreeGroup group 
)
protected
Note
not available in python bindings

Definition at line 1794 of file qgsproject.cpp.

QgsProject * QgsProject::instance ( )
static

access to canonical QgsProject instance

Definition at line 352 of file qgsproject.cpp.

bool QgsProject::isDirty ( ) const

the dirty flag is true if the project has been modified since the last write()

Definition at line 375 of file qgsproject.cpp.

QString QgsProject::layerIsEmbedded ( const QString id) const

Returns project file path if layer is embedded from other project file.

Returns empty string if layer is not embedded

Definition at line 1596 of file qgsproject.cpp.

void QgsProject::layerLoaded ( int  i,
int  n 
)
signal

emitted when a layer from a projects was read

QgsLayerTreeRegistryBridge* QgsProject::layerTreeRegistryBridge ( ) const
inline

Return pointer to the helper class that synchronizes map layer registry with layer tree.

Note
added in 2.4

Definition at line 309 of file qgsproject.h.

QgsLayerTreeGroup * QgsProject::layerTreeRoot ( ) const

Return pointer to the root (invisible) node of the project's layer tree.

Note
added in 2.4

Definition at line 1973 of file qgsproject.cpp.

void QgsProject::loadEmbeddedNodes ( QgsLayerTreeGroup group)
protected
Note
not available in python bindings

Definition at line 915 of file qgsproject.cpp.

void QgsProject::loadingLayer ( QString  )
signal
void QgsProject::oldProjectVersionWarning ( QString  )
signal

emitted when an old project file is read.

void QgsProject::projectSaved ( )
signal

emitted when the project file has been written and closed

bool QgsProject::read ( const QFileInfo file)

Read project file.

Please note that most of the contents were copied from qgsproject.

Note
Any current plug-in state is erased
dirty set to false after successful invocation
file name argument implicitly sets file
  • Gets the extents
  • Creates maplayers
  • Registers maplayers
Note
it's presumed that the caller has already reset the map canvas, map registry, and legend

Definition at line 760 of file qgsproject.cpp.

bool QgsProject::read ( )

presuming that the caller has already reset the map canvas, map registry, and legend

Shows a warning when an old project file is read.

Definition at line 772 of file qgsproject.cpp.

bool QgsProject::read ( QDomNode layerNode)

Read the layer described in the associated Dom node.

Parameters
layerNoderepresents a QgsProject Dom node that maps to a specific layer.

QgsProject raises an exception when one of the QgsProject::read() implementations fails. Since the read()s are invoked from qgisapp, then qgisapp handles the exception. It prompts the user for the new location of the data, if any. If there is a new location, the Dom node associated with the layer has its datasource tag corrected. Then that node is passed to this member function to be re-opened.

Definition at line 958 of file qgsproject.cpp.

bool QgsProject::readBoolEntry ( const QString scope,
const QString key,
bool  def = false,
bool *  ok = 0 
) const

Definition at line 1295 of file qgsproject.cpp.

double QgsProject::readDoubleEntry ( const QString scope,
const QString key,
double  def = 0,
bool *  ok = 0 
) const

Definition at line 1273 of file qgsproject.cpp.

QString QgsProject::readEntry ( const QString scope,
const QString key,
const QString def = QString::null,
bool *  ok = 0 
) const

Definition at line 1218 of file qgsproject.cpp.

QStringList QgsProject::readListEntry ( const QString scope,
const QString key,
QStringList  def = QStringList(),
bool *  ok = 0 
) const

Key value accessors.

keys would be the familiar QSettings-like '/' delimited entries, implying a hierarchy of keys and corresponding values

Note
The key string must include '/'s. E.g., "/foo" not "foo".

Definition at line 1190 of file qgsproject.cpp.

void QgsProject::readMapLayer ( QgsMapLayer mapLayer,
const QDomElement layerNode 
)
signal

Emitted, after the basic initialisation of a layer from the project file is done.

You can use this signal to read additional information from the project file.

Parameters
mapLayerThe map layer which is being initialized
layerNodeThe layer node from the project file
int QgsProject::readNumEntry ( const QString scope,
const QString key,
int  def = 0,
bool *  ok = 0 
) const

Definition at line 1244 of file qgsproject.cpp.

QString QgsProject::readPath ( QString  filename) const

Turn filename read from the project file to an absolute path.

Definition at line 1372 of file qgsproject.cpp.

void QgsProject::readProject ( const QDomDocument )
signal

emitted when project is being read

QgsRelationManager * QgsProject::relationManager ( ) const

Definition at line 1968 of file qgsproject.cpp.

bool QgsProject::removeEntry ( const QString scope,
const QString key 
)

Remove the given key.

Definition at line 1316 of file qgsproject.cpp.

void QgsProject::setBadLayerHandler ( QgsProjectBadLayerHandler handler)

Change handler for missing layers.

Deletes old handler and takes ownership of the new one.

Definition at line 1590 of file qgsproject.cpp.

void QgsProject::setDirty ( bool  b)

Set project as dirty (modified).

Note
added in 2.4

Definition at line 386 of file qgsproject.cpp.

void QgsProject::setError ( QString  errorMessage)
protected

Set error message from read/write operation.

Definition at line 1575 of file qgsproject.cpp.

void QgsProject::setFileName ( const QString name)

Every project has an associated file that contains its XML.

Definition at line 393 of file qgsproject.cpp.

void QgsProject::setSnapSettingsForLayer ( const QString layerId,
bool  enabled,
QgsSnapper::SnappingType  type,
QgsTolerance::UnitType  unit,
double  tolerance,
bool  avoidIntersection 
)

Convenience function to set snap settings per layer.

Definition at line 1815 of file qgsproject.cpp.

void QgsProject::setTitle ( const QString title)

Set project title.

Note
added in 2.4

Definition at line 361 of file qgsproject.cpp.

void QgsProject::setTopologicalEditing ( bool  enabled)

Convenience function to set topological editing.

Definition at line 1943 of file qgsproject.cpp.

void QgsProject::snapSettingsChanged ( )
signal
bool QgsProject::snapSettingsForLayer ( const QString layerId,
bool &  enabled,
QgsSnapper::SnappingType type,
QgsTolerance::UnitType units,
double &  tolerance,
bool &  avoidIntersection 
) const

Convenience function to query snap settings of a layer.

Definition at line 1872 of file qgsproject.cpp.

QStringList QgsProject::subkeyList ( const QString scope,
const QString key 
) const

Return keys with keys – do not return keys that contain only values.

Note
equivalent to QSettings subkeyList()

Definition at line 1345 of file qgsproject.cpp.

Q_DECL_DEPRECATED void QgsProject::title ( const QString title)
inline

Every project has an associated title string.

Deprecated:
Use setTitle instead.

Definition at line 89 of file qgsproject.h.

QString const & QgsProject::title ( ) const

Returns title.

Definition at line 369 of file qgsproject.cpp.

bool QgsProject::topologicalEditing ( ) const

Convenience function to query topological editing status.

Definition at line 1949 of file qgsproject.cpp.

QgsVisibilityPresetCollection * QgsProject::visibilityPresetCollection ( )

Returns pointer to the project's visibility preset collection.

Note
added in QGIS 2.12

Definition at line 1978 of file qgsproject.cpp.

bool QgsProject::write ( const QFileInfo file)

Write project file.

XXX How to best get read access to Qgis state? Actually we can finagle that by searching for qgisapp in object hiearchy.

Note
file name argument implicitly sets file
dirty set to false after successful invocation

Definition at line 967 of file qgsproject.cpp.

bool QgsProject::write ( )

Definition at line 975 of file qgsproject.cpp.

bool QgsProject::writeEntry ( const QString scope,
const QString key,
bool  value 
)
Note
available in python bindings as writeEntryBool

Definition at line 1143 of file qgsproject.cpp.

bool QgsProject::writeEntry ( const QString scope,
const QString key,
double  value 
)
Note
available in python bindings as writeEntryDouble

Definition at line 1152 of file qgsproject.cpp.

bool QgsProject::writeEntry ( const QString scope,
const QString key,
int  value 
)

Definition at line 1162 of file qgsproject.cpp.

bool QgsProject::writeEntry ( const QString scope,
const QString key,
const QString value 
)

Definition at line 1171 of file qgsproject.cpp.

bool QgsProject::writeEntry ( const QString scope,
const QString key,
const QStringList value 
)

Definition at line 1181 of file qgsproject.cpp.

void QgsProject::writeMapLayer ( QgsMapLayer mapLayer,
QDomElement layerElem,
QDomDocument doc 
)
signal

Emitted, when a layer is being saved.

You can use this method to save additional information to the layer.

Parameters
mapLayerThe map layer which is being initialized
layerElemThe layer element from the project file
docThe document
QString QgsProject::writePath ( QString  filename,
QString  relativeBasePath = QString::null 
) const

Prepare a filename to save it to the project file.

Definition at line 1481 of file qgsproject.cpp.

void QgsProject::writeProject ( QDomDocument )
signal

emitted when project is being written


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