KConfig Class Reference

from PyKDE4.kdecore import *

Inherits: KConfigBase
Subclasses: KDesktopFile, KSharedConfig

Detailed Description

\class KConfig kconfig.h <KConfig>

The central class of the KDE configuration data system.

Quickstart:

Get the default application config object via KGlobal.config().

Load a specific configuration file:

 KConfig config( "/etc/kderc", KConfig.SimpleConfig );

Load the configuration of a specific component (taking into account possible custom dirs in KStandardDirs):

 KConfig config( componentData(), "pluginrc" );

In general it is recommended to use KSharedConfig instead of creating multiple instances of KConfig to avoid the overhead of separate objects or concerns about synchronizing writes to disk even if the configuration object is updated from multiple code paths. KSharedConfig provides a set of open methods as counterparts for the KConfig constructors.

\sa KSharedConfig, KConfigGroup, the techbase HOWTO on KConfig.

Enumerations
OpenFlag	{ IncludeGlobals, CascadeConfig, SimpleConfig, NoCascade, NoGlobals, FullConfig } Typesafe wrapper: OpenFlags
Methods
	__init__ (self, QString file=QString(), KConfig.OpenFlags mode=KConfig.FullConfig, QString resourceType="config")
	__init__ (self, KComponentData componentData, QString file=QString(), KConfig.OpenFlags mode=KConfig.FullConfig, QString resourceType="config")
	__init__ (self, QString file, QString backend, QString resourceType="config")
	__init__ (self, KConfigPrivate d)
	__init__ (self, KConfig a0)
KConfigBase.AccessMode	accessMode (self)
	addConfigSources (self, QStringList sources)
	checkUpdate (self, QString id, QString updateFile)
KComponentData	componentData (self)
KConfig	copyTo (self, QString file, KConfig config=0)
	deleteGroupImpl (self, QByteArray group, KConfigBase.WriteConfigFlags flags=KConfigBase.Normal)
QMap	entryMap (self, QString aGroup=QString())
bool	forceGlobal (self)
KConfigGroup	groupImpl (self, QByteArray b)
KConfigGroup	groupImpl (self, QByteArray b)
QStringList	groupList (self)
bool	hasGroupImpl (self, QByteArray group)
bool	isConfigWritable (self, bool warnUser)
bool	isGroupImmutableImpl (self, QByteArray aGroup)
bool	isImmutable (self)
QString	locale (self)
	markAsClean (self)
QString	name (self)
bool	readDefaults (self)
	reparseConfiguration (self)
	setForceGlobal (self, bool force)
bool	setLocale (self, QString aLocale)
	setReadDefaults (self, bool b)
	sync (self)
	virtual_hook (self, int id, void data)

Method Documentation

__init__	(	self,
		QString	file=QString(),
		KConfig.OpenFlags	mode=KConfig.FullConfig,
		QString	resourceType="config"
	)

__init__	(	self,
		KComponentData	componentData,
		QString	file=QString(),
		KConfig.OpenFlags	mode=KConfig.FullConfig,
		QString	resourceType="config"
	)

__init__	(	self,
		QString	file,
		QString	backend,
		QString	resourceType="config"
	)

Creates a KConfig oject using the specified backend. If the backend can not be found or loaded, then the standard configuration parser is used as a fallback.

@arg file the file to be parsed @arg backend the backend to load @arg resourceType where to look for the file if an absolute path is not provided

Since:: 4.1

__init__	(	self,
		KConfigPrivate	d
	)

__init__	(	self,
		KConfig	a0
	)

KConfigBase.AccessMode accessMode ( self )

configuration object state

addConfigSources	(	self,
		QStringList	sources
	)

Sets the merge stack to the list of files. The stack is last in first out with the top of the stack being the most specific config file. The files in the merge stack will be read before the file passed to the constructor and any files that cascade from that file. This means that the entries read from the files in the merge stack will be treated as defaults. This function will automatically call reparseConfiguration() for you.

