• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KDECore

KConfig Class Reference

The central class of the KDE configuration data system. More...

#include <KConfig>

Inheritance diagram for KConfig:
KConfigBase KDesktopFile KSharedConfig

List of all members.

Public Types

enum  OpenFlag {
  IncludeGlobals = 0x01, CascadeConfig = 0x02, SimpleConfig = 0x00, NoCascade = IncludeGlobals,
  NoGlobals = CascadeConfig, FullConfig = IncludeGlobals|CascadeConfig
}

Public Member Functions

void checkUpdate (const QString &id, const QString &updateFile)
const KComponentData & componentData () const
KConfig * copyTo (const QString &file, KConfig *config=0) const
QMap< QString, QString > entryMap (const QString &aGroup=QString()) const
QStringList groupList () const
 KConfig (const QString &file, const QString &backend, const char *resourceType="config")
 KConfig (const KComponentData &componentData, const QString &file=QString(), OpenFlags mode=FullConfig, const char *resourceType="config")
 KConfig (const QString &file=QString(), OpenFlags mode=FullConfig, const char *resourceType="config")
void markAsClean ()
QString name () const
void reparseConfiguration ()
void sync ()
virtual ~KConfig ()



AccessMode accessMode () const
void addConfigSources (const QStringList &sources)
KDE_DEPRECATED bool forceGlobal () const
bool isConfigWritable (bool warnUser)
bool isImmutable () const
QString locale () const
bool readDefaults () const
KDE_DEPRECATED void setForceGlobal (bool force)
bool setLocale (const QString &aLocale)
void setReadDefaults (bool b)

Protected Member Functions

virtual void deleteGroupImpl (const QByteArray &group, WriteConfigFlags flags=Normal)
virtual const KConfigGroup groupImpl (const QByteArray &b) const
virtual KConfigGroup groupImpl (const QByteArray &b)
virtual bool hasGroupImpl (const QByteArray &group) const
virtual bool isGroupImmutableImpl (const QByteArray &aGroup) const
 KConfig (KConfigPrivate &d)
virtual void virtual_hook (int id, void *data)

Protected Attributes

KConfigPrivate *const d_ptr

Detailed Description

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.

See also:
KSharedConfig, KConfigGroup, the techbase HOWTO on KConfig.

Definition at line 70 of file kconfig.h.


Member Enumeration Documentation

enum KConfig::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.

Enumerator:
IncludeGlobals 

Blend kdeglobals into the config object.

CascadeConfig 

Cascade to system-wide config files.

SimpleConfig 

The following are convenience definitions for the basic mode.

Do not combine them with anything. Just a single config file.

NoCascade 

Include user's globals, but omit system settings.

NoGlobals 

Cascade to system settings, but omit user's globals.

FullConfig 

Fully-fledged config, including globals and cascading to system settings.

Definition at line 88 of file kconfig.h.


Constructor & Destructor Documentation

KConfig::KConfig ( const QString &  file = QString(),
OpenFlags  mode = FullConfig,
const char *  resourceType = "config" 
) [explicit]

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)
See also:
KSharedConfig::openConfig(const QString&, OpenFlags, const char*)

Definition at line 154 of file kconfig.cpp.

KConfig::KConfig ( const KComponentData &  componentData,
const QString &  file = QString(),
OpenFlags  mode = FullConfig,
const char *  resourceType = "config" 
) [explicit]

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

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 component's name.

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
See also:
KSharedConfig::openConfig(const KComponentData&, const QString&, OpenFlags, const char*)

Definition at line 164 of file kconfig.cpp.

KConfig::KConfig ( const QString &  file,
const QString &  backend,
const char *  resourceType = "config" 
)

For internal use only.

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.

  • file the file to be parsed
  • backend the backend to load
  • resourceType where to look for the file if an absolute path is not provided
Since:
4.1

Definition at line 174 of file kconfig.cpp.

KConfig::~KConfig (  )  [virtual]

Definition at line 190 of file kconfig.cpp.

KConfig::KConfig ( KConfigPrivate &  d  )  [protected]

Definition at line 185 of file kconfig.cpp.


Member Function Documentation

KConfig::AccessMode KConfig::accessMode (  )  const [virtual]

configuration object state

