Class: QgsSettingsEntryBase

Represents a settings entry and provides methods for reading and writing settings values.

Different subclasses are provided for different settings types with metainformations to validate set values and provide more accurate settings description for the gui.

Added in version 3.20.

Class Hierarchy

Subclasses

QgsSettingsEntryBaseTemplateQColorBase	Base abstract class for settings entries with typed get and set methods.
QgsSettingsEntryBaseTemplateQStringBase	Base abstract class for settings entries with typed get and set methods.
QgsSettingsEntryBaseTemplateQStringListBase	Base abstract class for settings entries with typed get and set methods.
QgsSettingsEntryBaseTemplateQVariantBase	Base abstract class for settings entries with typed get and set methods.
QgsSettingsEntryBaseTemplateQVariantMapBase	Base abstract class for settings entries with typed get and set methods.
QgsSettingsEntryBaseTemplateboolBase	Base abstract class for settings entries with typed get and set methods.
QgsSettingsEntryBaseTemplatedoubleBase	Base abstract class for settings entries with typed get and set methods.
QgsSettingsEntryBaseTemplateintBase	Base abstract class for settings entries with typed get and set methods.
PyQgsSettingsEntryEnumFlag	class PyQgsSettingsEntryEnumFlag An enum settings entry. since QGIS 3.20

Enums

SettingsType

Types of settings entries

Methods

copyValueFromKey	Copies the value from a given key if it exists.
copyValueToKey	Copies the settings to the given key.
copyValueToKeyIfChanged	Copies the settings to the given key, if it has changed during the current QGIS session (see hasChanged()).
defaultValueAsVariant	Returns settings default value.
definitionKey	Returns settings entry defining key.
description	Returns the settings entry description.
exists	Returns True if the settings is contained in the underlying QSettings.
formerValueAsVariant	Returns the former value of the settings if it has been enabled in the options.
hasChanged	Returns True if the setting was changed during the current QGIS session.
hasDynamicKey	Returns True if a part of the settings key is built dynamically.
key	Returns settings entry key.
keyIsValid	Returns True if the provided key match the settings entry.
name	Returns the name of the settings
options	Returns the settings options
origin	Returns the origin of the setting if it exists
parent	Returns the parent tree element
remove	Removes the settings from the underlying QSettings.
section	Returns settings section.
setVariantValue	Set settings value.
valueAsVariant	Returns settings value with:param dynamicKeyPart: specifying the dynamic part of the settings key.
valueAsVariantWithDefaultOverride	Returns settings value with a defaultValueOverride

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsSettingsEntryBase. See the FAQ for more details.

checkValueVariant	Returns True if the given value is valid towards the setting definition
settingsType	Returns the settings entry type.
typeId	Returns the id of the type of settings This can be re-implemented in a custom implementation of a setting

Static Methods

dynamicKeyPartToList

Transforms a dynamic key part string to list

class qgis.core.QgsSettingsEntryBase

Bases: object

__init__(key: str | None, section: str | None, defaultValue: Any = None, description: str | None = '', options: Qgis.SettingsOptions | Qgis.SettingsOption = Qgis.SettingsOptions())

Constructor for QgsSettingsEntryBase.

Parameters:

• key (Optional[str]) – specifies the key of the settings.

• section (Optional[str]) – specifies the section.

• defaultValue (Any = None) – specifies the default value for the settings entry.

• description (Optional[str] = '') – specifies a description for the settings entry.

• options (Union[Qgis.SettingsOptions, Qgis.SettingsOption] = Qgis.SettingsOptions()) – specifies the options for the settings entry.

__init__(name: str | None, parent: QgsSettingsTreeNode | None, defaultValue: Any = None, description: str | None = '', options: Qgis.SettingsOptions | Qgis.SettingsOption = Qgis.SettingsOptions())

Constructor for QgsSettingsEntryBase.

Parameters:

• name (Optional[str]) – specifies the name of the setting.

• parent (Optional[QgsSettingsTreeNode]) – specifies the parent in the tree of settings.

• defaultValue (Any = None) – specifies the default value for the settings entry.

• description (Optional[str] = '') – specifies a description for the settings entry.

• options (Union[Qgis.SettingsOptions, Qgis.SettingsOption] = Qgis.SettingsOptions()) – specifies the options for the settings entry.

Raises:

QgsSettingsException – if the number of given parent named items doesn’t match the complete key definition

Added in version 3.30.

__init__(a0: QgsSettingsEntryBase)

Parameters:

a0 (QgsSettingsEntryBase)

class SettingsType(*values)

Bases: IntEnum

Types of settings entries

Added in version 3.26.

• Custom: Custom implementation

