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

Creates a KConfig object to manipulate a configuration file for the current application.

If an absolute path is specified for file, that file will be used as the store for the configuration settings. If a non-absolute path is provided, the file will be looked for in the standard directory specified by resourceType. If no path is provided, a default configuration file will be used based on the name of the main application component.

mode determines whether the user or global settings will be allowed to influence the values returned by this object. See OpenFlags for more details.

Note:: You probably want to use KSharedConfig.openConfig instead.

Parameters:

	file	the name of the file
	mode	how global settings should affect the configuration options exposed by this KConfig object
	resourceType	The standard directory to look for the configuration file in (see KStandardDirs)

@sa KSharedConfig.openConfig(const QString&, OpenFlags, const char*)

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

Creates a KConfig object to manipulate the configuration for a specific component.

mode determines whether the user or global settings will be allowed to influence the values returned by this object. See KConfig.OpenFlags for more details.

Note:: You probably want to use KSharedConfig.openConfig instead.

Parameters:

	componentData	the component that you wish to load a configuration file for
	file	overrides the configuration file name if not empty
	mode	how global settings should affect the configuration options exposed by this KConfig object. See OpenFlags
	resourceType	The standard directory to look for the configuration file in

@sa KSharedConfig.openConfig(const KComponentData&, const QString&, OpenFlags, const char*)

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

Internal:

Creates a KConfig object 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
	)

Adds the list of configuration sources to the merge stack.

Currently only files are accepted as configuration sources.

The first entry in sources is treated as the most general and will be overridden by the second entry. The settings in the final entry in sources will override all the other sources provided in the list.

The settings in sources will also be overridden by the sources provided by any previous calls to addConfigSources().

The settings in the global configuration sources will be overridden by the sources provided to this method (@see IncludeGlobals). All the sources provided to any call to this method will be overridden by any files that cascade from the source provided to the constructor (@see CascadeConfig), which will in turn be overridden by the source provided to the constructor (either explicitly or implicity via a KComponentData).

Note that only the most specific file, ie: the file provided to the constructor, will be written to by this object.

The state is automatically updated by this method, so there is no need to call reparseConfiguration().

Parameters:

sources

A list of extra config sources.

checkUpdate	(	self,
		QString	id,
		QString	updateFile
	)

Ensures that the configuration file contains a certain update.

If the configuration file does not contain the update id as contained in updateFile, kconf_update is run to update the configuration 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 )

Returns the component data this configuration is for.

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.

The configuration will not actually be saved to file until the returned object is destroyed, or sync() is called on it.

Do not forget to delete the returned KConfig object if config was 0.

Parameters:

	file	the new config object will save itself to
	config	if not 0, copy to the given KConfig object rather than creating a new one

Returns:: config if it was set, otherwise a new KConfig object

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.

The entries are all returned as strings.

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 )

Deprecated:

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
	)

Whether the configuration can be written to.

If warnUser is true and the configuration cannot be written to (ie: this method returns false), a warning message box will be shown to the user telling them to contact their system administrator to get the problem fixed.

The most likely cause for this method returning false is that the user does not have write permission for the configuration file.

Parameters:

warnUser

whether to show a warning message to the user if the configuration cannot be written to

Returns:: true if the configuration can be written to, false if the configuration cannot be written to

bool isGroupImmutableImpl	(	self,
		QByteArray	aGroup
	)

bool isImmutable ( self )

immutability

QString locale ( self )

Returns the current locale.

markAsClean ( self )

QString name ( self )

Returns the filename used to store the configuration.

bool readDefaults ( self )

Returns:: true if the system-wide defaults will be read instead of the user's settings

reparseConfiguration ( self )

Updates the state of this object to match the persistent storage.

setForceGlobal	(	self,
		bool	force
	)

Deprecated:

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, false if the call had no effect (eg: aLocale was already the current locale for this object)

setReadDefaults	(	self,
		bool	b
	)

When set, all readEntry calls return the system-wide (default) values instead of the user's settings.

This is off by default.

Parameters:

whether to read the system-wide defaults instead of the user's settings

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

Determines how the system-wide and user's global settings will affect the reading of the configuration.

If CascadeConfig is selected, system-wide configuration sources are used to provide defaults for the settings accessed through this object, or possibly to override those settings in certain cases.

IncludeGlobals does the same, but with the global settings sources.

Note that the main configuration source overrides the cascaded sources, which override those provided to addConfigSources(), which override the global sources. The exception is that if a key or group is marked as being immutable, it will not be overridden.

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