KConfig 5.109.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
KConfig

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

#include <KConfig>

Public Types

enum  OpenFlag {
  IncludeGlobals = 0x01 , CascadeConfig = 0x02 , SimpleConfig = 0x00 , NoCascade = IncludeGlobals ,
  NoGlobals = CascadeConfig , FullConfig = IncludeGlobals | CascadeConfig
}
 Determines how the system-wide and user's global settings will affect the reading of the configuration. More...
 
typedef QFlags< OpenFlagOpenFlags
 Stores a combination of #OpenFlag values.
 
- Public Types inherited from KConfigBase
enum  AccessMode { NoAccess , ReadOnly , ReadWrite }
 Possible return values for accessMode(). More...
 
enum  WriteConfigFlag {
  Persistent = 0x01 , Global = 0x02 , Localized = 0x04 , Notify = 0x08 | Persistent ,
  Normal = Persistent
}
 Flags to control write entry. More...
 
typedef QFlags< WriteConfigFlagWriteConfigFlags
 Stores a combination of #WriteConfigFlag values.
 

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)
 Creates a KConfig object to manipulate a configuration file for the current application.
 
void checkUpdate (const QString &id, const QString &updateFile)
 Ensures that the configuration file contains a certain update.
 
KConfigcopyTo (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.
 
QMap< QString, QString > entryMap (const QString &aGroup=QString()) const
 Returns a map (tree) of entries in a particular group.
 
QStringList groupList () const override
 
bool isDirty () const
 Returns true if sync has any changes to write out.
 
QStandardPaths::StandardLocation locationType () const
 Returns the standard location enum passed to the constructor.
 
void markAsClean () override
 
QString name () const
 Returns the filename used to store the configuration.
 
OpenFlags openFlags () const
 
void reparseConfiguration ()
 Updates the state of this object to match the persistent storage.
 
bool sync () override
 
AccessMode accessMode () const override
 
bool isConfigWritable (bool warnUser)
 Whether the configuration can be written to.
 
void addConfigSources (const QStringList &sources)
 extra config files
 
QStringList additionalConfigSources () const
 Returns a list of the additional configuration sources used in this object.
 
QString locale () const
 locales
 
bool setLocale (const QString &aLocale)
 Sets the locale to aLocale.
 
void setReadDefaults (bool b)
 defaults
 
bool readDefaults () const
 
bool isImmutable () const override
 
void setForceGlobal (bool force)
 global
 
bool forceGlobal () const
 Returns whether all entries are being written to kdeglobals.
 
- Public Member Functions inherited from KConfigBase
virtual ~KConfigBase ()
 Destructs the KConfigBase object.
 
virtual AccessMode accessMode () const =0
 Returns the access mode of the app-config object.
 
void deleteGroup (const char *group, WriteConfigFlags flags=Normal)
 Overload for deleteGroup(const QString&, WriteConfigFlags)
 
void deleteGroup (const QByteArray &group, WriteConfigFlags flags=Normal)
 Overload for deleteGroup(const QString&, WriteConfigFlags)
 
void deleteGroup (const QString &group, WriteConfigFlags flags=Normal)
 Delete group.
 
KConfigGroup group (const char *group)
 Overload for group(const QString&)
 
const KConfigGroup group (const char *group) const
 Const overload for group(const QString&)
 
KConfigGroup group (const QByteArray &group)
 Overload for group(const QString&)
 
const KConfigGroup group (const QByteArray &group) const
 Const overload for group(const QString&)
 
KConfigGroup group (const QString &group)
 Returns an object for the named subgroup.
 
const KConfigGroup group (const QString &group) const
 Const overload for group(const QString&)
 
virtual QStringList groupList () const =0
 Returns a list of groups that are known about.
 
bool hasGroup (const char *group) const
 Overload for hasGroup(const QString&) const.
 
bool hasGroup (const QByteArray &group) const
 Overload for hasGroup(const QString&) const.
 
bool hasGroup (const QString &group) const
 Returns true if the specified group is known about.
 
bool isGroupImmutable (const char *group) const
 Overload for isGroupImmutable(const QString&) const.
 
bool isGroupImmutable (const QByteArray &group) const
 Overload for isGroupImmutable(const QString&) const.
 
bool isGroupImmutable (const QString &group) const
 Can changes be made to the entries in group?
 
virtual bool isImmutable () const =0
 Checks whether this configuration object can be modified.
 
virtual void markAsClean ()=0
 Reset the dirty flags of all entries in the entry map, so the values will not be written to disk on a later call to sync().
 
virtual bool sync ()=0
 Syncs the configuration object that this group belongs to.
 

Static Public Member Functions

static QString mainConfigName ()
 Get the name of application config file.
 
static void setMainConfigName (const QString &str)
 Sets the name of the application config file.
 

Protected Member Functions

 __attribute__ ((visibility("hidden"))) explicit 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
 Virtual hook, used to add new "virtual" functions while maintaining binary compatibility.
 
virtual void deleteGroupImpl (const QByteArray &group, WriteConfigFlags flags=Normal)=0
 
virtual const KConfigGroup groupImpl (const QByteArray &group) const =0
 
virtual KConfigGroup groupImpl (const QByteArray &group)=0
 
virtual bool hasGroupImpl (const QByteArray &group) const =0
 
virtual bool isGroupImmutableImpl (const QByteArray &group) const =0
 
virtual void virtual_hook (int id, void *data)
 Virtual hook, used to add new "virtual" functions while maintaining binary compatibility.
 

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:

KConfig config( "/etc/kderc", KConfig::SimpleConfig );
The central class of the KDE configuration data system.
Definition kconfig.h:57
@ SimpleConfig
Just a single config file.
Definition kconfig.h:86

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.

Member Typedef Documentation

◆ OpenFlags

typedef QFlags< OpenFlag > KConfig::OpenFlags

Stores a combination of #OpenFlag values.

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.

Constructor & Destructor Documentation

◆ KConfig()

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)