Reimplemented from superclass.

Implements KConfigBase.

Definition at line 541 of file kconfig.cpp.

void KConfig::addConfigSources ( const QStringList &  sources  ) 

extra config files

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 also:
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 (
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.

Definition at line 547 of file kconfig.cpp.

void KConfig::checkUpdate ( const QString &  id,
const 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

Definition at line 361 of file kconfig.cpp.

const KComponentData & KConfig::componentData (  )  const

Returns the component data this configuration is for.

Definition at line 198 of file kconfig.cpp.

KConfig * KConfig::copyTo ( const QString &  file,
KConfig *  config = 0 
) const

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

Definition at line 372 of file kconfig.cpp.

void KConfig::deleteGroupImpl ( const QByteArray &  group,
WriteConfigFlags  flags = Normal 
) [protected, virtual]

Implements KConfigBase.

Definition at line 643 of file kconfig.cpp.

QMap< QString, QString > KConfig::entryMap ( const QString &  aGroup = QString()  )  const

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

Definition at line 257 of file kconfig.cpp.

bool KConfig::forceGlobal (  )  const
Deprecated:

Returns whether all entries are being written to kdeglobals.

Returns:
true if all entries are being written to kdeglobals
See also:
setForceGlobal
Deprecated:

Definition at line 614 of file kconfig.cpp.

const KConfigGroup KConfig::groupImpl ( const QByteArray &  b  )  const [protected, virtual]

Implements KConfigBase.

Definition at line 625 of file kconfig.cpp.

KConfigGroup KConfig::groupImpl ( const QByteArray &  b  )  [protected, virtual]

Implements KConfigBase.

Definition at line 620 of file kconfig.cpp.

QStringList KConfig::groupList (  )  const [virtual]
Reimplemented from superclass.

Implements KConfigBase.

Definition at line 204 of file kconfig.cpp.

bool KConfig::hasGroupImpl ( const QByteArray &  group  )  const [protected, virtual]

Implements KConfigBase.

Definition at line 695 of file kconfig.cpp.

bool KConfig::isConfigWritable ( 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

Definition at line 670 of file kconfig.cpp.

bool KConfig::isGroupImmutableImpl ( const QByteArray &  aGroup  )  const [protected, virtual]

Implements KConfigBase.

Definition at line 602 of file kconfig.cpp.

bool KConfig::isImmutable (  )  const [virtual]

immutability

Reimplemented from superclass.

Implements KConfigBase.

Definition at line 596 of file kconfig.cpp.

QString KConfig::locale (  )  const

locales

Returns the current locale.

Definition at line 559 of file kconfig.cpp.

void KConfig::markAsClean (  )  [virtual]
Reimplemented from superclass.

Implements KConfigBase.

Definition at line 350 of file kconfig.cpp.

QString KConfig::name (  )  const

Returns the filename used to store the configuration.

Definition at line 389 of file kconfig.cpp.

bool KConfig::readDefaults (  )  const
Returns:
true if the system-wide defaults will be read instead of the user's settings

Definition at line 590 of file kconfig.cpp.

void KConfig::reparseConfiguration (  ) 

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

Definition at line 438 of file kconfig.cpp.

void KConfig::setForceGlobal ( bool  force  ) 

global

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

Definition at line 608 of file kconfig.cpp.

bool KConfig::setLocale ( const 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)

Definition at line 574 of file kconfig.cpp.

void KConfig::setReadDefaults ( bool  b  ) 

defaults

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

This is off by default.

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

Definition at line 584 of file kconfig.cpp.

void KConfig::sync (  )  [virtual]
Reimplemented from superclass.

Implements KConfigBase.

Definition at line 284 of file kconfig.cpp.

void KConfig::virtual_hook ( int  id,
void *  data 
) [protected, virtual]

Virtual hook, used to add new "virtual" functions while maintaining binary compatibility.

Unused in this class.

Reimplemented from KConfigBase.

Definition at line 757 of file kconfig.cpp.


Member Data Documentation

KConfigPrivate* const KConfig::d_ptr [protected]

Definition at line 387 of file kconfig.h.


The documentation for this class was generated from the following files:
  • kconfig.h
  • kconfig.cpp

KDECore

Skip menu "KDECore"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal