This class is a composition of two QSettings instances: More...

#include <qgssettings.h>

Inheritance diagram for QgsSettings:

Public Types
enum	Section { NoSection , Core , Gui , Server , Plugins , Auth , App , Providers , Expressions , Misc , Gps }
	Sections for namespaced settings. More...

Public Member Functions
	QgsSettings (const QString &fileName, QSettings::Format format, QObject *parent=nullptr)
	Constructs a QgsSettings object for accessing the settings stored in the file called fileName, with parent parent.

	QgsSettings (const QString &organization, const QString &application=QString(), QObject *parent=nullptr)
	Constructs a QgsSettings object for accessing settings of the application called application from the organization called organization, and with parent parent.

	QgsSettings (QObject *parent=nullptr)
	Constructs a QgsSettings object for accessing settings of the application and organization set previously with a call to QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain(), and QCoreApplication::setApplicationName().

	QgsSettings (QSettings::Format format, QSettings::Scope scope, const QString &organization, const QString &application=QString(), QObject *parent=nullptr)
	Constructs a QgsSettings object for accessing settings of the application called application from the organization called organization, and with parent parent.

	QgsSettings (QSettings::Scope scope, const QString &organization, const QString &application=QString(), QObject *parent=nullptr)
	Constructs a QgsSettings object for accessing settings of the application called application from the organization called organization, and with parent parent.

	~QgsSettings () override

QStringList	allKeys () const
	Returns a list of all keys, including subkeys, that can be read using the QSettings object.

void	beginGroup (const QString &prefix, QgsSettings::Section section=QgsSettings::NoSection)
	Appends prefix to the current group.

int	beginReadArray (const QString &prefix)
	Adds prefix to the current group and starts reading from an array. Returns the size of the array.

void	beginWriteArray (const QString &prefix, int size=-1)
	Adds prefix to the current group and starts writing an array of size size.

QStringList	childGroups (Qgis::SettingsOrigin origin=Qgis::SettingsOrigin::Any) const
	Returns a list of all key top-level groups that contain keys that can be read using the QSettings object.

QStringList	childKeys () const
	Returns a list of all top-level keys that can be read using the QSettings object.

void	clear ()
	Removes all entries in the user settings.

bool	contains (const QString &key, QgsSettings::Section section=QgsSettings::NoSection) const
	Returns `true` if there exists a setting called key; returns `false` otherwise.

void	endArray ()
	Closes the array that was started using beginReadArray() or beginWriteArray().

void	endGroup ()
	Resets the group to what it was before the corresponding beginGroup() call.

template<class T >
T	enumValue (const QString &key, const T &defaultValue, const Section section=NoSection)
	Returns the setting value for a setting based on an enum.

QString	fileName () const
	Returns the path where settings written using this QSettings object are stored.

template<class T >
T	flagValue (const QString &key, const T &defaultValue, const Section section=NoSection)
	Returns the setting value for a setting based on a flag.

QStringList	globalChildGroups () const
	Returns a list of all key top-level groups (same as childGroups) but only for groups defined in global settings.

QString	group () const
	Returns the current group.

Qgis::SettingsOrigin	origin (const QString &key) const
	Returns the origin of the setting if it exists at the given key.

QString	prefixedKey (const QString &key, QgsSettings::Section section) const
	Returns the sanitized and prefixed key.

void	remove (const QString &key, QgsSettings::Section section=QgsSettings::NoSection)
	Removes the setting key and any sub-settings of key in a section.

void	setArrayIndex (int i)
	Sets the current array index to i.

template<class T >
void	setEnumValue (const QString &key, const T &value, const Section section=NoSection)
	Set the value of a setting based on an enum.

template<class T >
void	setFlagValue (const QString &key, const T &value, const Section section=NoSection)
	Set the value of a setting based on a flag.

void	setValue (const QString &key, const QVariant &value, QgsSettings::Section section=QgsSettings::NoSection)
	Sets the value of setting key to value.

void	sync ()
	Writes any unsaved changes to permanent storage, and reloads any settings that have been changed in the meantime by another application.

