QGIS API Documentation  3.18.1-Zürich (202f1bf7e5)
Public Types | Public Slots | Signals | Public Member Functions | Static Public Member Functions | Properties | Friends | List of all members
QgsProject Class Reference

Encapsulates a QGIS project, including sets of map layers and their styles, layouts, annotations, canvases, etc. More...

#include <qgsproject.h>

Inheritance diagram for QgsProject:
Inheritance graph
[legend]

Public Types

enum class  AvoidIntersectionsMode { AllowIntersections , AvoidIntersectionsCurrentLayer , AvoidIntersectionsLayers }
 Flags which control how intersections of pre-existing feature are handled when digitizing new features. More...
 
enum  DataDefinedServerProperty { NoProperty = 0 , AllProperties = 1 , WMSOnlineResource = 2 }
 Data defined properties. More...
 
enum class  FileFormat { Qgz , Qgs }
 Flags which control project read behavior. More...
 
enum class  ReadFlag { FlagDontResolveLayers = 1 << 0 , FlagDontLoadLayouts = 1 << 1 , FlagTrustLayerMetadata = 1 << 2 , FlagDontStoreOriginalStyles = 1 << 3 }
 Flags which control project read behavior. More...
 

Public Slots

QgsPropertyCollection dataDefinedServerProperties () const
 Returns the data defined properties used for overrides in user defined server parameters. More...
 
void registerTranslatableContainers (QgsTranslationContext *translationContext, QgsAttributeEditorContainer *parent, const QString &layerId)
 Registers the containers that require translation into the translationContext. More...
 
void registerTranslatableObjects (QgsTranslationContext *translationContext)
 Registers the objects that require translation into the translationContext. More...
 
void setDataDefinedServerProperties (const QgsPropertyCollection &properties)
 Sets the data defined properties used for overrides in user defined server parameters to properties. More...
 
void setDirty (bool b=true)
 Flag the project as dirty (modified). More...
 
void setPresetHomePath (const QString &path)
 Sets the project's home path. More...
 
void setSnappingConfig (const QgsSnappingConfig &snappingConfig)
 The snapping configuration for this project. More...
 

Signals

void avoidIntersectionsLayersChanged ()
 Emitted whenever avoidIntersectionsLayers has changed. More...
 
void avoidIntersectionsModeChanged ()
 Emitted whenever the avoid intersections mode has changed. More...
 
void backgroundColorChanged ()
 Emitted whenever the project's canvas background color has been changed. More...
 
void cleared ()
 Emitted when the project is cleared (and additionally when an open project is cleared just before a new project is read). More...
 
void collectAttachedFiles (QgsStringMap &files)
 Emitted whenever the project is saved to a qgz file. More...
 
void crsChanged ()
 Emitted when the CRS of the project has changed. More...
 
void customVariablesChanged ()
 Emitted whenever the expression variables stored in the project have been changed. More...
 
void ellipsoidChanged (const QString &ellipsoid)
 Emitted when the project ellipsoid is changed. More...
 
void fileNameChanged ()
 Emitted when the file name of the project changes. More...
 
void homePathChanged ()
 Emitted when the home path of the project changes. More...
 
void isDirtyChanged (bool dirty)
 Emitted when the project dirty status changes. More...
 
void labelingEngineSettingsChanged ()
 Emitted when global configuration of the labeling engine changes. More...
 
void layerLoaded (int i, int n)
 Emitted when a layer from a projects was read. More...
 
void layerRemoved (const QString &layerId)
 Emitted after a layer was removed from the registry. More...
 
void layersAdded (const QList< QgsMapLayer * > &layers)
 Emitted when one or more layers were added to the registry. More...
 
void layersRemoved (const QStringList &layerIds)
 Emitted after one or more layers were removed from the registry. More...
 
void layersWillBeRemoved (const QList< QgsMapLayer * > &layers)
 Emitted when one or more layers are about to be removed from the registry. More...
 
void layersWillBeRemoved (const QStringList &layerIds)
 Emitted when one or more layers are about to be removed from the registry. More...
 
void layerWasAdded (QgsMapLayer *layer)
 Emitted when a layer was added to the registry. More...
 
void layerWillBeRemoved (const QString &layerId)
 Emitted when a layer is about to be removed from the registry. More...
 
void layerWillBeRemoved (QgsMapLayer *layer)
 Emitted when a layer is about to be removed from the registry. More...
 
void legendLayersAdded (const QList< QgsMapLayer * > &layers)
 Emitted, when a layer was added to the registry and the legend. More...
 
void loadingLayer (const QString &layerName)
 Emitted when a layer is loaded. More...
 
void loadingLayerMessageReceived (const QString &layerName, const QList< QgsReadWriteContext::ReadWriteMessage > &messages)
 Emitted when loading layers has produced some messages. More...
 
Q_DECL_DEPRECATED void mapScalesChanged ()
 Emitted when the list of custom project map scales changes. More...
 
void mapThemeCollectionChanged ()
 Emitted when the map theme collection changes. More...
 
void metadataChanged ()
 Emitted when the project's metadata is changed. More...
 
void missingDatumTransforms (const QStringList &missingTransforms)
 Emitted when datum transforms stored in the project are not available locally. More...
 
Q_DECL_DEPRECATED void nonIdentifiableLayersChanged (QStringList nonIdentifiableLayers)
 Emitted when the list of layer which are excluded from map identification changes. More...
 
void oldProjectVersionWarning (const QString &)
 Emitted when an old project file is read. More...
 
void projectColorsChanged ()
 Emitted whenever the project's color scheme has been changed. More...
 
void projectSaved ()
 Emitted when the project file has been written and closed. More...
 
void readMapLayer (QgsMapLayer *mapLayer, const QDomElement &layerNode)
 Emitted after the basic initialization of a layer from the project file is done. More...
 
void readProject (const QDomDocument &)
 Emitted when a project is being read. More...
 
void readProjectWithContext (const QDomDocument &, QgsReadWriteContext &context)
 Emitted when a project is being read. More...
 
void removeAll ()
 Emitted when all layers are removed, before layersWillBeRemoved() and layerWillBeRemoved() signals are emitted. More...
 
void selectionColorChanged ()
 Emitted whenever the project's selection color has been changed. More...
 
void snappingConfigChanged (const QgsSnappingConfig &config)
 Emitted whenever the configuration for snapping has changed. More...
 
void topologicalEditingChanged ()
 Emitted when the topological editing flag has changed. More...
 
void transactionGroupsChanged ()
 Emitted whenever a new transaction group has been created or a transaction group has been removed. More...
 
void transformContextChanged ()
 Emitted when the project transformContext() is changed. More...
 
void writeMapLayer (QgsMapLayer *mapLayer, QDomElement &layerElem, QDomDocument &doc)
 Emitted when a layer is being saved. More...
 
void writeProject (QDomDocument &)
 Emitted when the project is being written. More...
 

Public Member Functions

 QgsProject (QObject *parent=nullptr)
 Create a new QgsProject. More...
 
 ~QgsProject () override
 
QString absoluteFilePath () const
 Returns full absolute path to the project file if the project is stored in a file system - derived from fileName(). More...
 
QString absolutePath () const
 Returns full absolute path to the project folder if the project is stored in a file system - derived from fileName(). More...
 
bool accept (QgsStyleEntityVisitorInterface *visitor) const
 Accepts the specified style entity visitor, causing it to visit all style entities associated with the project. More...
 
QgsMapLayeraddMapLayer (QgsMapLayer *mapLayer, bool addToLegend=true, bool takeOwnership=true)
 Add a layer to the map of loaded layers. More...
 
QList< QgsMapLayer * > addMapLayers (const QList< QgsMapLayer * > &mapLayers, bool addToLegend=true, bool takeOwnership=true)
 Add a list of layers to the map of loaded layers. More...
 
QgsAnnotationManagerannotationManager ()
 Returns pointer to the project's annotation manager. More...
 
const QgsAnnotationManagerannotationManager () const
 Returns a const pointer to the project's annotation manager. More...
 
QgsUnitTypes::AreaUnit areaUnits () const
 Convenience function to query default area measurement units for project. More...
 
QString attachedFile (const QString &fileName) const
 Returns the path to an attached file known by fileName. More...
 
QgsStringMap attachedFiles () const
 Returns a map of all attached files with relative paths and real paths. More...
 
bool autoTransaction () const
 Transactional editing means that on supported datasources (postgres databases) the edit state of all tables that originate from the same database are synchronized and executed in a server side transaction. More...
 
QgsAuxiliaryStorageauxiliaryStorage ()
 Returns the current auxiliary storage. More...
 
const QgsAuxiliaryStorageauxiliaryStorage () const
 Returns the current const auxiliary storage. More...
 
QList< QgsVectorLayer * > avoidIntersectionsLayers () const
 A list of layers with which intersections should be avoided. More...
 
AvoidIntersectionsMode avoidIntersectionsMode () const
 Returns the current avoid intersections mode. More...
 
QColor backgroundColor () const
 Returns the default background color used by default map canvases. More...
 
QString baseName () const
 Returns the base name of the project file without the path and without extension - derived from fileName(). More...
 
QgsBookmarkManagerbookmarkManager ()
 Returns the project's bookmark manager, which manages bookmarks within the project. More...
 
const QgsBookmarkManagerbookmarkManager () const
 Returns the project's bookmark manager, which manages bookmarks within the project. More...
 
void clear ()
 Clears the project, removing all settings and resetting it back to an empty, default state. More...
 
int count () const
 Returns the number of registered layers. More...
 
QgsLayerTreeGroupcreateEmbeddedGroup (const QString &groupName, const QString &projectFilePath, const QStringList &invisibleLayers, QgsProject::ReadFlags flags=QgsProject::ReadFlags())
 Create layer group instance defined in an arbitrary project file. More...
 
bool createEmbeddedLayer (const QString &layerId, const QString &projectFilePath, QList< QDomNode > &brokenNodes, bool saveFlag=true, QgsProject::ReadFlags flags=QgsProject::ReadFlags())
 Creates a maplayer instance defined in an arbitrary project file. More...
 
QgsExpressionContext createExpressionContext () const override
 This method needs to be reimplemented in all classes which implement this interface and return an expression context. More...
 
QgsExpressionContextScopecreateExpressionContextScope () const override
 This method needs to be reimplemented in all classes which implement this interface and return an expression context scope. More...
 
QgsCoordinateReferenceSystem crs () const
 Returns the project's native coordinate reference system. More...
 
QVariantMap customVariables () const
 A map of custom project variables. More...
 
QgsCoordinateReferenceSystem defaultCrsForNewLayers () const
 Returns the default CRS for new layers based on the settings and the current project CRS. More...
 
QgsProjectDisplaySettingsdisplaySettings ()
 Returns the project's display settings, which settings and properties relating to how a QgsProject should display values such as map coordinates and bearings. More...
 
