QgsProject Class Reference
[QGIS core library]

Reads and writes project states. More...

#include <qgsproject.h>

Collaboration diagram for QgsProject:

Collaboration graph
[legend]

List of all members.

Signals

void readProject (const QDomDocument &)
 emitted when project is being read
void writeProject (QDomDocument &)
 emitted when project is being written
void oldProjectVersionWarning (QString)
 emitted when an old project file is read.
void layerLoaded (int i, int n)
 emitted when a layer from a projects was read

Public Member Functions

 ~QgsProject ()
bool read (QDomNode &layerNode)
 read the layer described in the associated Dom node
void clearProperties ()
 syntactic sugar for property lists
bool removeEntry (QString const &scope, const QString &key)
 remove the given key
QStringList entryList (QString const &scope, QString const &key) const
 return keys with values -- do not return keys that contain other keys
QStringList subkeyList (QString const &scope, QString const &key) const
 return keys with keys -- do not return keys that contain only values
void dumpProperties () const
 dump out current project properties to stderr
QString writePath (QString filename) const
 prepare a filename to save it to the project file
QString readPath (QString filename) const
 turn filename read from the project file to an absolute path
QString error () const
 Return error message from previous read/write.
void setBadLayerHandler (QgsProjectBadLayerHandler *handler)
 Change handler for missing layers.
void title (QString const &title)
 Every project has an associated title string.
QString const & title () const
 returns title
bool isDirty () const
 the dirty flag is true if the project has been modified since the last write()
void dirty (bool b)
void setFileName (QString const &name)
 Every project has an associated file that contains its XML.
QString fileName () const
 returns file name
bool read (QFileInfo const &file)
 read project file
bool read ()
bool write (QFileInfo const &file)
 write project file
bool write ()
bool writeEntry (QString const &scope, const QString &key, bool value)
bool writeEntry (QString const &scope, const QString &key, double value)
bool writeEntry (QString const &scope, const QString &key, int value)
bool writeEntry (QString const &scope, const QString &key, const QString &value)
bool writeEntry (QString const &scope, const QString &key, const QStringList &value)
QStringList readListEntry (QString const &scope, const QString &key, bool *ok=0) const
 key value accessors
QString readEntry (QString const &scope, const QString &key, const QString &def=QString::null, bool *ok=0) const
int readNumEntry (QString const &scope, const QString &key, int def=0, bool *ok=0) const
double readDoubleEntry (QString const &scope, const QString &key, double def=0, bool *ok=0) const
bool readBoolEntry (QString const &scope, const QString &key, bool def=false, bool *ok=0) const

Static Public Member Functions

static QgsProject * instance ()
 access to canonical QgsProject instance

Protected Member Functions

void setError (QString errorMessage)
 Set error message from read/write operation.
void clearError ()
 Clear error message.

Private Member Functions

 QgsProject ()
 QgsProject (QgsProject const &)
QPair< bool, QList< QDomNode > > _getMapLayers (QDomDocument const &doc)
 Read map layers from project file.

Private Attributes

std::auto_ptr< Imp > imp_
 implementation handle
QString mErrorMessage
QgsProjectBadLayerHandler * mBadLayerHandler

Static Private Attributes

static QgsProject * theProject_

Classes

struct  Imp

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 57 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 350 of file qgsproject.cpp.

References mBadLayerHandler.

QgsProject::QgsProject (  )  [private]

Definition at line 336 of file qgsproject.cpp.

References dirty(), and writeEntry().

QgsProject::QgsProject ( QgsProject const &   )  [private]

Member Function Documentation

QgsProject * QgsProject::instance (  )  [static]

access to canonical QgsProject instance

Definition at line 359 of file qgsproject.cpp.

