KConfigGroup Class Reference

from PyKDE4.kdecore import *

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	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 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 )

Syncs the parent config.

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
	)