const QgsProjectDisplaySettingsdisplaySettings () const
 Returns the project's display settings, which settings and properties relating to how a QgsProject should display values such as map coordinates and bearings. More...
 
QgsUnitTypes::DistanceUnit distanceUnits () const
 Convenience function to query default distance measurement units for project. More...
 
void dumpProperties () const
 Dump out current project properties to stderr. More...
 
QString ellipsoid () const
 Returns a proj string representing the project's ellipsoid setting, e.g., "WGS84". More...
 
QStringList entryList (const QString &scope, const QString &key) const
 Returns a list of child keys with values which exist within the the specified scope and key. More...
 
QString error () const
 Returns error message from previous read/write. More...
 
bool evaluateDefaultValues () const
 Should default values be evaluated on provider side when requested and not when committed. More...
 
Q_DECL_DEPRECATED QFileInfo fileInfo () const
 Returns QFileInfo object for the project's associated file. More...
 
QString fileName () const
 Returns the project's file name. More...
 
void generateTsFile (const QString &locale)
 Triggers the collection strings of .qgs to be included in ts file and calls writeTsFile() More...
 
QString homePath () const
 Returns the project's home path. More...
 
bool isDirty () const
 Returns true if the project has been modified since the last write() More...
 
bool isZipped () const
 Returns true if the project comes from a zip archive, false otherwise. More...
 
const QgsLabelingEngineSettingslabelingEngineSettings () const
 Returns project's global labeling engine settings. More...
 
QDateTime lastModified () const
 Returns last modified time of the project file as returned by the file system (or other project storage). More...
 
QDateTime lastSaveDateTime () const
 Returns the date and time when the project was last saved. More...
 
QgsProjectVersion lastSaveVersion () const
 Returns the QGIS version which the project was last saved using. More...
 
QString layerIsEmbedded (const QString &id) const
 Returns the source project file path if the layer with matching id is embedded from other project file. More...
 
template<typename T >
QVector< T > layers () const
 Returns a list of registered map layers with a specified layer type. More...
 
QgsMapLayerStorelayerStore ()
 Returns a pointer to the project's internal layer store. More...
 
const QgsMapLayerStorelayerStore () const
 Returns a pointer to the project's internal layer store. More...
 
QgsLayerTreeRegistryBridgelayerTreeRegistryBridge () const
 Returns pointer to the helper class that synchronizes map layer registry with layer tree. More...
 
QgsLayerTreelayerTreeRoot () const
 Returns pointer to the root (invisible) node of the project's layer tree. More...
 
QgsLayoutManagerlayoutManager ()
 Returns the project's layout manager, which manages print layouts, atlases and reports within the project. More...
 
const QgsLayoutManagerlayoutManager () const
 Returns the project's layout manager, which manages print layouts, atlases and reports within the project. More...
 
QgsAnnotationLayermainAnnotationLayer ()
 Returns the main annotation layer associated with the project. More...
 
Q_INVOKABLE QgsMapLayermapLayer (const QString &layerId) const
 Retrieve a pointer to a registered layer by layer ID. More...
 
template<class T >
mapLayer (const QString &layerId) const
 Retrieve a pointer to a registered layer by layerId converted to type T. More...
 
QMap< QString, QgsMapLayer * > mapLayers (const bool validOnly=false) const
 Returns a map of all registered layers by layer ID. More...
 
QList< QgsMapLayer * > mapLayersByName (const QString &layerName) const
 Retrieve a list of matching registered layers by layer name. More...
 
QList< QgsMapLayer * > mapLayersByShortName (const QString &shortName) const
 Retrieves a list of matching registered layers by layer shortName. More...
 
template<typename T >
QVector< T > mapLayersByShortName (const QString &shortName) const
 Retrieves a list of matching registered layers by layer shortName with a specified layer type, if layer's short name is empty a match with layer's name is attempted. More...
 
Q_DECL_DEPRECATED QVector< double > mapScales () const
 Returns the list of custom project map scales. More...
 
QgsMapThemeCollectionmapThemeCollection ()
 Returns pointer to the project's map theme collection. More...
 
const QgsProjectMetadatametadata () const
 Returns a reference to the project's metadata store. More...
 
Q_DECL_DEPRECATED QStringList nonIdentifiableLayers () const
 Gets the list of layers which currently should not be taken into account on map identification. More...
 
QString originalPath () const
 Returns the original path associated with the project. More...
 
QgsPathResolver pathResolver () const
 Returns path resolver object with considering whether the project uses absolute or relative paths and using current project's path. More...
 
QString presetHomePath () const
 Returns any manual project home path setting, or an empty string if not set. More...
 
QgsProjectStorageprojectStorage () const
 Returns pointer to project storage implementation that handles read/write of the project file. More...
 
bool read (const QString &filename, QgsProject::ReadFlags flags=QgsProject::ReadFlags())
 Reads given project file from the given file. More...
 
bool read (QgsProject::ReadFlags flags=QgsProject::ReadFlags())
 Reads the project from its currently associated file (see fileName() ). More...
 
bool readBoolEntry (const QString &scope, const QString &key, bool def=false, bool *ok=nullptr) const
 Reads a boolean from the specified scope and key. More...
 
double readDoubleEntry (const QString &scope, const QString &key, double def=0, bool *ok=nullptr) const
 Reads a double from the specified scope and key. More...
 
QString readEntry (const QString &scope, const QString &key, const QString &def=QString(), bool *ok=nullptr) const
 Reads a string from the specified scope and key. More...
 
bool readLayer (const QDomNode &layerNode)
 Reads the layer described in the associated DOM node. More...
 
QStringList readListEntry (const QString &scope, const QString &key, const QStringList &def=QStringList(), bool *ok=nullptr) const
 Reads a string list from the specified scope and key. More...
 
int readNumEntry (const QString &scope, const QString &key, int def=0, bool *ok=nullptr) const
 Reads an integer from the specified scope and key. More...
 
QString readPath (const QString &filename) const
 Transforms a filename read from the project file to an absolute path. More...
 
QgsRelationManagerrelationManager () const
 
void reloadAllLayers ()
 Reload all registered layer's provider data caches, synchronising the layer with any changes in the datasource. More...
 
void removeAllMapLayers ()
 Removes all registered layers. More...
 
bool removeEntry (const QString &scope, const QString &key)
 Remove the given key from the specified scope. More...
 
void removeMapLayer (const QString &layerId)
 Remove a layer from the registry by layer ID. More...
 
void removeMapLayer (QgsMapLayer *layer)
 Remove a layer from the registry. More...
 
void removeMapLayers (const QList< QgsMapLayer * > &layers)
 Remove a set of layers from the registry. More...
 
void removeMapLayers (const QStringList &layerIds)
 Remove a set of layers from the registry by layer ID. More...
 
Q_DECL_DEPRECATED QSet< QgsMapLayer * > requiredLayers () const
 Returns a set of map layers that are required in the project and therefore they should not get removed from the project. More...
 
QString saveUser () const
 Returns the user name that did the last save. More...
 
QString saveUserFullName () const
 Returns the full user name that did the last save. More...
 
QColor selectionColor () const
 Returns the color used to highlight selected features. More...
 
void setAreaUnits (QgsUnitTypes::AreaUnit unit)
 Sets the default area measurement units for the project. More...
 
void setAutoTransaction (bool autoTransaction)
 Transactional editing means that on supported datasources (postgres databases) the edit state of all tables that originate from the same database are synchronized and executed in a server side transaction. More...
 
void setAvoidIntersectionsLayers (const QList< QgsVectorLayer * > &layers)
 Sets the list of layers with which intersections should be avoided. More...
 
void setAvoidIntersectionsMode (const AvoidIntersectionsMode mode)
 Sets the avoid intersections mode. More...
 
void setBackgroundColor (const QColor &color)
 Sets the default background color used by default map canvases. More...
 
void setBadLayerHandler (QgsProjectBadLayerHandler *handler)
 Change handler for missing layers. More...
 
void setCrs (const QgsCoordinateReferenceSystem &crs, bool adjustEllipsoid=false)
 Sets the project's native coordinate reference system. More...
 
void setCustomVariables (const QVariantMap &customVariables)
 A map of custom project variables. More...
 
void setDistanceUnits (QgsUnitTypes::DistanceUnit unit)
 Sets the default distance measurement units for the project. More...
 
void setEllipsoid (const QString &ellipsoid)
 Sets the project's ellipsoid from a proj string representation, e.g., "WGS84". More...
 
void setEvaluateDefaultValues (bool evaluateDefaultValues)
 Defines if default values should be evaluated on provider side when requested and not when committed. More...
 
void setFileName (const QString &name)
 Sets the file name associated with the project. More...
 
void setLabelingEngineSettings (const QgsLabelingEngineSettings &settings)
 Sets project's global labeling engine settings. More...
 
Q_DECL_DEPRECATED void setMapScales (const QVector< double > &scales)
 Sets the list of custom project map scales. More...
 
void setMetadata (const QgsProjectMetadata &metadata)
 Sets the project's metadata store. More...
 
Q_DECL_DEPRECATED void setNonIdentifiableLayers (const QList< QgsMapLayer * > &layers)
 Set a list of layers which should not be taken into account on map identification. More...
 
Q_DECL_DEPRECATED void setNonIdentifiableLayers (const QStringList &layerIds)
 Set a list of layers which should not be taken into account on map identification. More...
 
void setOriginalPath (const QString &path)
 Sets the original path associated with the project. More...
 
void setProjectColors (const QgsNamedColorList &colors)
 Sets the colors for the project's color scheme (see QgsProjectColorScheme). More...
 
Q_DECL_DEPRECATED void setRequiredLayers (const QSet< QgsMapLayer * > &layers)
 Configures a set of map layers that are required in the project and therefore they should not get removed from the project. More...
 
void setSelectionColor (const QColor &color)
 Sets the color used to highlight selected features. More...
 
void setTitle (const QString &title)
 Sets the project's title. More...
 
void setTopologicalEditing (bool enabled)
 Convenience function to set topological editing. More...
 
void setTransformContext (const QgsCoordinateTransformContext &context)
 Sets the project's coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system. More...
 
void setTrustLayerMetadata (bool trust)
 Sets the trust option allowing to indicate if the extent has to be read from the XML document when data source has no metadata or if the data provider has to determine it. More...
 
Q_DECL_DEPRECATED void setUseProjectScales (bool enabled)
 Sets whether project mapScales() are enabled. More...
 
QgsSnappingConfig snappingConfig () const
 The snapping configuration for this project. More...
 
QStringList subkeyList (const QString &scope, const QString &key) const
 Returns a list of child keys which contain other keys that exist within the the specified scope and key. More...
 
QgsMapLayertakeMapLayer (QgsMapLayer *layer)
 Takes a layer from the registry. More...
 
QgsProjectTimeSettingstimeSettings ()
 Returns the project's time settings, which contains the project's temporal range and other time based settings. More...
 
const QgsProjectTimeSettingstimeSettings () const
 Returns the project's time settings, which contains the project's temporal range and other time based settings. More...
 
