mirror of
https://github.com/qgis/QGIS.git
synced 2025-02-25 00:58:06 -05:00
dfdcec8922
ton of available area units (eg m2, km2, mi2, ft2, yd2, ha, ac, etc) Adds a new option in both the QGIS setting and project properties to set the units used for area measurements. Just like the distance setting, this defaults to the units set in QGIS options, but can then be overridden for specific projects. The setting is respected for area calculations in: - Attribute table field update bar - Field calculator calculations - Identify tool derived length and perimeter values Also adds unit tests to ensure that area calculated by attribute table update bar, field calculator and identify tool are consistent wrt ellipsoidal calculations and area units. TODO: make measure tool respect area setting (refs #13209, #4252 and fixes #12939, #2402, #4857)
379 lines
12 KiB
Plaintext
379 lines
12 KiB
Plaintext
|
|
/** \ingroup core
|
|
* 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.
|
|
|
|
*/
|
|
class QgsProject : QObject
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgsproject.h>
|
|
%End
|
|
|
|
public:
|
|
|
|
/**
|
|
* @todo XXX Should have semantics for saving project if dirty as last gasp?
|
|
*/
|
|
~QgsProject();
|
|
|
|
/// access to canonical QgsProject instance
|
|
static QgsProject * instance();
|
|
|
|
/**
|
|
* Every project has an associated title string
|
|
*
|
|
* @deprecated Use setTitle instead.
|
|
*/
|
|
//@{
|
|
void title( const QString & title ) /Deprecated/;
|
|
|
|
/** Set project title
|
|
* @note added in 2.4
|
|
*/
|
|
void setTitle( const QString& title );
|
|
|
|
/** Returns title */
|
|
QString title() const;
|
|
//@}
|
|
|
|
/**
|
|
* the dirty flag is true if the project has been modified since the last
|
|
* write()
|
|
*/
|
|
//@{
|
|
bool isDirty() const;
|
|
|
|
// ### QGIS 3: remove in favor of setDirty(...)
|
|
void dirty( bool b );
|
|
|
|
/** Set project as dirty (modified).
|
|
* @note added in 2.4 */
|
|
void setDirty( bool b );
|
|
//@}
|
|
|
|
|
|
/**
|
|
* Every project has an associated file that contains its XML
|
|
*/
|
|
//@{
|
|
void setFileName( const QString & name );
|
|
|
|
/** Returns file name */
|
|
QString fileName() const;
|
|
//@}
|
|
|
|
/** Returns QFileInfo object for the project's associated file.
|
|
* @note added in QGIS 2.9
|
|
*/
|
|
QFileInfo fileInfo() const;
|
|
|
|
/** Clear the project
|
|
* @note added in 2.4
|
|
*/
|
|
void clear();
|
|
|
|
|
|
/** Read project file
|
|
*
|
|
* @note Any current plug-in state is erased
|
|
*
|
|
* @note dirty set to false after successful invocation
|
|
*
|
|
* @note file name argument implicitly sets file
|
|
*
|
|
* @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
|
|
*/
|
|
//@{
|
|
bool read( const QFileInfo & file );
|
|
bool read();
|
|
//@}
|
|
|
|
|
|
/** Read the layer described in the associated Dom node
|
|
*
|
|
* @param 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.
|
|
*
|
|
*/
|
|
bool read( QDomNode & layerNode );
|
|
|
|
|
|
/** 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
|
|
*
|
|
* @note dirty set to false after successful invocation
|
|
*/
|
|
//@{
|
|
bool write( const QFileInfo & file );
|
|
bool write();
|
|
//@}
|
|
|
|
/**
|
|
* removes all project properties
|
|
*
|
|
* ### QGIS 3: remove in favor of clear()
|
|
*/
|
|
void clearProperties();
|
|
|
|
|
|
/* key value mutators
|
|
*
|
|
* keys would be the familiar QSettings-like '/' delimited entries, implying
|
|
* a hierarchy of keys and corresponding values
|
|
*
|
|
* @note The key string must be valid xml tag names in order to be saved to the file.
|
|
*/
|
|
//@{
|
|
//! @note available in python bindings as writeEntryBool
|
|
bool writeEntry( const QString & scope, const QString & key, bool value ) /PyName=writeEntryBool/;
|
|
//! @note available in python bindings as writeEntryDouble
|
|
bool writeEntry( const QString & scope, const QString & key, double value ) /PyName=writeEntryDouble/;
|
|
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 );
|
|
//@}
|
|
|
|
/** Key value accessors
|
|
*
|
|
* keys would be the familiar QSettings-like '/' delimited entries,
|
|
* implying a hierarchy of keys and corresponding values
|
|
*
|
|
*/
|
|
//@{
|
|
QStringList readListEntry( const QString & scope, const QString & key, const QStringList& def = QStringList(), bool *ok = 0 ) const;
|
|
|
|
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;
|
|
//@}
|
|
|
|
|
|
/** Remove the given key */
|
|
bool removeEntry( const QString & scope, const QString & key );
|
|
|
|
|
|
/** Return keys with values -- do not return keys that contain other keys
|
|
*
|
|
* @note equivalent to QSettings entryList()
|
|
*/
|
|
QStringList entryList( const QString & scope, const QString & key ) const;
|
|
|
|
/** Return keys with keys -- do not return keys that contain only values
|
|
*
|
|
* @note equivalent to QSettings subkeyList()
|
|
*/
|
|
QStringList subkeyList( const QString & scope, const QString & key ) 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.
|
|
*/
|
|
void dumpProperties() const;
|
|
|
|
/** Prepare a filename to save it to the project file */
|
|
QString writePath( const QString& filename, const QString& relativeBasePath = QString::null ) const;
|
|
|
|
/** Turn filename read from the project file to an absolute path */
|
|
QString readPath( QString filename ) const;
|
|
|
|
/** Return error message from previous read/write */
|
|
QString error() const;
|
|
|
|
/** Change handler for missing layers.
|
|
* Deletes old handler and takes ownership of the new one.
|
|
*/
|
|
void setBadLayerHandler( QgsProjectBadLayerHandler* handler /Transfer/ );
|
|
|
|
/** Returns project file path if layer is embedded from other project file. Returns empty string if layer is not embedded*/
|
|
QString layerIsEmbedded( const QString& id ) const;
|
|
|
|
/** Creates a maplayer instance defined in an arbitrary project file. Caller takes ownership
|
|
* @return the layer or 0 in case of error
|
|
* @note not available in Python bindings
|
|
*/
|
|
/*
|
|
bool createEmbeddedLayer( const QString& layerId, const QString& projectFilePath, QList<QDomNode>& brokenNodes,
|
|
QList< QPair< QgsVectorLayer*, QDomElement > >& vectorLayerList, bool saveFlag = true );
|
|
*/
|
|
|
|
/** Create layer group instance defined in an arbitrary project file.
|
|
* @note: added in version 2.4
|
|
*/
|
|
QgsLayerTreeGroup* createEmbeddedGroup( const QString& groupName, const QString& projectFilePath, const QStringList &invisibleLayers );
|
|
|
|
/** Convenience function to set snap settings per layer */
|
|
void setSnapSettingsForLayer( const QString& layerId, bool enabled, QgsSnapper::SnappingType type, QgsTolerance::UnitType unit, double tolerance,
|
|
bool avoidIntersection );
|
|
|
|
/** Convenience function to query snap settings of a layer */
|
|
bool snapSettingsForLayer( const QString& layerId, bool& enabled /Out/, QgsSnapper::SnappingType& type /Out/, QgsTolerance::UnitType& units /Out/, double& tolerance /Out/,
|
|
bool& avoidIntersection /Out/ ) const;
|
|
|
|
/** Convenience function to set topological editing */
|
|
void setTopologicalEditing( bool enabled );
|
|
|
|
/** Convenience function to query topological editing status */
|
|
bool topologicalEditing() const;
|
|
|
|
/** Convenience function to query default distance measurement units for project.
|
|
* @note added in QGIS 2.14
|
|
* @see areaUnits()
|
|
*/
|
|
QGis::UnitType distanceUnits() const;
|
|
|
|
/** Convenience function to query default area measurement units for project.
|
|
* @note added in QGIS 2.14
|
|
* @see distanceUnits()
|
|
*/
|
|
QgsUnitTypes::AreaUnit areaUnits() const;
|
|
|
|
/** Return project's home path
|
|
@return home path of project (or QString::null if not set) */
|
|
QString homePath() const;
|
|
|
|
QgsRelationManager* relationManager() const;
|
|
|
|
/** Return pointer to the root (invisible) node of the project's layer tree
|
|
* @note added in 2.4
|
|
*/
|
|
QgsLayerTreeGroup* layerTreeRoot() const;
|
|
|
|
/** Return pointer to the helper class that synchronizes map layer registry with layer tree
|
|
* @note added in 2.4
|
|
*/
|
|
QgsLayerTreeRegistryBridge* layerTreeRegistryBridge() const;
|
|
|
|
/** Returns pointer to the project's visibility preset collection.
|
|
* @note added in QGIS 2.12
|
|
*/
|
|
QgsVisibilityPresetCollection* visibilityPresetCollection();
|
|
|
|
protected:
|
|
|
|
/** Set error message from read/write operation
|
|
* @note not available in Python bindings
|
|
*/
|
|
//void setError( const QString& errorMessage );
|
|
|
|
/** Clear error message
|
|
* @note not available in Python bindings
|
|
*/
|
|
//void clearError();
|
|
|
|
//! Creates layer and adds it to maplayer registry
|
|
//! @note not available in python bindings
|
|
// bool addLayer( const QDomElement& layerElem, QList<QDomNode>& brokenNodes, QList< QPair< QgsVectorLayer*, QDomElement > >& vectorLayerList );
|
|
|
|
//! @note not available in python bindings
|
|
// void initializeEmbeddedSubtree( const QString& projectFilePath, QgsLayerTreeGroup* group );
|
|
|
|
//! @note not available in python bindings
|
|
// void loadEmbeddedNodes( QgsLayerTreeGroup* group );
|
|
|
|
signals:
|
|
//! emitted when project is being read
|
|
void readProject( const QDomDocument & );
|
|
|
|
//! emitted when project is being written
|
|
void writeProject( QDomDocument & );
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param mapLayer The map layer which is being initialized
|
|
* @param layerNode The layer node from the project file
|
|
*/
|
|
void readMapLayer( QgsMapLayer *mapLayer, const QDomElement &layerNode );
|
|
|
|
/**
|
|
* Emitted, when a layer is being saved. You can use this method to save
|
|
* additional information to the layer.
|
|
*
|
|
* @param mapLayer The map layer which is being initialized
|
|
* @param layerElem The layer element from the project file
|
|
* @param doc The document
|
|
*/
|
|
void writeMapLayer( QgsMapLayer *mapLayer, QDomElement &layerElem, QDomDocument &doc );
|
|
|
|
//! emitted when the project file has been written and closed
|
|
void projectSaved();
|
|
|
|
//! emitted when an old project file is read.
|
|
void oldProjectVersionWarning( const QString& );
|
|
|
|
//! emitted when a layer from a projects was read
|
|
// @param i current layer
|
|
// @param n number of layers
|
|
void layerLoaded( int i, int n );
|
|
|
|
void loadingLayer( const QString& );
|
|
|
|
void snapSettingsChanged();
|
|
|
|
private:
|
|
|
|
QgsProject(); // private 'cause it's a singleton
|
|
|
|
}; // QgsProject
|
|
|
|
|
|
/** Interface for classes that handle missing layer files when reading project file. */
|
|
class QgsProjectBadLayerHandler
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgsproject.h>
|
|
%End
|
|
|
|
public:
|
|
virtual void handleBadLayers( const QList<QDomNode>& layers, const QDomDocument& projectDom ) = 0;
|
|
virtual ~QgsProjectBadLayerHandler();
|
|
};
|
|
|
|
|
|
/** Default bad layer handler which ignores any missing layers. */
|
|
class QgsProjectBadLayerDefaultHandler : QgsProjectBadLayerHandler
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgsproject.h>
|
|
%End
|
|
|
|
public:
|
|
virtual void handleBadLayers( const QList<QDomNode>& layers, const QDomDocument& projectDom );
|
|
|
|
};
|