KDE 4.2 PyKDE API Reference

- KDE's Python API

# KConfigGroup Class Reference

`from PyKDE4.kdecore import *`

Inherits: KConfigBase

## Detailed Description

\class KConfigGroup kconfiggroup.h <KConfigGroup>

A class for one specific group in a KConfig object.

If you want to access the top-level entries of a KConfig object, which are not associated with any group, use an empty group name.

A KConfigGroup will be read-only if it is constructed from a const config object or from another read-only group.

## Methods

| __init__ (self)
| __init__ (self, KConfigBase master, QString group)
| __init__ (self, KConfigBase master, QString group)
| __init__ (self, KConfigBase master, QString group)
| __init__ (self, KConfigBase master, QString group)
| __init__ (self, KSharedConfigPtr master, QString group)
| __init__ (self, KSharedConfigPtr master, QString group)
| __init__ (self, KConfigGroup a0)
KConfigBase.AccessMode | accessMode (self)
| changeGroup (self, QString group)
| changeGroup (self, QString group)
KConfig | config (self)
KConfig | config (self)
| copyTo (self, KConfigBase other, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| deleteEntry (self, QString pKey, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| deleteEntry (self, QString pKey, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| deleteGroup (self, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| deleteGroupImpl (self, QByteArray group, KConfigBase.WriteConfigFlags flags)
QMap<QString,QString> | entryMap (self)
bool | exists (self)
KConfigGroup | groupImpl (self, QByteArray b)
KConfigGroup | groupImpl (self, QByteArray b)
QStringList | groupList (self)
bool | hasDefault (self, QString key)
bool | hasDefault (self, QString key)
bool | hasGroupImpl (self, QByteArray group)
bool | hasKey (self, QString key)
bool | hasKey (self, QString key)
bool | isEntryImmutable (self, QString key)
bool | isEntryImmutable (self, QString key)
bool | isGroupImmutableImpl (self, QByteArray aGroup)
bool | isImmutable (self)
bool | isValid (self)
QStringList | keyList (self)
| markAsClean (self)
QString | name (self)
KConfigGroup | parent (self)
QVariant | readEntry (self, QString key, QVariant aDefault)
QVariant | readEntry (self, QString key, QVariant aDefault)
QString | readEntry (self, QString key, QString aDefault)
QString | readEntry (self, QString key, QString aDefault)
QString | readEntry (self, QString key, QString aDefault=0)
QString | readEntry (self, QString key, QString aDefault=0)
QVariantList | readEntry (self, QString key, QVariantList aDefault)
QVariantList | readEntry (self, QString key, QVariantList aDefault)
QStringList | readEntry (self, QString key, QStringList aDefault)
QStringList | readEntry (self, QString key, QStringList aDefault)
QString | readEntryUntranslated (self, QString pKey, QString aDefault=QString())
QString | readEntryUntranslated (self, QString key, QString aDefault=QString())
QString | readPathEntry (self, QString pKey, QString aDefault)
QString | readPathEntry (self, QString key, QString aDefault)
QStringList | readPathEntry (self, QString pKey, QStringList aDefault)
QStringList | readPathEntry (self, QString key, QStringList aDefault)
QStringList | readXdgListEntry (self, QString pKey, QStringList aDefault=QStringList())
QStringList | readXdgListEntry (self, QString pKey, QStringList aDefault=QStringList())
| reparent (self, KConfigBase parent, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| revertToDefault (self, QString key)
| revertToDefault (self, QString key)
| sync (self)
| writeEntry (self, QString key, QVariant value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QVariant value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QString value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QString value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QByteArray value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QByteArray value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QString value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QString value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QStringList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QStringList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QVariantList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeEntry (self, QString key, QVariantList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writePathEntry (self, QString pKey, QString path, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writePathEntry (self, QString pKey, QString path, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writePathEntry (self, QString pKey, QStringList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writePathEntry (self, QString pKey, QStringList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeXdgListEntry (self, QString pKey, QStringList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)
| writeXdgListEntry (self, QString pKey, QStringList value, KConfigBase.WriteConfigFlags pFlags=KConfigBase.Normal)

## Method Documentation

__init__ | ( |  | self ) |

Constructs an invalid group.

See also:
  isValid

__init__ | ( | self, |
|  | KConfigBase | master,
|  | QString | group
| ) |  |  |

Construct a config group corresponding to group in master.

This allows the creation of subgroups by passing another group as master.

group is the group name encoded in UTF-8.

__init__ | ( | self, |
|  | KConfigBase | master,
|  | QString | group
| ) |  |  |

Overload for KConfigGroup(KConfigBase*,const QString&)

__init__ | ( | self, |
|  | KConfigBase | master,
|  | QString | group
| ) |  |  |

Construct a read-only config group.

A read-only group will silently ignore any attempts to write to it.

This allows the creation of subgroups by passing an existing group as master.

__init__ | ( | self, |
|  | KConfigBase | master,
|  | QString | group
| ) |  |  |

Overload for KConfigGroup(const KConfigBase*,const QString&)

__init__ | ( | self, |
|  | KSharedConfigPtr | master,
|  | QString | group
| ) |  |  |

Overload for KConfigGroup(const KConfigBase*,const QString&)

__init__ | ( | self, |
|  | KSharedConfigPtr | master,
|  | QString | group
| ) |  |  |

Overload for KConfigGroup(const KConfigBase*,const QString&)

__init__ | ( | self, |
|  | KConfigGroup | a0
| ) |  |  |

Creates a read-only copy of a read-only group.

KConfigBase.AccessMode accessMode | ( |  | self ) |

changeGroup | ( | self, |
|  | QString | group
| ) |  |  |

Changes the group of the object

Deprecated:
  Create another KConfigGroup from the parent of this group instead.

changeGroup | ( | self, |
|  | QString | group
| ) |  |  |

Overload for changeGroup(const QString&)

Deprecated:
  Create another KConfigGroup from the parent of this group instead.

KConfig config | ( |  | self ) |

Return the config object that this group belongs to

KConfig config | ( |  | self ) |

Return the config object that this group belongs to

copyTo | ( | self, |
|  | KConfigBase | other,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Copies the entries in this group to another configuration object

Note:
  other can be either another group or a different file.

Parameters:

  | other | the configuration object to copy this group's entries to
  | pFlags | the flags to use when writing the entries to the other configuration object

Since:
  4.1

deleteEntry | ( | self, |
|  | QString | pKey,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Deletes the entry specified by pKey in the current group

This also hides system wide defaults.

Parameters:

  | pKey | the key to delete
  | pFlags | the flags to use when deleting this entry

See also:
  deleteGroup(), readEntry(), writeEntry()

deleteEntry | ( | self, |
|  | QString | pKey,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for deleteEntry(const QString&, WriteConfigFlags)

deleteGroup | ( | self, |
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Delete all entries in the entire group

Parameters:

  | pFlags | flags passed to KConfig.deleteGroup

See also:
  deleteEntry()

deleteGroupImpl | ( | self, |
|  | QByteArray | group,
|  | KConfigBase.WriteConfigFlags | flags
| ) |  |  |

QMap<QString,QString> entryMap | ( |  | self ) |

Returns a map (tree) of entries for all entries in this group

Only the actual entry string is returned, none of the other internal data should be included.

Returns:
  a map of entries in this group, indexed by key

bool exists | ( |  | self ) |

Check whether the containing KConfig object acutally contains a group with this name.

KConfigGroup groupImpl | ( | self, |
|  | QByteArray | b
| ) |  |  |

KConfigGroup groupImpl | ( | self, |
|  | QByteArray | b
| ) |  |  |

QStringList groupList | ( |  | self ) |

bool hasDefault | ( | self, |
|  | QString | key
| ) |  |  |

Whether a default is specified for an entry in either the system wide configuration file or the global KDE config file

If an application computes a default value at runtime for a certain entry, e.g. like:

     QColor computedDefault = qApp->palette().color(QPalette.Active, QPalette.Text)
     QColor color = config->readEntry(key, computedDefault);

then it may wish to make the following check before writing back changes:

     if ( (value == computedDefault) && !config->hasDefault(key) )
        config->revertToDefault(key)
     else
        config->writeEntry(key, value)

This ensures that as long as the entry is not modified to differ from the computed default, the application will keep using the computed default and will follow changes the computed default makes over time.

Parameters:

  | key | the key of the entry to check

Returns:
  true if the global or system settings files specify a default for key in this group, false otherwise

bool hasDefault | ( | self, |
|  | QString | key
| ) |  |  |

Overload for hasDefault(const QString&) const

bool hasGroupImpl | ( | self, |
|  | QByteArray | group
| ) |  |  |

bool hasKey | ( | self, |
|  | QString | key
| ) |  |  |

Checks whether the key has an entry in this group

Use this to determine if a key is not specified for the current group (hasKey() returns false).

If this returns false for a key, readEntry() (and its variants) will return the default value passed to them.

Parameters:

  | key | the key to search for

Returns:
  true if the key is defined in this group by any of the configuration sources, false otherwise

See also:
  readEntry()

bool hasKey | ( | self, |
|  | QString | key
| ) |  |  |

Overload for hasKey(const QString&) const

bool isEntryImmutable | ( | self, |
|  | QString | key
| ) |  |  |

Checks if it is possible to change the given entry

If isImmutable() returns true, then this method will return true for all inputs.

Parameters:

  | key | the key to check

Returns:
  false if the key may be changed using this configuration group object, true otherwise

bool isEntryImmutable | ( | self, |
|  | QString | key
| ) |  |  |

Overload for isEntryImmutable(const QString&) const

bool isGroupImmutableImpl | ( | self, |
|  | QByteArray | aGroup
| ) |  |  |

bool isImmutable | ( |  | self ) |

Whether this group may be changed

Returns:
  false if the group may be changed, true otherwise

bool isValid | ( |  | self ) |

Whether the group is valid.

A group is invalid if it was constructed without arguments.

You should not call any functions on an invalid group.

Returns:
  true if the group is valid, false if it is invalid.

QStringList keyList | ( |  | self ) |

Returns a list of keys this group contains

markAsClean | ( |  | self ) |

QString name | ( |  | self ) |

The name of this group.

The root group is named "<default>".

KConfigGroup parent | ( |  | self ) |

Returns the group that this group belongs to

Returns:
  the parent group, or an invalid group if this is a top-level group

Since:
  4.1

QVariant readEntry | ( | self, |
|  | QString | key,
|  | QVariant | aDefault
| ) |  |  |

Reads the value of an entry specified by key in the current group

Parameters:

  | key | the key to search for
  | aDefault | a default value returned if the key was not found

Returns:
  the value for this key, or aDefault if the key was not found

See also:
  writeEntry(), deleteEntry(), hasKey()

QVariant readEntry | ( | self, |
|  | QString | key,
|  | QVariant | aDefault
| ) |  |  |

Overload for readEntry(const QString&, const QVariant&)

QString readEntry | ( | self, |
|  | QString | key,
|  | QString | aDefault
| ) |  |  |

Reads the string value of an entry specified by key in the current group

If you want to read a path, please use readPathEntry().

Parameters:

  | key | the key to search for
  | aDefault | a default value returned if the key was not found

Returns:
  the value for this key, or aDefault if the key was not found

See also:
  readPathEntry(), writeEntry(), deleteEntry(), hasKey()

QString readEntry | ( | self, |
|  | QString | key,
|  | QString | aDefault
| ) |  |  |

Overload for readEntry(const QString&, const QString&)

QString readEntry | ( | self, |
|  | QString | key,
|  | QString | aDefault=0
| ) |  |  |

Overload for readEntry(const QString&, const QString&)

QString readEntry | ( | self, |
|  | QString | key,
|  | QString | aDefault=0
| ) |  |  |

Overload for readEntry(const QString&, const QString&)

QVariantList readEntry | ( | self, |
|  | QString | key,
|  | QVariantList | aDefault
| ) |  |  |

readEntry(const char*, const QStringList&) const

Warning:
  This function doesn't convert the items returned to any type. It's actually a list of QVariant.String's. If you want the items converted to a specific type use readEntry(const char*, const QList<T>&) const

QVariantList readEntry | ( | self, |
|  | QString | key,
|  | QVariantList | aDefault
| ) |  |  |

Overload for readEntry(const QString&, const QVariantList&)

QStringList readEntry | ( | self, |
|  | QString | key,
|  | QStringList | aDefault
| ) |  |  |

Reads a list of strings from the config object

Parameters:

  | key | The key to search for
  | aDefault | The default value to use if the key does not exist

Returns:
  The list, or aDefault if key does not exist

See also:
  readXdgListEntry(), writeEntry(), deleteEntry(), hasKey()

QStringList readEntry | ( | self, |
|  | QString | key,
|  | QStringList | aDefault
| ) |  |  |

Overload for readEntry(const QString&, const QStringList&)

QString readEntryUntranslated | ( | self, |
|  | QString | pKey,
|  | QString | aDefault=QString()
| ) |  |  |

Reads an untranslated string entry

You should not normally need to use this.

Parameters:

  | pKey | the key to search for
  | aDefault | a default value returned if the key was not found

Returns:
  the value for this key, or aDefault if the key does not exist

QString readEntryUntranslated | ( | self, |
|  | QString | key,
|  | QString | aDefault=QString()
| ) |  |  |

Overload for readEntryUntranslated(const QString&, const QString&)

QString readPathEntry | ( | self, |
|  | QString | pKey,
|  | QString | aDefault
| ) |  |  |

Reads a path

Read the value of an entry specified by pKey in the current group and interpret it as a path. This means, dollar expansion is activated for this value, so that e.g. $HOME gets expanded.

Parameters:

  | pKey | The key to search for.
  | aDefault | A default value returned if the key was not found.

Returns:
  The value for this key. Can be QString() if aDefault is null.

QString readPathEntry | ( | self, |
|  | QString | key,
|  | QString | aDefault
| ) |  |  |

Overload for readPathEntry(const QString&, const QString&)

QStringList readPathEntry | ( | self, |
|  | QString | pKey,
|  | QStringList | aDefault
| ) |  |  |

Reads a list of paths

Read the value of an entry specified by pKey in the current group and interpret it as a list of paths. This means, dollar expansion is activated for this value, so that e.g. $HOME gets expanded.

Parameters:

  | pKey | the key to search for
  | aDefault | a default value returned if the key was not found

Returns:
  the list, or aDefault if the key does not exist

QStringList readPathEntry | ( | self, |
|  | QString | key,
|  | QStringList | aDefault
| ) |  |  |

Overload for readPathEntry(const QString&, const QStringList&)

QStringList readXdgListEntry | ( | self, |
|  | QString | pKey,
|  | QStringList | aDefault=QStringList()
| ) |  |  |

Reads a list of strings from the config object, following XDG desktop entry spec separator semantics

Parameters:

  | pKey | the key to search for
  | aDefault | the default value to use if the key does not exist

Returns:
  the list, or aDefault if pKey does not exist

See also:
  readEntry(const QString&, const QStringList&) const

QStringList readXdgListEntry | ( | self, |
|  | QString | pKey,
|  | QStringList | aDefault=QStringList()
| ) |  |  |

Overload for readXdgListEntry(const QString&, const QStringList&)

reparent | ( | self, |
|  | KConfigBase | parent,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Changes the configuration object that this group belongs to

Note:
  other can be another group, the top-level KConfig object or a different KConfig object entirely.

If parent is already the parent of this group, this method will have no effect.

Parameters:

  | parent | the config object to place this group under
  | pFlags | the flags to use in determining which storage source to write the data to

Since:
  4.1

revertToDefault | ( | self, |
|  | QString | key
| ) |  |  |

Reverts an entry to the default settings.

Reverts the entry with key key in the current group in the application specific config file to either the system wide (default) value or the value specified in the global KDE config file.

To revert entries in the global KDE config file, the global KDE config file should be opened explicitly in a separate config object.

Note:
  This is not the same as deleting the key, as instead the global setting will be copied to the configuration file that this object manipulates.

Parameters:

  | key | The key of the entry to revert.

revertToDefault | ( | self, |
|  | QString | key
| ) |  |  |

Overload for revertToDefault(const QString&)

sync | ( |  | self ) |

writeEntry | ( | self, |
|  | QString | key,
|  | QVariant | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Writes a value to the configuration object.

Parameters:

  | key | the key to write to
  | value | the value to write
  | pFlags | the flags to use when writing this entry

See also:
  readEntry(), writeXdgListEntry(), deleteEntry()

writeEntry | ( | self, |
|  | QString | key,
|  | QVariant | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QString | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QString | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QByteArray | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QByteArray | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QString | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QString | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QStringList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QStringList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QVariantList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writeEntry | ( | self, |
|  | QString | key,
|  | QVariantList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)

writePathEntry | ( | self, |
|  | QString | pKey,
|  | QString | path,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Writes a file path to the configuration

If the path is located under $HOME, the user's home directory is replaced with $HOME in the persistent storage. The path should therefore be read back with readPathEntry()

Parameters:

  | pKey | the key to write to
  | path | the path to write
  | pFlags | the flags to use when writing this entry

See also:
  writeEntry(), readPathEntry()

writePathEntry | ( | self, |
|  | QString | pKey,
|  | QString | path,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writePathEntry(const QString&, const QString&, WriteConfigFlags)

writePathEntry | ( | self, |
|  | QString | pKey,
|  | QStringList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Writes a list of paths to the configuration

If any of the paths are located under $HOME, the user's home directory is replaced with $HOME in the persistent storage. The paths should therefore be read back with readPathEntry()

Parameters:

  | pKey | the key to write to
  | value | the list to write
  | pFlags | the flags to use when writing this entry

See also:
  writeEntry(), readPathEntry()

writePathEntry | ( | self, |
|  | QString | pKey,
|  | QStringList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writePathEntry(const QString&, const QStringList&, WriteConfigFlags)

writeXdgListEntry | ( | self, |
|  | QString | pKey,
|  | QStringList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Writes a list of strings to the config object, following XDG desktop entry spec separator semantics

Parameters:

  | pKey | the key to write to
  | value | the list to write
  | pFlags | the flags to use when writing this entry

See also:
  writeEntry(), readXdgListEntry()

writeXdgListEntry | ( | self, |
|  | QString | pKey,
|  | QStringList | value,
|  | KConfigBase.WriteConfigFlags | pFlags=KConfigBase.Normal
| ) |  |  |

Overload for writeXdgListEntry(const QString&, const QStringList&, WriteConfigFlags)