QString title () const
 Returns the project's title. More...
 
bool topologicalEditing () const
 Convenience function to query topological editing status. More...
 
QgsTransactionGrouptransactionGroup (const QString &providerKey, const QString &connString)
 Returns the matching transaction group from a provider key and connection string. More...
 
QMap< QPair< QString, QString >, QgsTransactionGroup * > transactionGroups ()
 Map of transaction groups. More...
 
QgsCoordinateTransformContext transformContext () const
 Returns a copy of the project's coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system. More...
 
QString translate (const QString &context, const QString &sourceText, const char *disambiguation=nullptr, int n=-1) const override
 Translates the project with QTranslator and qm file. More...
 
bool trustLayerMetadata () const
 Returns true if the trust option is activated, false otherwise. More...
 
Q_DECL_DEPRECATED bool useProjectScales () const
 Returns true if project mapScales() are enabled. More...
 
int validCount () const
 Returns the number of registered valid layers. More...
 
QgsProjectViewSettingsviewSettings ()
 Returns the project's view settings, which contains settings and properties relating to how a QgsProject should be viewed and behave inside a map canvas (e.g. More...
 
const QgsProjectViewSettingsviewSettings () const
 Returns the project's view settings, which contains settings and properties relating to how a QgsProject should be viewed and behave inside a map canvas (e.g. More...
 
bool write ()
 Writes the project to its current associated file (see fileName() ). More...
 
bool write (const QString &filename)
 Writes the project to a file. More...
 
bool writeEntry (const QString &scope, const QString &key, bool value)
 Write a boolean value to the project file. More...
 
bool writeEntry (const QString &scope, const QString &key, const QString &value)
 Write a string value to the project file. More...
 
bool writeEntry (const QString &scope, const QString &key, const QStringList &value)
 Write a string list value to the project file. More...
 
bool writeEntry (const QString &scope, const QString &key, double value)
 Write a double value to the project file. More...
 
bool writeEntry (const QString &scope, const QString &key, int value)
 Write an integer value to the project file. More...
 
QString writePath (const QString &filename) const
 Prepare a filename to save it to the project file. More...
 
- Public Member Functions inherited from QgsExpressionContextGenerator
virtual ~QgsExpressionContextGenerator ()=default
 
- Public Member Functions inherited from QgsExpressionContextScopeGenerator
virtual ~QgsExpressionContextScopeGenerator ()=default
 
- Public Member Functions inherited from QgsProjectTranslator
virtual ~QgsProjectTranslator ()=default
 

Static Public Member Functions

static QgsProjectinstance ()
 Returns the QgsProject singleton instance. More...
 
static void setInstance (QgsProject *project)
 Set the current project singleton instance to project. More...
 

Properties

QList< QgsVectorLayer * > avoidIntersectionsLayers
 
AvoidIntersectionsMode avoidIntersectionsMode
 
QColor backgroundColor
 
QgsCoordinateReferenceSystem crs
 
QString ellipsoid
 
QString fileName
 
QString homePath
 
QgsMapThemeCollectionmapThemeCollection
 
QgsProjectMetadata metadata
 
QStringList nonIdentifiableLayers
 
QgsRelationManagerrelationManager
 
QColor selectionColor
 
QgsSnappingConfig snappingConfig
 
bool topologicalEditing
 
QgsCoordinateTransformContext transformContext
 

Friends

class QgsProjectDirtyBlocker
 
class QgsProviderRegistry
 
class QgsServer
 
class TestQgsProject
 

Detailed Description

Encapsulates a QGIS project, including sets of map layers and their styles, layouts, annotations, canvases, etc.

QgsProject is available both as a singleton (QgsProject::instance()) and for use as standalone objects. The QGIS project singleton always gives access to the canonical project reference open within the main QGIS application.

Note
QgsProject has two general kinds of state to make persistent. (I.e., to read and write.) First, QGIS proprietary information. Second plugin information.

Definition at line 98 of file qgsproject.h.

Member Enumeration Documentation

◆ AvoidIntersectionsMode

Flags which control how intersections of pre-existing feature are handled when digitizing new features.

Since
QGIS 3.14
Enumerator
AllowIntersections 

Overlap with any feature allowed when digitizing new features.

AvoidIntersectionsCurrentLayer 

Overlap with features from the active layer when digitizing new features not allowed.

AvoidIntersectionsLayers 

Overlap with features from a specified list of layers when digitizing new features not allowed.

Definition at line 147 of file qgsproject.h.

◆ DataDefinedServerProperty

Data defined properties.

Overrides of user defined server parameters are stored in a property collection and they can be retrieved using the indexes specified in this enum.

Since
QGIS 3.14
Enumerator
NoProperty 

No property.

AllProperties 

All properties for item.

WMSOnlineResource 

Alias.

Definition at line 163 of file qgsproject.h.

◆ FileFormat

Flags which control project read behavior.

Since
QGIS 3.12
Enumerator
Qgz 

Archive file format, supports auxiliary data.

Qgs 

Project saved in a clear text, does not support auxiliary data.

Definition at line 136 of file qgsproject.h.

◆ ReadFlag

enum QgsProject::ReadFlag
strong

Flags which control project read behavior.

Since
QGIS 3.10
Enumerator
FlagDontResolveLayers 

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.

FlagDontLoadLayouts 

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).

FlagTrustLayerMetadata 

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.

FlagDontStoreOriginalStyles 

Skip the initial XML style storage for layers. Useful for minimising project load times in non-interactive contexts.

Definition at line 123 of file qgsproject.h.

Constructor & Destructor Documentation

◆ QgsProject()

QgsProject::QgsProject ( QObject *  parent = nullptr)
explicit

Create a new QgsProject.

Most of the time you want to use QgsProject::instance() instead as many components of QGIS work with the singleton.

Definition at line 398 of file qgsproject.cpp.

◆ ~QgsProject()

QgsProject::~QgsProject ( )
override

Definition at line 480 of file qgsproject.cpp.

Member Function Documentation

◆ absoluteFilePath()

QString QgsProject::absoluteFilePath ( ) const

Returns full absolute path to the project file if the project is stored in a file system - derived from fileName().

Returns empty string when the project is stored in a project storage (there is no concept of paths for custom project storages).

Since
QGIS 3.2

Definition at line 729 of file qgsproject.cpp.

◆ absolutePath()

QString QgsProject::absolutePath ( ) const

Returns full absolute path to the project folder if the project is stored in a file system - derived from fileName().

Returns empty string when the project is stored in a project storage (there is no concept of paths for custom project storages).

Since
QGIS 3.2

Definition at line 718 of file qgsproject.cpp.

◆ accept()

bool QgsProject::accept ( QgsStyleEntityVisitorInterface visitor) const

Accepts the specified style entity visitor, causing it to visit all style entities associated with the project.

Returns true if the visitor should continue visiting other objects, or false if visiting should be canceled.

Since
QGIS 3.10

Definition at line 3761 of file qgsproject.cpp.

◆ addMapLayer()

QgsMapLayer * QgsProject::addMapLayer ( QgsMapLayer mapLayer,
bool  addToLegend = true,
bool  takeOwnership = true 
)

Add a layer to the map of loaded layers.

The layersAdded() and layerWasAdded() signals will always be emitted. The legendLayersAdded() signal is emitted only if addToLegend is true. If you are adding multiple layers at once, you should use addMapLayers() instead.

Parameters
mapLayerA layer to add to the registry
addToLegendIf true (by default), the layer will be added to the legend and to the main canvas. If you have a private layer you can set this parameter to false to hide it.
takeOwnershipOwnership will be transferred to the layer registry. If you specify false here you have take care of deleting the layer yourself. Not available in Python.
Returns
nullptr if unable to add layer, otherwise pointer to newly added layer
See also
addMapLayers
Note
As a side-effect QgsProject is made dirty.
Use addMapLayers if adding more than one layer at a time
takeOwnership is not available in the Python bindings - the registry will always take ownership
See also
addMapLayers()

Definition at line 3449 of file qgsproject.cpp.

◆ addMapLayers()

QList< QgsMapLayer * > QgsProject::addMapLayers ( const QList< QgsMapLayer * > &  mapLayers,
bool  addToLegend = true,
bool  takeOwnership = true 
)

Add a list of layers to the map of loaded layers.

The layersAdded() and layerWasAdded() signals will always be emitted. The legendLayersAdded() signal is emitted only if addToLegend is true.

Parameters
mapLayersA list of layer which should be added to the registry
addToLegendIf true (by default), the layers will be added to the legend and to the main canvas. If you have a private layer you can set this parameter to false to hide it.
takeOwnershipOwnership will be transferred to the layer registry. If you specify false here you have take care of deleting the layers yourself. Not available in Python.
Returns
a list of the map layers that were added successfully. If a layer or already exists in the registry, it will not be part of the returned QList.
Note
As a side-effect QgsProject is made dirty.
takeOwnership is not available in the Python bindings - the registry will always take ownership
See also
addMapLayer()
Since
QGIS 1.8

Definition at line 3409 of file qgsproject.cpp.

◆ annotationManager() [1/2]

QgsAnnotationManager * QgsProject::annotationManager ( )

Returns pointer to the project's annotation manager.

Since
QGIS 3.0

Definition at line 3183 of file qgsproject.cpp.

◆ annotationManager() [2/2]

const QgsAnnotationManager * QgsProject::annotationManager ( ) const

Returns a const pointer to the project's annotation manager.

Since
QGIS 3.0

Definition at line 3188 of file qgsproject.cpp.

◆ areaUnits()

QgsUnitTypes::AreaUnit QgsProject::areaUnits ( ) const

Convenience function to query default area measurement units for project.

See also
distanceUnits()
Since
QGIS 2.14

Definition at line 3055 of file qgsproject.cpp.

◆ attachedFile()

QString QgsProject::attachedFile ( const QString &  fileName) const

Returns the path to an attached file known by fileName.

Note
Not available in Python bindings
Attached files are only supported by QGZ file based projects
See also
collectAttachedFiles()
Since
QGIS 3.8

◆ attachedFiles()

QgsStringMap QgsProject::attachedFiles ( ) const

Returns a map of all attached files with relative paths and real paths.

Note
Not available in Python bindings
Attached files are only supported by QGZ file based projects
See also
collectAttachedFiles()
attachedFile()
Since
QGIS 3.8

◆ autoTransaction()

bool QgsProject::autoTransaction ( ) const

Transactional editing means that on supported datasources (postgres databases) the edit state of all tables that originate from the same database are synchronized and executed in a server side transaction.

Since
QGIS 2.16

Definition at line 3242 of file qgsproject.cpp.

◆ auxiliaryStorage() [1/2]

QgsAuxiliaryStorage * QgsProject::auxiliaryStorage ( )

Returns the current auxiliary storage.

Since
QGIS 3.0

Definition at line 3613 of file qgsproject.cpp.

