Class: QgsSettings

class qgis.core.QgsSettings(organization: str, application: str = '', parent: QObject = None)

Bases: PyQt5.QtCore.QObject

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

QgsSettings(scope: QSettings.Scope, organization: str, application: str = ‘’, parent: QObject = None) 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.

QgsSettings(format: QSettings.Format, scope: QSettings.Scope, organization: str, application: str = ‘’, parent: QObject = None) 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.

QgsSettings(fileName: str, format: QSettings.Format, parent: QObject = None) 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.

QgsSettings(parent: QObject = None) 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.

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

New in version 3.0:

Methods

allKeys

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

beginGroup

Appends prefix to the current group.

beginReadArray

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

beginWriteArray

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

childEvent

childGroups

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

childKeys

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

clear

Removes all entries in the user settings

connectNotify

contains

Returns True if there exists a setting called key; returns False otherwise.

customEvent

disconnectNotify

endArray

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

endGroup

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

enumValue

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

fileName

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

flagValue

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

globalChildGroups

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

globalSettingsPath

Returns the path to the Global Settings QSettings storage file

group

Returns the current group.

isSignalConnected

prefixedKey

Returns the sanitized and prefixed key

receivers

remove

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

sender

senderSignalIndex

setArrayIndex

Sets the current array index to i.

setEnumValue

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

setGlobalSettingsPath

Sets the Global Settings QSettings storage file

setValue

Sets the value of setting key to value.

sync

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

timerEvent

value

Returns the value for setting key.

Attributes

App

Auth

Core

Expressions

Gui

Misc

NoSection

Plugins

Providers

Server

App = 6
Auth = 5
Core = 1
Expressions = 8
Gui = 2
Misc = 9
NoSection = 0
Plugins = 4
Providers = 7
class Section

Bases: int

Server = 3
allKeys(self) List[str]

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

Return type

List[str]

beginGroup(self, prefix: str, section: QgsSettings.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.

Parameters
  • prefix (str) –

  • section (QgsSettings.Section = QgsSettings.NoSection) –

beginReadArray(self, prefix: str) int

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

Parameters

prefix (str) –

Return type

int

beginWriteArray(self, prefix: str, size: int = - 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

Parameters
  • prefix (str) –

  • size (int = -1) –

childEvent(self, QChildEvent)
childGroups(self) List[str]

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

Return type

List[str]

childKeys(self) List[str]

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

Return type

List[str]

clear(self)

Removes all entries in the user settings

connectNotify(self, QMetaMethod)
contains(self, key: str, section: QgsSettings.Section = QgsSettings.NoSection) bool

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.

Parameters
  • key (str) –

  • section (QgsSettings.Section = QgsSettings.NoSection) –

Return type

bool

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
endArray(self)

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

endGroup(self)

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

enumValue(key, enumDefaultValue, section=0)

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

Parameters
  • self – the QgsSettings object

  • key – the setting key

  • enumDefaultValue – the default value as an enum value

  • section – optional section

Returns

the setting value

Note

The enum needs to be declared with Q_ENUM.

fileName(self) str

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

Return type

str

flagValue(key, flagDefaultValue, section=0)

Return the setting value for a setting based on a flag. 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.

Parameters
  • self – the QgsSettings object

  • key – the setting key

  • flagDefaultValue – the default value as a flag value

  • section – optional section

Returns

the setting value

Note

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

globalChildGroups(self) List[str]

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

Return type

List[str]

globalSettingsPath() str

Returns the path to the Global Settings QSettings storage file

Return type

str

group(self) str

Returns the current group.

See also

beginGroup()

See also

endGroup()

New in version 3.6.

Return type

str

isSignalConnected(self, QMetaMethod) bool
prefixedKey(self, key: str, section: QgsSettings.Section) str

Returns the sanitized and prefixed key

Parameters
Return type

str

receivers(self, PYQT_SIGNAL) int
remove(self, key: str, section: QgsSettings.Section = QgsSettings.NoSection)

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

Parameters
  • key (str) –

  • section (QgsSettings.Section = QgsSettings.NoSection) –

sender(self) QObject
senderSignalIndex(self) int
setArrayIndex(self, i: int)

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.

Parameters

i (int) –

setEnumValue(key, enumValue, section=0)

Save the setting value for a setting based on an enum. This forces the output to be a valid and existing entry of the enum. The entry is saved as a string.

Parameters
  • self – the QgsSettings object

  • key – the setting key

  • enumValue – the value to be saved

  • section – optional section

Returns

the setting value

Note

The enum needs to be declared with Q_ENUM.

setGlobalSettingsPath(path: str) bool

Sets the Global Settings QSettings storage file

Parameters

path (str) –

Return type

bool

setValue(self, key: str, value: Any, section: QgsSettings.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.

Parameters
  • key (str) –

  • value (Any) –

  • section (QgsSettings.Section = QgsSettings.NoSection) –

sync(self)

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.

timerEvent(self, QTimerEvent)
value(self, key: str, defaultValue: Any = None, type: object = 0, section: QgsSettings.Section = QgsSettings.NoSection) object

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.

Parameters
  • key (str) –

  • defaultValue (Any = None) –

  • type (object = 0) –

  • section (QgsSettings.Section = QgsSettings.NoSection) –

Return type

object