Branch data Line data Source code
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 <memory>
27 : : #include <QHash>
28 : : #include <QList>
29 : : #include <QObject>
30 : : #include <QPair>
31 : : #include <QFileInfo>
32 : : #include <QStringList>
33 : : #include <QTranslator>
34 : :
35 : : #include "qgsunittypes.h"
36 : : #include "qgssnappingconfig.h"
37 : : #include "qgsprojectversion.h"
38 : : #include "qgsexpressioncontextgenerator.h"
39 : : #include "qgsexpressioncontextscopegenerator.h"
40 : : #include "qgscoordinatereferencesystem.h"
41 : : #include "qgscoordinatetransformcontext.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"
49 : : #include "qgscolorscheme.h"
50 : : #include "qgssettings.h"
51 : : #include "qgspropertycollection.h"
52 : :
53 : : #include "qgsrelationmanager.h"
54 : : #include "qgsmapthemecollection.h"
55 : :
56 : : class QFileInfo;
57 : : class QDomDocument;
58 : : class QDomElement;
59 : : class QDomNode;
60 : :
61 : : class QgsLayerTreeGroup;
62 : : class QgsLayerTreeRegistryBridge;
63 : : class QgsMapLayer;
64 : : class QgsPathResolver;
65 : : class QgsProjectBadLayerHandler;
66 : : class QgsProjectStorage;
67 : : class QgsTolerance;
68 : : class QgsTransactionGroup;
69 : : class QgsVectorLayer;
70 : : class QgsAnnotationManager;
71 : : class QgsLayoutManager;
72 : : class QgsLayerTree;
73 : : class QgsLabelingEngineSettings;
74 : : class QgsAuxiliaryStorage;
75 : : class QgsMapLayer;
76 : : class QgsBookmarkManager;
77 : : class QgsProjectViewSettings;
78 : : class QgsProjectDisplaySettings;
79 : : class QgsProjectTimeSettings;
80 : : class QgsAnnotationLayer;
81 : : class QgsAttributeEditorContainer;
82 : : class QgsPropertyCollection;
83 : :
84 : :
85 : : /**
86 : : * \ingroup core
87 : : * \brief Encapsulates a QGIS project, including sets of map layers and their styles,
88 : : * layouts, annotations, canvases, etc.
89 : : *
90 : : * QgsProject is available both as a singleton (QgsProject::instance()) and for use as
91 : : * standalone objects. The QGIS project singleton always gives access to the canonical project reference
92 : : * open within the main QGIS application.
93 : : *
94 : : * \note QgsProject has two general kinds of state to make persistent. (I.e., to read and
95 : : * write.) First, QGIS proprietary information. Second plugin information.
96 : : */
97 : :
98 : : class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenerator, public QgsExpressionContextScopeGenerator, public QgsProjectTranslator
99 : : {
100 : 0 : Q_OBJECT
101 : : Q_PROPERTY( QStringList nonIdentifiableLayers READ nonIdentifiableLayers WRITE setNonIdentifiableLayers NOTIFY nonIdentifiableLayersChanged )
102 : : Q_PROPERTY( QString fileName READ fileName WRITE setFileName NOTIFY fileNameChanged )
103 : : Q_PROPERTY( QString homePath READ homePath WRITE setPresetHomePath NOTIFY homePathChanged )
104 : : Q_PROPERTY( QgsCoordinateReferenceSystem crs READ crs WRITE setCrs NOTIFY crsChanged )
105 : : Q_PROPERTY( QgsCoordinateTransformContext transformContext READ transformContext WRITE setTransformContext NOTIFY transformContextChanged )
106 : : Q_PROPERTY( QString ellipsoid READ ellipsoid WRITE setEllipsoid NOTIFY ellipsoidChanged )
107 : : Q_PROPERTY( QgsMapThemeCollection *mapThemeCollection READ mapThemeCollection NOTIFY mapThemeCollectionChanged )
108 : : Q_PROPERTY( QgsSnappingConfig snappingConfig READ snappingConfig WRITE setSnappingConfig NOTIFY snappingConfigChanged )
109 : : Q_PROPERTY( QgsRelationManager *relationManager READ relationManager )
110 : : Q_PROPERTY( AvoidIntersectionsMode avoidIntersectionsMode READ avoidIntersectionsMode WRITE setAvoidIntersectionsMode NOTIFY avoidIntersectionsModeChanged )
111 : : Q_PROPERTY( QList<QgsVectorLayer *> avoidIntersectionsLayers READ avoidIntersectionsLayers WRITE setAvoidIntersectionsLayers NOTIFY avoidIntersectionsLayersChanged )
112 : : Q_PROPERTY( QgsProjectMetadata metadata READ metadata WRITE setMetadata NOTIFY metadataChanged )
113 : : Q_PROPERTY( QColor backgroundColor READ backgroundColor WRITE setBackgroundColor NOTIFY backgroundColorChanged )
114 : : Q_PROPERTY( QColor selectionColor READ selectionColor WRITE setSelectionColor NOTIFY selectionColorChanged )
115 : : Q_PROPERTY( bool topologicalEditing READ topologicalEditing WRITE setTopologicalEditing NOTIFY topologicalEditingChanged )
116 : :
117 : : public:
118 : :
119 : : /**
120 : : * Flags which control project read behavior.
121 : : * \since QGIS 3.10
122 : : */
123 : : enum class ReadFlag SIP_MONKEYPATCH_SCOPEENUM
124 : : {
125 : : FlagDontResolveLayers = 1 << 0, //!< Don't resolve layer paths (i.e. don't load any layer content). Dramatically improves project read time if the actual data from the layers is not required.
126 : : FlagDontLoadLayouts = 1 << 1, //!< Don't load print layouts. Improves project read time if layouts are not required, and allows projects to be safely read in background threads (since print layouts are not thread safe).
127 : : FlagTrustLayerMetadata = 1 << 2, //!< Trust layer metadata. Improves project read time. Do not use it if layers' extent is not fixed during the project's use by QGIS and QGIS Server.
128 : : FlagDontStoreOriginalStyles = 1 << 3, //!< Skip the initial XML style storage for layers. Useful for minimising project load times in non-interactive contexts.
129 : : };
130 : : Q_DECLARE_FLAGS( ReadFlags, ReadFlag )
131 : :
132 : : /**
133 : : * Flags which control project read behavior.
134 : : * \since QGIS 3.12
135 : : */
136 : : enum class FileFormat
137 : : {
138 : : Qgz, //!< Archive file format, supports auxiliary data
139 : : Qgs, //!< Project saved in a clear text, does not support auxiliary data
140 : : };
141 : : Q_ENUM( FileFormat )
142 : :
143 : : /**
144 : : * Flags which control how intersections of pre-existing feature are handled when digitizing new features.
145 : : * \since QGIS 3.14
146 : : */
147 : : enum class AvoidIntersectionsMode
148 : : {
149 : : AllowIntersections, //!< Overlap with any feature allowed when digitizing new features
150 : : AvoidIntersectionsCurrentLayer, //!< Overlap with features from the active layer when digitizing new features not allowed
151 : : AvoidIntersectionsLayers, //!< Overlap with features from a specified list of layers when digitizing new features not allowed
152 : : };
153 : : Q_ENUM( AvoidIntersectionsMode )
154 : :
155 : : /**
156 : : * Data defined properties.
157 : : * Overrides of user defined server parameters are stored in a
158 : : * property collection and they can be retrieved using the
159 : : * indexes specified in this enum.
160 : : *
161 : : * \since QGIS 3.14
162 : : */
163 : : enum DataDefinedServerProperty
164 : : {
165 : : NoProperty = 0, //!< No property
166 : : AllProperties = 1, //!< All properties for item
167 : : WMSOnlineResource = 2, //!< Alias
168 : : };
169 : :
170 : : //! Returns the QgsProject singleton instance
171 : : static QgsProject *instance();
172 : :
173 : : /**
174 : : * Set the current project singleton instance to \a project
175 : : *
176 : : * \note this method is provided mainly for the server, which caches the projects and (potentially) needs to switch the current instance on every request.
177 : : * \warning calling this method can have serious, unintended consequences, including instability, data loss and undefined behavior. Use with EXTREME caution!
178 : : * \see instance()
179 : : * \since QGIS 3.10.11
180 : : */
181 : : static void setInstance( QgsProject *project ) ;
182 : :
183 : :
184 : : /**
185 : : * Create a new QgsProject.
186 : : *
187 : : * Most of the time you want to use QgsProject::instance() instead as many components of QGIS work with the singleton.
188 : : */
189 : : explicit QgsProject( QObject *parent SIP_TRANSFERTHIS = nullptr );
190 : :
191 : : ~QgsProject() override;
192 : :
193 : : /**
194 : : * Sets the project's title.
195 : : * \param title new title
196 : : *
197 : : * \note Since QGIS 3.2 this is just a shortcut to setting the title in the project's metadata().
198 : : *
199 : : * \see title()
200 : : * \since QGIS 2.4
201 : : */
202 : : void setTitle( const QString &title );
203 : :
204 : : /**
205 : : * Returns the project's title.
206 : : * \see setTitle()
207 : : *
208 : : * \note Since QGIS 3.2 this is just a shortcut to retrieving the title from the project's metadata().
209 : : */
210 : : QString title() const;
211 : :
212 : : /**
213 : : * Returns the user name that did the last save.
214 : : *
215 : : * \see saveUserFullName()
216 : : *
217 : : * \since QGIS 3.12
218 : : */
219 : : QString saveUser() const;
220 : :
221 : : /**
222 : : * Returns the full user name that did the last save.
223 : : *
224 : : * \see saveUser()
225 : : *
226 : : * \since QGIS 3.12
227 : : */
228 : : QString saveUserFullName() const;
229 : :
230 : : /**
231 : : * Returns the date and time when the project was last saved.
232 : : *
233 : : * \since QGIS 3.14
234 : : */
235 : : QDateTime lastSaveDateTime() const;
236 : :
237 : : /**
238 : : * Returns the QGIS version which the project was last saved using.
239 : : *
240 : : * \since QGIS 3.14
241 : : */
242 : : QgsProjectVersion lastSaveVersion() const;
243 : :
244 : : /**
245 : : * Returns TRUE if the project has been modified since the last write()
246 : : */
247 : : bool isDirty() const;
248 : :
249 : : /**
250 : : * Sets the file name associated with the project. This is the file or the storage URI which contains the project's XML
251 : : * representation.
252 : : * \param name project file name
253 : : * \see fileName()
254 : : */
255 : : void setFileName( const QString &name );
256 : :
257 : : /**
258 : : * Returns the project's file name. This is the file or the storage URI which contains the project's XML
259 : : * representation.
260 : : * \see setFileName()
261 : : * \see fileInfo()
262 : : */
263 : : QString fileName() const;
264 : :
265 : : /**
266 : : * Sets the original \a path associated with the project.
267 : : *
268 : : * This is intended for use with non-qgs/qgz project files (see QgsCustomProjectOpenHandler) in order to allow
269 : : * custom project open handlers to specify the original file name of the project. For custom project formats,
270 : : * it is NOT appropriate to call setFileName() with the original project path, as this causes the original (non
271 : : * QGIS) project file to be overwritten when the project is next saved.
272 : : *
273 : : * \see originalPath()
274 : : * \since QGIS 3.14
275 : : */
276 : : void setOriginalPath( const QString &path );
277 : :
278 : : /**
279 : : * Returns the original path associated with the project.
280 : : *
281 : : * This is intended for use with non-qgs/qgz project files (see QgsCustomProjectOpenHandler) in order to allow
282 : : * custom project open handlers to specify the original file name of the project. For custom project formats,
283 : : * it is NOT appropriate to call setFileName() with the original project path, as this causes the original (non
284 : : * QGIS) project file to be overwritten when the project is next saved.
285 : :
286 : : * \see setOriginalPath()
287 : : * \since QGIS 3.14
288 : : */
289 : : QString originalPath() const;
290 : :
291 : : /**
292 : : * Returns QFileInfo object for the project's associated file.
293 : : *
294 : : * \note The use of this method is discouraged since QGIS 3.2 as it only works with project files stored
295 : : * in the file system. It is recommended to use absoluteFilePath(), baseName(), lastModifiedTime() as
296 : : * replacements that are aware of the fact that projects may be saved in other project storages.
297 : : *
298 : : * \see fileName()
299 : : * \deprecated since QGIS 3.2 use absoluteFilePath(), baseName() or lastModifiedTime() instead
300 : : */
301 : : Q_DECL_DEPRECATED QFileInfo fileInfo() const SIP_DEPRECATED;
302 : :
303 : : /**
304 : : * Returns pointer to project storage implementation that handles read/write of the project file.
305 : : * If the project file is stored in the local file system, returns NULLPTR.
306 : : * The project storage object is inferred from fileName() of the project.
307 : : * \since QGIS 3.2
308 : : */
309 : : QgsProjectStorage *projectStorage() const;
310 : :
311 : : /**
312 : : * Returns last modified time of the project file as returned by the file system (or other project storage).
313 : : * \since QGIS 3.2
314 : : */
315 : : QDateTime lastModified() const;
316 : :
317 : : /**
318 : : * Returns full absolute path to the project file if the project is stored in a file system - derived from fileName().
319 : : * Returns empty string when the project is stored in a project storage (there is no concept of paths for custom project storages).
320 : : * \since QGIS 3.2
321 : : */
322 : : QString absoluteFilePath() const;
323 : :
324 : : /**
325 : : * Returns full absolute path to the project folder if the project is stored in a file system - derived from fileName().
326 : : * Returns empty string when the project is stored in a project storage (there is no concept of paths for custom project storages).
327 : : * \since QGIS 3.2
328 : : */
329 : : QString absolutePath() const;
330 : :
331 : : /**
332 : : * Returns the base name of the project file without the path and without extension - derived from fileName().
333 : : * \since QGIS 3.2
334 : : */
335 : : QString baseName() const;
336 : :
337 : : /**
338 : : * Returns the project's native coordinate reference system.
339 : : * \see setCrs()
340 : : * \see ellipsoid()
341 : : * \since QGIS 3.0
342 : : */
343 : : QgsCoordinateReferenceSystem crs() const;
344 : :
345 : : /**
346 : : * Sets the project's native coordinate reference system.
347 : : * If \a adjustEllipsoid is set to TRUE, the ellpsoid of this project will be set to
348 : : * the ellipsoid imposed by the CRS.
349 : : *
350 : : * \see crs()
351 : : * \see setEllipsoid()
352 : : * \since QGIS 3.0
353 : : */
354 : : void setCrs( const QgsCoordinateReferenceSystem &crs, bool adjustEllipsoid = false );
355 : :
356 : : /**
357 : : * Returns a proj string representing the project's ellipsoid setting, e.g., "WGS84".
358 : : * \see setEllipsoid()
359 : : * \see crs()
360 : : * \since QGIS 3.0
361 : : */
362 : : QString ellipsoid() const;
363 : :
364 : : /**
365 : : * Sets the project's ellipsoid from a proj string representation, e.g., "WGS84".
366 : : * \see ellipsoid()
367 : : * \see setCrs()
368 : : * \since QGIS 3.0
369 : : */
370 : : void setEllipsoid( const QString &ellipsoid );
371 : :
372 : :
373 : : /**
374 : : * Returns a copy of the project's coordinate transform context, which stores various
375 : : * information regarding which datum transforms should be used when transforming points
376 : : * from a source to destination coordinate reference system.
377 : : *
378 : : * \see setTransformContext()
379 : : * \see transformContextChanged()
380 : : * \since QGIS 3.0
381 : : */
382 : : QgsCoordinateTransformContext transformContext() const;
383 : :
384 : : /**
385 : : * Sets the project's coordinate transform \a context, which stores various
386 : : * information regarding which datum transforms should be used when transforming points
387 : : * from a source to destination coordinate reference system.
388 : : *
389 : : * \see transformContext()
390 : : * \see transformContextChanged()
391 : : * \since QGIS 3.0
392 : : */
393 : : void setTransformContext( const QgsCoordinateTransformContext &context );
394 : :
395 : : /**
396 : : * Clears the project, removing all settings and resetting it back to an empty, default state.
397 : : * \see cleared()
398 : : * \since QGIS 2.4
399 : : */
400 : : void clear();
401 : :
402 : : /**
403 : : * Reads given project file from the given file.
404 : : * \param filename name of project file to read
405 : : * \param flags optional flags which control the read behavior of projects
406 : : * \returns TRUE if project file has been read successfully
407 : : */
408 : : bool read( const QString &filename, QgsProject::ReadFlags flags = QgsProject::ReadFlags() );
409 : :
410 : : /**
411 : : * Reads the project from its currently associated file (see fileName() ).
412 : : *
413 : : * The \a flags argument can be used to specify optional flags which control
414 : : * the read behavior of projects.
415 : : *
416 : : * \returns TRUE if project file has been read successfully
417 : : */
418 : : bool read( QgsProject::ReadFlags flags = QgsProject::ReadFlags() );
419 : :
420 : : /**
421 : : * Reads the layer described in the associated DOM node.
422 : : *
423 : : * \note This method is mainly for use by QgsProjectBadLayerHandler subclasses
424 : : * that may fix definition of bad layers with the user's help in GUI. Calling
425 : : * this method with corrected DOM node adds the layer back to the project.
426 : : *
427 : : * \param layerNode represents a QgsProject DOM node that encodes a specific layer.
428 : : */
429 : : bool readLayer( const QDomNode &layerNode );
430 : :
431 : : /**
432 : : * Writes the project to a file.
433 : : * \param filename destination file
434 : : * \returns TRUE if project was written successfully
435 : : * \note calling this implicitly sets the project's filename (see setFileName() )
436 : : * \note isDirty() will be set to FALSE if project is successfully written
437 : : * \since QGIS 3.0
438 : : */
439 : : bool write( const QString &filename );
440 : :
441 : : /**
442 : : * Writes the project to its current associated file (see fileName() ).
443 : : * \returns TRUE if project was written successfully
444 : : * \note isDirty() will be set to FALSE if project is successfully written
445 : : */
446 : : bool write();
447 : :
448 : : /**
449 : : * Write a boolean \a value to the project file.
450 : : *
451 : : * Keys are '/'-delimited entries, implying
452 : : * a hierarchy of keys and corresponding values
453 : : *
454 : : * \note The key string must be valid xml tag names in order to be saved to the file.
455 : : * \note available in Python bindings as writeEntryBool
456 : : *
457 : : * \see readBoolEntry()
458 : : */
459 : : bool writeEntry( const QString &scope, const QString &key, bool value ) SIP_PYNAME( writeEntryBool );
460 : :
461 : : /**
462 : : * Write a double \a value to the project file.
463 : : *
464 : : * Keys are '/'-delimited entries, implying
465 : : * a hierarchy of keys and corresponding values
466 : : *
467 : : * \note The key string must be valid xml tag names in order to be saved to the file.
468 : : * \note available in Python bindings as writeEntryDouble
469 : : *
470 : : * \see readDoubleEntry()
471 : : */
472 : : bool writeEntry( const QString &scope, const QString &key, double value ) SIP_PYNAME( writeEntryDouble );
473 : :
474 : : /**
475 : : * Write an integer \a value to the project file.
476 : : *
477 : : * Keys are '/'-delimited entries, implying
478 : : * a hierarchy of keys and corresponding values
479 : : *
480 : : * \note The key string must be valid xml tag names in order to be saved to the file.
481 : : *
482 : : * \see readNumEntry()
483 : : */
484 : : bool writeEntry( const QString &scope, const QString &key, int value );
485 : :
486 : : /**
487 : : * Write a string \a value to the project file.
488 : : *
489 : : * Keys are '/'-delimited entries, implying
490 : : * a hierarchy of keys and corresponding values
491 : : *
492 : : * \note The key string must be valid xml tag names in order to be saved to the file.
493 : : *
494 : : * \see readEntry()
495 : : */
496 : : bool writeEntry( const QString &scope, const QString &key, const QString &value );
497 : :
498 : : /**
499 : : * Write a string list \a value to the project file.
500 : : *
501 : : * Keys are '/'-delimited entries, implying
502 : : * a hierarchy of keys and corresponding values
503 : : *
504 : : * \note The key string must be valid xml tag names in order to be saved to the file.
505 : : *
506 : : * \see readListEntry()
507 : : */
508 : : bool writeEntry( const QString &scope, const QString &key, const QStringList &value );
509 : :
510 : : /**
511 : : * Reads a string list from the specified \a scope and \a key.
512 : : *
513 : : * \param scope entry scope (group) name
514 : : * \param key entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
515 : : * \param def default value to return if the specified \a key does not exist within the \a scope.
516 : : * \param ok set to TRUE if key exists and has been successfully retrieved as a string list
517 : : *
518 : : * \returns entry value as a string list
519 : : */
520 : : QStringList readListEntry( const QString &scope, const QString &key, const QStringList &def = QStringList(), bool *ok SIP_OUT = nullptr ) const;
521 : :
522 : : /**
523 : : * Reads a string from the specified \a scope and \a key.
524 : : *
525 : : * \param scope entry scope (group) name
526 : : * \param key entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
527 : : * \param def default value to return if the specified \a key does not exist within the \a scope.
528 : : * \param ok set to TRUE if key exists and has been successfully retrieved as a string value
529 : : *
530 : : * \returns entry value as string from \a scope given its \a key
531 : : */
532 : : QString readEntry( const QString &scope, const QString &key, const QString &def = QString(), bool *ok SIP_OUT = nullptr ) const;
533 : :
534 : : /**
535 : : * Reads an integer from the specified \a scope and \a key.
536 : : *
537 : : * \param scope entry scope (group) name
538 : : * \param key entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
539 : : * \param def default value to return if the specified \a key does not exist within the \a scope.
540 : : * \param ok set to TRUE if key exists and has been successfully retrieved as an integer
541 : : *
542 : : * \returns entry value as integer from \a scope given its \a key
543 : : */
544 : : int readNumEntry( const QString &scope, const QString &key, int def = 0, bool *ok SIP_OUT = nullptr ) const;
545 : :
546 : : /**
547 : : * Reads a double from the specified \a scope and \a key.
548 : : *
549 : : * \param scope entry scope (group) name
550 : : * \param key entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
551 : : * \param def default value to return if the specified \a key does not exist within the \a scope.
552 : : * \param ok set to TRUE if key exists and has been successfully retrieved as a double
553 : : *
554 : : * \returns entry value as double from \a scope given its \a key
555 : : */
556 : : double readDoubleEntry( const QString &scope, const QString &key, double def = 0, bool *ok SIP_OUT = nullptr ) const;
557 : :
558 : : /**
559 : : * Reads a boolean from the specified \a scope and \a key.
560 : : *
561 : : * \param scope entry scope (group) name
562 : : * \param key entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
563 : : * \param def default value to return if the specified \a key does not exist within the \a scope.
564 : : * \param ok set to TRUE if key exists and has been successfully retrieved as a boolean
565 : : *
566 : : * \returns entry value as boolean from \a scope given its \a key
567 : : */
568 : : bool readBoolEntry( const QString &scope, const QString &key, bool def = false, bool *ok SIP_OUT = nullptr ) const;
569 : :
570 : : /**
571 : : * Remove the given \a key from the specified \a scope.
572 : : */
573 : : bool removeEntry( const QString &scope, const QString &key );
574 : :
575 : : /**
576 : : * Returns a list of child keys with values which exist within the the specified \a scope and \a key.
577 : : *
578 : : * This method does not return keys that contain other keys. See subkeyList() to retrieve keys
579 : : * which contain other keys.
580 : : *
581 : : * \note equivalent to QgsSettings entryList()
582 : : */
583 : : QStringList entryList( const QString &scope, const QString &key ) const;
584 : :
585 : : /**
586 : : * Returns a list of child keys which contain other keys that exist within the the specified \a scope and \a key.
587 : : *
588 : : * This method only returns keys with keys, it will not return keys that contain only values. See
589 : : * entryList() to retrieve keys with values.
590 : : *
591 : : * \note equivalent to QgsSettings subkeyList()
592 : : */
593 : : QStringList subkeyList( const QString &scope, const QString &key ) const;
594 : :
595 : : // TODO Now slightly broken since re-factoring. Won't print out top-level key
596 : : // and redundantly prints sub-keys.
597 : :
598 : : /**
599 : : * Dump out current project properties to stderr
600 : : */
601 : : void dumpProperties() const;
602 : :
603 : : /**
604 : : * Returns path resolver object with considering whether the project uses absolute
605 : : * or relative paths and using current project's path.
606 : : * \since QGIS 3.0
607 : : */
608 : : QgsPathResolver pathResolver() const;
609 : :
610 : : /**
611 : : * Prepare a filename to save it to the project file.
612 : : * Creates an absolute or relative path according to the project settings.
613 : : * Paths written to the project file should be prepared with this method.
614 : : */
615 : : QString writePath( const QString &filename ) const;
616 : :
617 : : /**
618 : : * Transforms a \a filename read from the project file to an absolute path.
619 : : */
620 : : QString readPath( const QString &filename ) const;
621 : :
622 : : //! Returns error message from previous read/write
623 : : QString error() const;
624 : :
625 : : /**
626 : : * Change handler for missing layers.
627 : : * Deletes old handler and takes ownership of the new one.
628 : : */
629 : : void setBadLayerHandler( QgsProjectBadLayerHandler *handler SIP_TRANSFER );
630 : :
631 : : /**
632 : : * Returns the source project file path if the layer with matching \a id is embedded from other project file.
633 : : *
634 : : * Returns an empty string if the matching layer is not embedded.
635 : : */
636 : : QString layerIsEmbedded( const QString &id ) const;
637 : :
638 : : /**
639 : : * Creates a maplayer instance defined in an arbitrary project file. Caller takes ownership.
640 : : *
641 : : * The optional \a flags argument can be used to specify flags which control layer reading.
642 : : *
643 : : * \returns the layer or 0 in case of error
644 : : * \note not available in Python bindings
645 : : */
646 : : bool createEmbeddedLayer( const QString &layerId, const QString &projectFilePath, QList<QDomNode> &brokenNodes,
647 : : bool saveFlag = true, QgsProject::ReadFlags flags = QgsProject::ReadFlags() ) SIP_SKIP;
648 : :
649 : : /**
650 : : * Create layer group instance defined in an arbitrary project file.
651 : : *
652 : : * The optional \a flags argument can be used to control layer reading behavior.
653 : : *
654 : : * \since QGIS 2.4
655 : : */
656 : : QgsLayerTreeGroup *createEmbeddedGroup( const QString &groupName, const QString &projectFilePath, const QStringList &invisibleLayers, QgsProject::ReadFlags flags = QgsProject::ReadFlags() );
657 : :
658 : : //! Convenience function to set topological editing
659 : : void setTopologicalEditing( bool enabled );
660 : :
661 : : //! Convenience function to query topological editing status
662 : : bool topologicalEditing() const;
663 : :
664 : : /**
665 : : * Convenience function to query default distance measurement units for project.
666 : : * \see setDistanceUnits()
667 : : * \see areaUnits()
668 : : * \since QGIS 2.14
669 : : */
670 : : QgsUnitTypes::DistanceUnit distanceUnits() const;
671 : :
672 : : /**
673 : : * Sets the default distance measurement units for the project.
674 : : * \see distanceUnits()
675 : : * \see setAreaUnits()
676 : : * \since QGIS 3.0
677 : : */
678 : : void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
679 : :
680 : : /**
681 : : * Convenience function to query default area measurement units for project.
682 : : * \see distanceUnits()
683 : : * \since QGIS 2.14
684 : : */
685 : : QgsUnitTypes::AreaUnit areaUnits() const;
686 : :
687 : : /**
688 : : * Sets the default area measurement units for the project.
689 : : * \see areaUnits()
690 : : * \see setDistanceUnits()
691 : : * \since QGIS 3.0
692 : : */
693 : : void setAreaUnits( QgsUnitTypes::AreaUnit unit );
694 : :
695 : : /**
696 : : * Returns the project's home path. This will either be a manually set home path
697 : : * (see presetHomePath()) or the path containing the project file itself.
698 : : *
699 : : * This method always returns the absolute path to the project's home. See
700 : : * presetHomePath() to retrieve any manual project home path override (e.g.
701 : : * relative home paths).
702 : : *
703 : : * \see setPresetHomePath()
704 : : * \see presetHomePath()
705 : : * \see homePathChanged()
706 : : */
707 : : QString homePath() const;
708 : :
709 : : /**
710 : : * Returns any manual project home path setting, or an empty string if not set.
711 : : *
712 : : * This path may be a relative path. See homePath() to retrieve a path which is always
713 : : * an absolute path.
714 : : *
715 : : * \see homePath()
716 : : * \see setPresetHomePath()
717 : : * \see homePathChanged()
718 : : *
719 : : * \since QGIS 3.2
720 : : */
721 : : QString presetHomePath() const;
722 : :
723 : : QgsRelationManager *relationManager() const;
724 : :
725 : : /**
726 : : * Returns the project's layout manager, which manages print layouts, atlases and reports within
727 : : * the project.
728 : : * \note not available in Python bindings
729 : : * \since QGIS 3.0
730 : : */
731 : : const QgsLayoutManager *layoutManager() const SIP_SKIP;
732 : :
733 : : /**
734 : : * Returns the project's layout manager, which manages print layouts, atlases and reports within
735 : : * the project.
736 : : * \since QGIS 3.0
737 : : */
738 : : QgsLayoutManager *layoutManager();
739 : :
740 : : /**
741 : : * Returns the project's bookmark manager, which manages bookmarks within
742 : : * the project.
743 : : * \note not available in Python bindings
744 : : * \since QGIS 3.10
745 : : */
746 : : const QgsBookmarkManager *bookmarkManager() const SIP_SKIP;
747 : :
748 : : /**
749 : : * Returns the project's bookmark manager, which manages bookmarks within
750 : : * the project.
751 : : * \since QGIS 3.10
752 : : */
753 : : QgsBookmarkManager *bookmarkManager();
754 : :
755 : : /**
756 : : * Returns the project's view settings, which contains settings and properties
757 : : * relating to how a QgsProject should be viewed and behave inside a map canvas
758 : : * (e.g. map scales and default view extent)
759 : : * \note not available in Python bindings
760 : : * \since QGIS 3.10.1
761 : : */
762 : : const QgsProjectViewSettings *viewSettings() const SIP_SKIP;
763 : :
764 : : /**
765 : : * Returns the project's view settings, which contains settings and properties
766 : : * relating to how a QgsProject should be viewed and behave inside a map canvas
767 : : * (e.g. map scales and default view extent)
768 : : * \since QGIS 3.10.1
769 : : */
770 : : QgsProjectViewSettings *viewSettings();
771 : :
772 : : /**
773 : : * Returns the project's time settings, which contains the project's temporal range and other
774 : : * time based settings.
775 : : *
776 : : * \note not available in Python bindings
777 : : * \since QGIS 3.14
778 : : */
779 : : const QgsProjectTimeSettings *timeSettings() const SIP_SKIP;
780 : :
781 : : /**
782 : : * Returns the project's time settings, which contains the project's temporal range and other
783 : : * time based settings.
784 : : *
785 : : * \since QGIS 3.14
786 : : */
787 : : QgsProjectTimeSettings *timeSettings();
788 : :
789 : : /**
790 : : * Returns the project's display settings, which settings and properties relating
791 : : * to how a QgsProject should display values such as map coordinates and bearings.
792 : : * \note not available in Python bindings
793 : : * \since QGIS 3.12
794 : : */
795 : : const QgsProjectDisplaySettings *displaySettings() const SIP_SKIP;
796 : :
797 : : /**
798 : : * Returns the project's display settings, which settings and properties relating
799 : : * to how a QgsProject should display values such as map coordinates and bearings.
800 : : * \since QGIS 3.12
801 : : */
802 : : QgsProjectDisplaySettings *displaySettings();
803 : :
804 : : /**
805 : : * Returns pointer to the root (invisible) node of the project's layer tree
806 : : * \since QGIS 2.4
807 : : */
808 : : QgsLayerTree *layerTreeRoot() const;
809 : :
810 : : /**
811 : : * Returns pointer to the helper class that synchronizes map layer registry with layer tree
812 : : * \since QGIS 2.4
813 : : */
814 : : QgsLayerTreeRegistryBridge *layerTreeRegistryBridge() const { return mLayerTreeRegistryBridge; }
815 : :
816 : : /**
817 : : * Returns pointer to the project's map theme collection.
818 : : * \note renamed in QGIS 3.0, formerly QgsVisibilityPresetCollection
819 : : * \since QGIS 2.12
820 : : */
821 : : QgsMapThemeCollection *mapThemeCollection();
822 : :
823 : : /**
824 : : * Returns pointer to the project's annotation manager.
825 : : * \since QGIS 3.0
826 : : */
827 : : QgsAnnotationManager *annotationManager();
828 : :
829 : : /**
830 : : * Returns a const pointer to the project's annotation manager.
831 : : * \since QGIS 3.0
832 : : */
833 : : const QgsAnnotationManager *annotationManager() const SIP_SKIP;
834 : :
835 : : /**
836 : : * Set a list of layers which should not be taken into account on map identification
837 : : * \deprecated since QGIS 3.4 use QgsMapLayer::setFlags() instead
838 : : */
839 : : Q_DECL_DEPRECATED void setNonIdentifiableLayers( const QList<QgsMapLayer *> &layers );
840 : :
841 : : /**
842 : : * Set a list of layers which should not be taken into account on map identification
843 : : * \deprecated since QGIS 3.4 use QgsMapLayer::setFlags() instead
844 : : */
845 : : Q_DECL_DEPRECATED void setNonIdentifiableLayers( const QStringList &layerIds );
846 : :
847 : : /**
848 : : * Gets the list of layers which currently should not be taken into account on map identification
849 : : * \deprecated since QGIS 3.4 use QgsMapLayer::setFlags() instead
850 : : */
851 : : Q_DECL_DEPRECATED QStringList nonIdentifiableLayers() const;
852 : :
853 : : /**
854 : : * Transactional editing means that on supported datasources (postgres databases) the edit state of
855 : : * all tables that originate from the same database are synchronized and executed in a server side
856 : : * transaction.
857 : : *
858 : : * \since QGIS 2.16
859 : : */
860 : : bool autoTransaction() const;
861 : :
862 : : /**
863 : : * Transactional editing means that on supported datasources (postgres databases) the edit state of
864 : : * all tables that originate from the same database are synchronized and executed in a server side
865 : : * transaction.
866 : : *
867 : : * Make sure that this is only called when all layers are not in edit mode.
868 : : *
869 : : * \since QGIS 2.16
870 : : */
871 : : void setAutoTransaction( bool autoTransaction );
872 : :
873 : : /**
874 : : * Map of transaction groups
875 : : *
876 : : * QPair( providerKey, connString ) -> transactionGroup
877 : : *
878 : : * \note Not available in Python bindings
879 : : * \since QGIS 2.16
880 : : */
881 : : QMap< QPair< QString, QString>, QgsTransactionGroup *> transactionGroups() SIP_SKIP;
882 : :
883 : : /**
884 : : * Returns the matching transaction group from a provider key and connection string.
885 : : *
886 : : * Returns NULLPTR if a matching transaction group is not available.
887 : : *
888 : : * \since QGIS 3.2
889 : : */
890 : : QgsTransactionGroup *transactionGroup( const QString &providerKey, const QString &connString );
891 : :
892 : : /**
893 : : * Should default values be evaluated on provider side when requested and not when committed.
894 : : *
895 : : * \since QGIS 2.16
896 : : */
897 : : bool evaluateDefaultValues() const;
898 : :
899 : : /**
900 : : * Defines if default values should be evaluated on provider side when requested and not when committed.
901 : : *
902 : : * \since QGIS 2.16
903 : : */
904 : : void setEvaluateDefaultValues( bool evaluateDefaultValues );
905 : :
906 : : QgsExpressionContext createExpressionContext() const override;
907 : : QgsExpressionContextScope *createExpressionContextScope() const override;
908 : :
909 : : /**
910 : : * The snapping configuration for this project.
911 : : *
912 : : * \since QGIS 3.0
913 : : */
914 : : QgsSnappingConfig snappingConfig() const;
915 : :
916 : : /**
917 : : * A list of layers with which intersections should be avoided.
918 : : *
919 : : * \since QGIS 3.0
920 : : */
921 : : QList<QgsVectorLayer *> avoidIntersectionsLayers() const;
922 : :
923 : : /**
924 : : * Sets the list of layers with which intersections should be avoided.
925 : : * Only used if the avoid intersection mode is set to advanced.
926 : : *
927 : : * \since QGIS 3.0
928 : : */
929 : : void setAvoidIntersectionsLayers( const QList<QgsVectorLayer *> &layers );
930 : :
931 : : /**
932 : : * Sets the avoid intersections mode.
933 : : *
934 : : * \since QGIS 3.14
935 : : */
936 : : void setAvoidIntersectionsMode( const AvoidIntersectionsMode mode );
937 : :
938 : : /**
939 : : * Returns the current avoid intersections mode.
940 : : *
941 : : * \since QGIS 3.14
942 : : */
943 : : AvoidIntersectionsMode avoidIntersectionsMode() const { return mAvoidIntersectionsMode; }
944 : :
945 : : /**
946 : : * A map of custom project variables.
947 : : * To get all available variables including generated ones
948 : : * use QgsExpressionContextUtils::projectScope() instead.
949 : : */
950 : : QVariantMap customVariables() const;
951 : :
952 : : /**
953 : : * A map of custom project variables.
954 : : * Be careful not to set generated variables.
955 : : */
956 : : void setCustomVariables( const QVariantMap &customVariables );
957 : :
958 : : /**
959 : : * Sets project's global labeling engine settings
960 : : * \since QGIS 3.0
961 : : */
962 : : void setLabelingEngineSettings( const QgsLabelingEngineSettings &settings );
963 : :
964 : : /**
965 : : * Returns project's global labeling engine settings
966 : : * \since QGIS 3.0
967 : : */
968 : : const QgsLabelingEngineSettings &labelingEngineSettings() const;
969 : :
970 : : //
971 : : // Functionality from QgsMapLayerRegistry
972 : : //
973 : :
974 : : /**
975 : : * Returns a pointer to the project's internal layer store.
976 : : * /since QGIS 3.0
977 : : */
978 : : QgsMapLayerStore *layerStore();
979 : :
980 : : /**
981 : : * Returns a pointer to the project's internal layer store.
982 : : * /since QGIS 3.0
983 : : */
984 : : SIP_SKIP const QgsMapLayerStore *layerStore() const;
985 : :
986 : : //! Returns the number of registered layers.
987 : : int count() const;
988 : :
989 : : //! Returns the number of registered valid layers.
990 : : int validCount() const;
991 : :
992 : : /**
993 : : * Retrieve a pointer to a registered layer by layer ID.
994 : : * \param layerId ID of layer to retrieve
995 : : * \returns matching layer, or NULLPTR if no matching layer found
996 : : * \see mapLayersByName()
997 : : * \see mapLayers()
998 : : */
999 : : Q_INVOKABLE QgsMapLayer *mapLayer( const QString &layerId ) const;
1000 : :
1001 : : #ifndef SIP_RUN
1002 : :
1003 : : /**
1004 : : * Retrieve a pointer to a registered layer by \p layerId converted
1005 : : * to type T. This is a convenience template.
1006 : : * A NULLPTR will be returned if the layer is not found or
1007 : : * if it cannot be cast to type T.
1008 : : *
1009 : : * \code{cpp}
1010 : : * QgsVectorLayer *layer = project->mapLayer<QgsVectorLayer*>( layerId );
1011 : : * \endcode
1012 : : *
1013 : : * \see mapLayer()
1014 : : * \see mapLayers()
1015 : : *
1016 : : * \since QGIS 3.6
1017 : : */
1018 : : template <class T>
1019 : 3 : T mapLayer( const QString &layerId ) const
1020 : : {
1021 : 3 : return qobject_cast<T>( mapLayer( layerId ) );
1022 : : }
1023 : : #endif
1024 : :
1025 : : /**
1026 : : * Retrieve a list of matching registered layers by layer name.
1027 : : * \param layerName name of layers to match
1028 : : * \returns list of matching layers
1029 : : * \see mapLayer()
1030 : : * \see mapLayers()
1031 : : */
1032 : : QList<QgsMapLayer *> mapLayersByName( const QString &layerName ) const;
1033 : :
1034 : : /**
1035 : : * Retrieves a list of matching registered layers by layer \a shortName.
1036 : : * If layer's short name is empty a match with layer's name is attempted.
1037 : : *
1038 : : * \returns list of matching layers
1039 : : * \see mapLayer()
1040 : : * \see mapLayers()
1041 : : * \since QGIS 3.10
1042 : : */
1043 : : QList<QgsMapLayer *> mapLayersByShortName( const QString &shortName ) const;
1044 : :
1045 : :
1046 : : /**
1047 : : * Returns a map of all registered layers by layer ID.
1048 : : *
1049 : : * \param validOnly if set only valid layers will be returned
1050 : : * \see mapLayer()
1051 : : * \see mapLayersByName()
1052 : : * \see layers()
1053 : : */
1054 : : QMap<QString, QgsMapLayer *> mapLayers( const bool validOnly = false ) const;
1055 : :
1056 : : /**
1057 : : * Returns TRUE if the project comes from a zip archive, FALSE otherwise.
1058 : : */
1059 : : bool isZipped() const;
1060 : :
1061 : : #ifndef SIP_RUN
1062 : :
1063 : : /**
1064 : : * Returns a list of registered map layers with a specified layer type.
1065 : : *
1066 : : * ### Example
1067 : : *
1068 : : * QVector<QgsVectorLayer*> vectorLayers = QgsProject::instance()->layers<QgsVectorLayer*>();
1069 : : *
1070 : : * \note not available in Python bindings
1071 : : * \see mapLayers()
1072 : : * \since QGIS 2.16
1073 : : */
1074 : : template <typename T>
1075 : 0 : QVector<T> layers() const
1076 : : {
1077 : 0 : return mLayerStore->layers<T>();
1078 : : }
1079 : :
1080 : : /**
1081 : : * Retrieves a list of matching registered layers by layer \a shortName with a specified layer type,
1082 : : * if layer's short name is empty a match with layer's name is attempted.
1083 : : *
1084 : : * \param shortName short name of layers to match
1085 : : * \returns list of matching layers
1086 : : * \see mapLayer()
1087 : : * \see mapLayers()
1088 : : * \note not available in Python bindings
1089 : : * \since QGIS 3.10
1090 : : */
1091 : : template <typename T>
1092 : : QVector<T> mapLayersByShortName( const QString &shortName ) const
1093 : : {
1094 : : QVector<T> layers;
1095 : : const auto constMapLayers { mLayerStore->layers<T>() };
1096 : : for ( const auto l : constMapLayers )
1097 : : {
1098 : : if ( ! l->shortName().isEmpty() )
1099 : : {
1100 : : if ( l->shortName() == shortName )
1101 : : layers << l;
1102 : : }
1103 : : else if ( l->name() == shortName )
1104 : : {
1105 : : layers << l;
1106 : : }
1107 : : }
1108 : : return layers;
1109 : : }
1110 : :
1111 : : #endif
1112 : :
1113 : : /**
1114 : : * \brief
1115 : : * Add a list of layers to the map of loaded layers.
1116 : : *
1117 : : * The layersAdded() and layerWasAdded() signals will always be emitted.
1118 : : * The legendLayersAdded() signal is emitted only if addToLegend is TRUE.
1119 : : *
1120 : : * \param mapLayers A list of layer which should be added to the registry
1121 : : * \param addToLegend If TRUE (by default), the layers will be added to the
1122 : : * legend and to the main canvas. If you have a private
1123 : : * layer you can set this parameter to FALSE to hide it.
1124 : : * \param takeOwnership Ownership will be transferred to the layer registry.
1125 : : * If you specify FALSE here you have take care of deleting
1126 : : * the layers yourself. Not available in Python.
1127 : : *
1128 : : * \returns a list of the map layers that were added
1129 : : * successfully. If a layer or already exists in the registry,
1130 : : * it will not be part of the returned QList.
1131 : : *
1132 : : * \note As a side-effect QgsProject is made dirty.
1133 : : * \note takeOwnership is not available in the Python bindings - the registry will always
1134 : : * take ownership
1135 : : * \see addMapLayer()
1136 : : * \since QGIS 1.8
1137 : : */
1138 : : QList<QgsMapLayer *> addMapLayers( const QList<QgsMapLayer *> &mapLayers SIP_TRANSFER,
1139 : : bool addToLegend = true,
1140 : : bool takeOwnership SIP_PYARGREMOVE = true );
1141 : :
1142 : : /**
1143 : : * \brief
1144 : : * Add a layer to the map of loaded layers.
1145 : : *
1146 : : * The layersAdded() and layerWasAdded() signals will always be emitted.
1147 : : * The legendLayersAdded() signal is emitted only if addToLegend is TRUE.
1148 : : * If you are adding multiple layers at once, you should use
1149 : : * addMapLayers() instead.
1150 : : *
1151 : : * \param mapLayer A layer to add to the registry
1152 : : * \param addToLegend If TRUE (by default), the layer will be added to the
1153 : : * legend and to the main canvas. If you have a private
1154 : : * layer you can set this parameter to FALSE to hide it.
1155 : : * \param takeOwnership Ownership will be transferred to the layer registry.
1156 : : * If you specify FALSE here you have take care of deleting
1157 : : * the layer yourself. Not available in Python.
1158 : : *
1159 : : * \returns NULLPTR if unable to add layer, otherwise pointer to newly added layer
1160 : : *
1161 : : * \see addMapLayers
1162 : : *
1163 : : * \note As a side-effect QgsProject is made dirty.
1164 : : * \note Use addMapLayers if adding more than one layer at a time
1165 : : * \note takeOwnership is not available in the Python bindings - the registry will always
1166 : : * take ownership
1167 : : * \see addMapLayers()
1168 : : */
1169 : : QgsMapLayer *addMapLayer( QgsMapLayer *mapLayer SIP_TRANSFER,
1170 : : bool addToLegend = true,
1171 : : bool takeOwnership SIP_PYARGREMOVE = true );
1172 : :
1173 : : /**
1174 : : * \brief
1175 : : * Remove a set of layers from the registry by layer ID.
1176 : : *
1177 : : * The specified layers will be removed from the registry. If the registry has ownership
1178 : : * of any layers these layers will also be deleted.
1179 : : *
1180 : : * \param layerIds list of IDs of the layers to remove
1181 : : *
1182 : : * \note As a side-effect the QgsProject instance is marked dirty.
1183 : : * \see removeMapLayer()
1184 : : * \see removeAllMapLayers()
1185 : : * \since QGIS 1.8
1186 : : */
1187 : : void removeMapLayers( const QStringList &layerIds );
1188 : :
1189 : : //TODO QGIS 4.0 - add PyName alias to avoid list type conversion error
1190 : :
1191 : : /**
1192 : : * \brief
1193 : : * Remove a set of layers from the registry.
1194 : : *
1195 : : * The specified layers will be removed from the registry. If the registry has ownership
1196 : : * of any layers these layers will also be deleted.
1197 : : *
1198 : : * \param layers A list of layers to remove. NULLPTR values are ignored.
1199 : : *
1200 : : * \note As a side-effect the QgsProject instance is marked dirty.
1201 : : * \see removeMapLayer()
1202 : : * \see removeAllMapLayers()
1203 : : */
1204 : : void removeMapLayers( const QList<QgsMapLayer *> &layers );
1205 : :
1206 : : /**
1207 : : * \brief
1208 : : * Remove a layer from the registry by layer ID.
1209 : : *
1210 : : * The specified layer will be removed from the registry. If the registry has ownership
1211 : : * of the layer then it will also be deleted.
1212 : : *
1213 : : * \param layerId ID of the layer to remove
1214 : : *
1215 : : * \note As a side-effect the QgsProject instance is marked dirty.
1216 : : * \see removeMapLayers()
1217 : : * \see removeAllMapLayers()
1218 : : */
1219 : : void removeMapLayer( const QString &layerId );
1220 : :
1221 : : /**
1222 : : * \brief
1223 : : * Remove a layer from the registry.
1224 : : *
1225 : : * The specified layer will be removed from the registry. If the registry has ownership
1226 : : * of the layer then it will also be deleted.
1227 : : *
1228 : : * \param layer The layer to remove. NULLPTR values are ignored.
1229 : : *
1230 : : * \note As a side-effect the QgsProject instance is marked dirty.
1231 : : * \see removeMapLayers()
1232 : : * \see removeAllMapLayers()
1233 : : */
1234 : : void removeMapLayer( QgsMapLayer *layer );
1235 : :
1236 : : /**
1237 : : * Takes a layer from the registry. If the layer was owned by the project, the
1238 : : * layer will be returned without deleting it. The caller takes ownership of
1239 : : * the layer and is responsible for deleting it.
1240 : : * \see removeMapLayer()
1241 : : * \since QGIS 3.0
1242 : : */
1243 : : QgsMapLayer *takeMapLayer( QgsMapLayer *layer ) SIP_TRANSFERBACK;
1244 : :
1245 : : /**
1246 : : * Returns the main annotation layer associated with the project.
1247 : : *
1248 : : * This layer is always present in projects, and will always be rendered
1249 : : * above any other map layers during map render jobs.
1250 : : *
1251 : : * It forms the default location to place new annotation items which
1252 : : * should appear above all map layers.
1253 : : *
1254 : : * \since QGIS 3.16
1255 : : */
1256 : : QgsAnnotationLayer *mainAnnotationLayer();
1257 : :
1258 : : /**
1259 : : * Removes all registered layers. If the registry has ownership
1260 : : * of any layers these layers will also be deleted.
1261 : : *
1262 : : * \note As a side-effect the QgsProject instance is marked dirty.
1263 : : * \note Calling this method will cause the removeAll() signal to
1264 : : * be emitted.
1265 : : * \see removeMapLayer()
1266 : : * \see removeMapLayers()
1267 : : */
1268 : : void removeAllMapLayers();
1269 : :
1270 : : /**
1271 : : * Reload all registered layer's provider data caches, synchronising the layer
1272 : : * with any changes in the datasource.
1273 : : * \see QgsMapLayer::reload()
1274 : : */
1275 : : void reloadAllLayers();
1276 : :
1277 : : /**
1278 : : * Returns the default CRS for new layers based on the settings and
1279 : : * the current project CRS
1280 : : */
1281 : : QgsCoordinateReferenceSystem defaultCrsForNewLayers() const;
1282 : :
1283 : : /**
1284 : : * Sets the trust option allowing to indicate if the extent has to be
1285 : : * read from the XML document when data source has no metadata or if the
1286 : : * data provider has to determine it. Moreover, when this option is
1287 : : * activated, primary key unicity is not checked for views and
1288 : : * materialized views with Postgres provider.
1289 : : *
1290 : : * \param trust TRUE to trust the project, FALSE otherwise
1291 : : *
1292 : : * \since QGIS 3.0
1293 : : */
1294 : : void setTrustLayerMetadata( bool trust );
1295 : :
1296 : : /**
1297 : : * Returns TRUE if the trust option is activated, FALSE otherwise. This
1298 : : * option allows indicateing if the extent has to be read from the XML
1299 : : * document when data source has no metadata or if the data provider has
1300 : : * to determine it. Moreover, when this option is activated, primary key
1301 : : * unicity is not checked for views and materialized views with Postgres
1302 : : * provider.
1303 : : *
1304 : : * \since QGIS 3.0
1305 : : */
1306 : : bool trustLayerMetadata() const { return mTrustLayerMetadata; }
1307 : :
1308 : : /**
1309 : : * Returns the current const auxiliary storage.
1310 : : *
1311 : : * \since QGIS 3.0
1312 : : */
1313 : : const QgsAuxiliaryStorage *auxiliaryStorage() const SIP_SKIP;
1314 : :
1315 : : /**
1316 : : * Returns the current auxiliary storage.
1317 : : *
1318 : : * \since QGIS 3.0
1319 : : */
1320 : : QgsAuxiliaryStorage *auxiliaryStorage();
1321 : :
1322 : : /**
1323 : : * Returns the path to an attached file known by \a fileName.
1324 : : *
1325 : : * \note Not available in Python bindings
1326 : : * \note Attached files are only supported by QGZ file based projects
1327 : : * \see collectAttachedFiles()
1328 : : * \since QGIS 3.8
1329 : : */
1330 : : QString attachedFile( const QString &fileName ) const SIP_SKIP;
1331 : :
1332 : : /**
1333 : : * Returns a map of all attached files with relative paths and real paths.
1334 : : *
1335 : : * \note Not available in Python bindings
1336 : : * \note Attached files are only supported by QGZ file based projects
1337 : : * \see collectAttachedFiles()
1338 : : * \see attachedFile()
1339 : : * \since QGIS 3.8
1340 : : */
1341 : : QgsStringMap attachedFiles() const SIP_SKIP;
1342 : :
1343 : : /**
1344 : : * Returns a reference to the project's metadata store.
1345 : : * \see setMetadata()
1346 : : * \see metadataChanged()
1347 : : * \since QGIS 3.2
1348 : : */
1349 : : const QgsProjectMetadata &metadata() const;
1350 : :
1351 : : /**
1352 : : * Sets the project's \a metadata store.
1353 : : * \see metadata()
1354 : : * \see metadataChanged()
1355 : : * \since QGIS 3.2
1356 : : */
1357 : : void setMetadata( const QgsProjectMetadata &metadata );
1358 : :
1359 : : /**
1360 : : * Returns a set of map layers that are required in the project and therefore they should not get
1361 : : * removed from the project. The set of layers may be configured by users in project properties.
1362 : : * and it is mainly a hint for the user interface to protect users from removing layers that important
1363 : : * in the project. The removeMapLayer(), removeMapLayers() calls do not block removal of layers listed here.
1364 : : * \deprecated since QGIS 3.4 use QgsMapLayer::flags() instead
1365 : : * \since QGIS 3.2
1366 : : */
1367 : : Q_DECL_DEPRECATED QSet<QgsMapLayer *> requiredLayers() const;
1368 : :
1369 : : /**
1370 : : * Configures a set of map layers that are required in the project and therefore they should not get
1371 : : * removed from the project. The set of layers may be configured by users in project properties.
1372 : : * and it is mainly a hint for the user interface to protect users from removing layers that important
1373 : : * in the project. The removeMapLayer(), removeMapLayers() calls do not block removal of layers listed here.
1374 : : * \deprecated since QGIS 3.4 use QgsMapLayer::setFlags() instead
1375 : : * \since QGIS 3.2
1376 : : */
1377 : : Q_DECL_DEPRECATED void setRequiredLayers( const QSet<QgsMapLayer *> &layers );
1378 : :
1379 : : /**
1380 : : * Sets the \a colors for the project's color scheme (see QgsProjectColorScheme).
1381 : : *
1382 : : * \see projectColorsChanged()
1383 : : * \since QGIS 3.6
1384 : : */
1385 : : void setProjectColors( const QgsNamedColorList &colors );
1386 : :
1387 : : /**
1388 : : * Sets the default background \a color used by default map canvases.
1389 : : *
1390 : : * \see backgroundColor()
1391 : : * \since QGIS 3.10
1392 : : */
1393 : : void setBackgroundColor( const QColor &color );
1394 : :
1395 : : /**
1396 : : * Returns the default background color used by default map canvases.
1397 : : *
1398 : : * \see setBackgroundColor()
1399 : : * \since QGIS 3.10
1400 : : */
1401 : : QColor backgroundColor() const;
1402 : :
1403 : : /**
1404 : : * Sets the \a color used to highlight selected features.
1405 : : *
1406 : : * \see selectionColor()
1407 : : * \since QGIS 3.10
1408 : : */
1409 : : void setSelectionColor( const QColor &color );
1410 : :
1411 : : /**
1412 : : * Returns the color used to highlight selected features
1413 : : *
1414 : : * \see setSelectionColor()
1415 : : * \since QGIS 3.10
1416 : : */
1417 : : QColor selectionColor() const;
1418 : :
1419 : : /**
1420 : : * Sets the list of custom project map \a scales.
1421 : : *
1422 : : * The \a scales list consists of a list of scale denominator values, e.g.
1423 : : * 1000 for a 1:1000 scale.
1424 : : *
1425 : : * \see mapScales()
1426 : : * \see mapScalesChanged()
1427 : : *
1428 : : * \deprecated Use viewSettings() instead
1429 : : */
1430 : : Q_DECL_DEPRECATED void setMapScales( const QVector<double> &scales ) SIP_DEPRECATED;
1431 : :
1432 : : /**
1433 : : * Returns the list of custom project map scales.
1434 : : *
1435 : : * The scales list consists of a list of scale denominator values, e.g.
1436 : : * 1000 for a 1:1000 scale.
1437 : : *
1438 : : * \see setMapScales()
1439 : : * \see mapScalesChanged()
1440 : : *
1441 : : * \deprecated Use viewSettings() instead
1442 : : */
1443 : : Q_DECL_DEPRECATED QVector<double> mapScales() const SIP_DEPRECATED;
1444 : :
1445 : : /**
1446 : : * Sets whether project mapScales() are \a enabled.
1447 : : *
1448 : : * \see useProjectScales()
1449 : : * \see setMapScales()
1450 : : *
1451 : : * \deprecated Use viewSettings() instead
1452 : : */
1453 : : Q_DECL_DEPRECATED void setUseProjectScales( bool enabled ) SIP_DEPRECATED;
1454 : :
1455 : : /**
1456 : : * Returns TRUE if project mapScales() are enabled.
1457 : : *
1458 : : * \see setUseProjectScales()
1459 : : * \see mapScales()
1460 : : *
1461 : : * \deprecated Use viewSettings() instead
1462 : : */
1463 : : Q_DECL_DEPRECATED bool useProjectScales() const SIP_DEPRECATED;
1464 : :
1465 : : /**
1466 : : * Triggers the collection strings of .qgs to be included in ts file and calls writeTsFile()
1467 : : * \since QGIS 3.4
1468 : : */
1469 : : void generateTsFile( const QString &locale );
1470 : :
1471 : : /**
1472 : : * Translates the project with QTranslator and qm file
1473 : : * \returns the result string (in case there is no QTranslator loaded the sourceText)
1474 : : *
1475 : : * \param context describing layer etc.
1476 : : * \param sourceText is the identifier of this text
1477 : : * \param disambiguation it's the disambiguation
1478 : : * \param n if -1 uses the appropriate form
1479 : : * \since QGIS 3.4
1480 : : */
1481 : : QString translate( const QString &context, const QString &sourceText, const char *disambiguation = nullptr, int n = -1 ) const override;
1482 : :
1483 : : /**
1484 : : * Accepts the specified style entity \a visitor, causing it to visit all style entities associated
1485 : : * with the project.
1486 : : *
1487 : : * Returns TRUE if the visitor should continue visiting other objects, or FALSE if visiting
1488 : : * should be canceled.
1489 : : *
1490 : : * \since QGIS 3.10
1491 : : */
1492 : : bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
1493 : :
1494 : : #ifdef SIP_RUN
1495 : : SIP_PYOBJECT __repr__();
1496 : : % MethodCode
1497 : : QString str = QStringLiteral( "<QgsProject: '%1'%2>" ).arg( sipCpp->fileName(),
1498 : : sipCpp == QgsProject::instance() ? QStringLiteral( " (singleton instance)" ) : QString() );
1499 : : sipRes = PyUnicode_FromString( str.toUtf8().constData() );
1500 : : % End
1501 : : #endif
1502 : :
1503 : : signals:
1504 : :
1505 : : /**
1506 : : * Emitted when the project is cleared (and additionally when an open project is cleared
1507 : : * just before a new project is read).
1508 : : *
1509 : : * \see clear()
1510 : : * \since QGIS 3.2
1511 : : */
1512 : : void cleared();
1513 : :
1514 : : /**
1515 : : * Emitted when a project is being read.
1516 : : */
1517 : : void readProject( const QDomDocument & );
1518 : :
1519 : : /**
1520 : : * Emitted when a project is being read. And passing the /a context
1521 : : */
1522 : : void readProjectWithContext( const QDomDocument &, QgsReadWriteContext &context );
1523 : :
1524 : : /**
1525 : : * Emitted when the project is being written.
1526 : : */
1527 : : void writeProject( QDomDocument & );
1528 : :
1529 : : /**
1530 : : * Emitted after the basic initialization of a layer from the project
1531 : : * file is done. You can use this signal to read additional information
1532 : : * from the project file.
1533 : : *
1534 : : * \param mapLayer The map layer which is being initialized
1535 : : * \param layerNode The layer node from the project file
1536 : : */
1537 : : void readMapLayer( QgsMapLayer *mapLayer, const QDomElement &layerNode );
1538 : :
1539 : : /**
1540 : : * Emitted when a layer is being saved. You can use this method to save
1541 : : * additional information to the layer.
1542 : : *
1543 : : * \param mapLayer The map layer which is being initialized
1544 : : * \param layerElem The layer element from the project file
1545 : : * \param doc The document
1546 : : */
1547 : : void writeMapLayer( QgsMapLayer *mapLayer, QDomElement &layerElem, QDomDocument &doc );
1548 : :
1549 : : /**
1550 : : * Emitted when the project file has been written and closed.
1551 : : */
1552 : : void projectSaved();
1553 : :
1554 : : /**
1555 : : * Emitted when an old project file is read.
1556 : : */
1557 : : void oldProjectVersionWarning( const QString & );
1558 : :
1559 : : /**
1560 : : * Emitted when a layer from a projects was read.
1561 : : * \param i current layer
1562 : : * \param n number of layers
1563 : : */
1564 : : void layerLoaded( int i, int n );
1565 : :
1566 : : //! Emitted when a layer is loaded
1567 : : void loadingLayer( const QString &layerName );
1568 : :
1569 : : /**
1570 : : * \brief Emitted when loading layers has produced some messages
1571 : : * \param layerName the layer name
1572 : : * \param messages a list of pairs of Qgis::MessageLevel and messages
1573 : : * \since 3.2
1574 : : */
1575 : : void loadingLayerMessageReceived( const QString &layerName, const QList<QgsReadWriteContext::ReadWriteMessage> &messages );
1576 : :
1577 : : /**
1578 : : * Emitted when the list of layer which are excluded from map identification changes
1579 : : * \deprecated since QGIS 3.4
1580 : : */
1581 : : Q_DECL_DEPRECATED void nonIdentifiableLayersChanged( QStringList nonIdentifiableLayers );
1582 : :
1583 : : //! Emitted when the file name of the project changes
1584 : : void fileNameChanged();
1585 : :
1586 : : /**
1587 : : * Emitted when the home path of the project changes.
1588 : : * \see setPresetHomePath()
1589 : : * \see homePath()
1590 : : * \see presetHomePath()
1591 : : */
1592 : : void homePathChanged();
1593 : :
1594 : : /**
1595 : : * Emitted whenever the configuration for snapping has changed.
1596 : : */
1597 : : void snappingConfigChanged( const QgsSnappingConfig &config );
1598 : :
1599 : : /**
1600 : : * Emitted whenever the avoid intersections mode has changed.
1601 : : *
1602 : : * \since QGIS 3.14
1603 : : */
1604 : : void avoidIntersectionsModeChanged();
1605 : :
1606 : : /**
1607 : : * Emitted whenever the expression variables stored in the project have been changed.
1608 : : * \since QGIS 3.0
1609 : : */
1610 : : void customVariablesChanged();
1611 : :
1612 : : /**
1613 : : * Emitted when the CRS of the project has changed.
1614 : : *
1615 : : * \since QGIS 3.0
1616 : : */
1617 : : void crsChanged();
1618 : :
1619 : : /**
1620 : : * Emitted when the project \a ellipsoid is changed.
1621 : : *
1622 : : * \see setEllipsoid()
1623 : : * \see ellipsoid()
1624 : : * \since QGIS 3.0
1625 : : */
1626 : : void ellipsoidChanged( const QString &ellipsoid );
1627 : :
1628 : :
1629 : : /**
1630 : : * Emitted when the project transformContext() is changed.
1631 : : *
1632 : : * \see transformContext()
1633 : : * \since QGIS 3.0
1634 : : */
1635 : : void transformContextChanged();
1636 : :
1637 : : /**
1638 : : * Emitted when datum transforms stored in the project are not available locally.
1639 : : * \since QGIS 3.0
1640 : : */
1641 : : void missingDatumTransforms( const QStringList &missingTransforms );
1642 : :
1643 : : /**
1644 : : * Emitted whenever a new transaction group has been created or a
1645 : : * transaction group has been removed.
1646 : : *
1647 : : * \since QGIS 3.0
1648 : : */
1649 : : void transactionGroupsChanged();
1650 : :
1651 : : /**
1652 : : * Emitted when the topological editing flag has changed.
1653 : : *
1654 : : * \since QGIS 3.0
1655 : : */
1656 : : void topologicalEditingChanged();
1657 : :
1658 : : /**
1659 : : * Emitted whenever avoidIntersectionsLayers has changed.
1660 : : *
1661 : : * \since QGIS 3.0
1662 : : */
1663 : : void avoidIntersectionsLayersChanged();
1664 : :
1665 : : /**
1666 : : * Emitted when the map theme collection changes.
1667 : : * This only happens when the map theme collection is reset.
1668 : : * Any pointer previously received from mapThemeCollection()
1669 : : * must no longer be used after this signal is emitted.
1670 : : * You must still connect to signals from the map theme collection
1671 : : * if you want to be notified about new map themes being added and
1672 : : * map themes being removed.
1673 : : *
1674 : : * \since QGIS 3.0
1675 : : */
1676 : : void mapThemeCollectionChanged();
1677 : :
1678 : : /**
1679 : : * Emitted when global configuration of the labeling engine changes.
1680 : : * \since QGIS 3.0
1681 : : */
1682 : : void labelingEngineSettingsChanged();
1683 : :
1684 : : /**
1685 : : * Emitted when the project's metadata is changed.
1686 : : * \see setMetadata()
1687 : : * \see metadata()
1688 : : * \since QGIS 3.2
1689 : : */
1690 : : void metadataChanged();
1691 : :
1692 : : /**
1693 : : * Emitted whenever the project's color scheme has been changed.
1694 : :
1695 : : * \see setProjectColors()
1696 : : * \since QGIS 3.6
1697 : : */
1698 : : void projectColorsChanged();
1699 : :
1700 : : /**
1701 : : * Emitted whenever the project's canvas background color has been changed.
1702 : :
1703 : : * \see setBackgroundColor()
1704 : : * \since QGIS 3.10
1705 : : */
1706 : : void backgroundColorChanged();
1707 : :
1708 : : /**
1709 : : * Emitted whenever the project's selection color has been changed.
1710 : :
1711 : : * \see setSelectionColor()
1712 : : * \since QGIS 3.10
1713 : : */
1714 : : void selectionColorChanged();
1715 : :
1716 : : //
1717 : : // signals from QgsMapLayerRegistry
1718 : : //
1719 : :
1720 : : /**
1721 : : * Emitted when one or more layers are about to be removed from the registry.
1722 : : *
1723 : : * \param layerIds A list of IDs for the layers which are to be removed.
1724 : : * \see layerWillBeRemoved()
1725 : : * \see layersRemoved()
1726 : : */
1727 : : void layersWillBeRemoved( const QStringList &layerIds );
1728 : :
1729 : : /**
1730 : : * Emitted when one or more layers are about to be removed from the registry.
1731 : : *
1732 : : * \param layers A list of layers which are to be removed.
1733 : : * \see layerWillBeRemoved()
1734 : : * \see layersRemoved()
1735 : : */
1736 : : void layersWillBeRemoved( const QList<QgsMapLayer *> &layers );
1737 : :
1738 : : /**
1739 : : * Emitted when a layer is about to be removed from the registry.
1740 : : *
1741 : : * \param layerId The ID of the layer to be removed.
1742 : : *
1743 : : * \note Consider using layersWillBeRemoved() instead
1744 : : * \see layersWillBeRemoved()
1745 : : * \see layerRemoved()
1746 : : */
1747 : : void layerWillBeRemoved( const QString &layerId );
1748 : :
1749 : : /**
1750 : : * Emitted when a layer is about to be removed from the registry.
1751 : : *
1752 : : * \param layer The layer to be removed.
1753 : : *
1754 : : * \note Consider using layersWillBeRemoved() instead
1755 : : * \see layersWillBeRemoved()
1756 : : * \see layerRemoved()
1757 : : */
1758 : : void layerWillBeRemoved( QgsMapLayer *layer );
1759 : :
1760 : : /**
1761 : : * Emitted after one or more layers were removed from the registry.
1762 : : *
1763 : : * \param layerIds A list of IDs of the layers which were removed.
1764 : : * \see layersWillBeRemoved()
1765 : : */
1766 : : void layersRemoved( const QStringList &layerIds );
1767 : :
1768 : : /**
1769 : : * Emitted after a layer was removed from the registry.
1770 : : *
1771 : : * \param layerId The ID of the layer removed.
1772 : : *
1773 : : * \note Consider using layersRemoved() instead
1774 : : * \see layerWillBeRemoved()
1775 : : */
1776 : : void layerRemoved( const QString &layerId );
1777 : :
1778 : : //TODO QGIS 4.0 - rename to past tense
1779 : :
1780 : : /**
1781 : : * Emitted when all layers are removed, before layersWillBeRemoved() and
1782 : : * layerWillBeRemoved() signals are emitted. The layersWillBeRemoved() and
1783 : : * layerWillBeRemoved() signals will still be emitted following this signal.
1784 : : * You can use this signal to do easy (and fast) cleanup.
1785 : : */
1786 : : void removeAll();
1787 : :
1788 : : /**
1789 : : * Emitted when one or more layers were added to the registry.
1790 : : * This signal is also emitted for layers added to the registry,
1791 : : * but not to the legend.
1792 : : *
1793 : : * \param layers List of layers which have been added.
1794 : : *
1795 : : * \see legendLayersAdded()
1796 : : * \see layerWasAdded()
1797 : : */
1798 : : void layersAdded( const QList<QgsMapLayer *> &layers );
1799 : :
1800 : : /**
1801 : : * Emitted when a layer was added to the registry.
1802 : : *
1803 : : * \note Consider using layersAdded() instead
1804 : : * \see layersAdded()
1805 : : */
1806 : : void layerWasAdded( QgsMapLayer *layer );
1807 : :
1808 : : /**
1809 : : * Emitted, when a layer was added to the registry and the legend.
1810 : : * Layers can also be private layers, which are signalled by
1811 : : * layersAdded() and layerWasAdded() but will not be
1812 : : * advertised by this signal.
1813 : : *
1814 : : * \param layers List of QgsMapLayer which were added to the legend.
1815 : : */
1816 : : void legendLayersAdded( const QList<QgsMapLayer *> &layers );
1817 : :
1818 : : /**
1819 : : * Emitted when the project dirty status changes.
1820 : : *
1821 : : * \param dirty TRUE if the project is in a dirty state and has pending unsaved changes.
1822 : : *
1823 : : * \since QGIS 3.2
1824 : : */
1825 : : void isDirtyChanged( bool dirty );
1826 : :
1827 : : /**
1828 : : * Emitted whenever the project is saved to a qgz file.
1829 : : * This can be used to package additional files into the qgz file by modifying the \a files map.
1830 : : *
1831 : : * Map keys represent relative paths inside the qgz file, map values represent the path to
1832 : : * the source file.
1833 : : *
1834 : : * \note Not available in Python bindings
1835 : : * \note Only will be emitted with QGZ project files
1836 : : * \see attachedFiles()
1837 : : * \see attachedFile()
1838 : : * \since QGIS 3.8
1839 : : */
1840 : : void collectAttachedFiles( QgsStringMap &files SIP_INOUT ) SIP_SKIP;
1841 : :
1842 : : /**
1843 : : * Emitted when the list of custom project map scales changes.
1844 : : *
1845 : : * \see mapScales()
1846 : : * \see setMapScales()
1847 : : *
1848 : : * \deprecated Use viewSettings() instead
1849 : : */
1850 : : Q_DECL_DEPRECATED void mapScalesChanged() SIP_DEPRECATED;
1851 : :
1852 : : public slots:
1853 : :
1854 : : /**
1855 : : * The snapping configuration for this project.
1856 : : *
1857 : : * \since QGIS 3.0
1858 : : */
1859 : : void setSnappingConfig( const QgsSnappingConfig &snappingConfig );
1860 : :
1861 : : // TODO QGIS 4.0 - rename b to dirty
1862 : :
1863 : : /**
1864 : : * Flag the project as dirty (modified). If this flag is set, the user will
1865 : : * be asked to save changes to the project before closing the current project.
1866 : : *
1867 : : * \note promoted to public slot in 2.16
1868 : : * \since QGIS 2.4
1869 : : */
1870 : : void setDirty( bool b = true );
1871 : :
1872 : : /**
1873 : : * Sets the project's home \a path. If an empty path is specified than the
1874 : : * home path will be automatically determined from the project's file path.
1875 : : * \see presetHomePath()
1876 : : * \see homePath()
1877 : : * \see homePathChanged()
1878 : : * \since QGIS 3.2
1879 : : */
1880 : : void setPresetHomePath( const QString &path );
1881 : :
1882 : : /**
1883 : : * Registers the containers that require translation into the translationContext.
1884 : : * This is a recursive function to get all the child containers.
1885 : : *
1886 : : * \param translationContext where the objects will be registered
1887 : : * \param parent parent-container containing list of children
1888 : : * \param layerId to store under the correct context
1889 : : * \since QGIS 3.4
1890 : : */
1891 : : void registerTranslatableContainers( QgsTranslationContext *translationContext, QgsAttributeEditorContainer *parent, const QString &layerId );
1892 : :
1893 : : /**
1894 : : * Registers the objects that require translation into the \a translationContext.
1895 : : * So there can be created a ts file with these values.
1896 : : *
1897 : : * \since QGIS 3.4
1898 : : */
1899 : : void registerTranslatableObjects( QgsTranslationContext *translationContext );
1900 : :
1901 : : /**
1902 : : * Sets the data defined properties used for overrides in user defined server
1903 : : * parameters to \a properties
1904 : : *
1905 : : * \since QGIS 3.14
1906 : : */
1907 : : void setDataDefinedServerProperties( const QgsPropertyCollection &properties );
1908 : :
1909 : : /**
1910 : : * Returns the data defined properties used for overrides in user defined server
1911 : : * parameters
1912 : : *
1913 : : * \since QGIS 3.14
1914 : : */
1915 : : QgsPropertyCollection dataDefinedServerProperties() const;
1916 : :
1917 : : private slots:
1918 : : void onMapLayersAdded( const QList<QgsMapLayer *> &layers );
1919 : : void onMapLayersRemoved( const QList<QgsMapLayer *> &layers );
1920 : : void cleanTransactionGroups( bool force = false );
1921 : :
1922 : : private:
1923 : :
1924 : : static QgsProject *sProject;
1925 : :
1926 : :
1927 : : /**
1928 : : * Read map layers from project file.
1929 : : * \param doc DOM document to parse
1930 : : * \param brokenNodes a list of DOM nodes corresponding to layers that we were unable to load; this could be
1931 : : * because the layers were removed or re-located after the project was last saved
1932 : : * \param flags optional project reading flags
1933 : : * \returns TRUE if function worked; else is FALSE
1934 : : */
1935 : : bool _getMapLayers( const QDomDocument &doc, QList<QDomNode> &brokenNodes, QgsProject::ReadFlags flags = QgsProject::ReadFlags() );
1936 : :
1937 : : /**
1938 : : * Set error message from read/write operation
1939 : : * \note not available in Python bindings
1940 : : */
1941 : : void setError( const QString &errorMessage ) SIP_SKIP;
1942 : :
1943 : : /**
1944 : : * Clear error message
1945 : : * \note not available in Python bindings
1946 : : */
1947 : : void clearError() SIP_SKIP;
1948 : :
1949 : : /**
1950 : : * Creates layer and adds it to maplayer registry.
1951 : : *
1952 : : * The optional \a flags argument can be used to control layer reading behavior.
1953 : : *
1954 : : * \note not available in Python bindings
1955 : : */
1956 : : bool addLayer( const QDomElement &layerElem, QList<QDomNode> &brokenNodes, QgsReadWriteContext &context, QgsProject::ReadFlags flags = QgsProject::ReadFlags() ) SIP_SKIP;
1957 : :
1958 : : /**
1959 : : * The optional \a flags argument can be used to control layer reading behavior.
1960 : : *
1961 : : * \note not available in Python bindings
1962 : : */
1963 : : void initializeEmbeddedSubtree( const QString &projectFilePath, QgsLayerTreeGroup *group, QgsProject::ReadFlags flags = QgsProject::ReadFlags() ) SIP_SKIP;
1964 : :
1965 : : /**
1966 : : * The optional \a flags argument can be used to control layer reading behavior.
1967 : : * \note not available in Python bindings
1968 : : */
1969 : : bool loadEmbeddedNodes( QgsLayerTreeGroup *group, QgsProject::ReadFlags flags = QgsProject::ReadFlags() ) SIP_SKIP;
1970 : :
1971 : : //! Read .qgs file
1972 : : bool readProjectFile( const QString &filename, QgsProject::ReadFlags flags = QgsProject::ReadFlags() );
1973 : :
1974 : : //! Write .qgs file
1975 : : bool writeProjectFile( const QString &filename );
1976 : :
1977 : : //! Unzip .qgz file then read embedded .qgs file
1978 : : bool unzip( const QString &filename, QgsProject::ReadFlags flags = QgsProject::ReadFlags() );
1979 : :
1980 : : //! Zip project
1981 : : bool zip( const QString &filename );
1982 : :
1983 : : //! Save auxiliary storage to database
1984 : : bool saveAuxiliaryStorage( const QString &filename = QString() );
1985 : :
1986 : : //! Returns the property definition used for a data defined server property
1987 : : static QgsPropertiesDefinition &dataDefinedServerPropertyDefinitions();
1988 : :
1989 : : std::unique_ptr< QgsMapLayerStore > mLayerStore;
1990 : :
1991 : : QString mErrorMessage;
1992 : :
1993 : : QgsProjectBadLayerHandler *mBadLayerHandler = nullptr;
1994 : :
1995 : : /**
1996 : : * Embedded layers which are defined in other projects. Key: layer id,
1997 : : * value: pair< project file path, save layer yes / no (e.g. if the layer is part of an embedded group, loading/saving is done by the legend)
1998 : : * If the project file path is empty, QgsProject is going to ignore the layer for saving (e.g. because it is part and managed by an embedded group)
1999 : : */
2000 : : QHash< QString, QPair< QString, bool> > mEmbeddedLayers;
2001 : :
2002 : : QgsSnappingConfig mSnappingConfig;
2003 : : AvoidIntersectionsMode mAvoidIntersectionsMode = AvoidIntersectionsMode::AllowIntersections;
2004 : :
2005 : : QgsRelationManager *mRelationManager = nullptr;
2006 : :
2007 : : std::unique_ptr<QgsAnnotationManager> mAnnotationManager;
2008 : : std::unique_ptr<QgsLayoutManager> mLayoutManager;
2009 : :
2010 : : QgsBookmarkManager *mBookmarkManager = nullptr;
2011 : :
2012 : : QgsProjectViewSettings *mViewSettings = nullptr;
2013 : :
2014 : : QgsProjectTimeSettings *mTimeSettings = nullptr;
2015 : :
2016 : : QgsProjectDisplaySettings *mDisplaySettings = nullptr;
2017 : :
2018 : : QgsLayerTree *mRootGroup = nullptr;
2019 : :
2020 : : QgsLayerTreeRegistryBridge *mLayerTreeRegistryBridge = nullptr;
2021 : :
2022 : : QgsAnnotationLayer *mMainAnnotationLayer = nullptr;
2023 : :
2024 : : //! map of transaction group: QPair( providerKey, connString ) -> transactionGroup
2025 : : QMap< QPair< QString, QString>, QgsTransactionGroup *> mTransactionGroups;
2026 : :
2027 : : std::unique_ptr<QgsMapThemeCollection> mMapThemeCollection;
2028 : :
2029 : : std::unique_ptr<QgsLabelingEngineSettings> mLabelingEngineSettings;
2030 : :
2031 : : QVariantMap mCustomVariables;
2032 : :
2033 : : std::unique_ptr<QgsProjectArchive> mArchive;
2034 : :
2035 : : std::unique_ptr<QgsAuxiliaryStorage> mAuxiliaryStorage;
2036 : :
2037 : : QFile mFile; // current physical project file
2038 : :
2039 : : QString mOriginalPath;
2040 : :
2041 : : QString mSaveUser; // last saved user.
2042 : : QString mSaveUserFull; // last saved user full name.
2043 : : QDateTime mSaveDateTime;
2044 : : QgsProjectVersion mSaveVersion;
2045 : :
2046 : : /**
2047 : : * Manual override for project home path - if empty, home path is automatically
2048 : : * created based on file name.
2049 : : */
2050 : : QString mHomePath;
2051 : : mutable QString mCachedHomePath;
2052 : :
2053 : : QColor mBackgroundColor;
2054 : : QColor mSelectionColor;
2055 : :
2056 : : mutable QgsProjectPropertyKey mProperties; // property hierarchy, TODO: this shouldn't be mutable
2057 : : bool mAutoTransaction = false; // transaction grouped editing
2058 : : bool mEvaluateDefaultValues = false; // evaluate default values immediately
2059 : : QgsCoordinateReferenceSystem mCrs;
2060 : : bool mDirty = false; // project has been modified since it has been read or saved
2061 : : int mDirtyBlockCount = 0;
2062 : : bool mTrustLayerMetadata = false;
2063 : :
2064 : : QgsPropertyCollection mDataDefinedServerProperties;
2065 : :
2066 : : QgsCoordinateTransformContext mTransformContext;
2067 : :
2068 : : QgsProjectMetadata mMetadata;
2069 : :
2070 : : std::unique_ptr< QTranslator > mTranslator;
2071 : :
2072 : : bool mIsBeingDeleted = false;
2073 : :
2074 : : QgsSettings mSettings;
2075 : :
2076 : : mutable std::unique_ptr< QgsExpressionContextScope > mProjectScope;
2077 : :
2078 : : int mBlockSnappingUpdates = 0;
2079 : :
2080 : : friend class QgsProjectDirtyBlocker;
2081 : :
2082 : : // Required to avoid creating a new project in it's destructor
2083 : : friend class QgsProviderRegistry;
2084 : :
2085 : : // Required by QGIS Server for switching the current project instance
2086 : : friend class QgsServer;
2087 : :
2088 : : friend class TestQgsProject;
2089 : :
2090 : : Q_DISABLE_COPY( QgsProject )
2091 : : };
2092 : :
2093 : : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProject::ReadFlags )
2094 : :
2095 : : /**
2096 : : * \brief Temporarily blocks QgsProject "dirtying" for the lifetime of the object.
2097 : : *
2098 : : * QgsProjectDirtyBlocker supports "stacked" blocking, so two QgsProjectDirtyBlockers created
2099 : : * for the same project will both need to be destroyed before the project can be dirtied again.
2100 : : *
2101 : : * Note that QgsProjectDirtyBlocker only blocks calls which set the project as dirty - calls
2102 : : * which set the project as clean are not blocked.
2103 : : *
2104 : : * Python scripts should not use QgsProjectDirtyBlocker directly. Instead, use QgsProject.blockDirtying()
2105 : : * \code{.py}
2106 : : * project = QgsProject.instance()
2107 : : * with QgsProject.blockDirtying(project):
2108 : : * # do something
2109 : : * \endcode
2110 : : *
2111 : : * \see QgsProject::setDirty()
2112 : : *
2113 : : * \ingroup core
2114 : : * \since QGIS 3.2
2115 : : */
2116 : : class CORE_EXPORT QgsProjectDirtyBlocker
2117 : : {
2118 : : public:
2119 : :
2120 : : /**
2121 : : * Constructor for QgsProjectDirtyBlocker.
2122 : : *
2123 : : * This will block dirtying the specified \a project for the lifetime of this object.
2124 : : */
2125 : : QgsProjectDirtyBlocker( QgsProject *project )
2126 : : : mProject( project )
2127 : : {
2128 : : mProject->mDirtyBlockCount++;
2129 : : }
2130 : :
2131 : : //! QgsProjectDirtyBlocker cannot be copied
2132 : : QgsProjectDirtyBlocker( const QgsProjectDirtyBlocker &other ) = delete;
2133 : :
2134 : : //! QgsProjectDirtyBlocker cannot be copied
2135 : : QgsProjectDirtyBlocker &operator=( const QgsProjectDirtyBlocker &other ) = delete;
2136 : :
2137 : : ~QgsProjectDirtyBlocker()
2138 : : {
2139 : : mProject->mDirtyBlockCount--;
2140 : : }
2141 : :
2142 : : private:
2143 : : QgsProject *mProject = nullptr;
2144 : :
2145 : : #ifdef SIP_RUN
2146 : : QgsProjectDirtyBlocker( const QgsProjectDirtyBlocker &other );
2147 : : #endif
2148 : : };
2149 : :
2150 : : /**
2151 : : * Returns the version string found in the given DOM document
2152 : : * \returns the version string or an empty string if none found
2153 : : * \note not available in Python bindings.
2154 : : */
2155 : : CORE_EXPORT QgsProjectVersion getVersion( QDomDocument const &doc ) SIP_SKIP;
2156 : :
2157 : :
2158 : :
2159 : : /// @cond PRIVATE
2160 : : #ifndef SIP_RUN
2161 : 4 : class GetNamedProjectColor : public QgsScopedExpressionFunction
2162 : : {
2163 : : public:
2164 : : GetNamedProjectColor( const QgsProject *project );
2165 : :
2166 : : /**
2167 : : * Optimized constructor for GetNamedProjectColor when a list of map is already available
2168 : : * and does not need to be read from a project.
2169 : : */
2170 : : GetNamedProjectColor( const QHash< QString, QColor > &colors );
2171 : :
2172 : : QVariant func( const QVariantList &values, const QgsExpressionContext *, QgsExpression *, const QgsExpressionNodeFunction * ) override;
2173 : : QgsScopedExpressionFunction *clone() const override;
2174 : :
2175 : : private:
2176 : :
2177 : : QHash< QString, QColor > mColors;
2178 : :
2179 : : };
2180 : :
2181 : : #endif
2182 : : ///@endcond
2183 : :
2184 : : #endif
|