◆ auxiliaryStorage() [2/2]

const QgsAuxiliaryStorage * QgsProject::auxiliaryStorage ( ) const

Returns the current const auxiliary storage.

Since
QGIS 3.0

Definition at line 3608 of file qgsproject.cpp.

◆ avoidIntersectionsLayers()

QList< QgsVectorLayer * > QgsProject::avoidIntersectionsLayers ( ) const

A list of layers with which intersections should be avoided.

Since
QGIS 3.0

Definition at line 1914 of file qgsproject.cpp.

◆ avoidIntersectionsLayersChanged

void QgsProject::avoidIntersectionsLayersChanged ( )
signal

Emitted whenever avoidIntersectionsLayers has changed.

Since
QGIS 3.0

◆ avoidIntersectionsMode()

AvoidIntersectionsMode QgsProject::avoidIntersectionsMode ( ) const
inline

Returns the current avoid intersections mode.

Since
QGIS 3.14

Definition at line 943 of file qgsproject.h.

◆ avoidIntersectionsModeChanged

void QgsProject::avoidIntersectionsModeChanged ( )
signal

Emitted whenever the avoid intersections mode has changed.

Since
QGIS 3.14

◆ backgroundColor()

QColor QgsProject::backgroundColor ( ) const

Returns the default background color used by default map canvases.

See also
setBackgroundColor()
Since
QGIS 3.10

Definition at line 3695 of file qgsproject.cpp.

◆ backgroundColorChanged

void QgsProject::backgroundColorChanged ( )
signal

Emitted whenever the project's canvas background color has been changed.

See also
setBackgroundColor()
Since
QGIS 3.10

◆ baseName()

QString QgsProject::baseName ( ) const

Returns the base name of the project file without the path and without extension - derived from fileName().

Since
QGIS 3.2

Definition at line 740 of file qgsproject.cpp.

◆ bookmarkManager() [1/2]

QgsBookmarkManager * QgsProject::bookmarkManager ( )

Returns the project's bookmark manager, which manages bookmarks within the project.

Since
QGIS 3.10

Definition at line 3138 of file qgsproject.cpp.

◆ bookmarkManager() [2/2]

const QgsBookmarkManager * QgsProject::bookmarkManager ( ) const

Returns the project's bookmark manager, which manages bookmarks within the project.

Note
not available in Python bindings
Since
QGIS 3.10

Definition at line 3133 of file qgsproject.cpp.

◆ clear()

void QgsProject::clear ( )

Clears the project, removing all settings and resetting it back to an empty, default state.

See also
cleared()
Since
QGIS 2.4

Definition at line 813 of file qgsproject.cpp.

◆ cleared

void QgsProject::cleared ( )
signal

Emitted when the project is cleared (and additionally when an open project is cleared just before a new project is read).

See also
clear()
Since
QGIS 3.2

◆ collectAttachedFiles

void QgsProject::collectAttachedFiles ( QgsStringMap files)
signal

Emitted whenever the project is saved to a qgz file.

This can be used to package additional files into the qgz file by modifying the files map.

Map keys represent relative paths inside the qgz file, map values represent the path to the source file.

Note
Not available in Python bindings
Only will be emitted with QGZ project files
See also
attachedFiles()
attachedFile()
Since
QGIS 3.8

◆ count()

int QgsProject::count ( ) const

Returns the number of registered layers.

Definition at line 3271 of file qgsproject.cpp.

◆ createEmbeddedGroup()

QgsLayerTreeGroup * QgsProject::createEmbeddedGroup ( const QString &  groupName,
const QString &  projectFilePath,
const QStringList &  invisibleLayers,
QgsProject::ReadFlags  flags = QgsProject::ReadFlags() 
)

Create layer group instance defined in an arbitrary project file.

The optional flags argument can be used to control layer reading behavior.

Since
QGIS 2.4

Definition at line 2906 of file qgsproject.cpp.

◆ createEmbeddedLayer()

bool QgsProject::createEmbeddedLayer ( const QString &  layerId,
const QString &  projectFilePath,
QList< QDomNode > &  brokenNodes,
bool  saveFlag = true,
QgsProject::ReadFlags  flags = QgsProject::ReadFlags() 
)

Creates a maplayer instance defined in an arbitrary project file.

Caller takes ownership.

The optional flags argument can be used to specify flags which control layer reading.

Returns
the layer or 0 in case of error
Note
not available in Python bindings

Definition at line 2811 of file qgsproject.cpp.

◆ createExpressionContext()

QgsExpressionContext QgsProject::createExpressionContext ( ) const
overridevirtual

This method needs to be reimplemented in all classes which implement this interface and return an expression context.

Since
QGIS 3.0

Implements QgsExpressionContextGenerator.

Definition at line 1937 of file qgsproject.cpp.

◆ createExpressionContextScope()

QgsExpressionContextScope * QgsProject::createExpressionContextScope ( ) const
overridevirtual

This method needs to be reimplemented in all classes which implement this interface and return an expression context scope.

Since
QGIS 3.0

Implements QgsExpressionContextScopeGenerator.

Definition at line 1947 of file qgsproject.cpp.

◆ crs()

QgsCoordinateReferenceSystem QgsProject::crs ( ) const

Returns the project's native coordinate reference system.

See also
setCrs()
ellipsoid()
Since
QGIS 3.0

Definition at line 754 of file qgsproject.cpp.

◆ crsChanged

void QgsProject::crsChanged ( )
signal

Emitted when the CRS of the project has changed.

Since
QGIS 3.0

◆ customVariables()

QVariantMap QgsProject::customVariables ( ) const

A map of custom project variables.

To get all available variables including generated ones use QgsExpressionContextUtils::projectScope() instead.

Definition at line 1862 of file qgsproject.cpp.

◆ customVariablesChanged

void QgsProject::customVariablesChanged ( )
signal

Emitted whenever the expression variables stored in the project have been changed.

Since
QGIS 3.0

◆ dataDefinedServerProperties

QgsPropertyCollection QgsProject::dataDefinedServerProperties ( ) const
slot

Returns the data defined properties used for overrides in user defined server parameters.

Since
QGIS 3.14

Definition at line 654 of file qgsproject.cpp.

◆ defaultCrsForNewLayers()

QgsCoordinateReferenceSystem QgsProject::defaultCrsForNewLayers ( ) const

Returns the default CRS for new layers based on the settings and the current project CRS.

Definition at line 3528 of file qgsproject.cpp.

◆ displaySettings() [1/2]

QgsProjectDisplaySettings * QgsProject::displaySettings ( )

Returns the project's display settings, which settings and properties relating to how a QgsProject should display values such as map coordinates and bearings.

Since
QGIS 3.12

Definition at line 3168 of file qgsproject.cpp.

◆ displaySettings() [2/2]

const QgsProjectDisplaySettings * QgsProject::displaySettings ( ) const

Returns the project's display settings, which settings and properties relating to how a QgsProject should display values such as map coordinates and bearings.

Note
not available in Python bindings
Since
QGIS 3.12

Definition at line 3163 of file qgsproject.cpp.

◆ distanceUnits()

QgsUnitTypes::DistanceUnit QgsProject::distanceUnits ( ) const

Convenience function to query default distance measurement units for project.

See also
setDistanceUnits()
areaUnits()
Since
QGIS 2.14

Definition at line 3038 of file qgsproject.cpp.

◆ dumpProperties()

void QgsProject::dumpProperties ( ) const

Dump out current project properties to stderr.

Definition at line 2744 of file qgsproject.cpp.

◆ ellipsoid()

QString QgsProject::ellipsoid ( ) const

Returns a proj string representing the project's ellipsoid setting, e.g., "WGS84".

See also
setEllipsoid()
crs()
Since
QGIS 3.0

Definition at line 774 of file qgsproject.cpp.

◆ ellipsoidChanged

void QgsProject::ellipsoidChanged ( const QString &  ellipsoid)
signal

Emitted when the project ellipsoid is changed.

See also
setEllipsoid()
ellipsoid()
Since
QGIS 3.0

◆ entryList()

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

Returns a list of child keys with values which exist within the the specified scope and key.

This method does not return keys that contain other keys. See subkeyList() to retrieve keys which contain other keys.

Note
equivalent to QgsSettings entryList()

Definition at line 2710 of file qgsproject.cpp.

◆ error()

QString QgsProject::error ( ) const

Returns error message from previous read/write.

Definition at line 2785 of file qgsproject.cpp.

◆ evaluateDefaultValues()

bool QgsProject::evaluateDefaultValues ( ) const

Should default values be evaluated on provider side when requested and not when committed.

Since
QGIS 2.16

Definition at line 3003 of file qgsproject.cpp.

◆ fileInfo()

QFileInfo QgsProject::fileInfo ( ) const

Returns QFileInfo object for the project's associated file.

Note
The use of this method is discouraged since QGIS 3.2 as it only works with project files stored in the file system. It is recommended to use absoluteFilePath(), baseName(), lastModifiedTime() as replacements that are aware of the fact that projects may be saved in other project storages.
See also
fileName()
Deprecated:
since QGIS 3.2 use absoluteFilePath(), baseName() or lastModifiedTime() instead

Definition at line 694 of file qgsproject.cpp.

◆ fileName()

QString QgsProject::fileName ( ) const

Returns the project's file name.

This is the file or the storage URI which contains the project's XML representation.

See also
setFileName()
fileInfo()

Definition at line 679 of file qgsproject.cpp.

◆ fileNameChanged

void QgsProject::fileNameChanged ( )
signal

Emitted when the file name of the project changes.

◆ generateTsFile()

void QgsProject::generateTsFile ( const QString &  locale)

Triggers the collection strings of .qgs to be included in ts file and calls writeTsFile()

Since
QGIS 3.4

Definition at line 3734 of file qgsproject.cpp.

◆ homePath()

QString QgsProject::homePath ( ) const

Returns the project's home path.

This will either be a manually set home path (see presetHomePath()) or the path containing the project file itself.

This method always returns the absolute path to the project's home. See presetHomePath() to retrieve any manual project home path override (e.g. relative home paths).

See also
setPresetHomePath()
presetHomePath()
homePathChanged()

Definition at line 3072 of file qgsproject.cpp.

◆ homePathChanged

void QgsProject::homePathChanged ( )
signal

Emitted when the home path of the project changes.

See also
setPresetHomePath()
homePath()
presetHomePath()

◆ instance()

QgsProject * QgsProject::instance ( )
static

Returns the QgsProject singleton instance.

Definition at line 501 of file qgsproject.cpp.

◆ isDirty()

bool QgsProject::isDirty ( ) const

Returns true if the project has been modified since the last write()

Definition at line 547 of file qgsproject.cpp.

◆ isDirtyChanged

void QgsProject::isDirtyChanged ( bool  dirty)
signal

Emitted when the project dirty status changes.

Parameters
dirtytrue if the project is in a dirty state and has pending unsaved changes.
Since
QGIS 3.2