Referenced by QgsGeometry::avoidIntersections(), QgsProject::Imp::clear(), QgsProjectBadLayerGuiHandler::findMissingFile(), QgsMapLayer::loadNamedStyle(), QgsMapCanvas::QgsMapCanvas(), QgsVectorLayer::readSymbology(), QgsSymbol::readXML(), QgsMapLayer::readXML(), QgsComposerPicture::readXML(), QgsSymbol::setNamedPointSymbol(), QgsMapCanvasSnapper::snapToBackgroundLayers(), QgsMapCanvasSnapper::snapToCurrentLayer(), QgsSvgMarkerSymbolLayerV2::symbolNameToPath(), QgsVectorLayer::writeSymbology(), QgsSymbol::writeXML(), QgsMapLayer::writeXML(), and QgsComposerPicture::writeXML().

void QgsProject::title ( QString const &  title  ) 

Every project has an associated title string.

Todo:
However current dialogs don't allow setting of it yet

Definition at line 372 of file qgsproject.cpp.

References dirty(), and imp_.

QString const & QgsProject::title (  )  const

returns title

Definition at line 380 of file qgsproject.cpp.

References imp_.

Referenced by write().

bool QgsProject::isDirty (  )  const

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

Definition at line 386 of file qgsproject.cpp.

References imp_.

void QgsProject::dirty ( bool  b  ) 

Definition at line 392 of file qgsproject.cpp.

References imp_.

Referenced by clearProperties(), QgsProject(), read(), removeEntry(), setFileName(), title(), write(), and writeEntry().

void QgsProject::setFileName ( QString const &  name  ) 

Every project has an associated file that contains its XML.

Definition at line 399 of file qgsproject.cpp.

References dirty(), and imp_.

QString QgsProject::fileName (  )  const

returns file name

Definition at line 408 of file qgsproject.cpp.

References imp_.

Referenced by readPath(), and writePath().

