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 kconfigbase.h <KConfigBase>
24 * \brief Interface to interact with configuration.
25 *
26 * KConfigBase allows a component of an application to persists its configuration
27 * without the component knowing if it is storing the configuration into a top
28 * level KConfig or a KConfigGroup inside a KConfig instance.
29 */
30class KCONFIGCORE_EXPORT KConfigBase
31{
32public:
33 /**
34 * Flags to control write entry
35 * @see WriteConfigFlags
36 */
37 enum WriteConfigFlag {
38 Persistent = 0x01,
39 /**<
40 * Save this entry when saving the config object.
41 */
42 Global = 0x02,
43 /**<
44 * Save the entry to the global %KDE config file instead of the
45 * application specific config file.
46 */
47 Localized = 0x04,
48 /**<
49 * Add the locale tag to the key when writing it.
50 */
51 Notify = 0x08 | Persistent,
52 /**<
53 * Notify remote KConfigWatchers of changes (requires DBus support)
54 * Implied persistent
55 * @since 5.51
56 */
57 Normal = Persistent,
58 /**<
59 * Save the entry to the application specific config file without
60 * a locale tag. This is the default.
61 */
62
63 };
64 /**
65 * Stores a combination of #WriteConfigFlag values.
66 */
67 Q_DECLARE_FLAGS(WriteConfigFlags, WriteConfigFlag)
68
69 /**
70 * Destructs the KConfigBase object.
71 */
72 virtual ~KConfigBase();
73
74 /**
75 * Returns a list of groups that are known about.
76 *
77 * @return The list of groups.
78 **/
79 virtual QStringList groupList() const = 0;
80
81 /**
82 * Returns true if the specified group is known about.
83 *
84 * @param group name of group to search for
85 * @return true if the group exists.
86 */
87 bool hasGroup(const QString &group) const;
88
89 /**
90 * Returns an object for the named subgroup.
91 *
92 * @param group the group to open. Pass an empty string here to the KConfig
93 * object to obtain a handle on the root group.
94 * @return config group object for the given group name.
95 */
96 KConfigGroup group(const QString &group);
97
98 /**
99 * Const overload for group(const QString&)
100 */
101 const KConfigGroup group(const QString &group) const;
102
103 /**
104 * Delete @p group.
105 * This marks @p group as @em deleted in the config object. This effectively
106 * removes any cascaded values from config files earlier in the stack.
107 */
108 void deleteGroup(const QString &group, WriteConfigFlags flags = Normal);
109
110 /**
111 * Syncs the configuration object that this group belongs to.
112 * Unrelated concurrent changes to the same file are merged and thus
113 * not overwritten. Note however, that this object is @em not automatically
114 * updated with those changes.
115 */
116 virtual bool sync() = 0;
117
118 /**
119 * Reset the dirty flags of all entries in the entry map, so the
120 * values will not be written to disk on a later call to sync().
121 */
122 virtual void markAsClean() = 0;
123
124 /**
125 * Possible return values for accessMode().
126 */
127 enum AccessMode {
128 NoAccess,
129 ReadOnly,
130 ReadWrite,
131 };
132
133 /**
134 * Returns the access mode of the app-config object.
135 *
136 * Possible return values
137 * are NoAccess (the application-specific config file could not be
138 * opened neither read-write nor read-only), ReadOnly (the
139 * application-specific config file is opened read-only, but not
140 * read-write) and ReadWrite (the application-specific config
141 * file is opened read-write).
142 *
143 * @return the access mode of the app-config object
144 */
145 virtual AccessMode accessMode() const = 0;
146
147 /**
148 * Checks whether this configuration object can be modified.
149 * @return whether changes may be made to this configuration object.
150 */
151 virtual bool isImmutable() const = 0;
152
153 /**
154 * Can changes be made to the entries in @p group?
155 *
156 * @param group The group to check for immutability.
157 * @return @c false if the entries in @p group can be modified, otherwise @c true
158 */
159 bool isGroupImmutable(const QString &group) const;
160
161protected:
162 KConfigBase();
163
164 /// @param groupName name of group
165 virtual bool hasGroupImpl(const QString &groupName) const = 0;
166 /// @param groupName name of group
167 virtual KConfigGroup groupImpl(const QString &groupName) = 0;
168 /// @param groupName name of group
169 virtual const KConfigGroup groupImpl(const QString &groupName) const = 0;
170 /// @param groupName name of group
171 virtual void deleteGroupImpl(const QString &groupName, WriteConfigFlags flags = Normal) = 0;
172 /// @param groupName name of group
173 virtual bool isGroupImmutableImpl(const QString &groupName) const = 0;
174
175 /** Virtual hook, used to add new "virtual" functions while maintaining
176 * binary compatibility. Unused in this class.
177 */
178 virtual void virtual_hook(int id, void *data);
179};
180
181Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBase::WriteConfigFlags)
182
183#endif // KCONFIG_H
184

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