• Variant: Generic variant

• String: String

• StringList: List of strings

• VariantMap: Map of strings

• Bool: Boolean

• Integer: Integer

• Double: Double precision number

• EnumFlag: Enum or Flag

• Color: Color

virtual checkValueVariant(self, value: Any) → bool

Returns True if the given value is valid towards the setting definition

Parameters:

value (Any)

Return type:

bool

copyValueFromKey(self, key: str | None, removeSettingAtKey: bool = False) → bool

Copies the value from a given key if it exists.

Parameters:

• key (Optional[str]) – the key to copy the setting value from.

• removeSettingAtKey (bool = False) – if True, the setting at the old key will be removed.

Return type:

bool

Returns:

True if the key exists and the setting value could be copied.

Added in version 3.30.

copyValueFromKey(self, key: str | None, dynamicKeyPartList: Iterable[str | None], removeSettingAtKey: bool = False) → bool

Copies the value from a given key if it exists.

Parameters:

• key (Optional[str]) – the key to copy the setting value from.

• dynamicKeyPartList (Iterable[Optional[str]]) – is the optional dynamic key part to determine the key. It must be the same for origin and destination keys.

• removeSettingAtKey (bool = False) – if True, the setting at the old key will be removed.

Return type:

bool

Returns:

True if the key exists and the setting value could be copied.

Added in version 3.30.

copyValueToKey(self, key: str | None, dynamicKeyPartList: Iterable[str | None] = [])

Copies the settings to the given key.

Parameters:

• key (Optional[str]) – the key to copy the setting value to.

• dynamicKeyPartList (Iterable[Optional[str]] = []) – is the optional dynamic key part to determine the key. It must be the same for origin and destination keys.

Added in version 3.30.

copyValueToKeyIfChanged(self, key: str | None, dynamicKeyPartList: Iterable[str | None] = [])

Copies the settings to the given key, if it has changed during the current QGIS session (see hasChanged()).

Parameters:

• key (Optional[str]) – the key to copy the setting value to.

• dynamicKeyPartList (Iterable[Optional[str]] = []) – is the optional dynamic key part to determine the key. It must be the same for origin and destination keys.

Added in version 3.36.

defaultValueAsVariant(self) → Any

Returns settings default value.

Return type:

Any

definitionKey(self) → str

Returns settings entry defining key. For dynamic settings it return the key with the placeholder for dynamic part included. For non-dynamic settings returns the same as key().

Return type:

str

description(self) → str

Returns the settings entry description.

Return type:

str

static dynamicKeyPartToList(dynamicKeyPart: str | None) → List[str]

Transforms a dynamic key part string to list

Added in version 3.26.

Parameters:

dynamicKeyPart (Optional[str])

Return type:

List[str]

exists(self, dynamicKeyPart: str | None = '') → bool

Returns True if the settings is contained in the underlying QSettings.

Parameters:

dynamicKeyPart (Optional[str] = '') – specifies the dynamic part of the settings key.

Return type:

bool

exists(self, dynamicKeyPartList: Iterable[str | None]) → bool

Returns True if the settings is contained in the underlying QSettings.

Parameters:

dynamicKeyPartList (Iterable[Optional[str]]) – specifies the list of dynamic parts of the settings key.

Return type:

bool

formerValueAsVariant(self, dynamicKeyPart: str | None) → Any

Returns the former value of the settings if it has been enabled in the options. Returns the current value (or default) if there is no former value.

Added in version 3.26.

Parameters:

dynamicKeyPart (Optional[str])

Return type:

Any

formerValueAsVariant(self, dynamicKeyPartList: Iterable[str | None]) → Any

Returns the former value of the settings if it has been enabled in the options Returns the current value (or default) if there is no former value.

Added in version 3.26.

Parameters:

dynamicKeyPartList (Iterable[Optional[str]])

Return type:

Any

hasChanged(self) → bool

Returns True if the setting was changed during the current QGIS session.

Added in version 3.36.

Return type:

bool

hasDynamicKey(self) → bool

Returns True if a part of the settings key is built dynamically.

Return type:

bool

key(self, dynamicKeyPart: str | None = '') → str

Returns settings entry key.

Parameters:

dynamicKeyPart (Optional[str] = '') – specifies the dynamic part of the settings key.

Return type:

str

key(self, dynamicKeyPartList: Iterable[str | None]) → str

Returns settings entry key.

Parameters:

dynamicKeyPartList (Iterable[Optional[str]]) – specifies the list of dynamic parts of the settings key.

Return type:

str

keyIsValid(self, key: str | None) → bool

Returns True if the provided key match the settings entry.