bool QgsProject::read ( QFileInfo const &  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

(Is that really desirable behavior? Maybe prompt to save before reading new one?)

Should we presume the file is opened elsewhere? Or do we open it ourselves?

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

Note:
  • Gets the extents
  • Creates maplayers
  • Registers maplayers

Note:
it's presumed that the caller has already reset the map canvas, map registry, and legend
Exceptions:
 

Definition at line 742 of file qgsproject.cpp.

References imp_, and read().

Referenced by QgsProjectBadLayerGuiHandler::findMissingFile().

bool QgsProject::read (  ) 

Shows a warning when an old project file is read.

Definition at line 754 of file qgsproject.cpp.

References _getMapLayers(), _getProperties(), _getTitle(), _getVersion(), clearError(), dirty(), dump_(), QgsProjectBadLayerHandler::handleBadLayers(), imp_, mBadLayerHandler, oldProjectVersionWarning(), QGis::QGIS_VERSION, QgsDebugMsg, readProject(), setError(), QgsProjectVersion::text(), and QgsLogger::warning().

Referenced by read().

bool QgsProject::read ( QDomNode &  layerNode  ) 

read the layer described in the associated Dom node

Parameters:
layerNode represents 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 878 of file qgsproject.cpp.

References QgsMapLayerRegistry::addMapLayer(), QgsPluginLayerRegistry::createLayer(), QgsMapLayerRegistry::instance(), QgsPluginLayerRegistry::instance(), QgsDebugMsg, and QgsMapLayer::readXML().

bool QgsProject::write ( QFileInfo const &  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 928 of file qgsproject.cpp.

References imp_, and write().

bool QgsProject::write (  ) 

Definition at line 936 of file qgsproject.cpp.

References clearError(), dirty(), dump_(), imp_, QgsMapLayerRegistry::instance(), QgsMapLayerRegistry::mapLayers(), QGis::QGIS_VERSION, QgsDebugMsg, setError(), title(), writeProject(), and QgsMapLayer::writeXML().

Referenced by write().

void QgsProject::clearProperties (  ) 

syntactic sugar for property lists

extra properties, typically added by plug-ins This allows for extra properties to be associated with projects. Think of it as a registry bound to a project.

Properties are arbitrary values keyed by a name and associated with a scope. The scope would presumably refer to your plug-in. E.g., "openmodeller".

Note:
E.g., open modeller might use:

"QgsProject::instance()->properties("openmodeller")["foo"].

Todo:
"properties" is, overall, a good name; but that might imply that the qgis specific state properites are different since they aren't accessible here. Actually, what if we make "qgis" yet another scope that stores its state in the properties list? E.g., QgsProject::instance()->properties()["qgis"]?
removes all project properties

Definition at line 1057 of file qgsproject.cpp.

References dirty(), and imp_.

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

Definition at line 1069 of file qgsproject.cpp.

References addKey_(), dirty(), and imp_.

Referenced by QgsProject::Imp::clear(), and QgsProject().

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

Definition at line 1078 of file qgsproject.cpp.

References addKey_(), dirty(), and imp_.

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

Definition at line 1088 of file qgsproject.cpp.

References addKey_(), dirty(), and imp_.

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

Definition at line 1097 of file qgsproject.cpp.

References addKey_(), dirty(), and imp_.

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

Definition at line 1107 of file qgsproject.cpp.

References addKey_(), dirty(), and imp_.

QStringList QgsProject::readListEntry ( QString const &  scope,
const QString &  key,
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 1119 of file qgsproject.cpp.

References findKey_(), and imp_.

Referenced by QgsGeometry::avoidIntersections(), and QgsMapCanvasSnapper::snapToBackgroundLayers().

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

Definition at line 1149 of file qgsproject.cpp.

References findKey_(), and imp_.

int QgsProject::readNumEntry ( QString const &  scope,
const QString &  key,
int  def = 0,
bool *  ok = 0 
) const

Definition at line 1180 of file qgsproject.cpp.

References findKey_(), and imp_.

Referenced by QgsMapCanvasSnapper::snapToBackgroundLayers(), and QgsMapCanvasSnapper::snapToCurrentLayer().

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

Definition at line 1209 of file qgsproject.cpp.

References findKey_(), and imp_.

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

Definition at line 1239 of file qgsproject.cpp.

References findKey_(), and imp_.

Referenced by readPath(), and writePath().

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

remove the given key

Definition at line 1267 of file qgsproject.cpp.

References dirty(), findKey_(), imp_, and removeKey_().

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

return keys with values -- do not return keys that contain other keys

Note:
equivalent to QSettings entryList()

Definition at line 1278 of file qgsproject.cpp.

References QgsPropertyKey::entryList(), findKey_(), and imp_.

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

return keys with keys -- do not return keys that contain only values

Note:
equivalent to QSettings subkeyList()

Definition at line 1297 of file qgsproject.cpp.

References findKey_(), imp_, and QgsPropertyKey::subkeyList().

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 1317 of file qgsproject.cpp.

References dump_(), and imp_.

QString QgsProject::writePath ( QString  filename  )  const

prepare a filename to save it to the project file

Note:
added in 1.3

Definition at line 1414 of file qgsproject.cpp.

References fileName(), and readBoolEntry().

Referenced by QgsMapLayer::writeXML().

QString QgsProject::readPath ( QString  filename  )  const

turn filename read from the project file to an absolute path

Note:
added in 1.3

Definition at line 1324 of file qgsproject.cpp.

References fileName(), and readBoolEntry().

Referenced by QgsVectorLayer::readSymbology(), QgsMapLayer::readXML(), and QgsComposerPicture::readXML().

QString QgsProject::error (  )  const

Return error message from previous read/write.

Note:
added in 1.4

Definition at line 1494 of file qgsproject.cpp.

References mErrorMessage.

void QgsProject::setBadLayerHandler ( QgsProjectBadLayerHandler *  handler  ) 

Change handler for missing layers.

Deletes old handler and takes ownership of the new one.

Note:
added in 1.4

Definition at line 1504 of file qgsproject.cpp.

References mBadLayerHandler.

void QgsProject::setError ( QString  errorMessage  )  [protected]

Set error message from read/write operation.

Note:
added in 1.4

Definition at line 1489 of file qgsproject.cpp.

References mErrorMessage.

Referenced by clearError(), read(), and write().

void QgsProject::clearError (  )  [protected]

Clear error message.

Note:
added in 1.4

Definition at line 1499 of file qgsproject.cpp.

References setError().

Referenced by read(), and write().

void QgsProject::readProject ( const QDomDocument &   )  [signal]

emitted when project is being read

Referenced by read().

void QgsProject::writeProject ( QDomDocument &   )  [signal]

emitted when project is being written

Referenced by write().

void QgsProject::oldProjectVersionWarning ( QString   )  [signal]

emitted when an old project file is read.

Referenced by read().

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

emitted when a layer from a projects was read

Referenced by _getMapLayers().

QPair< bool, QList< QDomNode > > QgsProject::_getMapLayers ( QDomDocument const &  doc  )  [private]

Read map layers from project file.

Returns:
 QPair< bool, QList<QDomNode> >
bool is true if function worked; else is false. list contains nodes corresponding to layers that couldn't be loaded
Note:
XML of form:
   <maplayer type="vector">
      <layername>Hydrop</layername>
      <datasource>/data/usgs/city_shp/hydrop.shp</datasource>
      <zorder>0</zorder>
      <provider>ogr</provider>
      <singlesymbol>
         <renderitem>
            <value>blabla</value>
            <symbol>
               <outlinecolor red="85" green="0" blue="255" />
               <outlinestyle>SolidLine</outlinestyle>
               <outlinewidth>1</outlinewidth>
               <fillcolor red="0" green="170" blue="255" />
               <fillpattern>SolidPattern</fillpattern>
            </symbol>
            <label>blabla</label>
         </renderitem>
      </singlesymbol>
      <label>0</label>
      <labelattributes>
         <label text="Label" field="" />
         <family name="Sans Serif" field="" />
         <size value="12" units="pt" field="" />
         <bold on="0" field="" />
         <italic on="0" field="" />
         <underline on="0" field="" />
         <color red="0" green="0" blue="0" field="" />
         <x field="" />
         <y field="" />
         <offset  units="pt" x="0" xfield="" y="0" yfield="" />
         <angle value="0" field="" />
         <alignment value="center" field="" />
      </labelattributes>
   </maplayer>

Definition at line 647 of file qgsproject.cpp.

References QgsMapLayerRegistry::addMapLayer(), QgsPluginLayerRegistry::createLayer(), QgsMapLayerRegistry::instance(), QgsPluginLayerRegistry::instance(), layerLoaded(), QgsDebugMsg, and QgsMapLayer::readXML().

Referenced by read().

Member Data Documentation

std::auto_ptr<Imp> QgsProject::imp_ [private]

implementation handle

Definition at line 311 of file qgsproject.h.

Referenced by clearProperties(), dirty(), dumpProperties(), entryList(), fileName(), isDirty(), read(), readBoolEntry(), readDoubleEntry(), readEntry(), readListEntry(), readNumEntry(), removeEntry(), setFileName(), subkeyList(), title(), write(), and writeEntry().

QgsProject * QgsProject::theProject_ [static, private]

Definition at line 316 of file qgsproject.h.

QString QgsProject::mErrorMessage [private]

Definition at line 320 of file qgsproject.h.

Referenced by error(), and setError().

QgsProjectBadLayerHandler* QgsProject::mBadLayerHandler [private]

Definition at line 322 of file qgsproject.h.

Referenced by read(), setBadLayerHandler(), and ~QgsProject().

The documentation for this class was generated from the following files:
Generated on Sat Feb 4 19:17:44 2012 for Quantum GIS API Documentation by  doxygen 1.5.6