◆ isZipped()

bool QgsProject::isZipped ( ) const

Returns true if the project comes from a zip archive, false otherwise.

Definition at line 3404 of file qgsproject.cpp.

◆ labelingEngineSettings()

const QgsLabelingEngineSettings & QgsProject::labelingEngineSettings ( ) const

Returns project's global labeling engine settings.

Since
QGIS 3.0

Definition at line 1898 of file qgsproject.cpp.

◆ labelingEngineSettingsChanged

void QgsProject::labelingEngineSettingsChanged ( )
signal

Emitted when global configuration of the labeling engine changes.

Since
QGIS 3.0

◆ lastModified()

QDateTime QgsProject::lastModified ( ) const

Returns last modified time of the project file as returned by the file system (or other project storage).

Since
QGIS 3.2

Definition at line 704 of file qgsproject.cpp.

◆ lastSaveDateTime()

QDateTime QgsProject::lastSaveDateTime ( ) const

Returns the date and time when the project was last saved.

Since
QGIS 3.14

Definition at line 537 of file qgsproject.cpp.

◆ lastSaveVersion()

QgsProjectVersion QgsProject::lastSaveVersion ( ) const

Returns the QGIS version which the project was last saved using.

Since
QGIS 3.14

Definition at line 542 of file qgsproject.cpp.

◆ layerIsEmbedded()

QString QgsProject::layerIsEmbedded ( const QString &  id) const

Returns the source project file path if the layer with matching id is embedded from other project file.

Returns an empty string if the matching layer is not embedded.

Definition at line 2801 of file qgsproject.cpp.

◆ layerLoaded

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

Emitted when a layer from a projects was read.

Parameters
icurrent layer
nnumber of layers

◆ layerRemoved

void QgsProject::layerRemoved ( const QString &  layerId)
signal

Emitted after a layer was removed from the registry.

Parameters
layerIdThe ID of the layer removed.
Note
Consider using layersRemoved() instead
See also
layerWillBeRemoved()

◆ layers()

template<typename T >
QVector<T> QgsProject::layers ( ) const
inline

Returns a list of registered map layers with a specified layer type.

Example

QVector<QgsVectorLayer*> vectorLayers = QgsProject::instance()->layers<QgsVectorLayer*>();
Note
not available in Python bindings
See also
mapLayers()
Since
QGIS 2.16

Definition at line 1075 of file qgsproject.h.

◆ layersAdded

void QgsProject::layersAdded ( const QList< QgsMapLayer * > &  layers)
signal

Emitted when one or more layers were added to the registry.

This signal is also emitted for layers added to the registry, but not to the legend.

Parameters
layersList of layers which have been added.
See also
legendLayersAdded()
layerWasAdded()

◆ layersRemoved

void QgsProject::layersRemoved ( const QStringList &  layerIds)
signal

Emitted after one or more layers were removed from the registry.

Parameters
layerIdsA list of IDs of the layers which were removed.
See also
layersWillBeRemoved()

◆ layerStore() [1/2]

QgsMapLayerStore * QgsProject::layerStore ( )

Returns a pointer to the project's internal layer store.

/since QGIS 3.0

Definition at line 1903 of file qgsproject.cpp.

◆ layerStore() [2/2]

const QgsMapLayerStore * QgsProject::layerStore ( ) const

Returns a pointer to the project's internal layer store.

/since QGIS 3.0

Definition at line 1909 of file qgsproject.cpp.

◆ layersWillBeRemoved [1/2]

void QgsProject::layersWillBeRemoved ( const QList< QgsMapLayer * > &  layers)
signal

Emitted when one or more layers are about to be removed from the registry.

Parameters
layersA list of layers which are to be removed.
See also
layerWillBeRemoved()
layersRemoved()

◆ layersWillBeRemoved [2/2]

void QgsProject::layersWillBeRemoved ( const QStringList &  layerIds)
signal

Emitted when one or more layers are about to be removed from the registry.

Parameters
layerIdsA list of IDs for the layers which are to be removed.
See also
layerWillBeRemoved()
layersRemoved()

◆ layerTreeRegistryBridge()

QgsLayerTreeRegistryBridge* QgsProject::layerTreeRegistryBridge ( ) const
inline

Returns pointer to the helper class that synchronizes map layer registry with layer tree.

Since
QGIS 2.4

Definition at line 814 of file qgsproject.h.

◆ layerTreeRoot()

QgsLayerTree * QgsProject::layerTreeRoot ( ) const

Returns pointer to the root (invisible) node of the project's layer tree.

Since
QGIS 2.4

Definition at line 3173 of file qgsproject.cpp.

◆ layerWasAdded

void QgsProject::layerWasAdded ( QgsMapLayer layer)
signal

Emitted when a layer was added to the registry.

Note
Consider using layersAdded() instead
See also
layersAdded()

◆ layerWillBeRemoved [1/2]

void QgsProject::layerWillBeRemoved ( const QString &  layerId)
signal

Emitted when a layer is about to be removed from the registry.

Parameters
layerIdThe ID of the layer to be removed.
Note
Consider using layersWillBeRemoved() instead
See also
layersWillBeRemoved()
layerRemoved()

◆ layerWillBeRemoved [2/2]

void QgsProject::layerWillBeRemoved ( QgsMapLayer layer)
signal

Emitted when a layer is about to be removed from the registry.

Parameters
layerThe layer to be removed.
Note
Consider using layersWillBeRemoved() instead
See also
layersWillBeRemoved()
layerRemoved()

◆ layoutManager() [1/2]

QgsLayoutManager * QgsProject::layoutManager ( )

Returns the project's layout manager, which manages print layouts, atlases and reports within the project.

Since
QGIS 3.0

Definition at line 3128 of file qgsproject.cpp.

◆ layoutManager() [2/2]

const QgsLayoutManager * QgsProject::layoutManager ( ) const

Returns the project's layout manager, which manages print layouts, atlases and reports within the project.

Note
not available in Python bindings
Since
QGIS 3.0

Definition at line 3123 of file qgsproject.cpp.

◆ legendLayersAdded

void QgsProject::legendLayersAdded ( const QList< QgsMapLayer * > &  layers)
signal

Emitted, when a layer was added to the registry and the legend.

Layers can also be private layers, which are signalled by layersAdded() and layerWasAdded() but will not be advertised by this signal.

Parameters
layersList of QgsMapLayer which were added to the legend.

◆ loadingLayer

void QgsProject::loadingLayer ( const QString &  layerName)
signal

Emitted when a layer is loaded.

◆ loadingLayerMessageReceived

void QgsProject::loadingLayerMessageReceived ( const QString &  layerName,
const QList< QgsReadWriteContext::ReadWriteMessage > &  messages 
)
signal

Emitted when loading layers has produced some messages.

Parameters
layerNamethe layer name
messagesa list of pairs of Qgis::MessageLevel and messages
Since
3.2

◆ mainAnnotationLayer()

QgsAnnotationLayer * QgsProject::mainAnnotationLayer ( )

Returns the main annotation layer associated with the project.

This layer is always present in projects, and will always be rendered above any other map layers during map render jobs.

It forms the default location to place new annotation items which should appear above all map layers.

Since
QGIS 3.16

Definition at line 3488 of file qgsproject.cpp.

◆ mapLayer() [1/2]

QgsMapLayer * QgsProject::mapLayer ( const QString &  layerId) const

Retrieve a pointer to a registered layer by layer ID.

Parameters
layerIdID of layer to retrieve
Returns
matching layer, or nullptr if no matching layer found
See also
mapLayersByName()
mapLayers()

Definition at line 3281 of file qgsproject.cpp.

◆ mapLayer() [2/2]

template<class T >
T QgsProject::mapLayer ( const QString &  layerId) const
inline

Retrieve a pointer to a registered layer by layerId converted to type T.

This is a convenience template. A nullptr will be returned if the layer is not found or if it cannot be cast to type T.

QgsVectorLayer *layer = project->mapLayer<QgsVectorLayer*>( layerId );
Represents a vector layer which manages a vector based data sets.
See also
mapLayer()
mapLayers()
Since
QGIS 3.6

Definition at line 1019 of file qgsproject.h.

◆ mapLayers()

QMap< QString, QgsMapLayer * > QgsProject::mapLayers ( const bool  validOnly = false) const

Returns a map of all registered layers by layer ID.

Parameters
validOnlyif set only valid layers will be returned
See also
mapLayer()
mapLayersByName()
layers()

Definition at line 3518 of file qgsproject.cpp.

◆ mapLayersByName()

QList< QgsMapLayer * > QgsProject::mapLayersByName ( const QString &  layerName) const

Retrieve a list of matching registered layers by layer name.

Parameters
layerNamename of layers to match
Returns
list of matching layers
See also
mapLayer()
mapLayers()

Definition at line 3286 of file qgsproject.cpp.

◆ mapLayersByShortName() [1/2]

QList< QgsMapLayer * > QgsProject::mapLayersByShortName ( const QString &  shortName) const

Retrieves a list of matching registered layers by layer shortName.

If layer's short name is empty a match with layer's name is attempted.

Returns
list of matching layers
See also
mapLayer()
mapLayers()
Since
QGIS 3.10

Definition at line 3291 of file qgsproject.cpp.

◆ mapLayersByShortName() [2/2]

template<typename T >
QVector<T> QgsProject::mapLayersByShortName ( const QString &  shortName) const
inline

Retrieves a list of matching registered layers by layer shortName with a specified layer type, if layer's short name is empty a match with layer's name is attempted.

Parameters
shortNameshort name of layers to match
Returns
list of matching layers
See also
mapLayer()
mapLayers()
Note
not available in Python bindings
Since
QGIS 3.10

Definition at line 1092 of file qgsproject.h.

◆ mapScales()

QVector< double > QgsProject::mapScales ( ) const

Returns the list of custom project map scales.

The scales list consists of a list of scale denominator values, e.g. 1000 for a 1:1000 scale.

See also
setMapScales()
mapScalesChanged()
Deprecated:
Use viewSettings() instead

Definition at line 3719 of file qgsproject.cpp.

◆ mapScalesChanged

Q_DECL_DEPRECATED void QgsProject::mapScalesChanged ( )
signal

Emitted when the list of custom project map scales changes.

See also
mapScales()
setMapScales()
Deprecated:
Use viewSettings() instead

◆ mapThemeCollection()

QgsMapThemeCollection* QgsProject::mapThemeCollection ( )

Returns pointer to the project's map theme collection.

Note
renamed in QGIS 3.0, formerly QgsVisibilityPresetCollection
Since
QGIS 2.12

◆ mapThemeCollectionChanged

void QgsProject::mapThemeCollectionChanged ( )
signal

Emitted when the map theme collection changes.

This only happens when the map theme collection is reset. Any pointer previously received from mapThemeCollection() must no longer be used after this signal is emitted. You must still connect to signals from the map theme collection if you want to be notified about new map themes being added and map themes being removed.

