QGIS API Documentation  3.4.15-Madeira (e83d02e274)
qgsproject.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsproject.h
3 
4  Implements persistent project state.
5 
6  -------------------
7  begin : July 23, 2004
8  copyright : (C) 2004 by Mark Coletti
9  email : mcoletti at gmail.com
10  ***************************************************************************/
11 
12 /***************************************************************************
13  * *
14  * This program is free software; you can redistribute it and/or modify *
15  * it under the terms of the GNU General Public License as published by *
16  * the Free Software Foundation; either version 2 of the License, or *
17  * (at your option) any later version. *
18  * *
19  ***************************************************************************/
20 
21 #ifndef QGSPROJECT_H
22 #define QGSPROJECT_H
23 
24 #include "qgis_core.h"
25 #include "qgis_sip.h"
26 #include "qgis.h"
27 #include <memory>
28 #include <QHash>
29 #include <QList>
30 #include <QObject>
31 #include <QPair>
32 #include <QFileInfo>
33 #include <QStringList>
34 #include <QTranslator>
35 
36 #include "qgsunittypes.h"
37 #include "qgssnappingconfig.h"
38 #include "qgsprojectversion.h"
42 #include "qgsprojectproperty.h"
43 #include "qgsmaplayerstore.h"
44 #include "qgsarchive.h"
45 #include "qgsreadwritecontext.h"
46 #include "qgsprojectmetadata.h"
47 #include "qgstranslationcontext.h"
48 #include "qgsprojecttranslator.h"
50 
51 class QFileInfo;
52 class QDomDocument;
53 class QDomElement;
54 class QDomNode;
55 
56 class QgsLayerTreeGroup;
58 class QgsMapLayer;
60 class QgsPathResolver;
62 class QgsProjectStorage;
63 class QgsRelationManager;
64 class QgsTolerance;
66 class QgsVectorLayer;
68 class QgsLayoutManager;
69 class QgsLayerTree;
72 class QgsMapLayer;
73 
89 class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenerator, public QgsProjectTranslator
90 {
91  Q_OBJECT
92  Q_PROPERTY( QStringList nonIdentifiableLayers READ nonIdentifiableLayers WRITE setNonIdentifiableLayers NOTIFY nonIdentifiableLayersChanged )
93  Q_PROPERTY( QString fileName READ fileName WRITE setFileName NOTIFY fileNameChanged )
94  Q_PROPERTY( QString homePath READ homePath WRITE setPresetHomePath NOTIFY homePathChanged )
95  Q_PROPERTY( QgsCoordinateReferenceSystem crs READ crs WRITE setCrs NOTIFY crsChanged )
96  Q_PROPERTY( QgsCoordinateTransformContext transformContext READ transformContext WRITE setTransformContext NOTIFY transformContextChanged )
97  Q_PROPERTY( QString ellipsoid READ ellipsoid WRITE setEllipsoid NOTIFY ellipsoidChanged )
98  Q_PROPERTY( QgsMapThemeCollection *mapThemeCollection READ mapThemeCollection NOTIFY mapThemeCollectionChanged )
99  Q_PROPERTY( QgsSnappingConfig snappingConfig READ snappingConfig WRITE setSnappingConfig NOTIFY snappingConfigChanged )
100  Q_PROPERTY( QgsRelationManager *relationManager READ relationManager )
101  Q_PROPERTY( QList<QgsVectorLayer *> avoidIntersectionsLayers READ avoidIntersectionsLayers WRITE setAvoidIntersectionsLayers NOTIFY avoidIntersectionsLayersChanged )
102  Q_PROPERTY( QgsProjectMetadata metadata READ metadata WRITE setMetadata NOTIFY metadataChanged )
103 
104  public:
106  static QgsProject *instance();
107 
113  explicit QgsProject( QObject *parent SIP_TRANSFERTHIS = nullptr );
114 
115  ~QgsProject() override;
116 
126  void setTitle( const QString &title );
127 
134  QString title() const;
135 
139  bool isDirty() const;
140 
147  void setFileName( const QString &name );
148 
155  QString fileName() const;
156 
168  Q_DECL_DEPRECATED QFileInfo fileInfo() const SIP_DEPRECATED;
169 
176  QgsProjectStorage *projectStorage() const;
177 
182  QDateTime lastModified() const;
183 
189  QString absoluteFilePath() const;
190 
196  QString absolutePath() const;
197 
202  QString baseName() const;
203 
211 
218  void setCrs( const QgsCoordinateReferenceSystem &crs );
219 
226  QString ellipsoid() const;
227 
234  void setEllipsoid( const QString &ellipsoid );
235 
236 
246  QgsCoordinateTransformContext transformContext() const;
247 
257  void setTransformContext( const QgsCoordinateTransformContext &context );
258 
264  void clear();
265 
271  bool read( const QString &filename );
272 
277  bool read();
278 
288  bool readLayer( const QDomNode &layerNode );
289 
298  bool write( const QString &filename );
299 
305  bool write();
306 
316  bool writeEntry( const QString &scope, const QString &key, bool value ) SIP_PYNAME( writeEntryBool );
317 
327  bool writeEntry( const QString &scope, const QString &key, double value ) SIP_PYNAME( writeEntryDouble );
328 
337  bool writeEntry( const QString &scope, const QString &key, int value );
338 
347  bool writeEntry( const QString &scope, const QString &key, const QString &value );
348 
357  bool writeEntry( const QString &scope, const QString &key, const QStringList &value );
358 
365  QStringList readListEntry( const QString &scope, const QString &key, const QStringList &def = QStringList(), bool *ok = nullptr ) const;
366 
367  QString readEntry( const QString &scope, const QString &key, const QString &def = QString(), bool *ok = nullptr ) const;
368  int readNumEntry( const QString &scope, const QString &key, int def = 0, bool *ok = nullptr ) const;
369  double readDoubleEntry( const QString &scope, const QString &key, double def = 0, bool *ok = nullptr ) const;
370  bool readBoolEntry( const QString &scope, const QString &key, bool def = false, bool *ok = nullptr ) const;
371 
372 
374  bool removeEntry( const QString &scope, const QString &key );
375 
376 
382  QStringList entryList( const QString &scope, const QString &key ) const;
383 
389  QStringList subkeyList( const QString &scope, const QString &key ) const;
390 
391 
395  // TODO Now slightly broken since re-factoring. Won't print out top-level key
396  // and redundantly prints sub-keys.
397  void dumpProperties() const;
398 
404  QgsPathResolver pathResolver() const;
405 
411  QString writePath( const QString &filename ) const;
412 
414  QString readPath( const QString &filename ) const;
415 
417  QString error() const;
418 
423  void setBadLayerHandler( QgsProjectBadLayerHandler *handler SIP_TRANSFER );
424 
426  QString layerIsEmbedded( const QString &id ) const;
427 
433  bool createEmbeddedLayer( const QString &layerId, const QString &projectFilePath, QList<QDomNode> &brokenNodes,
434  bool saveFlag = true ) SIP_SKIP;
435 
440  QgsLayerTreeGroup *createEmbeddedGroup( const QString &groupName, const QString &projectFilePath, const QStringList &invisibleLayers );
441 
443  void setTopologicalEditing( bool enabled );
444 
446  bool topologicalEditing() const;
447 
454  QgsUnitTypes::DistanceUnit distanceUnits() const;
455 
462  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
463 
469  QgsUnitTypes::AreaUnit areaUnits() const;
470 
477  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
478 
491  QString homePath() const;
492 
505  QString presetHomePath() const;
506 
507  QgsRelationManager *relationManager() const;
508 
515  const QgsLayoutManager *layoutManager() const SIP_SKIP;
516 
522  QgsLayoutManager *layoutManager();
523 
528  QgsLayerTree *layerTreeRoot() const;
529 
534  QgsLayerTreeRegistryBridge *layerTreeRegistryBridge() const { return mLayerTreeRegistryBridge; }
535 
541  QgsMapThemeCollection *mapThemeCollection();
542 
547  QgsAnnotationManager *annotationManager();
548 
553  const QgsAnnotationManager *annotationManager() const SIP_SKIP;
554 
559  Q_DECL_DEPRECATED void setNonIdentifiableLayers( const QList<QgsMapLayer *> &layers );
560 
565  Q_DECL_DEPRECATED void setNonIdentifiableLayers( const QStringList &layerIds );
566 
571  Q_DECL_DEPRECATED QStringList nonIdentifiableLayers() const;
572 
580  bool autoTransaction() const;
581 
591  void setAutoTransaction( bool autoTransaction );
592 
601  QMap< QPair< QString, QString>, QgsTransactionGroup *> transactionGroups() SIP_SKIP;
602 
610  QgsTransactionGroup *transactionGroup( const QString &providerKey, const QString &connString );
611 
617  bool evaluateDefaultValues() const;
618 
624  void setEvaluateDefaultValues( bool evaluateDefaultValues );
625 
627 
633  QgsSnappingConfig snappingConfig() const;
634 
640  QList<QgsVectorLayer *> avoidIntersectionsLayers() const;
641 
647  void setAvoidIntersectionsLayers( const QList<QgsVectorLayer *> &layers );
648 
654  QVariantMap customVariables() const;
655 
660  void setCustomVariables( const QVariantMap &customVariables );
661 
666  void setLabelingEngineSettings( const QgsLabelingEngineSettings &settings );
667 
672  const QgsLabelingEngineSettings &labelingEngineSettings() const;
673 
674  //
675  // Functionality from QgsMapLayerRegistry
676  //
677 
682  QgsMapLayerStore *layerStore();
683 
688  SIP_SKIP const QgsMapLayerStore *layerStore() const;
689 
691  int count() const;
692 
700  QgsMapLayer *mapLayer( const QString &layerId ) const;
701 
709  QList<QgsMapLayer *> mapLayersByName( const QString &layerName ) const;
710 
717  QMap<QString, QgsMapLayer *> mapLayers() const;
718 
722  bool isZipped() const;
723 
724 #ifndef SIP_RUN
725 
737  template <typename T>
738  QVector<T> layers() const
739  {
740  return mLayerStore->layers<T>();
741  }
742 #endif
743 
769  QList<QgsMapLayer *> addMapLayers( const QList<QgsMapLayer *> &mapLayers SIP_TRANSFER,
770  bool addToLegend = true,
771  bool takeOwnership SIP_PYARGREMOVE = true );
772 
800  QgsMapLayer *addMapLayer( QgsMapLayer *mapLayer SIP_TRANSFER,
801  bool addToLegend = true,
802  bool takeOwnership SIP_PYARGREMOVE = true );
803 
818  void removeMapLayers( const QStringList &layerIds );
819 
833  //TODO QGIS 3.0 - add PyName alias to avoid list type conversion error
834  void removeMapLayers( const QList<QgsMapLayer *> &layers );
835 
849  void removeMapLayer( const QString &layerId );
850 
864  void removeMapLayer( QgsMapLayer *layer );
865 
873  QgsMapLayer *takeMapLayer( QgsMapLayer *layer ) SIP_TRANSFERBACK;
874 
885  void removeAllMapLayers();
886 
892  void reloadAllLayers();
893 
898  QgsCoordinateReferenceSystem defaultCrsForNewLayers() const;
899 
911  void setTrustLayerMetadata( bool trust );
912 
923  bool trustLayerMetadata() const { return mTrustLayerMetadata; }
924 
930  const QgsAuxiliaryStorage *auxiliaryStorage() const SIP_SKIP;
931 
937  QgsAuxiliaryStorage *auxiliaryStorage();
938 
945  const QgsProjectMetadata &metadata() const;
946 
953  void setMetadata( const QgsProjectMetadata &metadata );
954 
963  Q_DECL_DEPRECATED QSet<QgsMapLayer *> requiredLayers() const;
964 
973  Q_DECL_DEPRECATED void setRequiredLayers( const QSet<QgsMapLayer *> &layers );
974 
979  void generateTsFile( const QString &locale );
980 
991  QString translate( const QString &context, const QString &sourceText, const char *disambiguation = nullptr, int n = -1 ) const override;
992 
993  signals:
994 
1002  void cleared();
1003 
1007  void readProject( const QDomDocument & );
1008 
1012  void readProjectWithContext( const QDomDocument &, QgsReadWriteContext &context );
1013 
1017  void writeProject( QDomDocument & );
1018 
1027  void readMapLayer( QgsMapLayer *mapLayer, const QDomElement &layerNode );
1028 
1037  void writeMapLayer( QgsMapLayer *mapLayer, QDomElement &layerElem, QDomDocument &doc );
1038 
1042  void projectSaved();
1043 
1047  void oldProjectVersionWarning( const QString & );
1048 
1054  void layerLoaded( int i, int n );
1055 
1057  void loadingLayer( const QString &layerName );
1058 
1065  void loadingLayerMessageReceived( const QString &layerName, const QList<QgsReadWriteContext::ReadWriteMessage> &messages );
1066 
1071  Q_DECL_DEPRECATED void nonIdentifiableLayersChanged( QStringList nonIdentifiableLayers );
1072 
1074  void fileNameChanged();
1075 
1082  void homePathChanged();
1083 
1087  void snappingConfigChanged( const QgsSnappingConfig &config );
1088 
1093  void customVariablesChanged();
1094 
1100  void crsChanged();
1101 
1109  void ellipsoidChanged( const QString &ellipsoid );
1110 
1111 
1118  void transformContextChanged();
1119 
1124  void missingDatumTransforms( const QStringList &missingTransforms );
1125 
1132  void transactionGroupsChanged();
1133 
1139  void topologicalEditingChanged();
1140 
1146  void avoidIntersectionsLayersChanged();
1147 
1159  void mapThemeCollectionChanged();
1160 
1165  void labelingEngineSettingsChanged();
1166 
1173  void metadataChanged();
1174 
1175  //
1176  // signals from QgsMapLayerRegistry
1177  //
1178 
1186  void layersWillBeRemoved( const QStringList &layerIds );
1187 
1195  void layersWillBeRemoved( const QList<QgsMapLayer *> &layers );
1196 
1206  void layerWillBeRemoved( const QString &layerId );
1207 
1217  void layerWillBeRemoved( QgsMapLayer *layer );
1218 
1225  void layersRemoved( const QStringList &layerIds );
1226 
1235  void layerRemoved( const QString &layerId );
1236 
1243  //TODO QGIS 3.0 - rename to past tense
1244  void removeAll();
1245 
1256  void layersAdded( const QList<QgsMapLayer *> &layers );
1257 
1264  void layerWasAdded( QgsMapLayer *layer );
1265 
1274  void legendLayersAdded( const QList<QgsMapLayer *> &layers );
1275 
1283  void isDirtyChanged( bool dirty );
1284 
1285  public slots:
1286 
1292  void setSnappingConfig( const QgsSnappingConfig &snappingConfig );
1293 
1294  // TODO QGIS 4.0 - rename b to dirty
1295 
1303  void setDirty( bool b = true );
1304 
1313  void setPresetHomePath( const QString &path );
1314 
1324  void registerTranslatableContainers( QgsTranslationContext *translationContext, QgsAttributeEditorContainer *parent, const QString &layerId );
1325 
1332  void registerTranslatableObjects( QgsTranslationContext *translationContext );
1333 
1334  private slots:
1335  void onMapLayersAdded( const QList<QgsMapLayer *> &layers );
1336  void onMapLayersRemoved( const QList<QgsMapLayer *> &layers );
1337  void cleanTransactionGroups( bool force = false );
1338 
1339  private:
1340 
1341  static QgsProject *sProject;
1342 
1351  static void setInstance( QgsProject *project ) SIP_SKIP;
1352 
1360  bool _getMapLayers( const QDomDocument &doc, QList<QDomNode> &brokenNodes );
1361 
1366  void setError( const QString &errorMessage ) SIP_SKIP;
1367 
1372  void clearError() SIP_SKIP;
1373 
1378  bool addLayer( const QDomElement &layerElem, QList<QDomNode> &brokenNodes, QgsReadWriteContext &context ) SIP_SKIP;
1379 
1381  void initializeEmbeddedSubtree( const QString &projectFilePath, QgsLayerTreeGroup *group ) SIP_SKIP;
1382 
1384  void loadEmbeddedNodes( QgsLayerTreeGroup *group ) SIP_SKIP;
1385 
1387  bool readProjectFile( const QString &filename );
1388 
1390  bool writeProjectFile( const QString &filename );
1391 
1393  bool unzip( const QString &filename );
1394 
1396  bool zip( const QString &filename );
1397 
1399  bool saveAuxiliaryStorage( const QString &filename = QString() );
1400 
1401  std::unique_ptr< QgsMapLayerStore > mLayerStore;
1402 
1403  QString mErrorMessage;
1404 
1405  QgsProjectBadLayerHandler *mBadLayerHandler = nullptr;
1406 
1412  QHash< QString, QPair< QString, bool> > mEmbeddedLayers;
1413 
1414  QgsSnappingConfig mSnappingConfig;
1415 
1416  QgsRelationManager *mRelationManager = nullptr;
1417 
1418  std::unique_ptr<QgsAnnotationManager> mAnnotationManager;
1419  std::unique_ptr<QgsLayoutManager> mLayoutManager;
1420 
1421  QgsLayerTree *mRootGroup = nullptr;
1422 
1423  QgsLayerTreeRegistryBridge *mLayerTreeRegistryBridge = nullptr;
1424 
1426  QMap< QPair< QString, QString>, QgsTransactionGroup *> mTransactionGroups;
1427 
1428  std::unique_ptr<QgsMapThemeCollection> mMapThemeCollection;
1429 
1430  std::unique_ptr<QgsLabelingEngineSettings> mLabelingEngineSettings;
1431 
1432  QVariantMap mCustomVariables;
1433 
1434  std::unique_ptr<QgsProjectArchive> mArchive;
1435 
1436  std::unique_ptr<QgsAuxiliaryStorage> mAuxiliaryStorage;
1437 
1438  QFile mFile; // current physical project file
1439 
1444  QString mHomePath;
1445  mutable QgsProjectPropertyKey mProperties; // property hierarchy, TODO: this shouldn't be mutable
1446  bool mAutoTransaction = false; // transaction grouped editing
1447  bool mEvaluateDefaultValues = false; // evaluate default values immediately
1449  bool mDirty = false; // project has been modified since it has been read or saved
1450  int mDirtyBlockCount = 0;
1451  bool mTrustLayerMetadata = false;
1452 
1453  QgsCoordinateTransformContext mTransformContext;
1454 
1455  QgsProjectMetadata mMetadata;
1456 
1457  std::unique_ptr< QTranslator > mTranslator;
1458 
1460 
1461  // Required to avoid creating a new project in it's destructor
1462  friend class QgsProviderRegistry;
1463 
1464  // Required by QGIS Server for switching the current project instance
1465  friend class QgsConfigCache;
1466 };
1467 
1489 class CORE_EXPORT QgsProjectDirtyBlocker
1490 {
1491  public:
1492 
1499  : mProject( project )
1500  {
1501  mProject->mDirtyBlockCount++;
1502  }
1503 
1505  QgsProjectDirtyBlocker( const QgsProjectDirtyBlocker &other ) = delete;
1506 
1508  QgsProjectDirtyBlocker &operator=( const QgsProjectDirtyBlocker &other ) = delete;
1509 
1511  {
1512  mProject->mDirtyBlockCount--;
1513  }
1514 
1515  private:
1516  QgsProject *mProject = nullptr;
1517 
1518 #ifdef SIP_RUN
1520 #endif
1521 };
1522 
1528 CORE_EXPORT QgsProjectVersion getVersion( QDomDocument const &doc ) SIP_SKIP;
1529 
1530 #endif
Layer tree group node serves as a container for layers and further groups.
The class is used as a container of context for various read/write operations on other objects...
Base class for all map layer types.
Definition: qgsmaplayer.h:63
#define SIP_TRANSFERTHIS
Definition: qgis_sip.h:46
Manages storage of a set of QgsAnnotation annotation objects.
Helper functions for various unit types.
Definition: qgsunittypes.h:37
Class providing some utility methods to manage auxiliary storage.
bool trustLayerMetadata() const
Returns true if the trust option is activated, false otherwise.
Definition: qgsproject.h:923
const QgsCoordinateReferenceSystem & crs
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:41
virtual QgsExpressionContext createExpressionContext() const =0
This method needs to be reimplemented in all classes which implement this interface and return an exp...
Namespace with helper functions for layer tree operations.
Definition: qgslayertree.h:32
CORE_EXPORT bool unzip(const QString &zip, const QString &dir, QStringList &files)
Unzip a zip file in an output directory.
Definition: qgsziputils.cpp:34
#define SIP_SKIP
Definition: qgis_sip.h:119
CORE_EXPORT QgsProjectVersion getVersion(QDomDocument const &doc)
Returns the version string found in the given DOM document.
Definition: qgsproject.cpp:820
A class to describe the version of a project.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
This is the class is providing tolerance value in map unit values.
Definition: qgstolerance.h:32
Listens to the updates in map layer registry and does changes in layer tree.
#define SIP_TRANSFER
Definition: qgis_sip.h:36
Reads and writes project states.
Definition: qgsproject.h:89
Contains information about the context in which a coordinate transform is executed.
Wherever an object of this class is available, the derived translate function can be called from...
Manages storage of a set of layouts.
#define SIP_DEPRECATED
Definition: qgis_sip.h:99
Used for the collecting of strings from projects for translation and creation of ts files...
Abstract interface for generating an expression context.
virtual QString translate(const QString &context, const QString &sourceText, const char *disambiguation=nullptr, int n=-1) const =0
The derived translate() translates with QTranslator and qm file the sourceText.
A registry / canonical manager of data providers.
Project property key node.
Cache for server configuration.
#define SIP_PYARGREMOVE
Definition: qgis_sip.h:139
QVector< T > layers() const
Returns a list of registered map layers with a specified layer type.
Definition: qgsproject.h:738
This class manages a set of relations between layers.
Stores global configuration for labeling engine.
This class represents a coordinate reference system (CRS).
This is a container for attribute editors, used to group them visually in the attribute form if it is...
Abstract interface for project storage - to be implemented by various backends and registered in QgsP...
QgsProjectDirtyBlocker(QgsProject *project)
Constructor for QgsProjectDirtyBlocker.
Definition: qgsproject.h:1498
Temporarily blocks QgsProject "dirtying" for the lifetime of the object.
Definition: qgsproject.h:1489
A storage object for map layers, in which the layers are owned by the store and have their lifetime b...
Container class that allows storage of map themes consisting of visible map layers and layer styles...
This is a container for configuration of the snapping of the project.
Resolves relative paths into absolute paths and vice versa.
Represents a vector layer which manages a vector based data sets.
CORE_EXPORT bool zip(const QString &zip, const QStringList &files)
Zip the list of files in the zip file.
Interface for classes that handle missing layer files when reading project file.
#define SIP_PYNAME(name)
Definition: qgis_sip.h:74
A structured metadata store for a map layer.