This is useful for settings with dynamic keys. For example this permits one to check that the settings key “NewsFeed/httpsfeedqgisorg/27/content” is valid for the settings entry defined with the key “NewsFeed/%1/%2/content”

Parameters:

key (Optional[str]) – to check

Return type:

bool

name(self) → str

Returns the name of the settings

Added in version 3.30.

Return type:

str

options(self) → Qgis.SettingsOptions

Returns the settings options

Added in version 3.26.

Return type:

Qgis.SettingsOptions

origin(self, dynamicKeyPartList: Iterable[str | None]) → Qgis.SettingsOrigin

Returns the origin of the setting if it exists

Note

it will return Qgis.SettingsOrigin.Any if the key doesn’t exist

Added in version 3.30.

Parameters:

dynamicKeyPartList (Iterable[Optional[str]])

Return type:

Qgis.SettingsOrigin

parent(self) → QgsSettingsTreeNode | None

Returns the parent tree element

Added in version 3.30.

Return type:

Optional[QgsSettingsTreeNode]

remove(self, dynamicKeyPart: str | None = '')

Removes the settings from the underlying QSettings.

Parameters:

dynamicKeyPart (Optional[str] = '') – specifies the dynamic part of the settings key.

remove(self, dynamicKeyPartList: Iterable[str | None])

Removes the settings from the underlying QSettings.

Parameters:

dynamicKeyPartList (Iterable[Optional[str]]) – specifies the list of dynamic parts of the settings key.

section(self) → int

Returns settings section. The settings section of the parent group is returned if available.

Deprecated since version 3.26: The key is entirely self-defined.

Return type:

int

setVariantValue(self, value: Any, dynamicKeyPart: str | None = '') → bool

Set settings value.

Parameters:

• value (Any) – specifies the value to set.

• dynamicKeyPart (Optional[str] = '') – specifies the dynamic part of the settings key.

Return type:

bool

setVariantValue(self, value: Any, dynamicKeyPartList: Iterable[str | None]) → bool

Set settings value. This should be called from any implementation as it takes care of actually calling QSettings

Parameters:

• value (Any) – specifies the value to set.

• dynamicKeyPartList (Iterable[Optional[str]]) – specifies the list of dynamic parts of the settings key.

Return type:

bool

virtual settingsType(self) → Qgis.SettingsType

Returns the settings entry type.

Return type:

Qgis.SettingsType

virtual typeId(self) → str

Returns the id of the type of settings This can be re-implemented in a custom implementation of a setting

Added in version 3.32.

Return type:

str

valueAsVariant(self, dynamicKeyPart: str | None = '') → Any

Returns settings value with:param dynamicKeyPart: specifying the dynamic part of the settings key.

Parameters:

dynamicKeyPart (Optional[str] = '')

Return type:

Any

valueAsVariant(self, dynamicKeyPartList: Iterable[str | None]) → Any

Returns settings value with:param dynamicKeyPartList: specifying the dynamic part of the settings key.

Parameters:

dynamicKeyPartList (Iterable[Optional[str]])

Return type:

Any

valueAsVariant(self, dynamicKeyPart: str | None, useDefaultValueOverride: bool, defaultValueOverride: Any) → Any

Returns settings value with an optional default value override

Deprecated since version 3.26: Use valueAsVariantWithDefaultOverride() instead.

Parameters:

• dynamicKeyPart (Optional[str])

• useDefaultValueOverride (bool)

• defaultValueOverride (Any)

Return type:

Any

valueAsVariant(self, dynamicKeyPartList: Iterable[str | None], useDefaultValueOverride: bool, defaultValueOverride: Any) → Any

Returns settings value with an optional default value override

Deprecated since version 3.26: Use valueAsVariantWithDefaultOverride() instead.

Parameters:

• dynamicKeyPartList (Iterable[Optional[str]])

• useDefaultValueOverride (bool)

• defaultValueOverride (Any)

Return type:

Any

valueAsVariantWithDefaultOverride(self, defaultValueOverride: Any, dynamicKeyPart: str | None = '') → Any

Returns settings value with a defaultValueOverride

Added in version 3.26.

Parameters:

• defaultValueOverride (Any)

• dynamicKeyPart (Optional[str] = '')

Return type:

Any

valueAsVariantWithDefaultOverride(self, defaultValueOverride: Any, dynamicKeyPartList: Iterable[str | None]) → Any

Returns settings value.

Parameters:

• dynamicKeyPartList (Iterable[Optional[str]]) – specifies the list of dynamic parts of the settings key.

• defaultValueOverride (Any) – if valid is used instead of the normal default value.

Added in version 3.26.

Return type:

Any