Since
QGIS 3.0

◆ metadata()

const QgsProjectMetadata & QgsProject::metadata ( ) const

Returns a reference to the project's metadata store.

See also
setMetadata()
metadataChanged()
Since
QGIS 3.2

Definition at line 3618 of file qgsproject.cpp.

◆ metadataChanged

void QgsProject::metadataChanged ( )
signal

Emitted when the project's metadata is changed.

See also
setMetadata()
metadata()
Since
QGIS 3.2

◆ missingDatumTransforms

void QgsProject::missingDatumTransforms ( const QStringList &  missingTransforms)
signal

Emitted when datum transforms stored in the project are not available locally.

Since
QGIS 3.0

◆ nonIdentifiableLayers()

QStringList QgsProject::nonIdentifiableLayers ( ) const

Gets the list of layers which currently should not be taken into account on map identification.

Deprecated:
since QGIS 3.4 use QgsMapLayer::setFlags() instead

Definition at line 3227 of file qgsproject.cpp.

◆ nonIdentifiableLayersChanged

Q_DECL_DEPRECATED void QgsProject::nonIdentifiableLayersChanged ( QStringList  nonIdentifiableLayers)
signal

Emitted when the list of layer which are excluded from map identification changes.

Deprecated:
since QGIS 3.4

◆ oldProjectVersionWarning

void QgsProject::oldProjectVersionWarning ( const QString &  )
signal

Emitted when an old project file is read.

◆ originalPath()

QString QgsProject::originalPath ( ) const

Returns the original path associated with the project.

This is intended for use with non-qgs/qgz project files (see QgsCustomProjectOpenHandler) in order to allow custom project open handlers to specify the original file name of the project. For custom project formats, it is NOT appropriate to call setFileName() with the original project path, as this causes the original (non QGIS) project file to be overwritten when the project is next saved.

See also
setOriginalPath()
Since
QGIS 3.14

Definition at line 689 of file qgsproject.cpp.

◆ pathResolver()

QgsPathResolver QgsProject::pathResolver ( ) const

Returns path resolver object with considering whether the project uses absolute or relative paths and using current project's path.

Since
QGIS 3.0

Definition at line 2749 of file qgsproject.cpp.

◆ presetHomePath()

QString QgsProject::presetHomePath ( ) const

Returns any manual project home path setting, or an empty string if not set.

This path may be a relative path. See homePath() to retrieve a path which is always an absolute path.

See also
homePath()
setPresetHomePath()
homePathChanged()
Since
QGIS 3.2

Definition at line 3113 of file qgsproject.cpp.

◆ projectColorsChanged

void QgsProject::projectColorsChanged ( )
signal

Emitted whenever the project's color scheme has been changed.

See also
setProjectColors()
Since
QGIS 3.6

◆ projectSaved

void QgsProject::projectSaved ( )
signal

Emitted when the project file has been written and closed.

◆ projectStorage()

QgsProjectStorage * QgsProject::projectStorage ( ) const

Returns pointer to project storage implementation that handles read/write of the project file.

If the project file is stored in the local file system, returns nullptr. The project storage object is inferred from fileName() of the project.

Since
QGIS 3.2

Definition at line 699 of file qgsproject.cpp.

◆ read() [1/2]

bool QgsProject::read ( const QString &  filename,
QgsProject::ReadFlags  flags = QgsProject::ReadFlags() 
)

Reads given project file from the given file.

Parameters
filenamename of project file to read
flagsoptional flags which control the read behavior of projects
Returns
true if project file has been read successfully

Definition at line 1283 of file qgsproject.cpp.

◆ read() [2/2]

bool QgsProject::read ( QgsProject::ReadFlags  flags = QgsProject::ReadFlags())

Reads the project from its currently associated file (see fileName() ).

The flags argument can be used to specify optional flags which control the read behavior of projects.

Returns
true if project file has been read successfully

Definition at line 1292 of file qgsproject.cpp.

◆ readBoolEntry()

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

Reads a boolean from the specified scope and key.

Parameters
scopeentry scope (group) name
keyentry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
defdefault value to return if the specified key does not exist within the scope.
okset to true if key exists and has been successfully retrieved as a boolean
Returns
entry value as boolean from scope given its key

Definition at line 2676 of file qgsproject.cpp.

◆ readDoubleEntry()

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

Reads a double from the specified scope and key.

Parameters
scopeentry scope (group) name
keyentry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
defdefault value to return if the specified key does not exist within the scope.
okset to true if key exists and has been successfully retrieved as a double
Returns
entry value as double from scope given its key

Definition at line 2654 of file qgsproject.cpp.

◆ readEntry()

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

Reads a string from the specified scope and key.

Parameters
scopeentry scope (group) name
keyentry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
defdefault value to return if the specified key does not exist within the scope.
okset to true if key exists and has been successfully retrieved as a string value
Returns
entry value as string from scope given its key

Definition at line 2601 of file qgsproject.cpp.

◆ readLayer()

bool QgsProject::readLayer ( const QDomNode &  layerNode)

Reads the layer described in the associated DOM node.

Note
This method is mainly for use by QgsProjectBadLayerHandler subclasses that may fix definition of bad layers with the user's help in GUI. Calling this method with corrected DOM node adds the layer back to the project.
Parameters
layerNoderepresents a QgsProject DOM node that encodes a specific layer.

Definition at line 2114 of file qgsproject.cpp.

◆ readListEntry()

QStringList QgsProject::readListEntry ( const QString &  scope,
const QString &  key,
const QStringList &  def = QStringList(),
bool *  ok = nullptr 
) const

Reads a string list from the specified scope and key.

Parameters
scopeentry scope (group) name
keyentry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
defdefault value to return if the specified key does not exist within the scope.
okset to true if key exists and has been successfully retrieved as a string list
Returns
entry value as a string list

Definition at line 2571 of file qgsproject.cpp.

◆ readMapLayer

void QgsProject::readMapLayer ( QgsMapLayer mapLayer,
const QDomElement &  layerNode 
)
signal

Emitted after the basic initialization of a layer from the project file is done.

You can use this signal to read additional information from the project file.

Parameters
mapLayerThe map layer which is being initialized
layerNodeThe layer node from the project file

◆ readNumEntry()

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

Reads an integer from the specified scope and key.

Parameters
scopeentry scope (group) name
keyentry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
defdefault value to return if the specified key does not exist within the scope.
okset to true if key exists and has been successfully retrieved as an integer
Returns
entry value as integer from scope given its key

Definition at line 2627 of file qgsproject.cpp.

◆ readPath()

QString QgsProject::readPath ( const QString &  filename) const

Transforms a filename read from the project file to an absolute path.

Definition at line 2770 of file qgsproject.cpp.

◆ readProject

void QgsProject::readProject ( const QDomDocument &  )
signal

Emitted when a project is being read.

◆ readProjectWithContext

void QgsProject::readProjectWithContext ( const QDomDocument &  ,
QgsReadWriteContext context 
)
signal

Emitted when a project is being read.

And passing the /a context

◆ registerTranslatableContainers

void QgsProject::registerTranslatableContainers ( QgsTranslationContext translationContext,
QgsAttributeEditorContainer *  parent,
const QString &  layerId 
)
slot

Registers the containers that require translation into the translationContext.

This is a recursive function to get all the child containers.

Parameters
translationContextwhere the objects will be registered
parentparent-container containing list of children
layerIdto store under the correct context
Since
QGIS 3.4

Definition at line 578 of file qgsproject.cpp.

◆ registerTranslatableObjects

void QgsProject::registerTranslatableObjects ( QgsTranslationContext translationContext)
slot

Registers the objects that require translation into the translationContext.

So there can be created a ts file with these values.

Since
QGIS 3.4

Definition at line 596 of file qgsproject.cpp.

◆ relationManager()

QgsRelationManager * QgsProject::relationManager ( ) const

Definition at line 3118 of file qgsproject.cpp.

◆ reloadAllLayers()

void QgsProject::reloadAllLayers ( )

Reload all registered layer's provider data caches, synchronising the layer with any changes in the datasource.

See also
QgsMapLayer::reload()

Definition at line 3508 of file qgsproject.cpp.

◆ removeAll

void QgsProject::removeAll ( )
signal

Emitted when all layers are removed, before layersWillBeRemoved() and layerWillBeRemoved() signals are emitted.

The layersWillBeRemoved() and layerWillBeRemoved() signals will still be emitted following this signal. You can use this signal to do easy (and fast) cleanup.

◆ removeAllMapLayers()

void QgsProject::removeAllMapLayers ( )

Removes all registered layers.

If the registry has ownership of any layers these layers will also be deleted.

Note
As a side-effect the QgsProject instance is marked dirty.
Calling this method will cause the removeAll() signal to be emitted.
See also
removeMapLayer()
removeMapLayers()

Definition at line 3493 of file qgsproject.cpp.

◆ removeEntry()

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

Remove the given key from the specified scope.

Definition at line 2698 of file qgsproject.cpp.

◆ removeMapLayer() [1/2]

void QgsProject::removeMapLayer ( const QString &  layerId)

Remove a layer from the registry by layer ID.

The specified layer will be removed from the registry. If the registry has ownership of the layer then it will also be deleted.

Parameters
layerIdID of the layer to remove
Note
As a side-effect the QgsProject instance is marked dirty.
See also
removeMapLayers()
removeAllMapLayers()

Definition at line 3470 of file qgsproject.cpp.

◆ removeMapLayer() [2/2]

void QgsProject::removeMapLayer ( QgsMapLayer layer)

Remove a layer from the registry.

The specified layer will be removed from the registry. If the registry has ownership of the layer then it will also be deleted.

Parameters
layerThe layer to remove. nullptr values are ignored.
Note
As a side-effect the QgsProject instance is marked dirty.
See also
removeMapLayers()
removeAllMapLayers()

Definition at line 3476 of file qgsproject.cpp.

◆ removeMapLayers() [1/2]

void QgsProject::removeMapLayers ( const QList< QgsMapLayer * > &  layers)

Remove a set of layers from the registry.

The specified layers will be removed from the registry. If the registry has ownership of any layers these layers will also be deleted.

Parameters
layersA list of layers to remove. nullptr values are ignored.
Note
As a side-effect the QgsProject instance is marked dirty.
See also
removeMapLayer()
removeAllMapLayers()

Definition at line 3464 of file qgsproject.cpp.

◆ removeMapLayers() [2/2]

void QgsProject::removeMapLayers ( const QStringList &  layerIds)

Remove a set of layers from the registry by layer ID.

The specified layers will be removed from the registry. If the registry has ownership of any layers these layers will also be deleted.

Parameters
layerIdslist of IDs of the layers to remove
Note
As a side-effect the QgsProject instance is marked dirty.
See also
removeMapLayer()
removeAllMapLayers()
Since
QGIS 1.8

Definition at line 3458 of file qgsproject.cpp.

◆ requiredLayers()

QSet< QgsMapLayer * > QgsProject::requiredLayers ( ) const

