KConfigGroup Class

auto config = KSharedConfig::openConfig();
auto globalGroup = KConfigGroup(config, QString());

Member Function Documentation

KConfigGroup::KConfigGroup()

Constructs an invalid group.

See also isValid.

KConfigGroup::KConfigGroup(KConfigBase *master, const QString &group)

Constructs a config group corresponding to group in master.

This allows the creation of subgroups by passing another group as master. For example:

auto generalGroup = KConfigGroup(config, "General");
auto preferencesGroup = KConfigGroup(&generalGroup, "Preferences");
preferencesGroup.writeEntry("SomeKey", true);

Will render the following in the configuration file:

[General][Preferences]
SomeKey=true

KConfigGroup::KConfigGroup(const KConfigBase *master, const QString &group)

Constructs a read-only config group by passing a const config object.

A read-only group will silently ignore any attempts to write to it.

This allows the creation of subgroups by passing an existing group as master.

KConfigGroup::KConfigGroup(const QExplicitlySharedDataPointer<KSharedConfig> &master, const QString &group)

KConfig *KConfigGroup::config()

Returns the config object that this group belongs to.

const KConfig *KConfigGroup::config() const

Returns the read-only config object that this group belongs to.

void KConfigGroup::copyTo(KConfigBase *other, KConfigBase::WriteConfigFlags pFlags = Normal) const

Copies the entries in this group to other configuration object with the given pFlags.

void KConfigGroup::deleteEntry(const QString &pKey, KConfigBase::WriteConfigFlags pFlags = Normal)

Deletes the entry specified by pKey in the current group with the given pFlags.

This also hides system wide defaults.

See also deleteGroup(), readEntry(), and writeEntry().