QVariant	value (const QString &key, const QVariant &defaultValue=QVariant(), Section section=NoSection) const
	Returns the value for setting key.

Static Public Member Functions
static QgsSettingsProxy	get ()
	Returns a proxy for a QgsSettings object.

static QString	globalSettingsPath ()
	Returns the path to the Global Settings QSettings storage file.

static void	holdFlush ()
	Temporarily places a hold on flushing QgsSettings objects and writing new values to the underlying ini files.

static void	releaseFlush ()
	Releases a previously made hold on flushing QgsSettings objects and writing new values to the underlying ini files.

static bool	setGlobalSettingsPath (const QString &path)
	Sets the Global Settings QSettings storage file.

Detailed Description

This class is a composition of two QSettings instances:

the main QSettings instance is the standard User Settings and
the second one (Global Settings) is meant to provide read-only pre-configuration and defaults to the first one.

For a given settings key, the function call to value(key, default) will return the first existing setting in the order specified below:

User Settings
Global Settings
Default Value

The path to the Global Settings storage can be set before constructing the QgsSettings objects, with a static call to: static bool setGlobalSettingsPath( QString path );

QgsSettings provides some shortcuts to get/set namespaced settings from/to a specific section:

Core
Gui
Server
Plugins
Auth
App
Providers
Misc

Definition at line 63 of file qgssettings.h.

Member Enumeration Documentation

◆ Section

enum QgsSettings::Section

Sections for namespaced settings.

Enumerator
NoSection
Core
Gui
Server
Plugins
Auth
App
Providers
Expressions
Misc
Gps	GPS section, since QGIS 3.22.

Definition at line 69 of file qgssettings.h.

Constructor & Destructor Documentation

◆ QgsSettings() [1/5]

QgsSettings::QgsSettings	(	const QString &	organization,
		const QString &	application = `QString()`,
		QObject *	parent = `nullptr`
	)

explicit

Constructs a QgsSettings object for accessing settings of the application called application from the organization called organization, and with parent parent.

Definition at line 54 of file qgssettings.cpp.

◆ QgsSettings() [2/5]

QgsSettings::QgsSettings	(	QSettings::Scope	scope,
		const QString &	organization,
		const QString &	application = `QString()`,
		QObject *	parent = `nullptr`
	)

Constructs a QgsSettings object for accessing settings of the application called application from the organization called organization, and with parent parent.

If scope is QSettings::UserScope, the QSettings object searches user-specific settings first, before it searches system-wide settings as a fallback. If scope is QSettings::SystemScope, the QSettings object ignores user-specific settings and provides access to system-wide settings.

The storage format is set to QSettings::NativeFormat (i.e. calling setDefaultFormat() before calling this constructor has no effect).

If no application name is given, the QSettings object will only access the organization-wide locations.

Definition at line 60 of file qgssettings.cpp.

◆ QgsSettings() [3/5]

QgsSettings::QgsSettings	(	QSettings::Format	format,
		QSettings::Scope	scope,
		const QString &	organization,
		const QString &	application = `QString()`,
		QObject *	parent = `nullptr`
	)

Constructs a QgsSettings object for accessing settings of the application called application from the organization called organization, and with parent parent.

If scope is QSettings::UserScope, the QSettings object searches user-specific settings first, before it searches system-wide settings as a fallback. If scope is QSettings::SystemScope, the QSettings object ignores user-specific settings and provides access to system-wide settings.

If format is QSettings::NativeFormat, the native API is used for storing settings. If format is QSettings::IniFormat, the INI format is used.

If no application name is given, the QSettings object will only access the organization-wide locations.

Definition at line 67 of file qgssettings.cpp.

◆ QgsSettings() [4/5]

QgsSettings::QgsSettings	(	const QString &	fileName,
		QSettings::Format	format,
		QObject *	parent = `nullptr`
	)

Constructs a QgsSettings object for accessing the settings stored in the file called fileName, with parent parent.

If the file doesn't already exist, it is created.

If format is QSettings::NativeFormat, the meaning of fileName depends on the platform. On Unix, fileName is the name of an INI file. On macOS and iOS, fileName is the name of a .plist file. On Windows, fileName is a path in the system registry.

If format is QSettings::IniFormat, fileName is the name of an INI file.

Warning: This function is provided for convenience. It works well for accessing INI or .plist files generated by Qt, but might fail on some syntaxes found in such files originated by other programs. In particular, be aware of the following limitations:

QgsSettings provides no way of reading INI "path" entries, i.e., entries with unescaped slash characters. (This is because these entries are ambiguous and cannot be resolved automatically.)
In INI files, QSettings uses the @ character as a metacharacter in some contexts, to encode Qt-specific data types (e.g., @Rect), and might therefore misinterpret it when it occurs in pure INI files.

Definition at line 74 of file qgssettings.cpp.

◆ QgsSettings() [5/5]

QgsSettings::QgsSettings ( QObject * parent = nullptr )

explicit

Constructs a QgsSettings object for accessing settings of the application and organization set previously with a call to QCoreApplication::setOrganizationName(), QCoreApplication::setOrganizationDomain(), and QCoreApplication::setApplicationName().

The scope is QSettings::UserScope and the format is defaultFormat() (QSettings::NativeFormat by default). Use setDefaultFormat() before calling this constructor to change the default format used by this constructor.

Definition at line 80 of file qgssettings.cpp.

◆ ~QgsSettings()

QgsSettings::~QgsSettings ( )

override

Definition at line 86 of file qgssettings.cpp.

Member Function Documentation

◆ allKeys()

QStringList QgsSettings::allKeys ( ) const

Returns a list of all keys, including subkeys, that can be read using the QSettings object.

Definition at line 117 of file qgssettings.cpp.

◆ beginGroup()

void QgsSettings::beginGroup	(	const QString &	prefix,
		QgsSettings::Section	section = `QgsSettings::NoSection`
	)

Appends prefix to the current group.

The current group is automatically prepended to all keys specified to QSettings. In addition, query functions such as childGroups(), childKeys(), and allKeys() are based on the group. By default, no group is set.

Definition at line 93 of file qgssettings.cpp.

◆ beginReadArray()

int QgsSettings::beginReadArray ( const QString & prefix )

Adds prefix to the current group and starts reading from an array. Returns the size of the array.

Definition at line 254 of file qgssettings.cpp.

◆ beginWriteArray()

void QgsSettings::beginWriteArray	(	const QString &	prefix,
		int	size = `-1`
	)

Adds prefix to the current group and starts writing an array of size size.

If size is -1 (the default), it is automatically determined based on the indexes of the entries written.

Note: This will completely shadow any existing array with the same name in the global settings

Definition at line 265 of file qgssettings.cpp.

◆ childGroups()

QStringList QgsSettings::childGroups ( Qgis::SettingsOrigin origin = Qgis::SettingsOrigin::Any ) const

Returns a list of all key top-level groups that contain keys that can be read using the QSettings object.

Definition at line 140 of file qgssettings.cpp.

◆ childKeys()

QStringList QgsSettings::childKeys ( ) const

Returns a list of all top-level keys that can be read using the QSettings object.

Definition at line 129 of file qgssettings.cpp.

◆ clear()

void QgsSettings::clear ( )

Removes all entries in the user settings.

Definition at line 333 of file qgssettings.cpp.

◆ contains()

bool QgsSettings::contains	(	const QString &	key,
		QgsSettings::Section	section = `QgsSettings::NoSection`
	)		const

Returns true if there exists a setting called key; returns false otherwise.

If a group is set using beginGroup(), key is taken to be relative to that group.

Definition at line 189 of file qgssettings.cpp.

◆ endArray()

void QgsSettings::endArray ( )

Closes the array that was started using beginReadArray() or beginWriteArray().

Definition at line 271 of file qgssettings.cpp.

◆ endGroup()

void QgsSettings::endGroup ( )

Resets the group to what it was before the corresponding beginGroup() call.

Definition at line 103 of file qgssettings.cpp.

◆ enumValue()

template<class T >

T QgsSettings::enumValue	(	const QString &	key,
		const T &	defaultValue,
		const Section	section = `NoSection`
	)

inline

Returns the setting value for a setting based on an enum.

This forces the output to be a valid and existing entry of the enum. Hence if the setting value is incorrect, the given default value is returned. This tries first with setting as a string (as the enum) and then as an integer value.

Note: The enum needs to be declared with Q_ENUM, and flags with Q_FLAG (not Q_FLAGS).; for Python bindings, a custom implementation is achieved in Python directly

See also: setEnumValue; flagValue

Definition at line 263 of file qgssettings.h.

◆ fileName()

QString QgsSettings::fileName ( ) const

Returns the path where settings written using this QSettings object are stored.

Definition at line 196 of file qgssettings.cpp.

◆ flagValue()

template<class T >

T QgsSettings::flagValue	(	const QString &	key,
		const T &	defaultValue,
		const Section	section = `NoSection`
	)

inline

Returns the setting value for a setting based on a flag.

This forces the output to be a valid and existing entry of the flag. Hence if the setting value is incorrect, the given default value is returned. This tries first with setting as a string (using a byte array) and then as an integer value.

Note: The flag needs to be declared with Q_FLAG (not Q_FLAGS).; for Python bindings, a custom implementation is achieved in Python directly.

See also: setFlagValue; enumValue

Definition at line 341 of file qgssettings.h.

◆ get()

QgsSettingsProxy QgsSettings::get ( )

static

Returns a proxy for a QgsSettings object.

This either directly constructs a QgsSettings object, or if a previous call to holdFlush() has been made then the thread local QgsSettings object will be used.

Warning: ALWAYS use this function to retrieve a QgsSettings object for entries, NEVER create one manually!

Note: Not available in Python bindings

Since: QGIS 3.36

Definition at line 353 of file qgssettings.cpp.

◆ globalChildGroups()

QStringList QgsSettings::globalChildGroups ( ) const

Returns a list of all key top-level groups (same as childGroups) but only for groups defined in global settings.

Definition at line 165 of file qgssettings.cpp.

◆ globalSettingsPath()

QString QgsSettings::globalSettingsPath ( )

static

Returns the path to the Global Settings QSettings storage file.

Definition at line 170 of file qgssettings.cpp.

◆ group()

QString QgsSettings::group ( ) const

Returns the current group.

See also: beginGroup(); endGroup()

Since: QGIS 3.6

Definition at line 112 of file qgssettings.cpp.

◆ holdFlush()

void QgsSettings::holdFlush ( )

static

Temporarily places a hold on flushing QgsSettings objects and writing new values to the underlying ini files.

This can be used in code which access multiple settings to avoid creation and destruction of many QgsSettings objects for each in turn. This can be a VERY expensive operation due to flushing of new values to disk.

Warning: This method ONLY affects access to the settings from the current thread!; A corresponding call to releaseFlush() MUST be made from the SAME thread.

See also: releaseFlush()

Note: Not available in Python bindings

Since: QGIS 3.36

Definition at line 339 of file qgssettings.cpp.

◆ origin()

Qgis::SettingsOrigin QgsSettings::origin ( const QString & key ) const

Returns the origin of the setting if it exists at the given key.

Note: it will return Qgis::SettingsOrigin::Any if the key doesn't exist

Since: QGIS 3.30

Definition at line 293 of file qgssettings.cpp.

◆ prefixedKey()

QString QgsSettings::prefixedKey	(	const QString &	key,
		QgsSettings::Section	section
	)		const

Returns the sanitized and prefixed key.

Definition at line 212 of file qgssettings.cpp.

◆ releaseFlush()

void QgsSettings::releaseFlush ( )

static

Releases a previously made hold on flushing QgsSettings objects and writing new values to the underlying ini files.

Warning: This method ONLY affects access to the settings from the current thread!; This must ALWAYS be called after a corresponding call to holdFlush() and MUST be made from the SAME thread.

See also: holdFlush()

Note: Not available in Python bindings

Since: QGIS 3.36

Definition at line 347 of file qgssettings.cpp.

◆ remove()

void QgsSettings::remove	(	const QString &	key,
		QgsSettings::Section	section = `QgsSettings::NoSection`
	)

Removes the setting key and any sub-settings of key in a section.

Definition at line 206 of file qgssettings.cpp.

◆ setArrayIndex()

void QgsSettings::setArrayIndex ( int i )

Sets the current array index to i.

Calls to functions such as setValue(), value(), remove(), and contains() will operate on the array entry at that index.

Definition at line 281 of file qgssettings.cpp.

◆ setEnumValue()

template<class T >

void QgsSettings::setEnumValue	(	const QString &	key,
		const T &	value,
		const Section	section = `NoSection`
	)

inline

Set the value of a setting based on an enum.

The setting will be saved as string.

Note: The enum needs to be declared with Q_ENUM, and flags with Q_FLAG (not Q_FLAGS).

See also: enumValue; setFlagValue

Definition at line 315 of file qgssettings.h.

◆ setFlagValue()

template<class T >

void QgsSettings::setFlagValue	(	const QString &	key,
		const T &	value,
		const Section	section = `NoSection`
	)

inline

Set the value of a setting based on a flag.

The setting will be saved as string.

Note: The flag needs to be declared with Q_FLAG (not Q_FLAGS).

See also: flagValue; setEnumValue

Definition at line 405 of file qgssettings.h.

◆ setGlobalSettingsPath()

bool QgsSettings::setGlobalSettingsPath ( const QString & path )

static

Sets the Global Settings QSettings storage file.

Definition at line 32 of file qgssettings.cpp.

◆ setValue()

void QgsSettings::setValue	(	const QString &	key,
		const QVariant &	value,
		QgsSettings::Section	section = `QgsSettings::NoSection`
	)

Sets the value of setting key to value.

If the key already exists, the previous value is overwritten. An optional Section argument can be used to set a value to a specific Section.

Definition at line 304 of file qgssettings.cpp.

◆ sync()

void QgsSettings::sync ( )

Writes any unsaved changes to permanent storage, and reloads any settings that have been changed in the meantime by another application.

This function is called automatically from QSettings's destructor and by the event loop at regular intervals, so you normally don't need to call it yourself.

Definition at line 201 of file qgssettings.cpp.

◆ value()

QVariant QgsSettings::value	(	const QString &	key,
		const QVariant &	defaultValue = `QVariant()`,
		const QgsSettings::Section	section = `NoSection`
	)		const

Returns the value for setting key.

If the setting doesn't exist, it will be searched in the Global Settings and if not found, returns defaultValue. If no default value is specified, a default QVariant is returned. An optional Section argument can be used to get a value from a specific Section.

Definition at line 175 of file qgssettings.cpp.

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

/build/qgis-3.41.0+git20241116+25ec5511245+99sid/src/core/settings/qgssettings.h
/build/qgis-3.41.0+git20241116+25ec5511245+99sid/src/core/settings/qgssettings.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Section

Constructor & Destructor Documentation

◆ QgsSettings() [1/5]

◆ QgsSettings() [2/5]

◆ QgsSettings() [3/5]

◆ QgsSettings() [4/5]

◆ QgsSettings() [5/5]

◆ ~QgsSettings()

Member Function Documentation

◆ allKeys()

◆ beginGroup()

◆ beginReadArray()

◆ beginWriteArray()

◆ childGroups()

◆ childKeys()

◆ clear()

◆ contains()

◆ endArray()

◆ endGroup()

◆ enumValue()

◆ fileName()

◆ flagValue()

◆ get()

◆ globalChildGroups()

◆ globalSettingsPath()

◆ group()

◆ holdFlush()

◆ origin()

◆ prefixedKey()

◆ releaseFlush()

◆ remove()

◆ setArrayIndex()

◆ setEnumValue()

◆ setFlagValue()

◆ setGlobalSettingsPath()

◆ setValue()

◆ sync()

◆ value()