KConfig

Search for usage in LXR

#include <KConfig>

Inheritance diagram for KConfig:

Public Types

enum  OpenFlag {
  IncludeGlobals = 0x01, CascadeConfig = 0x02, SimpleConfig = 0x00, NoCascade = IncludeGlobals,
  NoGlobals = CascadeConfig, FullConfig = IncludeGlobals | CascadeConfig
}
 
typedef QFlags< OpenFlagOpenFlags
 
- Public Types inherited from KConfigBase
enum  AccessMode { NoAccess, ReadOnly, ReadWrite }
 
enum  WriteConfigFlag {
  Persistent = 0x01, Global = 0x02, Localized = 0x04, Notify = 0x08 | Persistent,
  Normal = Persistent
}
 
typedef QFlags< WriteConfigFlagWriteConfigFlags
 

Public Member Functions

 KConfig (const QString &file, const QString &backend, QStandardPaths::StandardLocation type=QStandardPaths::GenericConfigLocation)
 
 KConfig (const QString &file=QString(), OpenFlags mode=FullConfig, QStandardPaths::StandardLocation type=QStandardPaths::GenericConfigLocation)
 
void checkUpdate (const QString &id, const QString &updateFile)
 
KConfigcopyTo (const QString &file, KConfig *config=nullptr) const
 
QMap< QString, QStringentryMap (const QString &aGroup=QString()) const
 
QStringList groupList () const override
 
bool isDirty () const
 
QStandardPaths::StandardLocation locationType () const
 
void markAsClean () override
 
QString name () const
 
OpenFlags openFlags () const
 
void reparseConfiguration ()
 
bool sync () override
 
AccessMode accessMode () const override
 
bool isConfigWritable (bool warnUser)
 
void addConfigSources (const QStringList &sources)
 
QStringList additionalConfigSources () const
 
QString locale () const
 
bool setLocale (const QString &aLocale)
 
void setReadDefaults (bool b)
 
bool readDefaults () const
 
bool isImmutable () const override
 
void setForceGlobal (bool force)
 
bool forceGlobal () const
 
- Public Member Functions inherited from KConfigBase
virtual ~KConfigBase ()
 
void deleteGroup (const char *group, WriteConfigFlags flags=Normal)
 
void deleteGroup (const QByteArray &group, WriteConfigFlags flags=Normal)
 
void deleteGroup (const QString &group, WriteConfigFlags flags=Normal)
 
KConfigGroup group (const char *group)
 
const KConfigGroup group (const char *group) const
 
KConfigGroup group (const QByteArray &group)
 
const KConfigGroup group (const QByteArray &group) const
 
KConfigGroup group (const QString &group)
 
const KConfigGroup group (const QString &group) const
 
bool hasGroup (const char *group) const
 
bool hasGroup (const QByteArray &group) const
 
bool hasGroup (const QString &group) const
 
bool isGroupImmutable (const char *group) const
 
bool isGroupImmutable (const QByteArray &group) const
 
bool isGroupImmutable (const QString &group) const
 

Static Public Member Functions

static QString mainConfigName ()
 
static void setMainConfigName (const QString &str)
 

Protected Member Functions

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

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 KSharedConfig::openConfig().

Load a specific configuration file:

Load the configuration of a specific component:

