1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
4 SPDX-FileCopyrightText: 2001 Waldo Bastian <bastian@kde.org>
5 SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org>
6 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KCONFIGBASE_H
12#define KCONFIGBASE_H
13
14#include <kconfigcore_export.h>
15
16#include <QStringList>
17#include <QtGlobal>
18
19class KConfigGroup;
20class KConfigBasePrivate;
21
22/*!
23 * \class KConfigBase
24 * \inmodule KConfigCore
25 * \brief Interface to interact with configuration.
26 *
27 * KConfigBase allows a component of an application to persists its configuration
28 * without the component knowing if it is storing the configuration into a top
29 * level KConfig or a KConfigGroup inside a KConfig instance.
30 */
31class KCONFIGCORE_EXPORT KConfigBase
32{
33public:
34 /*!
35 * Flags to control write entry
36 *
37 * \value Persistent Save this entry when saving the config object.
38 * \value Global Save the entry to the global KDE config file instead of the application specific config file.
39 * \value Add the locale tag to the key when writing it.
40 * \value[since 5.51] Notify remote KConfigWatchers of changes (requires DBus support). Imlies Persistent.
41 * \value Normal Save the entry to the application specific config file without a locale tag. This is the default.
42 */
43 enum WriteConfigFlag {
44 Persistent = 0x01,
45 Global = 0x02,
46 Localized = 0x04,
47 Notify = 0x08 | Persistent,
48 Normal = Persistent,
49 };
50 Q_DECLARE_FLAGS(WriteConfigFlags, WriteConfigFlag)
51
52 virtual ~KConfigBase();
53
54 /*!
55 * Returns a list of groups that are known about.
56 **/
57 virtual QStringList groupList() const = 0;
58
59 /*!
60 * Returns \c true if the specified group is known about.
61 *
62 * \a group name of group to search for
63 */
64 bool hasGroup(const QString &group) const;
65
66 /*!
67 * Returns an object for the named subgroup.
68 *
69 * \a group the group to open. Pass an empty string here to the KConfig
70 * object to obtain a handle on the root group.
71 * Returns config group object for the given group name.
72 */
73 KConfigGroup group(const QString &group);
74
75 /*!
76 * Const overload for group(const QString&)
77 * \overload
78 */
79 const KConfigGroup group(const QString &group) const;
80
81 /*!
82 * Delete \a group.
83 *
84 * This marks \a group as deleted in the config object. This effectively
85 * removes any cascaded values from config files earlier in the stack.
86 */
87 void deleteGroup(const QString &group, WriteConfigFlags flags = Normal);
88
89 /*!
90 * Syncs the configuration object that this group belongs to.
91 *
92 * Unrelated concurrent changes to the same file are merged and thus
93 * not overwritten. Note however, that this object is not automatically
94 * updated with those changes.
95 */
96 virtual bool sync() = 0;
97
98 /*!
99 * Reset the dirty flags of all entries in the entry map, so the
100 * values will not be written to disk on a later call to sync().
101 */
102 virtual void markAsClean() = 0;
103
104 /*!
105 * Possible return values for accessMode().
106 * \value NoAccess
107 * \value ReadOnly
108 * \value ReadWrite
109 */
110 enum AccessMode {
111 NoAccess,
112 ReadOnly,
113 ReadWrite,
114 };
115
116 /*!
117 * Returns the access mode of the app-config object.
118 *
119 * Possible return values
120 * are NoAccess (the application-specific config file could not be
121 * opened neither read-write nor read-only), ReadOnly (the
122 * application-specific config file is opened read-only, but not
123 * read-write) and ReadWrite (the application-specific config
124 * file is opened read-write).
125 */
126 virtual AccessMode accessMode() const = 0;
127
128 /*!
129 * Checks whether this configuration object can be modified.
130 */
131 virtual bool isImmutable() const = 0;
132
133 /*!
134 * Can changes be made to the entries in \a group?
135 *
136 * \a group The group to check for immutability.
137 *
138 * Returns \c false if the entries in \a group can be modified, otherwise \c true
139 */
140 bool isGroupImmutable(const QString &group) const;
141
142protected:
143 KConfigBase();
144
145 virtual bool hasGroupImpl(const QString &groupName) const = 0;
146 virtual KConfigGroup groupImpl(const QString &groupName) = 0;
147 virtual const KConfigGroup groupImpl(const QString &groupName) const = 0;
148 virtual void deleteGroupImpl(const QString &groupName, WriteConfigFlags flags = Normal) = 0;
149 virtual bool isGroupImmutableImpl(const QString &groupName) const = 0;
150
151 /*
152 * Virtual hook, used to add new "virtual" functions while maintaining
153 * binary compatibility. Unused in this class.
154 */
155 virtual void virtual_hook(int id, void *data);
156};
157
158Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBase::WriteConfigFlags)
159
160#endif // KCONFIG_H
161

source code of kconfig/src/core/kconfigbase.h