KConfig 5.109.0
|
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< OpenFlag > | OpenFlags |
Stores a combination of #OpenFlag values. | |
![]() | |
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< WriteConfigFlag > | WriteConfigFlags |
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. | |
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 . | |
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 . | |
![]() | |
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 |
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:
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.
typedef QFlags< OpenFlag > KConfig::OpenFlags |
Stores a combination of #OpenFlag values.
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.
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.
|
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.
file | the 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. |
mode | how global settings should affect the configuration options exposed by this KConfig object |
type | The standard directory to look for the configuration file in |
|
overridevirtual |
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 (
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().
sources | A list of extra config sources. |
QStringList KConfig::additionalConfigSources | ( | ) | const |
Returns a list of the additional configuration sources used in this object.
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.
id | the update to check |
updateFile | the file containing the update |
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.
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 |
config
if it was set, otherwise a new KConfig object
|
overrideprotectedvirtual |
group | name of group, encoded in UTF-8 |
Implements KConfigBase.
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.
aGroup | The group to get entries from. |
bool KConfig::forceGlobal | ( | ) | const |
Returns whether all entries are being written to kdeglobals
.
true
if all entries are being written to kdeglobals
|
overrideprotectedvirtual |
group | name of group, encoded in UTF-8 |
Implements KConfigBase.
|
overrideprotectedvirtual |
group | name of group, encoded in UTF-8 |
Implements KConfigBase.
|
overridevirtual |
Implements KConfigBase.
|
overrideprotectedvirtual |
group | name of group, encoded in UTF-8 |
Implements KConfigBase.
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.
warnUser | whether to show a warning message to the user if the configuration cannot be written to |
bool KConfig::isDirty | ( | ) | const |
Returns true if sync has any changes to write out.
|
overrideprotectedvirtual |
group | name of group, encoded in UTF-8 |
Implements KConfigBase.
|
overridevirtual |
QString KConfig::locale | ( | ) | const |
locales
Returns the current locale.
QStandardPaths::StandardLocation KConfig::locationType | ( | ) | const |
|
static |
Get the name of application config file.
|
overridevirtual |
Implements KConfigBase.
QString KConfig::name | ( | ) | const |
Returns the filename used to store the configuration.
OpenFlags KConfig::openFlags | ( | ) | const |
bool KConfig::readDefaults | ( | ) | const |
true
if the system-wide defaults will be read instead of the user's settings 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.
void KConfig::setForceGlobal | ( | bool | force | ) |
global
Forces all following write-operations to be performed on kdeglobals
, independent of the Global
flag in writeEntry().
force | true to force writing to kdeglobals |
bool KConfig::setLocale | ( | const QString & | aLocale | ) |
Sets the locale to aLocale
.
The global locale is used by default.
true
if locale was changed, false
if the call had no effect (eg: aLocale
was already the current locale for this object)
|
static |
Sets the name of the application config file.
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.
b | whether to read the system-wide defaults instead of the user's settings |
|
overridevirtual |
Implements KConfigBase.
|
overrideprotectedvirtual |
Virtual hook, used to add new "virtual" functions while maintaining binary compatibility.
Unused in this class.
Reimplemented from KConfigBase.