KConfig 5.109.0
kconfiggroup.h
1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
4 SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org>
5 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
6 SPDX-FileCopyrightText: 2001 Waldo Bastian <bastian@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KCONFIGGROUP_H
12#define KCONFIGGROUP_H
13
14#include "kconfigbase.h"
15
16#include <kconfigcore_export.h>
17
18#include <QExplicitlySharedDataPointer>
19#include <QStringList>
20#include <QVariant>
21
22class KConfig;
23class KConfigGroupPrivate;
24class KSharedConfig;
25
38class KCONFIGCORE_EXPORT KConfigGroup : public KConfigBase
39{
40public:
47
56 KConfigGroup(KConfigBase *master, const QString &group);
62 KConfigGroup(KConfigBase *master, const char *group);
63
72 KConfigGroup(const KConfigBase *master, const QString &group);
78 KConfigGroup(const KConfigBase *master, const char *group);
79
81 KConfigGroup(const QExplicitlySharedDataPointer<KSharedConfig> &master, const QString &group);
87 KConfigGroup(const QExplicitlySharedDataPointer<KSharedConfig> &master, const char *group);
88
93 KConfigGroup &operator=(const KConfigGroup &);
94
95 ~KConfigGroup() override;
96
106 bool isValid() const;
107
113 QString name() const;
114
119 bool exists() const;
120
126 bool sync() override;
127
129 void markAsClean() override;
130
132 AccessMode accessMode() const override;
133
141 const KConfig *config() const;
142
143#if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
150 KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Create another KConfigGroup from the parent of this group")
151 void changeGroup(const QString &group);
152#endif
153
154#if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
163 KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Create another KConfigGroup from the parent of this group")
164 void changeGroup(const char *group);
165#endif
166
178 void copyTo(KConfigBase *other, WriteConfigFlags pFlags = Normal) const;
179
195 void reparent(KConfigBase *parent, WriteConfigFlags pFlags = Normal);
196
203 void moveValuesTo(const QList<const char *> &keys, KConfigGroup &other, WriteConfigFlags pFlags = Normal);
204
214
218 QStringList groupList() const override;
219
223 QStringList keyList() const;
224
232 void deleteGroup(WriteConfigFlags pFlags = Normal);
234
257 template<typename T>
258 T readEntry(const QString &key, const T &aDefault) const
259 {
260 return readEntry(key.toUtf8().constData(), aDefault);
261 }
266 template<typename T>
267 T readEntry(const char *key, const T &aDefault) const;
268
278 QVariant readEntry(const QString &key, const QVariant &aDefault) const;
283 QVariant readEntry(const char *key, const QVariant &aDefault) const;
284
296 QString readEntry(const QString &key, const QString &aDefault) const;
301 QString readEntry(const char *key, const QString &aDefault) const;
302
304 QString readEntry(const QString &key, const char *aDefault = nullptr) const;
309 QString readEntry(const char *key, const char *aDefault = nullptr) const;
310
319 QVariantList readEntry(const QString &key, const QVariantList &aDefault) const;
324 QVariantList readEntry(const char *key, const QVariantList &aDefault) const;
325
335 QStringList readEntry(const QString &key, const QStringList &aDefault) const;
340 QStringList readEntry(const char *key, const QStringList &aDefault) const;
341
351 template<typename T>
352 QList<T> readEntry(const QString &key, const QList<T> &aDefault) const
353 {
354 return readEntry(key.toUtf8().constData(), aDefault);
355 }
360 template<typename T>
361 QList<T> readEntry(const char *key, const QList<T> &aDefault) const;
362
373 QStringList readXdgListEntry(const QString &pKey, const QStringList &aDefault = QStringList()) const;
378 QStringList readXdgListEntry(const char *key, const QStringList &aDefault = QStringList()) const;
379
391 QString readPathEntry(const QString &pKey, const QString &aDefault) const;
396 QString readPathEntry(const char *key, const QString &aDefault) const;
397
409 QStringList readPathEntry(const QString &pKey, const QStringList &aDefault) const;
414 QStringList readPathEntry(const char *key, const QStringList &aDefault) const;
415
425 QString readEntryUntranslated(const QString &pKey, const QString &aDefault = QString()) const;
430 QString readEntryUntranslated(const char *key, const QString &aDefault = QString()) const;
431
441 void writeEntry(const QString &key, const QVariant &value, WriteConfigFlags pFlags = Normal);
446 void writeEntry(const char *key, const QVariant &value, WriteConfigFlags pFlags = Normal);
447
449 void writeEntry(const QString &key, const QString &value, WriteConfigFlags pFlags = Normal);
454 void writeEntry(const char *key, const QString &value, WriteConfigFlags pFlags = Normal);
455
457 void writeEntry(const QString &key, const QByteArray &value, WriteConfigFlags pFlags = Normal);
462 void writeEntry(const char *key, const QByteArray &value, WriteConfigFlags pFlags = Normal);
463
465 void writeEntry(const QString &key, const char *value, WriteConfigFlags pFlags = Normal);
470 void writeEntry(const char *key, const char *value, WriteConfigFlags pFlags = Normal);
471
476 template<typename T>
477 void writeEntry(const char *key, const T &value, WriteConfigFlags pFlags = Normal);
479 template<typename T>
480 void writeEntry(const QString &key, const T &value, WriteConfigFlags pFlags = Normal)
481 {
482 writeEntry(key.toUtf8().constData(), value, pFlags);
483 }
484
486 void writeEntry(const QString &key, const QStringList &value, WriteConfigFlags pFlags = Normal);
491 void writeEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags = Normal);
492
494 void writeEntry(const QString &key, const QVariantList &value, WriteConfigFlags pFlags = Normal);
499 void writeEntry(const char *key, const QVariantList &value, WriteConfigFlags pFlags = Normal);
500
502 template<typename T>
503 void writeEntry(const QString &key, const QList<T> &value, WriteConfigFlags pFlags = Normal)
504 {
505 writeEntry(key.toUtf8().constData(), value, pFlags);
506 }
511 template<typename T>
512 void writeEntry(const char *key, const QList<T> &value, WriteConfigFlags pFlags = Normal);
513
524 void writeXdgListEntry(const QString &pKey, const QStringList &value, WriteConfigFlags pFlags = Normal);
529 void writeXdgListEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags = Normal);
530
544 void writePathEntry(const QString &pKey, const QString &path, WriteConfigFlags pFlags = Normal);
549 void writePathEntry(const char *Key, const QString &path, WriteConfigFlags pFlags = Normal);
550
564 void writePathEntry(const QString &pKey, const QStringList &value, WriteConfigFlags pFlags = Normal);
569 void writePathEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags = Normal);
570
581 void deleteEntry(const QString &pKey, WriteConfigFlags pFlags = Normal);
586 void deleteEntry(const char *key, WriteConfigFlags pFlags = Normal);
587
603 bool hasKey(const QString &key) const;
608 bool hasKey(const char *key) const;
609
615 bool isImmutable() const override;
616
627 bool isEntryImmutable(const QString &key) const;
632 bool isEntryImmutable(const char *key) const;
633
650 // TODO KF6 merge with the other one
651 void revertToDefault(const QString &key);
652 void revertToDefault(const QString &key, WriteConfigFlags pFlag);
653
654 // TODO KF6 merge with the other one
659 void revertToDefault(const char *key);
664 void revertToDefault(const char *key, WriteConfigFlags pFlag);
665
693 bool hasDefault(const QString &key) const;
698 bool hasDefault(const char *key) const;
699
708 QMap<QString, QString> entryMap() const;
709
710protected:
711 bool hasGroupImpl(const QByteArray &group) const override;
712 KConfigGroup groupImpl(const QByteArray &b) override;
713 const KConfigGroup groupImpl(const QByteArray &b) const override;
714 void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags) override;
715 bool isGroupImmutableImpl(const QByteArray &aGroup) const override;
716
717private:
718 QExplicitlySharedDataPointer<KConfigGroupPrivate> d;
719
720 friend class KConfigGroupPrivate;
721
731 static QVariant convertToQVariant(const char *pKey, const QByteArray &value, const QVariant &aDefault);
732 // exported for usage by KServices' KService & KServiceAction
733 friend class KServicePrivate; // XXX yeah, ugly^5
734 friend class KServiceAction;
735};
736
737#define KCONFIGGROUP_ENUMERATOR_ERROR(ENUM) "The Qt MetaObject system does not seem to know about \"" ENUM "\" please use Q_ENUM or Q_FLAG to register it."
738
747#define KCONFIGGROUP_DECLARE_ENUM_QOBJECT(Class, Enum) \
748 template<> \
749 Class::Enum KConfigGroup::readEntry(const char *key, const Class::Enum &def) const \
750 { \
751 const QMetaObject *M_obj = &Class::staticMetaObject; \
752 const int M_index = M_obj->indexOfEnumerator(#Enum); \
753 if (M_index == -1) \
754 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Enum)); \
755 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
756 const QByteArray M_data = readEntry(key, QByteArray(M_enum.valueToKey(def))); \
757 return static_cast<Class::Enum>(M_enum.keyToValue(M_data.constData())); \
758 } \
759 inline Class::Enum KCONFIGCORE_DECL_DEPRECATED readEntry(const KConfigGroup &group, const char *key, const Class::Enum &def) \
760 { \
761 return group.readEntry(key, def); \
762 } \
763 template<> \
764 void KConfigGroup::writeEntry(const char *key, const Class::Enum &value, KConfigBase::WriteConfigFlags flags) \
765 { \
766 const QMetaObject *M_obj = &Class::staticMetaObject; \
767 const int M_index = M_obj->indexOfEnumerator(#Enum); \
768 if (M_index == -1) \
769 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Enum)); \
770 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
771 writeEntry(key, QByteArray(M_enum.valueToKey(value)), flags); \
772 } \
773 inline void KCONFIGCORE_DECL_DEPRECATED writeEntry(KConfigGroup &group, \
774 const char *key, \
775 const Class::Enum &value, \
776 KConfigBase::WriteConfigFlags flags = KConfigBase::Normal) \
777 { \
778 group.writeEntry(key, value, flags); \
779 }
780
785#define KCONFIGGROUP_DECLARE_FLAGS_QOBJECT(Class, Flags) \
786 template<> \
787 Class::Flags KConfigGroup::readEntry(const char *key, const Class::Flags &def) const \
788 { \
789 const QMetaObject *M_obj = &Class::staticMetaObject; \
790 const int M_index = M_obj->indexOfEnumerator(#Flags); \
791 if (M_index == -1) \
792 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Flags)); \
793 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
794 const QByteArray M_data = readEntry(key, QByteArray(M_enum.valueToKeys(def))); \
795 return static_cast<Class::Flags>(M_enum.keysToValue(M_data.constData())); \
796 } \
797 inline Class::Flags KCONFIGCORE_DECL_DEPRECATED readEntry(const KConfigGroup &group, const char *key, const Class::Flags &def) \
798 { \
799 return group.readEntry(key, def); \
800 } \
801 template<> \
802 void KConfigGroup::writeEntry(const char *key, const Class::Flags &value, KConfigBase::WriteConfigFlags flags) \
803 { \
804 const QMetaObject *M_obj = &Class::staticMetaObject; \
805 const int M_index = M_obj->indexOfEnumerator(#Flags); \
806 if (M_index == -1) \
807 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Flags)); \
808 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
809 writeEntry(key, QByteArray(M_enum.valueToKeys(value)), flags); \
810 } \
811 inline void KCONFIGCORE_DECL_DEPRECATED writeEntry(KConfigGroup &group, \
812 const char *key, \
813 const Class::Flags &value, \
814 KConfigBase::WriteConfigFlags flags = KConfigBase::Normal) \
815 { \
816 group.writeEntry(key, value, flags); \
817 }
818
819#include "conversioncheck.h"
820
821template<typename T>
822T KConfigGroup::readEntry(const char *key, const T &defaultValue) const
823{
824 ConversionCheck::to_QVariant<T>();
825 return qvariant_cast<T>(readEntry(key, QVariant::fromValue(defaultValue)));
826}
827
828template<typename T>
829QList<T> KConfigGroup::readEntry(const char *key, const QList<T> &defaultValue) const
830{
831 ConversionCheck::to_QVariant<T>();
832 ConversionCheck::to_QString<T>();
833
834 QVariantList data;
835
836 for (const T &value : defaultValue) {
837 data.append(QVariant::fromValue(value));
838 }
839
840 QList<T> list;
841 const auto variantList = readEntry<QVariantList>(key, data);
842 for (const QVariant &value : variantList) {
843 Q_ASSERT(value.canConvert<T>());
844 list.append(qvariant_cast<T>(value));
845 }
846
847 return list;
848}
849
850template<typename T>
851void KConfigGroup::writeEntry(const char *key, const T &value, WriteConfigFlags pFlags)
852{
853 ConversionCheck::to_QVariant<T>();
854 writeEntry(key, QVariant::fromValue(value), pFlags);
855}
856
857template<typename T>
858void KConfigGroup::writeEntry(const char *key, const QList<T> &list, WriteConfigFlags pFlags)
859{
860 ConversionCheck::to_QVariant<T>();
861 ConversionCheck::to_QString<T>();
862 QVariantList data;
863 for (const T &value : list) {
864 data.append(QVariant::fromValue(value));
865 }
866
867 writeEntry(key, data, pFlags);
868}
869
870#endif // KCONFIGGROUP_H
Interface to interact with configuration.
Definition kconfigbase.h:31
void deleteGroup(const QString &group, WriteConfigFlags flags=Normal)
Delete group.
AccessMode
Possible return values for accessMode().
Definition kconfigbase.h:175
QFlags< WriteConfigFlag > WriteConfigFlags
Stores a combination of #WriteConfigFlag values.
Definition kconfigbase.h:67
A class for one specific group in a KConfig object.
Definition kconfiggroup.h:39
void reparent(KConfigBase *parent, WriteConfigFlags pFlags=Normal)
Changes the configuration object that this group belongs to.
QVariant readEntry(const char *key, const QVariant &aDefault) const
Overload for readEntry(const QString&, const QVariant&) const.
QString readEntryUntranslated(const char *key, const QString &aDefault=QString()) const
Overload for readEntryUntranslated(const QString&, const QString&) const.
QString readEntry(const char *key, const QString &aDefault) const
Overload for readEntry(const QString&, const QString&) const.
KConfigGroup(const KConfigGroup &)
Creates a copy of a group.
T readEntry(const QString &key, const T &aDefault) const
Reads the value of an entry specified by pKey in the current group.
Definition kconfiggroup.h:258
QVariantList readEntry(const char *key, const QVariantList &aDefault) const
Overload for readEntry(const QString&, const QVariantList&) const.
void writeXdgListEntry(const QString &pKey, const QStringList &value, WriteConfigFlags pFlags=Normal)
Writes a list of strings to the config object, following XDG desktop entry spec separator semantics.
QString name() const
The name of this group.
void writeEntry(const QString &key, const char *value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
KConfigGroup(KConfigBase *master, const char *group)
Overload for KConfigGroup(KConfigBase*,const QString&)
void writeEntry(const QString &key, const QString &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
bool hasDefault(const QString &key) const
Whether a default is specified for an entry in either the system wide configuration file or the globa...
bool hasKey(const QString &key) const
Checks whether the key has an entry in this group.
void writePathEntry(const QString &pKey, const QStringList &value, WriteConfigFlags pFlags=Normal)
Writes a list of paths to the configuration.
void writeEntry(const QString &key, const QStringList &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
void writeEntry(const QString &key, const QByteArray &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
QString readPathEntry(const QString &pKey, const QString &aDefault) const
Reads a path.
void deleteEntry(const char *key, WriteConfigFlags pFlags=Normal)
Overload for deleteEntry(const QString&, WriteConfigFlags)
bool hasDefault(const char *key) const
Overload for hasDefault(const QString&) const.
bool hasKey(const char *key) const
Overload for hasKey(const QString&) const.
void writeEntry(const char *key, const QVariant &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
void writeEntry(const char *key, const char *value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
void writePathEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags=Normal)
Overload for writePathEntry(const QString&, const QStringList&, WriteConfigFlags)
void writePathEntry(const QString &pKey, const QString &path, WriteConfigFlags pFlags=Normal)
Writes a file path to the configuration.
KConfigGroup(const KConfigBase *master, const char *group)
Overload for KConfigGroup(const KConfigBase*,const QString&)
bool isEntryImmutable(const QString &key) const
Checks if it is possible to change the given entry.
KConfigGroup(const KConfigBase *master, const QString &group)
Construct a read-only config group.
void writeEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
void writePathEntry(const char *Key, const QString &path, WriteConfigFlags pFlags=Normal)
Overload for writePathEntry(const QString&, const QString&, WriteConfigFlags)
bool isEntryImmutable(const char *key) const
Overload for isEntryImmutable(const QString&) const.
KConfigGroup groupImpl(const QByteArray &b) override
QString readEntry(const QString &key, const QString &aDefault) const
Reads the string value of an entry specified by key in the current group.
void revertToDefault(const char *key, WriteConfigFlags pFlag)
Overload for revertToDefault(const QString&, WriteConfigFlags)
QString readPathEntry(const char *key, const QString &aDefault) const
Overload for readPathEntry(const QString&, const QString&) const.
void writeEntry(const char *key, const QByteArray &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
void writeEntry(const QString &key, const QVariant &value, WriteConfigFlags pFlags=Normal)
Writes a value to the configuration object.
void deleteGroup(WriteConfigFlags pFlags=Normal)
Delete all entries in the entire group.
QVariant readEntry(const QString &key, const QVariant &aDefault) const
Reads the value of an entry specified by key in the current group.
bool isValid() const
Whether the group is valid.
QStringList readEntry(const char *key, const QStringList &aDefault) const
Overload for readEntry(const QString&, const QStringList&) const.
QVariantList readEntry(const QString &key, const QVariantList &aDefault) const
void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags) override
void writeEntry(const char *key, const QString &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
QString readEntry(const QString &key, const char *aDefault=nullptr) const
Overload for readEntry(const QString&, const QString&) const.
QStringList readXdgListEntry(const char *key, const QStringList &aDefault=QStringList()) const
Overload for readXdgListEntry(const QString&, const QStringList&) const.
void writeEntry(const QString &key, const QList< T > &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
Definition kconfiggroup.h:503
void writeEntry(const QString &key, const QVariantList &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
AccessMode accessMode() const override
void writeXdgListEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags=Normal)
Overload for writeXdgListEntry(const QString&, const QStringList&, WriteConfigFlags)
QStringList readPathEntry(const QString &pKey, const QStringList &aDefault) const
Reads a list of paths.
void revertToDefault(const QString &key)
Reverts an entry to the default settings.
bool hasGroupImpl(const QByteArray &group) const override
void markAsClean() override
KConfigGroup(const QExplicitlySharedDataPointer< KSharedConfig > &master, const QString &group)
Overload for KConfigGroup(const KConfigBase*,const QString&)
KConfigGroup()
Constructs an invalid group.
KConfigGroup(const QExplicitlySharedDataPointer< KSharedConfig > &master, const char *group)
Overload for KConfigGroup(const KConfigBase*,const QString&)
bool isImmutable() const override
Whether this group may be changed.
QStringList readEntry(const QString &key, const QStringList &aDefault) const
Reads a list of strings from the config object.
KConfig * config()
Return the config object that this group belongs to.
QString readEntry(const char *key, const char *aDefault=nullptr) const
Overload for readEntry(const QString&, const QString&) const.
bool exists() const
Check whether the containing KConfig object actually contains a group with this name.
void deleteEntry(const QString &pKey, WriteConfigFlags pFlags=Normal)
Deletes the entry specified by pKey in the current group.
bool sync() override
void moveValuesTo(const QList< const char * > &keys, KConfigGroup &other, WriteConfigFlags pFlags=Normal)
Moves the key-value pairs from one config group to the other.
KConfigGroup parent() const
Returns the group that this group belongs to.
QMap< QString, QString > entryMap() const
Returns a map (tree) of entries for all entries in this group.
KConfigGroup(KConfigBase *master, const QString &group)
Construct a config group corresponding to group in master.
QList< T > readEntry(const QString &key, const QList< T > &aDefault) const
Reads a list of values from the config object.
Definition kconfiggroup.h:352
void writeEntry(const char *key, const QVariantList &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
void writeEntry(const QString &key, const T &value, WriteConfigFlags pFlags=Normal)
Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
Definition kconfiggroup.h:480
const KConfig * config() const
Return the config object that this group belongs to.
QStringList readXdgListEntry(const QString &pKey, const QStringList &aDefault=QStringList()) const
Reads a list of strings from the config object, following XDG desktop entry spec separator semantics.
QStringList groupList() const override
bool isGroupImmutableImpl(const QByteArray &aGroup) const override
const KConfigGroup groupImpl(const QByteArray &b) const override
QString readEntryUntranslated(const QString &pKey, const QString &aDefault=QString()) const
Reads an untranslated string entry.
QStringList keyList() const
Returns a list of keys this group contains.
void revertToDefault(const char *key)
Overload for revertToDefault(const QString&)
QStringList readPathEntry(const char *key, const QStringList &aDefault) const
Overload for readPathEntry(const QString&, const QStringList&) const.
void copyTo(KConfigBase *other, WriteConfigFlags pFlags=Normal) const
Copies the entries in this group to another configuration object.
The central class of the KDE configuration data system.
Definition kconfig.h:57
KConfig variant using shared memory.
Definition ksharedconfig.h:32