Returns a set of map layers that are required in the project and therefore they should not get removed from the project.

The set of layers may be configured by users in project properties. and it is mainly a hint for the user interface to protect users from removing layers that important in the project. The removeMapLayer(), removeMapLayers() calls do not block removal of layers listed here.

Deprecated:
since QGIS 3.4 use QgsMapLayer::flags() instead
Since
QGIS 3.2

Definition at line 3636 of file qgsproject.cpp.

◆ saveUser()

QString QgsProject::saveUser ( ) const

Returns the user name that did the last save.

See also
saveUserFullName()
Since
QGIS 3.12

Definition at line 527 of file qgsproject.cpp.

◆ saveUserFullName()

QString QgsProject::saveUserFullName ( ) const

Returns the full user name that did the last save.

See also
saveUser()
Since
QGIS 3.12

Definition at line 532 of file qgsproject.cpp.

◆ selectionColor()

QColor QgsProject::selectionColor ( ) const

Returns the color used to highlight selected features.

See also
setSelectionColor()
Since
QGIS 3.10

Definition at line 3709 of file qgsproject.cpp.

◆ selectionColorChanged

void QgsProject::selectionColorChanged ( )
signal

Emitted whenever the project's selection color has been changed.

See also
setSelectionColor()
Since
QGIS 3.10

◆ setAreaUnits()

void QgsProject::setAreaUnits ( QgsUnitTypes::AreaUnit  unit)

Sets the default area measurement units for the project.

See also
areaUnits()
setDistanceUnits()
Since
QGIS 3.0

Definition at line 3067 of file qgsproject.cpp.

◆ setAutoTransaction()

void QgsProject::setAutoTransaction ( bool  autoTransaction)

Transactional editing means that on supported datasources (postgres databases) the edit state of all tables that originate from the same database are synchronized and executed in a server side transaction.

Make sure that this is only called when all layers are not in edit mode.

Since
QGIS 2.16

Definition at line 3247 of file qgsproject.cpp.

◆ setAvoidIntersectionsLayers()

void QgsProject::setAvoidIntersectionsLayers ( const QList< QgsVectorLayer * > &  layers)

Sets the list of layers with which intersections should be avoided.

Only used if the avoid intersection mode is set to advanced.

Since
QGIS 3.0

Definition at line 1927 of file qgsproject.cpp.

◆ setAvoidIntersectionsMode()

void QgsProject::setAvoidIntersectionsMode ( const AvoidIntersectionsMode  mode)

Sets the avoid intersections mode.

Since
QGIS 3.14

Definition at line 1080 of file qgsproject.cpp.

◆ setBackgroundColor()

void QgsProject::setBackgroundColor ( const QColor &  color)

Sets the default background color used by default map canvases.

See also
backgroundColor()
Since
QGIS 3.10

Definition at line 3686 of file qgsproject.cpp.

◆ setBadLayerHandler()

void QgsProject::setBadLayerHandler ( QgsProjectBadLayerHandler handler)

Change handler for missing layers.

Deletes old handler and takes ownership of the new one.

Definition at line 2795 of file qgsproject.cpp.

◆ setCrs()

void QgsProject::setCrs ( const QgsCoordinateReferenceSystem crs,
bool  adjustEllipsoid = false 
)

Sets the project's native coordinate reference system.

If adjustEllipsoid is set to true, the ellpsoid of this project will be set to the ellipsoid imposed by the CRS.

See also
crs()
setEllipsoid()
Since
QGIS 3.0

Definition at line 759 of file qgsproject.cpp.

◆ setCustomVariables()

void QgsProject::setCustomVariables ( const QVariantMap &  customVariables)

A map of custom project variables.

Be careful not to set generated variables.

Definition at line 1867 of file qgsproject.cpp.

◆ setDataDefinedServerProperties

void QgsProject::setDataDefinedServerProperties ( const QgsPropertyCollection properties)
slot

Sets the data defined properties used for overrides in user defined server parameters to properties.

Since
QGIS 3.14

Definition at line 649 of file qgsproject.cpp.

◆ setDirty

void QgsProject::setDirty ( bool  b = true)
slot

Flag the project as dirty (modified).

If this flag is set, the user will be asked to save changes to the project before closing the current project.

Note
promoted to public slot in 2.16
Since
QGIS 2.4

Definition at line 552 of file qgsproject.cpp.

◆ setDistanceUnits()

void QgsProject::setDistanceUnits ( QgsUnitTypes::DistanceUnit  unit)

Sets the default distance measurement units for the project.

See also
distanceUnits()
setAreaUnits()
Since
QGIS 3.0

Definition at line 3050 of file qgsproject.cpp.

◆ setEllipsoid()

void QgsProject::setEllipsoid ( const QString &  ellipsoid)

Sets the project's ellipsoid from a proj string representation, e.g., "WGS84".

See also
ellipsoid()
setCrs()
Since
QGIS 3.0

Definition at line 782 of file qgsproject.cpp.

◆ setEvaluateDefaultValues()

void QgsProject::setEvaluateDefaultValues ( bool  evaluateDefaultValues)

Defines if default values should be evaluated on provider side when requested and not when committed.

Since
QGIS 2.16

Definition at line 3008 of file qgsproject.cpp.

◆ setFileName()

void QgsProject::setFileName ( const QString &  name)

Sets the file name associated with the project.

This is the file or the storage URI which contains the project's XML representation.

Parameters
nameproject file name
See also
fileName()

Definition at line 659 of file qgsproject.cpp.

◆ setInstance()

void QgsProject::setInstance ( QgsProject project)
static

Set the current project singleton instance to project.

Note
this method is provided mainly for the server, which caches the projects and (potentially) needs to switch the current instance on every request.
Warning
calling this method can have serious, unintended consequences, including instability, data loss and undefined behavior. Use with EXTREME caution!
See also
instance()
Since
QGIS 3.10.11

Definition at line 495 of file qgsproject.cpp.

◆ setLabelingEngineSettings()

void QgsProject::setLabelingEngineSettings ( const QgsLabelingEngineSettings settings)

Sets project's global labeling engine settings.

Since
QGIS 3.0

Definition at line 1892 of file qgsproject.cpp.

◆ setMapScales()

void QgsProject::setMapScales ( const QVector< double > &  scales)

Sets the list of custom project map scales.

The scales list consists of a list of scale denominator values, e.g. 1000 for a 1:1000 scale.

See also
mapScales()
mapScalesChanged()
Deprecated:
Use viewSettings() instead

Definition at line 3714 of file qgsproject.cpp.

◆ setMetadata()

void QgsProject::setMetadata ( const QgsProjectMetadata metadata)

Sets the project's metadata store.

See also
metadata()
metadataChanged()
Since
QGIS 3.2

Definition at line 3623 of file qgsproject.cpp.

◆ setNonIdentifiableLayers() [1/2]

void QgsProject::setNonIdentifiableLayers ( const QList< QgsMapLayer * > &  layers)

Set a list of layers which should not be taken into account on map identification.

Deprecated:
since QGIS 3.4 use QgsMapLayer::setFlags() instead

Definition at line 3193 of file qgsproject.cpp.

◆ setNonIdentifiableLayers() [2/2]

void QgsProject::setNonIdentifiableLayers ( const QStringList &  layerIds)

Set a list of layers which should not be taken into account on map identification.

Deprecated:
since QGIS 3.4 use QgsMapLayer::setFlags() instead

Definition at line 3212 of file qgsproject.cpp.

◆ setOriginalPath()

void QgsProject::setOriginalPath ( const QString &  path)

Sets the original path associated with the project.

This is intended for use with non-qgs/qgz project files (see QgsCustomProjectOpenHandler) in order to allow custom project open handlers to specify the original file name of the project. For custom project formats, it is NOT appropriate to call setFileName() with the original project path, as this causes the original (non QGIS) project file to be overwritten when the project is next saved.

See also
originalPath()
Since
QGIS 3.14

Definition at line 684 of file qgsproject.cpp.

◆ setPresetHomePath

void QgsProject::setPresetHomePath ( const QString &  path)
slot

Sets the project's home path.

If an empty path is specified than the home path will be automatically determined from the project's file path.

See also
presetHomePath()
homePath()
homePathChanged()
Since
QGIS 3.2

Definition at line 564 of file qgsproject.cpp.

◆ setProjectColors()

void QgsProject::setProjectColors ( const QgsNamedColorList colors)

Sets the colors for the project's color scheme (see QgsProjectColorScheme).

See also
projectColorsChanged()
Since
QGIS 3.6

Definition at line 3666 of file qgsproject.cpp.

◆ setRequiredLayers()

void QgsProject::setRequiredLayers ( const QSet< QgsMapLayer * > &  layers)

Configures a set of map layers that are required in the project and therefore they should not get removed from the project.

The set of layers may be configured by users in project properties. and it is mainly a hint for the user interface to protect users from removing layers that important in the project. The removeMapLayer(), removeMapLayers() calls do not block removal of layers listed here.

Deprecated:
since QGIS 3.4 use QgsMapLayer::setFlags() instead
Since
QGIS 3.2

Definition at line 3651 of file qgsproject.cpp.

◆ setSelectionColor()

void QgsProject::setSelectionColor ( const QColor &  color)

Sets the color used to highlight selected features.

See also
selectionColor()
Since
QGIS 3.10

Definition at line 3700 of file qgsproject.cpp.

◆ setSnappingConfig

void QgsProject::setSnappingConfig ( const QgsSnappingConfig snappingConfig)
slot

The snapping configuration for this project.

Since
QGIS 3.0

Definition at line 1070 of file qgsproject.cpp.

◆ setTitle()

void QgsProject::setTitle ( const QString &  title)

Sets the project's title.

Parameters
titlenew title
Note
Since QGIS 3.2 this is just a shortcut to setting the title in the project's metadata().
See also
title()
Since
QGIS 2.4

Definition at line 510 of file qgsproject.cpp.

◆ setTopologicalEditing()

void QgsProject::setTopologicalEditing ( bool  enabled)

Convenience function to set topological editing.

Definition at line 3027 of file qgsproject.cpp.

◆ setTransformContext()

void QgsProject::setTransformContext ( const QgsCoordinateTransformContext context)

Sets the project's coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

See also
transformContext()
transformContextChanged()
Since
QGIS 3.0

Definition at line 797 of file qgsproject.cpp.

◆ setTrustLayerMetadata()

void QgsProject::setTrustLayerMetadata ( bool  trust)

Sets the trust option allowing to indicate if the extent has to be read from the XML document when data source has no metadata or if the data provider has to determine it.

Moreover, when this option is activated, primary key unicity is not checked for views and materialized views with Postgres provider.

Parameters
trusttrue to trust the project, false otherwise
Since
QGIS 3.0

Definition at line 3550 of file qgsproject.cpp.

◆ setUseProjectScales()

void QgsProject::setUseProjectScales ( bool  enabled)

