Class: QgsSettingsEntryBase

class qgis.core.QgsSettingsEntryBase

Bases: sip.wrapper

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

New in version 3.20.

QgsSettingsEntryBase(key: str, section: str, defaultValue: Any = None, description: str = ‘’, options: Union[Qgis.SettingsOptions, Qgis.SettingsOption] = Qgis.SettingsOptions()) Constructor for QgsSettingsEntryBase.

Parameters

  • key – specifies the key of the settings.

  • section – specifies the section.

  • defaultValue – specifies the default value for the settings entry.

  • description – specifies a description for the settings entry.

  • options – specifies the options for the settings entry.

QgsSettingsEntryBase(name: str, parent: QgsSettingsTreeNode, defaultValue: Any = None, description: str = ‘’, options: Union[Qgis.SettingsOptions, Qgis.SettingsOption] = Qgis.SettingsOptions()) Constructor for QgsSettingsEntryBase.

Parameters

  • name – specifies the name of the setting.

  • parent – specifies the parent in the tree of settings.

  • defaultValue – specifies the default value for the settings entry.

  • description – specifies a description for the settings entry.

  • options – specifies the options for the settings entry.

Raises

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

New in version 3.30.

QgsSettingsEntryBase(QgsSettingsEntryBase)

Enums

SettingsType

Bases: enum.IntEnum

Methods

copyValueFromKey

Copies the value from a given key if it exists.

copyValueToKey

Copies the settings to the given key.

defaultValueAsVariant

Returns settings default value.

definitionKey

Returns settings entry defining key.

description

Returns the settings entry description.

dynamicKeyPartToList

Transforms a dynamic key part string to list

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.

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.

setVariantValuePrivate

Sets the settings value with a variant value.

settingsType

Returns the settings entry type.

valueAsVariant

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

valueAsVariantWithDefaultOverride

Returns settings value with a defaultValueOverride
class SettingsType(value)

Bases: enum.IntEnum

Types of settings entries

New 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

baseClass

alias of Qgis

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

Copies the value from a given key if it exists.

Parameters

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

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

Returns

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

New in version 3.30.

copyValueFromKey(self, key: str, dynamicKeyPartList: Iterable[str], removeSettingAtKey: bool = False) -> bool Copies the value from a given key if it exists.

Parameters

  • key – the key to copy the setting value from.

  • dynamicKeyPartList – is the optional dynamic key part to determine the key. It must be the same for origin and destination keys.

  • removeSettingAtKey – 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.

New in version 3.30.

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

Copies the settings to the given key.

Parameters

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

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

New in version 3.30.

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

dynamicKeyPartToList(dynamicKeyPart: str) → List[str]

Transforms a dynamic key part string to list

New in version 3.26.

Parameters

dynamicKeyPart (str) –

Return type

List[str]

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

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

Parameters

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

exists(self, dynamicKeyPartList: Iterable[str]) -> bool Returns True if the settings is contained in the underlying QSettings.

Parameters

dynamicKeyPartList – specifies the list of dynamic parts of the settings key.

Return type

bool

formerValueAsVariant(self, dynamicKeyPart: str) → 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.

New in version 3.26.

formerValueAsVariant(self, dynamicKeyPartList: Iterable[str]) -> 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.

New in version 3.26.

Parameters

dynamicKeyPart (str) –

Return type

Any

hasDynamicKey(self) → bool

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

Return type

bool

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

Returns settings entry key.

Parameters

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

key(self, dynamicKeyPartList: Iterable[str]) -> str Returns settings entry key.

Parameters

dynamicKeyPartList – specifies the list of dynamic parts of the settings key.

Return type

str

keyIsValid(self, key: str) → 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 (str) – to check

Return type

bool

name(self) → str

Returns the name of the settings

New in version 3.30.

Return type

str

options(self) → Qgis.SettingsOptions

Returns the settings options

New in version 3.26.

Return type

Qgis.SettingsOptions

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

Returns the origin of the setting if it exists

Note

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

New in version 3.30.

Parameters

dynamicKeyPartList (Iterable[str]) –

Return type

Qgis.SettingsOrigin

parent(self) → QgsSettingsTreeNode

Returns the parent tree element

New in version 3.30.

Return type

QgsSettingsTreeNode

remove(self, dynamicKeyPart: str = '')

Removes the settings from the underlying QSettings.

Parameters

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

remove(self, dynamicKeyPartList: Iterable[str]) Removes the settings from the underlying QSettings.

Parameters

dynamicKeyPartList – specifies the list of dynamic parts of the settings key.

section(self) → QgsSettings.Section

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

Deprecated since version QGIS: 3.26 the key is entirely self-defined

Return type

QgsSettings.Section

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

Set settings value.

Parameters

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

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

Deprecated since version QGIS: 3.26 use setVariantValuePrivate or an implementation setValue instead

setVariantValue(self, value: Any, dynamicKeyPartList: Iterable[str]) -> bool Set settings value.

Parameters

  • value – specifies the value to set.

  • dynamicKeyPartList – specifies the list of dynamic parts of the settings key.

Deprecated since version QGIS: 3.26 use setVariantValuePrivate or an implementation setValue instead

Return type

bool

setVariantValuePrivate(self, value: Any, dynamicKeyPartList: Iterable[str] = []) → bool

Sets the settings value with a variant value. This should be called from any implementation as it takes care of actually calling QSettings

New in version 3.26.

Parameters

  • value (Any) –

  • dynamicKeyPartList (Iterable[str] = []) –

Return type

bool

settingsType(self) → Qgis.SettingsType

Returns the settings entry type.

Return type

Qgis.SettingsType

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

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

valueAsVariant(self, dynamicKeyPartList: Iterable[str]) -> Any Returns settings value with:param dynamicKeyPartList: specifying the dynamic part of the settings key.

valueAsVariant(self, dynamicKeyPart: str, useDefaultValueOverride: bool, defaultValueOverride: Any) -> Any Returns settings value with an optional default value override

Deprecated since version QGIS: 3.26 use valueAsVariantWithDefaultOverride instead

valueAsVariant(self, dynamicKeyPartList: Iterable[str], useDefaultValueOverride: bool, defaultValueOverride: Any) -> Any Returns settings value with an optional default value override

Deprecated since version QGIS: 3.26 use valueAsVariantWithDefaultOverride instead

Parameters

dynamicKeyPart (str = '') –

Return type

Any

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

Returns settings value with a defaultValueOverride

New in version 3.26.

valueAsVariantWithDefaultOverride(self, defaultValueOverride: Any, dynamicKeyPartList: Iterable[str]) -> Any Returns settings value.

Parameters

  • dynamicKeyPartList – specifies the list of dynamic parts of the settings key.

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

New in version 3.26.

Parameters

dynamicKeyPart (str = '') –

Return type

Any