Member Function Documentation

◆ accessMode()

AccessMode KConfig::accessMode ( ) const
overridevirtual

configuration object state

Reimplemented from superclass.

Implements KConfigBase.

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

◆ additionalConfigSources()

QStringList KConfig::additionalConfigSources ( ) const

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

◆ 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

◆ 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

◆ deleteGroupImpl()

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

Implements KConfigBase.

◆ 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

◆ 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

◆ groupImpl() [1/2]

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

Implements KConfigBase.

◆ groupImpl() [2/2]

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

Implements KConfigBase.

◆ groupList()

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

Implements KConfigBase.

◆ hasGroupImpl()

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

Implements KConfigBase.

◆ 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

◆ isDirty()

bool KConfig::isDirty ( ) const

Returns true if sync has any changes to write out.

Since
4.12

◆ isGroupImmutableImpl()

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

Implements KConfigBase.

◆ isImmutable()

bool KConfig::isImmutable ( ) const
overridevirtual

immutability

Reimplemented from superclass.

Implements KConfigBase.

◆ locale()

QString KConfig::locale ( ) const

locales

Returns the current locale.

◆ locationType()

QStandardPaths::StandardLocation KConfig::locationType ( ) const

Returns the standard location enum passed to the constructor.

Used by KSharedConfig.

Since
5.0

◆ mainConfigName()

static QString KConfig::mainConfigName ( )
static

Get the name of application config file.

Since
5.93

◆ markAsClean()

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

Implements KConfigBase.

◆ name()

QString KConfig::name ( ) const

Returns the filename used to store the configuration.

◆ openFlags()

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

◆ readDefaults()

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

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

◆ 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

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

◆ setMainConfigName()

static void KConfig::setMainConfigName ( const QString &  str)
static

Sets the name of the application config file.

Since
5.0

◆ 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

◆ sync()

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

Implements KConfigBase.

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