KConfig config( "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 56 of file kconfig.h.

Member Typedef Documentation

◆ OpenFlags

Stores a combination of OpenFlag values.

Definition at line 94 of file kconfig.h.

Member 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.

If IncludeGlobals is selected, the kdeglobals configuration is used as additional configuration sources to provide defaults. Additionally selecting CascadeConfig will result in the system-wide kdeglobals sources also getting included.

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 that all values other than IncludeGlobals and CascadeConfig are convenience definitions for the basic mode. Do not combine them with anything.

See also
OpenFlags
Enumerator
IncludeGlobals 

Blend kdeglobals into the config object.

CascadeConfig 

Cascade to system-wide config files.

SimpleConfig 

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 82 of file kconfig.h.

Constructor & Destructor Documentation

◆ KConfig() [1/2]

KConfig::KConfig ( const QString file = QString(),
OpenFlags  mode = FullConfig,
QStandardPaths::StandardLocation  type = QStandardPaths::GenericConfigLocation 
)
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 type. 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
filethe name of the file. If an empty string is passed in and SimpleConfig is passed in for the OpenFlags, then an in-memory KConfig object is created which will not write out to file nor which requires any file in the filesystem at all.
modehow global settings should affect the configuration options exposed by this KConfig object
typeThe standard directory to look for the configuration file in
See also
KSharedConfig::openConfig(const QString&, OpenFlags, QStandardPaths::StandardLocation)

Definition at line 246 of file kconfig.cpp.

◆ KConfig() [2/2]

KConfig::KConfig ( const QString file,
const QString backend,
QStandardPaths::StandardLocation  type = QStandardPaths::GenericConfigLocation 
)

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.

Parameters
filethe file to be parsed
backendthe backend to load
typewhere to look for the file if an absolute path is not provided
Since
4.1

Definition at line 255 of file kconfig.cpp.

Member Function Documentation

◆ accessMode()

KConfig::AccessMode KConfig::accessMode ( ) const
overridevirtual

configuration object state

Reimplemented from superclass.

Implements KConfigBase.

Definition at line 810 of file kconfig.cpp.

◆ addConfigSources()

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.

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
sourcesA list of extra config sources.

Definition at line 816 of file kconfig.cpp.

◆ additionalConfigSources()

QStringList KConfig::additionalConfigSources ( ) const

Returns a list of the additional configuration sources used in this object.

Definition at line 828 of file kconfig.cpp.

◆ checkUpdate()

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
idthe update to check
updateFilethe file containing the update

Definition at line 534 of file kconfig.cpp.

◆ copyTo()

KConfig * KConfig::copyTo ( const QString file,
KConfig config = nullptr 
) 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
filethe new config object will save itself to
configif 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 545 of file kconfig.cpp.

◆ deleteGroupImpl()

void KConfig::deleteGroupImpl ( const QByteArray group,
WriteConfigFlags  flags = Normal 
)
overrideprotectedvirtual
Parameters
groupname of group, encoded in UTF-8

Implements KConfigBase.

Definition at line 928 of file kconfig.cpp.

◆ entryMap()

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
aGroupThe 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 380 of file kconfig.cpp.

◆ forceGlobal()

bool KConfig::forceGlobal ( ) const

Returns whether all entries are being written to kdeglobals.

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

Definition at line 892 of file kconfig.cpp.

◆ groupImpl() [1/2]

const KConfigGroup KConfig::groupImpl ( const QByteArray group) const
overrideprotectedvirtual
Parameters
groupname of group, encoded in UTF-8

Implements KConfigBase.

Definition at line 904 of file kconfig.cpp.

◆ groupImpl() [2/2]

KConfigGroup KConfig::groupImpl ( const QByteArray group)
overrideprotectedvirtual
Parameters
groupname of group, encoded in UTF-8

Implements KConfigBase.

Definition at line 899 of file kconfig.cpp.

◆ groupList()

QStringList KConfig::groupList ( ) const
overridevirtual
Reimplemented from superclass.

Implements KConfigBase.

Definition at line 305 of file kconfig.cpp.

◆ hasGroupImpl()

bool KConfig::hasGroupImpl ( const QByteArray group) const
overrideprotectedvirtual
Parameters
groupname of group, encoded in UTF-8

Implements KConfigBase.

Definition at line 970 of file kconfig.cpp.

◆ isConfigWritable()

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
warnUserwhether 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 946 of file kconfig.cpp.

◆ isDirty()

bool KConfig::isDirty ( ) const

Returns true if sync has any changes to write out.

Since
4.12

Definition at line 528 of file kconfig.cpp.

◆ isGroupImmutableImpl()

bool KConfig::isGroupImmutableImpl ( const QByteArray group) const
overrideprotectedvirtual
Parameters
groupname of group, encoded in UTF-8

Implements KConfigBase.

Definition at line 877 of file kconfig.cpp.

◆ isImmutable()

bool KConfig::isImmutable ( ) const
overridevirtual

immutability

Reimplemented from superclass.

Implements KConfigBase.

Definition at line 871 of file kconfig.cpp.

◆ locale()

QString KConfig::locale ( ) const

locales

Returns the current locale.

Definition at line 834 of file kconfig.cpp.

◆ locationType()

QStandardPaths::StandardLocation KConfig::locationType ( ) const

Returns the standard location enum passed to the constructor.

Used by KSharedConfig.

Since
5.0

Definition at line 1044 of file kconfig.cpp.

◆ mainConfigName()

QString KConfig::mainConfigName ( )
static

Get the name of application config file.

Since
5.93

Definition at line 588 of file kconfig.cpp.

◆ markAsClean()

void KConfig::markAsClean ( )
overridevirtual
Reimplemented from superclass.

Implements KConfigBase.

Definition at line 515 of file kconfig.cpp.

◆ name()

QString KConfig::name ( ) const

Returns the filename used to store the configuration.

Definition at line 564 of file kconfig.cpp.

◆ openFlags()

KConfig::OpenFlags KConfig::openFlags ( ) const
Returns
the flags this object was opened with
Since
5.3

Definition at line 570 of file kconfig.cpp.

◆ readDefaults()

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

Definition at line 865 of file kconfig.cpp.

◆ reparseConfiguration()

void KConfig::reparseConfiguration ( )

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

Note that if this object has pending changes, this method will call sync() first so as not to lose those changes.

Definition at line 652 of file kconfig.cpp.

◆ setForceGlobal()

void KConfig::setForceGlobal ( bool  force)

global

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

Parameters
forcetrue to force writing to kdeglobals
See also
forceGlobal
Deprecated:
Since 4.0

Definition at line 884 of file kconfig.cpp.

◆ setLocale()

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 849 of file kconfig.cpp.

◆ setMainConfigName()

void KConfig::setMainConfigName ( const QString str)
static

Sets the name of the application config file.

Since
5.0

Definition at line 583 of file kconfig.cpp.

◆ setReadDefaults()

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
bwhether to read the system-wide defaults instead of the user's settings

Definition at line 859 of file kconfig.cpp.

◆ sync()

bool KConfig::sync ( )
overridevirtual
Reimplemented from superclass.

Implements KConfigBase.

Definition at line 411 of file kconfig.cpp.

◆ virtual_hook()

void KConfig::virtual_hook ( int  id,
void *  data 
)
overrideprotectedvirtual

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

Unused in this class.

Reimplemented from KConfigBase.

Definition at line 1050 of file kconfig.cpp.


The documentation for this class was generated from the following files:
The central class of the KDE configuration data system.
Definition: kconfig.h:56
KSharedConfigPtr config()
@ SimpleConfig
Just a single config file.
Definition: kconfig.h:86
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Oct 3 2023 04:08:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.