void KConfigGroup::deleteEntry(const char *key, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::deleteGroup(KConfigBase::WriteConfigFlags pFlags = Normal)

Delete all entries in the entire group with the given pFlags.

See also deleteEntry().

QMap<QString, QString> KConfigGroup::entryMap() const

Returns a map (tree) of entries for all entries in this group.

Only the actual entry string is returned, none of the other internal data should be included.

bool KConfigGroup::exists() const

Returns whether the containing KConfig object actually contains a group with this name.

bool KConfigGroup::hasDefault(const QString &key) const

Returns whether a default is specified for an entry key in either the system wide configuration file or the global KDE config file.

If an application computes a default value at runtime for a certain entry, like:

QColor computedDefault = qApp->palette().color(QPalette::Active, QPalette::Text);
QColor color = group.readEntry(key, computedDefault);

then it may wish to make the following check before writing back changes:

if ( (value == computedDefault) && !group.hasDefault(key) )
   group.revertToDefault(key);
else
   group.writeEntry(key, value);

This ensures that as long as the entry is not modified to differ from the computed default, the application will keep using the computed default and will follow changes the computed default makes over time.

bool KConfigGroup::hasDefault(const char *key) const

The key will be encoded in UTF-8.

bool KConfigGroup::hasKey(const QString &key) const

Returns whether the key exists in this group in any of the configuration sources.

If this returns false for a key, readEntry() (and its variants) will return the default value passed to them.

See also readEntry().

bool KConfigGroup::hasKey(const char *key) const

The key will be encoded in UTF-8.

bool KConfigGroup::isEntryImmutable(const QString &key) const

Returns whether it is possible to change the given entry key.

If isImmutable() returns true, then this method will return true for all inputs.

See also KAuthorized and Kiosk - Simple configuration management for large deployment.

bool KConfigGroup::isEntryImmutable(const char *key) const

The key will be encoded in UTF-8.

[override virtual] bool KConfigGroup::isImmutable() const

Reimplements: KConfigBase::isImmutable() const.

Returns whether this group may be changed.

See also KAuthorized and Kiosk - Simple configuration management for large deployment.

bool KConfigGroup::isValid() const

Returns whether the group is valid.

A group is invalid if it was constructed without arguments.

You should not call any functions on an invalid group.

QStringList KConfigGroup::keyList() const

Returns a list of keys this group contains.

[since 6.3] void KConfigGroup::moveValuesTo(KConfigGroup &other, KConfigBase::WriteConfigFlags pFlags = Normal)

Moves the key-value pairs from one config group to the other with the given pFlags.

This function was introduced in 6.3.

void KConfigGroup::moveValuesTo(const QList<const char *> &keys, KConfigGroup &other, KConfigBase::WriteConfigFlags pFlags = Normal)

Moves the key-value pairs with specific keys from one config group to the other with the given pFlags.

In case the entries do not exist the key is ignored.

QString KConfigGroup::name() const

The name of this group.

The root group is named "<default>".

KConfigGroup KConfigGroup::parent() const

Returns the parent group that this group belongs to, or an invalid group if this is a top-level group.

template <typename T> QList<T> KConfigGroup::readEntry(const QString &key, const QList<T> &aDefault) const

Reads a list of values of an entry specified by key in the current group, returning aDefault value if the key is not found.

See also readXdgListEntry(), writeEntry(), deleteEntry(), and hasKey().

QString KConfigGroup::readEntry(const QString &key, const QString &aDefault) const

Reads the string value of an entry specified by key in the current group, returning aDefault value if the key is not found.

If you want to read a path, use readPathEntry().

See also readPathEntry(), writeEntry(), deleteEntry(), and hasKey().

QStringList KConfigGroup::readEntry(const QString &key, const QStringList &aDefault) const

Reads the string list values of an entry specified by key in the current group, returning aDefault value if the key is not found.

See also readXdgListEntry(), writeEntry(), deleteEntry(), and hasKey().

QVariant KConfigGroup::readEntry(const QString &key, const QVariant &aDefault) const

Reads the value of an entry specified by key in the current group, returning aDefault value if the key is not found.

See also writeEntry(), deleteEntry(), and hasKey().

template <typename T> T KConfigGroup::readEntry(const QString &key, const T &aDefault) const

Reads the value of an entry specified by key in the current group, returning aDefault value if the key is not found.

This template method makes it possible to write:

QString foo = readEntry("...", QString("default"));

and the same with all other types supported by QVariant.

The return type of the method is simply the same as the type of the default value.

See also writeEntry(), deleteEntry(), and hasKey().

[since 6.22] template <typename Rep, typename Period> std::chrono::duration<Rep, Period> KConfigGroup::readEntry(const QString &key, std::chrono::duration<Rep, Period> defaultValue) const

Reads a std::chrono duration of an entry specified by key in the current group, returning the defaultValue if the key is not found.

This function was introduced in 6.22.

QVariantList KConfigGroup::readEntry(const QString &key, const QVariantList &aDefault) const

See also readEntry().

QString KConfigGroup::readEntry(const QString &key, const char *aDefault = nullptr) const

template <typename T> QList<T> KConfigGroup::readEntry(const char *key, const QList<T> &aDefault) const

The key name will be encoded in UTF-8.

QString KConfigGroup::readEntry(const char *key, const QString &aDefault) const

The key name will be encoded in UTF-8.

QStringList KConfigGroup::readEntry(const char *key, const QStringList &aDefault) const

The key name will be encoded in UTF-8.

QVariant KConfigGroup::readEntry(const char *key, const QVariant &aDefault) const

The key name will be encoded in UTF-8.

QVariantList KConfigGroup::readEntry(const char *key, const QVariantList &aDefault) const

The key name will be encoded in UTF-8.

template <typename T> T KConfigGroup::readEntry(const char *key, const T &aDefault) const

The key name will be encoded in UTF-8.

QString KConfigGroup::readEntry(const char *key, const char *aDefault = nullptr) const

The key name will be encoded in UTF-8.

[since 6.22] template <typename Rep, typename Period> std::chrono::duration<Rep, Period> KConfigGroup::readEntry(const char *key, std::chrono::duration<Rep, Period> defaultValue) const

The key name will be encoded in UTF-8.

This function was introduced in 6.22.

QString KConfigGroup::readEntryUntranslated(const QString &pKey, const QString &aDefault = QString()) const

Reads the untranslated string for an entry specified by pKey in the current group, returning aDefault value if the key is not found.

QString KConfigGroup::readEntryUntranslated(const char *key, const QString &aDefault = QString()) const

The key name will be encoded in UTF-8.

QString KConfigGroup::readPathEntry(const QString &pKey, const QString &aDefault) const

Reads the path value of an entry specified by pKey in the current group, returning aDefault value if the key is not found. If aDefault is null, an empty QString() is returned.

Dollar expansion is activated for this value, so that for example $HOME gets expanded.

QStringList KConfigGroup::readPathEntry(const QString &pKey, const QStringList &aDefault) const

Reads the list of paths of an entry specified by pKey in the current group, returning aDefault value if the key is not found.

Dollar expansion is activated for this value, so that for example $HOME gets expanded.

QString KConfigGroup::readPathEntry(const char *key, const QString &aDefault) const

The key name will be encoded in UTF-8.

QStringList KConfigGroup::readPathEntry(const char *key, const QStringList &aDefault) const

The key name will be encoded in UTF-8.

QStringList KConfigGroup::readXdgListEntry(const QString &pKey, const QStringList &aDefault = QStringList()) const

Reads the list of strings of an entry specified by pKey in the current group, returning aDefault value if the key is not found.

See also readEntry(const QString&, const QStringList&).

QStringList KConfigGroup::readXdgListEntry(const char *key, const QStringList &aDefault = QStringList()) const

The key name will be encoded in UTF-8.

void KConfigGroup::reparent(KConfigBase *parent, KConfigBase::WriteConfigFlags pFlags = Normal)

Changes the configuration object that this group belongs to to parent with the given pFlags.

void KConfigGroup::revertToDefault(const QString &key, KConfigBase::WriteConfigFlags pFlag = WriteConfigFlags())

Reverts an entry key to the default settings with the given pFlag in the current group.

The default settings will be either the system wide (default) value or the value specified in the global KDE config file.

To revert entries in the global KDE config file, the global KDE config file should be opened explicitly in a separate config object.

void KConfigGroup::revertToDefault(const char *key, KConfigBase::WriteConfigFlags pFlag = WriteConfigFlags())

The key will be encoded in UTF-8.

void KConfigGroup::writeEntry(const QString &key, const QVariant &value, KConfigBase::WriteConfigFlags pFlags = Normal)

Writes key and value to the configuration object with the given pFlags.

Changes to the file will only be synced with KConfig::reparseConfiguration() or KConfigBase::sync().

See also readEntry(), writeXdgListEntry(), and deleteEntry().

void KConfigGroup::writeEntry(const QString &key, const QByteArray &value, KConfigBase::WriteConfigFlags pFlags = Normal)

template <typename T> void KConfigGroup::writeEntry(const QString &key, const QList<T> &value, KConfigBase::WriteConfigFlags pFlags = Normal)

void KConfigGroup::writeEntry(const QString &key, const QString &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writeEntry(const QString &key, const QStringList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

void KConfigGroup::writeEntry(const QString &key, const QVariantList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

template <typename T> void KConfigGroup::writeEntry(const QString &key, const T &value, KConfigBase::WriteConfigFlags pFlags = Normal)

void KConfigGroup::writeEntry(const QString &key, const char *value, KConfigBase::WriteConfigFlags pFlags = Normal)

[since 6.22] template <typename Rep, typename Period> void KConfigGroup::writeEntry(const QString &key, std::chrono::duration<Rep, Period> value, KConfigBase::WriteConfigFlags pFlags = Normal)

This function was introduced in 6.22.

void KConfigGroup::writeEntry(const char *key, const QByteArray &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

template <typename T> void KConfigGroup::writeEntry(const char *key, const QList<T> &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writeEntry(const char *key, const QString &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writeEntry(const char *key, const QStringList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writeEntry(const char *key, const QVariant &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writeEntry(const char *key, const QVariantList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

template <typename T> void KConfigGroup::writeEntry(const char *key, const T &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writeEntry(const char *key, const char *value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

[since 6.22] template <typename Rep, typename Period> void KConfigGroup::writeEntry(const char *key, std::chrono::duration<Rep, Period> value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

This function was introduced in 6.22.

void KConfigGroup::writePathEntry(const QString &pKey, const QString &path, KConfigBase::WriteConfigFlags pFlags = Normal)

Writes pKey and value to the configuration object with the given pFlags, where the value matches a file path.

If the path includes the absolute name for $HOME, the user's home directory is replaced with "$HOME" in the persistent storage.

The path should therefore be read back with readPathEntry().

See also writeEntry() and readPathEntry().

void KConfigGroup::writePathEntry(const QString &pKey, const QStringList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

Writes pKey and value to the configuration object with the given pFlags, where the value matches a file path.

If the path includes the absolute name for $HOME, the user's home directory is replaced with "$HOME" in the persistent storage.

The path should therefore be read back with readPathEntry().

See also writeEntry() and readPathEntry().

void KConfigGroup::writePathEntry(const char *Key, const QString &path, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writePathEntry(const char *key, const QStringList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

void KConfigGroup::writeXdgListEntry(const QString &pKey, const QStringList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

Writes pKey and value to the configuration object with the given pFlags, where the value matches a list of strings following the XDG desktop entry specification.

See also writeEntry() and readXdgListEntry().

void KConfigGroup::writeXdgListEntry(const char *key, const QStringList &value, KConfigBase::WriteConfigFlags pFlags = Normal)

The key will be encoded in UTF-8.

KCONFIGGROUP_DECLARE_ENUM_QOBJECT(MyClass, MyEnum)