Sets whether project mapScales() are enabled.

See also
useProjectScales()
setMapScales()
Deprecated:
Use viewSettings() instead

Definition at line 3724 of file qgsproject.cpp.

◆ snappingConfig()

QgsSnappingConfig QgsProject::snappingConfig ( ) const

The snapping configuration for this project.

Since
QGIS 3.0

Definition at line 1065 of file qgsproject.cpp.

◆ snappingConfigChanged

void QgsProject::snappingConfigChanged ( const QgsSnappingConfig config)
signal

Emitted whenever the configuration for snapping has changed.

◆ subkeyList()

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

Returns a list of child keys which contain other keys that exist within the the specified scope and key.

This method only returns keys with keys, it will not return keys that contain only values. See entryList() to retrieve keys with values.

Note
equivalent to QgsSettings subkeyList()

Definition at line 2727 of file qgsproject.cpp.

◆ takeMapLayer()

QgsMapLayer * QgsProject::takeMapLayer ( QgsMapLayer layer)

Takes a layer from the registry.

If the layer was owned by the project, the layer will be returned without deleting it. The caller takes ownership of the layer and is responsible for deleting it.

See also
removeMapLayer()
Since
QGIS 3.0

Definition at line 3482 of file qgsproject.cpp.

◆ timeSettings() [1/2]

QgsProjectTimeSettings * QgsProject::timeSettings ( )

Returns the project's time settings, which contains the project's temporal range and other time based settings.

Since
QGIS 3.14

Definition at line 3158 of file qgsproject.cpp.

◆ timeSettings() [2/2]

const QgsProjectTimeSettings * QgsProject::timeSettings ( ) const

Returns the project's time settings, which contains the project's temporal range and other time based settings.

Note
not available in Python bindings
Since
QGIS 3.14

Definition at line 3153 of file qgsproject.cpp.

◆ title()

QString QgsProject::title ( ) const

Returns the project's title.

See also
setTitle()
Note
Since QGIS 3.2 this is just a shortcut to retrieving the title from the project's metadata().

Definition at line 522 of file qgsproject.cpp.

◆ topologicalEditing()

bool QgsProject::topologicalEditing ( ) const

Convenience function to query topological editing status.

Definition at line 3033 of file qgsproject.cpp.

◆ topologicalEditingChanged

void QgsProject::topologicalEditingChanged ( )
signal

Emitted when the topological editing flag has changed.

Since
QGIS 3.0

◆ transactionGroup()

QgsTransactionGroup * QgsProject::transactionGroup ( const QString &  providerKey,
const QString &  connString 
)

Returns the matching transaction group from a provider key and connection string.

Returns nullptr if a matching transaction group is not available.

Since
QGIS 3.2

Definition at line 3523 of file qgsproject.cpp.

◆ transactionGroups()

QMap< QPair< QString, QString >, QgsTransactionGroup * > QgsProject::transactionGroups ( )

Map of transaction groups.

QPair( providerKey, connString ) -> transactionGroup

Note
Not available in Python bindings
Since
QGIS 2.16

Definition at line 3260 of file qgsproject.cpp.

◆ transactionGroupsChanged

void QgsProject::transactionGroupsChanged ( )
signal

Emitted whenever a new transaction group has been created or a transaction group has been removed.

Since
QGIS 3.0

◆ transformContext()

QgsCoordinateTransformContext QgsProject::transformContext ( ) const

Returns a copy of the project's coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

See also
setTransformContext()
transformContextChanged()
Since
QGIS 3.0

Definition at line 792 of file qgsproject.cpp.

◆ transformContextChanged

void QgsProject::transformContextChanged ( )
signal

Emitted when the project transformContext() is changed.

See also
transformContext()
Since
QGIS 3.0

◆ translate()

QString QgsProject::translate ( const QString &  context,
const QString &  sourceText,
const char *  disambiguation = nullptr,
int  n = -1 
) const
overridevirtual

Translates the project with QTranslator and qm file.

Returns
the result string (in case there is no QTranslator loaded the sourceText)
Parameters
contextdescribing layer etc.
sourceTextis the identifier of this text
disambiguationit's the disambiguation
nif -1 uses the appropriate form
Since
QGIS 3.4

Implements QgsProjectTranslator.

Definition at line 3745 of file qgsproject.cpp.

◆ trustLayerMetadata()

bool QgsProject::trustLayerMetadata ( ) const
inline

Returns true if the trust option is activated, false otherwise.

This option allows indicateing if the extent has to be read from the XML document when data source has no metadata or if the data provider has to determine it. Moreover, when this option is activated, primary key unicity is not checked for views and materialized views with Postgres provider.

Since
QGIS 3.0

Definition at line 1306 of file qgsproject.h.

◆ useProjectScales()

bool QgsProject::useProjectScales ( ) const

Returns true if project mapScales() are enabled.

See also
setUseProjectScales()
mapScales()
Deprecated:
Use viewSettings() instead

Definition at line 3729 of file qgsproject.cpp.

◆ validCount()

int QgsProject::validCount ( ) const

Returns the number of registered valid layers.

Definition at line 3276 of file qgsproject.cpp.

◆ viewSettings() [1/2]

QgsProjectViewSettings * QgsProject::viewSettings ( )

Returns the project's view settings, which contains settings and properties relating to how a QgsProject should be viewed and behave inside a map canvas (e.g.

map scales and default view extent)

Since
QGIS 3.10.1

Definition at line 3148 of file qgsproject.cpp.

◆ viewSettings() [2/2]

const QgsProjectViewSettings * QgsProject::viewSettings ( ) const

Returns the project's view settings, which contains settings and properties relating to how a QgsProject should be viewed and behave inside a map canvas (e.g.

map scales and default view extent)

Note
not available in Python bindings
Since
QGIS 3.10.1

Definition at line 3143 of file qgsproject.cpp.

◆ write() [1/2]

bool QgsProject::write ( )

Writes the project to its current associated file (see fileName() ).

Returns
true if project was written successfully
Note
isDirty() will be set to false if project is successfully written

Definition at line 2145 of file qgsproject.cpp.

◆ write() [2/2]

bool QgsProject::write ( const QString &  filename)

Writes the project to a file.

Parameters
filenamedestination file
Returns
true if project was written successfully
Note
calling this implicitly sets the project's filename (see setFileName() )
isDirty() will be set to false if project is successfully written
Since
QGIS 3.0

Definition at line 2138 of file qgsproject.cpp.

◆ writeEntry() [1/5]

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

Write a boolean value to the project file.

Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values

Note
The key string must be valid xml tag names in order to be saved to the file.
available in Python bindings as writeEntryBool
See also
readBoolEntry()

Definition at line 2516 of file qgsproject.cpp.

◆ writeEntry() [2/5]

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

Write a string value to the project file.

Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values

Note
The key string must be valid xml tag names in order to be saved to the file.
See also
readEntry()

Definition at line 2549 of file qgsproject.cpp.

◆ writeEntry() [3/5]

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

Write a string list value to the project file.

Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values

Note
The key string must be valid xml tag names in order to be saved to the file.
See also
readListEntry()

Definition at line 2560 of file qgsproject.cpp.

◆ writeEntry() [4/5]

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

Write a double value to the project file.

Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values

Note
The key string must be valid xml tag names in order to be saved to the file.
available in Python bindings as writeEntryDouble
See also
readDoubleEntry()

Definition at line 2527 of file qgsproject.cpp.

◆ writeEntry() [5/5]

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

Write an integer value to the project file.

Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values

Note
The key string must be valid xml tag names in order to be saved to the file.
See also
readNumEntry()

Definition at line 2538 of file qgsproject.cpp.

◆ writeMapLayer

void QgsProject::writeMapLayer ( QgsMapLayer mapLayer,
QDomElement &  layerElem,
QDomDocument &  doc 
)
signal

Emitted when a layer is being saved.

You can use this method to save additional information to the layer.

Parameters
mapLayerThe map layer which is being initialized
layerElemThe layer element from the project file
docThe document

◆ writePath()

QString QgsProject::writePath ( const QString &  filename) const

Prepare a filename to save it to the project file.

Creates an absolute or relative path according to the project settings. Paths written to the project file should be prepared with this method.

Definition at line 2775 of file qgsproject.cpp.

◆ writeProject

void QgsProject::writeProject ( QDomDocument &  )
signal

Emitted when the project is being written.

Friends And Related Function Documentation

◆ QgsProjectDirtyBlocker

friend class QgsProjectDirtyBlocker
friend

Definition at line 2080 of file qgsproject.h.

◆ QgsProviderRegistry

friend class QgsProviderRegistry
friend

Definition at line 2083 of file qgsproject.h.

◆ QgsServer

friend class QgsServer
friend

Definition at line 2086 of file qgsproject.h.

◆ TestQgsProject

friend class TestQgsProject
friend

Definition at line 2088 of file qgsproject.h.

Property Documentation

◆ avoidIntersectionsLayers

QList<QgsVectorLayer *> QgsProject::avoidIntersectionsLayers
readwrite

Definition at line 2155 of file qgsproject.h.

◆ avoidIntersectionsMode

AvoidIntersectionsMode QgsProject::avoidIntersectionsMode
readwrite

Definition at line 2155 of file qgsproject.h.

◆ backgroundColor

QColor QgsProject::backgroundColor
readwrite

Definition at line 2155 of file qgsproject.h.

◆ crs

QgsCoordinateReferenceSystem QgsProject::crs
readwrite

Definition at line 2155 of file qgsproject.h.

◆ ellipsoid

QString QgsProject::ellipsoid
readwrite

Definition at line 2155 of file qgsproject.h.

◆ fileName

QString QgsProject::fileName
readwrite

Definition at line 2155 of file qgsproject.h.

◆ homePath

QString QgsProject::homePath
readwrite

Definition at line 2155 of file qgsproject.h.

◆ mapThemeCollection

QgsMapThemeCollection * QgsProject::mapThemeCollection
read

Definition at line 2155 of file qgsproject.h.

◆ metadata

QgsProjectMetadata QgsProject::metadata
readwrite

Definition at line 2155 of file qgsproject.h.

◆ nonIdentifiableLayers

QStringList QgsProject::nonIdentifiableLayers
readwrite

Definition at line 2155 of file qgsproject.h.

◆ relationManager

QgsRelationManager * QgsProject::relationManager
read

Definition at line 2155 of file qgsproject.h.

◆ selectionColor

QColor QgsProject::selectionColor
readwrite

Definition at line 2155 of file qgsproject.h.

◆ snappingConfig

QgsSnappingConfig QgsProject::snappingConfig
readwrite

Definition at line 2155 of file qgsproject.h.

◆ topologicalEditing

bool QgsProject::topologicalEditing
readwrite

Definition at line 2155 of file qgsproject.h.

◆ transformContext

QgsCoordinateTransformContext QgsProject::transformContext
readwrite

Definition at line 2155 of file qgsproject.h.


The documentation for this class was generated from the following files: