QGIS API Documentation 3.40.0-Bratislava (b56115d8743)
|
This class is a composition of two QSettings instances: More...
#include <qgssettings.h>
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. | |
This class is a composition of two QSettings instances:
For a given settings key, the function call to value(key, default) will return the first existing setting in the order specified below:
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:
Definition at line 63 of file qgssettings.h.
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.
|
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 53 of file qgssettings.cpp.
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 59 of file qgssettings.cpp.
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 66 of file qgssettings.cpp.
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.
Definition at line 73 of file qgssettings.cpp.
|
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 79 of file qgssettings.cpp.
|
override |
Definition at line 85 of file qgssettings.cpp.
QStringList QgsSettings::allKeys | ( | ) | const |
Returns a list of all keys, including subkeys, that can be read using the QSettings object.
Definition at line 116 of file qgssettings.cpp.
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 92 of file qgssettings.cpp.
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 253 of file qgssettings.cpp.
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.
Definition at line 264 of file qgssettings.cpp.
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 139 of file qgssettings.cpp.
QStringList QgsSettings::childKeys | ( | ) | const |
Returns a list of all top-level keys that can be read using the QSettings object.
Definition at line 128 of file qgssettings.cpp.
void QgsSettings::clear | ( | ) |
Removes all entries in the user settings.
Definition at line 332 of file qgssettings.cpp.
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 188 of file qgssettings.cpp.
void QgsSettings::endArray | ( | ) |
Closes the array that was started using beginReadArray() or beginWriteArray().
Definition at line 270 of file qgssettings.cpp.
void QgsSettings::endGroup | ( | ) |
Resets the group to what it was before the corresponding beginGroup() call.
Definition at line 102 of file qgssettings.cpp.
|
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.
Definition at line 263 of file qgssettings.h.
QString QgsSettings::fileName | ( | ) | const |
Returns the path where settings written using this QSettings object are stored.
Definition at line 195 of file qgssettings.cpp.
|
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.
Definition at line 341 of file qgssettings.h.
|
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.
Definition at line 352 of file qgssettings.cpp.
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 164 of file qgssettings.cpp.
|
static |
Returns the path to the Global Settings QSettings storage file.
Definition at line 169 of file qgssettings.cpp.
QString QgsSettings::group | ( | ) | const |
Returns the current group.
Definition at line 111 of file qgssettings.cpp.
|
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.
Definition at line 338 of file qgssettings.cpp.
Qgis::SettingsOrigin QgsSettings::origin | ( | const QString & | key | ) | const |
Returns the origin of the setting if it exists at the given key.
Definition at line 292 of file qgssettings.cpp.
QString QgsSettings::prefixedKey | ( | const QString & | key, |
QgsSettings::Section | section | ||
) | const |
Returns the sanitized and prefixed key.
Definition at line 211 of file qgssettings.cpp.
|
static |
Releases a previously made hold on flushing QgsSettings objects and writing new values to the underlying ini files.
Definition at line 346 of file qgssettings.cpp.
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 205 of file qgssettings.cpp.
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 280 of file qgssettings.cpp.
|
inline |
Set the value of a setting based on an enum.
The setting will be saved as string.
Definition at line 315 of file qgssettings.h.
|
inline |
Set the value of a setting based on a flag.
The setting will be saved as string.
Definition at line 405 of file qgssettings.h.
|
static |
Sets the Global Settings QSettings storage file.
Definition at line 31 of file qgssettings.cpp.
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 303 of file qgssettings.cpp.
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 200 of file qgssettings.cpp.
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 174 of file qgssettings.cpp.