@note: Most specific config file is relative to this list, the overall most specific file of this KConfig object is still the file it was created with, no matter which file is passed last into this function. This means that writing always goes to the file which was used to create the KConfig object.

Parameters:

files

A list of extra config files.

checkUpdate	(	self,
		QString	id,
		QString	updateFile
	)

Checks whether the config file contains the update id as contained in updateFile. If not, it runs kconf_update to update the config file.

If you install config update files with critical fixes you may wish to use this method to verify that a critical update has indeed been performed to catch the case where a user restores an old config file from backup that has not been updated yet.

Parameters:

	id	the update to check
	updateFile	the file containing the update

KComponentData componentData ( self )

KConfig copyTo	(	self,
		QString	file,
		KConfig	config=0
	)

Copies all entries from this config object to a new config object that will save itself to file.

Actual saving to file happens when the returned object is destructed or when sync() is called upon it.

Parameters:

	file	the new config object will save itself to.
	config	optional config object to reuse

Returns:: the same as config if it was set, otherwise a new KConfig object. In that case, do not forget to delete it!

deleteGroupImpl	(	self,
		QByteArray	group,
		KConfigBase.WriteConfigFlags	flags=KConfigBase.Normal
	)

QMap entryMap	(	self,
		QString	aGroup=QString()
	)

Returns a map (tree) of entries in a particular group. Only the actual entry as a string is returned.

Parameters:

aGroup

The group to get entries from.

Returns:: A map of entries in the group specified, indexed by key. The returned map may be empty if the group is empty, or not found.

See also:: QMap

bool forceGlobal ( self )

Returns whether all entries are being written to kdeglobals.

Returns:: true if all entries are being written to kdeglobals

See also:: setForceGlobal

Deprecated:

KConfigGroup groupImpl	(	self,
		QByteArray	b
	)

KConfigGroup groupImpl	(	self,
		QByteArray	b
	)

QStringList groupList ( self )

bool hasGroupImpl	(	self,
		QByteArray	group
	)

bool isConfigWritable	(	self,
		bool	warnUser
	)

Return false if the user cannot write to this KConfig instance, for instance because of permission problems.

Parameters:

warnUser

if true, show a message box telling the user to contact his system administrator for getting this problem fixed.

bool isGroupImmutableImpl	(	self,
		QByteArray	aGroup
	)

bool isImmutable ( self )

immutability

QString locale ( self )

Returns the current locale.

markAsClean ( self )

QString name ( self )

Returns the filename passed to the constructor.

bool readDefaults ( self )

reparseConfiguration ( self )

Clears all internal data structures and then reread configuration information from persistent storage.

setForceGlobal	(	self,
		bool	force
	)

Forces all following write-operations to be performed on kdeglobals, independent of the Global flag in writeEntry().

Parameters:

force

true to force writing to kdeglobals

See also:: forceGlobal

bool setLocale	(	self,
		QString	aLocale
	)

Sets the locale to aLocale. The global locale is used by default.

Note:: If set to the empty string, no locale will be matched. This effectively disables reading translated entries.

Returns:: true if locale was changed and configuration was reparsed.

setReadDefaults	(	self,
		bool	b
	)

When set, all readEntry calls return the system-wide (default) values instead of the user's preference. This is off by default.

sync ( self )

virtual_hook	(	self,
		int	id,
		void	data
	)

Virtual hook, used to add new "virtual" functions while maintaining binary compatibility. Unused in this class.

Enumeration Documentation

OpenFlag

Note:: It is necessary to wrap members of this enumeration in a OpenFlags instance when passing them to a method as group of flags. For example: OpenFlags( IncludeGlobals | CascadeConfig)

Enumerator:

IncludeGlobals = 0x01
CascadeConfig = 0x02
SimpleConfig = 0x00
NoCascade = IncludeGlobals
NoGlobals = CascadeConfig
FullConfig = IncludeGlobals\|CascadeConfig

KConfig Class Reference

Detailed Description

Enumerations

Methods

Method Documentation

Enumeration Documentation

Modules