Reads and writes project states. More...

#include <qgsproject.h>

Classes
struct	Imp

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

Public Member Functions
	~QgsProject ()
void	clear ()
	Clear the project.
void	clearProperties ()
	removes all project properties
QgsLayerTreeGroup *	createEmbeddedGroup (const QString &groupName, const QString &projectFilePath, const QStringList &invisibleLayers)
	Create layer group instance defined in an arbitrary project file.
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.
void	dumpProperties () const
	dump out current project properties to stderr
QStringList	entryList (const QString &scope, const QString &key) const
	return keys with values – do not return keys that contain other keys
QString	error () const
	Return error message from previous read/write.
QString	homePath () const
	Return project's home path.
QString	layerIsEmbedded (const QString &id) const
	Returns project file path if layer is embedded from other project file.
QgsLayerTreeRegistryBridge *	layerTreeRegistryBridge () const
	Return pointer to the helper class that synchronizes map layer registry with layer tree.
QgsLayerTreeGroup *	layerTreeRoot () const
	Return pointer to the root (invisible) node of the project's layer tree.
bool	read (QDomNode &layerNode)
	read the layer described in the associated Dom node
QString	readPath (QString filename) const
	turn filename read from the project file to an absolute path
QgsRelationManager *	relationManager () const
bool	removeEntry (const QString &scope, const QString &key)
	remove the given key
void	setBadLayerHandler (QgsProjectBadLayerHandler *handler)
	Change handler for missing layers.
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.
void	setTopologicalEditing (bool enabled)
	Convenience function to set topological editing.
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.
QStringList	subkeyList (const QString &scope, const QString &key) const
	return keys with keys – do not return keys that contain only values
bool	topologicalEditing () const
	Convenience function to query topological editing status.
QString	writePath (QString filename, QString relativeBasePath=QString::null) const
	prepare a filename to save it to the project file

void	title (const QString &title)
	Every project has an associated title string.
void	setTitle (const QString &title)
	Set project title.
const QString &	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	setDirty (bool b)
	Set project as dirty (modified).

void	setFileName (const QString &name)
	Every project has an associated file that contains its XML.
QString	fileName () const
	returns file name

bool	read (const QFileInfo &file)
	read project file
bool	read ()
	presuming that the caller has already reset the map canvas, map registry, and legend

bool	write (const QFileInfo &file)
	write project file
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
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

Static Public Member Functions
static QgsProject *	instance ()
	access to canonical QgsProject instance

Protected Member Functions
bool	addLayer (const QDomElement &layerElem, QList< QDomNode > &brokenNodes, QList< QPair< QgsVectorLayer *, QDomElement > > &vectorLayerList)
void	clearError ()
	Clear error message.
void	initializeEmbeddedSubtree (const QString &projectFilePath, QgsLayerTreeGroup *group)
void	loadEmbeddedNodes (QgsLayerTreeGroup *group)
void	setError (QString errorMessage)
	Set error message from read/write operation.

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 67 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 340 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 698 of file qgsproject.cpp.

void QgsProject::clear ( )

Clear the project.

Note: added in 2.4

Definition at line 411 of file qgsproject.cpp.

void QgsProject::clearError ( )

protected

Clear error message.

Definition at line 1577 of file qgsproject.cpp.

void QgsProject::clearProperties ( )

removes all project properties

QGIS 3: remove in favor of clear()

Definition at line 1125 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 1706 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 1598 of file qgsproject.cpp.

void QgsProject::dirty ( bool b )

Definition at line 385 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 1357 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 1319 of file qgsproject.cpp.

QString QgsProject::error ( ) const

Return error message from previous read/write.

Definition at line 1572 of file qgsproject.cpp.

QString QgsProject::fileName ( ) const

returns file name

Definition at line 406 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 1951 of file qgsproject.cpp.

void QgsProject::initializeEmbeddedSubtree	(	const QString &	projectFilePath,
		QgsLayerTreeGroup *	group
	)

protected

Note: not available in python bindings

Definition at line 1786 of file qgsproject.cpp.

QgsProject * QgsProject::instance ( )

static

access to canonical QgsProject instance

Definition at line 351 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 379 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 1588 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 302 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 1965 of file qgsproject.cpp.

void QgsProject::loadEmbeddedNodes ( QgsLayerTreeGroup * group )

protected

Note: not available in python bindings

Definition at line 909 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 757 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 769 of file qgsproject.cpp.

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

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

Definition at line 1287 of file qgsproject.cpp.

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

Definition at line 1265 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 1210 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 1182 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

mapLayer	The map layer which is being initialized
layerNode	The 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 1236 of file qgsproject.cpp.

QString QgsProject::readPath ( QString filename ) const

turn filename read from the project file to an absolute path

Definition at line 1364 of file qgsproject.cpp.

void QgsProject::readProject ( const QDomDocument & )

signal

emitted when project is being read

QgsRelationManager * QgsProject::relationManager ( ) const

Definition at line 1960 of file qgsproject.cpp.

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

remove the given key

Definition at line 1308 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 1582 of file qgsproject.cpp.

void QgsProject::setDirty ( bool b )

Set project as dirty (modified).

Note: added in 2.4

Definition at line 390 of file qgsproject.cpp.

void QgsProject::setError ( QString errorMessage )

protected

Set error message from read/write operation.

Definition at line 1567 of file qgsproject.cpp.

void QgsProject::setFileName ( const QString & name )

Every project has an associated file that contains its XML.

Definition at line 397 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 1807 of file qgsproject.cpp.

void QgsProject::setTitle ( const QString & title )

Set project title.

Note: added in 2.4

Definition at line 367 of file qgsproject.cpp.

void QgsProject::setTopologicalEditing ( bool enabled )

Convenience function to set topological editing.

Definition at line 1935 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 1864 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 1337 of file qgsproject.cpp.

void QgsProject::title ( const QString & title )

Every project has an associated title string.

QGIS 3: remove in favor of setTitle(...)

Definition at line 360 of file qgsproject.cpp.

QString const & QgsProject::title ( ) const

returns title

Definition at line 373 of file qgsproject.cpp.

bool QgsProject::topologicalEditing ( ) const

Convenience function to query topological editing status.

Definition at line 1941 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 961 of file qgsproject.cpp.

bool QgsProject::write ( )

Definition at line 969 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 1135 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 1144 of file qgsproject.cpp.

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

Definition at line 1154 of file qgsproject.cpp.

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

Definition at line 1163 of file qgsproject.cpp.

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

Definition at line 1173 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

mapLayer	The map layer which is being initialized
layerElem	The layer element from the project file
doc	The document

QString QgsProject::writePath	(	QString	filename,
		QString	relativeBasePath = `QString::null`
	)		const

prepare a filename to save it to the project file

Definition at line 1473 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:

/tmp/buildd/qgis-2.8.2+12wheezy/src/core/qgsproject.h
/tmp/buildd/qgis-2.8.2+12wheezy/src/core/qgsproject.cpp

Classes

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

QGIS 3: remove in favor of clear()

QGIS 3: remove in favor of setTitle(...)