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 KCONFIG_H
12#define KCONFIG_H
13
14#include "kconfigbase.h"
15
16#include <kconfigcore_export.h>
17
18#include <QByteArray>
19#include <QList>
20#include <QStandardPaths>
21#include <QString>
22#include <QVariant>
23
24class KConfigGroup;
25class KConfigPrivate;
26
27/*!
28 * \class KConfig
29 * \inmodule KConfigCore
30 *
31 * \brief The central class of the KDE configuration data system.
32 *
33 * Quickstart:
34 *
35 * Get the default application config object via KSharedConfig::openConfig().
36 *
37 * Load a specific configuration file:
38 * \code
39 * KConfig config("/etc/kderc", KConfig::SimpleConfig);
40 * \endcode
41 *
42 * Load the configuration of a specific component:
43 * \code
44 * KConfig config("pluginrc");
45 * \endcode
46 *
47 * In general it is recommended to use KSharedConfig instead of
48 * creating multiple instances of KConfig to avoid the overhead of
49 * separate objects or concerns about synchronizing writes to disk
50 * even if the configuration object is updated from multiple code paths.
51 * KSharedConfig provides a set of open methods as counterparts for the
52 * KConfig constructors.
53 *
54 * See \l {https://techbase.kde.org/index.php?title=Development/Tutorials/KConfig}{the techbase HOWTO on KConfig}
55 *
56 * \sa KSharedConfig, KConfigGroup
57 */
58class KCONFIGCORE_EXPORT KConfig : public KConfigBase
59{
60public:
61 /*!
62 * Determines how the system-wide and user's global settings will affect
63 * the reading of the configuration.
64 *
65 * If CascadeConfig is selected, system-wide configuration sources are used
66 * to provide defaults for the settings accessed through this object, or
67 * possibly to override those settings in certain cases.
68 *
69 * If IncludeGlobals is selected, the kdeglobals configuration is used
70 * as additional configuration sources to provide defaults. Additionally
71 * selecting CascadeConfig will result in the system-wide kdeglobals sources
72 * also getting included.
73 *
74 * Note that the main configuration source overrides the cascaded sources,
75 * which override those provided to addConfigSources(), which override the
76 * global sources. The exception is that if a key or group is marked as
77 * being immutable, it will not be overridden.
78 *
79 * Note that all values other than IncludeGlobals and CascadeConfig are
80 * convenience definitions for the basic mode.
81 * Do not combine them with anything.
82 *
83 * \value IncludeGlobals Blend kdeglobals into the config object.
84 * \value CascadeConfig Cascade to system-wide config files.
85 * \value SimpleConfig Just a single config file.
86 * \value NoCascade Include user's globals, but omit system settings.
87 * \value NoGlobals Cascade to system settings, but omit user's globals.
88 * \value FullConfig Fully-fledged config, including globals and cascading to system settings.
89 */
90 enum OpenFlag {
91 IncludeGlobals = 0x01,
92 CascadeConfig = 0x02,
93
94 SimpleConfig = 0x00,
95 NoCascade = IncludeGlobals,
96 NoGlobals = CascadeConfig,
97 FullConfig = IncludeGlobals | CascadeConfig,
98 };
99 Q_DECLARE_FLAGS(OpenFlags, OpenFlag)
100
101 /*!
102 * Creates a KConfig object to manipulate a configuration file for the
103 * current application.
104 *
105 * If an absolute path is specified for \a file, that file will be used
106 * as the store for the configuration settings. If a non-absolute path
107 * is provided, the file will be looked for in the standard directory
108 * specified by type. If no path is provided, a default
109 * configuration file will be used based on the name of the main
110 * application component.
111 *
112 * \a mode determines whether the user or global settings will be allowed
113 * to influence the values returned by this object. See OpenFlags for
114 * more details.
115 *
116 * \note You probably want to use KSharedConfig::openConfig() instead.
117 *
118 * \a file The name of the file. If an empty string is passed in
119 * and SimpleConfig is passed in for the OpenFlags, then an in-memory
120 * KConfig object is created which will not write out to file nor which
121 * requires any file in the filesystem at all.
122 *
123 * \a mode How global settings should affect the configuration
124 * options exposed by this KConfig object
125 *
126 * \a type The standard directory to look for the configuration
127 * file in
128 *
129 * \sa KSharedConfig::openConfig()
130 */
131 explicit KConfig(const QString &file = QString(),
132 OpenFlags mode = FullConfig,
133 QStandardPaths::StandardLocation type = QStandardPaths::GenericConfigLocation);
134
135#if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(6, 3)
136 /*!
137 * Creates a KConfig object using the specified backend. If the backend can not
138 * be found or loaded, then the standard configuration parser is used as a fallback.
139 *
140 * \a file the file to be parsed
141 *
142 * \a backend the backend to load
143 *
144 * \a type where to look for the file if an absolute path is not provided
145 *
146 * \since 4.1
147 *
148 * \deprecated[6.3]
149 *
150 * Use other constructor
151 */
152 KCONFIGCORE_DEPRECATED_VERSION(6, 3, "Use other constructor")
153 KConfig(const QString &file, const QString &backend, QStandardPaths::StandardLocation type = QStandardPaths::GenericConfigLocation);
154#endif
155
156 ~KConfig() override;
157
158 /*!
159 * Returns the standard location enum passed to the constructor.
160 *
161 * Used by KSharedConfig.
162 * \since 5.0
163 */
164 QStandardPaths::StandardLocation locationType() const;
165
166 /*!
167 * Returns the filename used to store the configuration.
168 */
169 QString name() const;
170
171 /*!
172 * Returns the flags this object was opened with
173 * \since 5.3
174 */
175 OpenFlags openFlags() const;
176
177 bool sync() override;
178
179 /*!
180 * Returns \c true if sync has any changes to write out.
181 * \since 4.12
182 */
183 bool isDirty() const;
184
185 void markAsClean() override;
186
187 AccessMode accessMode() const override;
188
189 /*!
190 * Whether the configuration can be written to.
191 *
192 * If \a warnUser is true and the configuration cannot be
193 * written to (ie: this method returns \c false), a warning
194 * message box will be shown to the user telling them to
195 * contact their system administrator to get the problem fixed.
196 *
197 * The most likely cause for this method returning \c false
198 * is that the user does not have write permission for the
199 * configuration file.
200 *
201 * \a warnUser whether to show a warning message to the user
202 * if the configuration cannot be written to
203 *
204 * Returns \c true if the configuration can be written to, false
205 * if the configuration cannot be written to
206 */
207 bool isConfigWritable(bool warnUser);
208
209 /*!
210 * Copies all entries from this config object to a new config
211 * object that will save itself to \a file.
212 *
213 * The configuration will not actually be saved to \a file
214 * until the returned object is destroyed, or sync() is called
215 * on it.
216 *
217 * Do not forget to delete the returned KConfig object if
218 *
219 * \a config was 0.
220 *
221 * \a file the new config object will save itself to
222 *
223 * \a config if not 0, copy to the given KConfig object rather
224 * than creating a new one
225 *
226 * Returns \a config if it was set, otherwise a new KConfig object
227 */
228 KConfig *copyTo(const QString &file, KConfig *config = nullptr) const;
229
230 /*!
231 * Ensures that the configuration file contains a certain update.
232 *
233 * If the configuration file does not contain the update \a id
234 * as contained in \a updateFile, kconf_update is run to update
235 * the configuration file.
236 *
237 * If you install config update files with critical fixes
238 * you may wish to use this method to verify that a critical
239 * update has indeed been performed to catch the case where
240 * a user restores an old config file from backup that has
241 * not been updated yet.
242 *
243 * \a id the update to check
244 *
245 * \a updateFile the file containing the update
246 */
247 void checkUpdate(const QString &id, const QString &updateFile);
248
249 /*!
250 * Updates the state of this object to match the persistent storage.
251 * Note that if this object has pending changes, this method will
252 * call sync() first so as not to lose those changes.
253 */
254 void reparseConfiguration();
255
256 /*!
257 * Adds the list of configuration sources to the merge stack.
258 *
259 * Currently only files are accepted as configuration sources.
260 *
261 * The first entry in \a sources is treated as the most general and will
262 * be overridden by the second entry. The settings in the final entry
263 * in \a sources will override all the other sources provided in the list.
264 *
265 * The settings in \a sources will also be overridden by the sources
266 * provided by any previous calls to addConfigSources().
267 *
268 * The settings in the global configuration sources will be overridden by
269 * the sources provided to this method (see IncludeGlobals).
270 * All the sources provided to any call to this method will be overridden
271 * by any files that cascade from the source provided to the constructor
272 * (see CascadeConfig), which will in turn be
273 * overridden by the source provided to the constructor.
274 *
275 * Note that only the most specific file, ie: the file provided to the
276 * constructor, will be written to by this object.
277 *
278 * The state is automatically updated by this method, so there is no need to call
279 * reparseConfiguration().
280 *
281 * \a sources A list of extra config sources.
282 */
283 void addConfigSources(const QStringList &sources);
284
285 /*!
286 * Returns a list of the additional configuration sources used in this object
287 */
288 QStringList additionalConfigSources() const;
289
290 /*!
291 * Returns the current locale.
292 */
293 QString locale() const;
294 /*!
295 * Sets the locale to \a aLocale.
296 *
297 * The global locale is used by default.
298 *
299 * \note If set to the empty string, no locale will be matched. This effectively disables
300 * reading translated entries.
301 *
302 * Returns \c true if locale was changed, \c false if the call had no
303 * effect (eg: \a aLocale was already the current locale for this
304 * object)
305 */
306 bool setLocale(const QString &aLocale);
307
308 /*!
309 * When set, all readEntry calls return the system-wide (default) values
310 * instead of the user's settings.
311 *
312 * This is off by default.
313 *
314 * \a b whether to read the system-wide defaults instead of the
315 * user's settings
316 */
317 void setReadDefaults(bool b);
318 /*!
319 * Returns \c true if the system-wide defaults will be read instead of the
320 * user's settings
321 */
322 bool readDefaults() const;
323
324 bool isImmutable() const override;
325
326 QStringList groupList() const override;
327
328 /*!
329 * Returns a map (tree) of entries in a particular group.
330 *
331 * The entries are all returned as strings.
332 *
333 * \a aGroup The group to get entries from.
334 *
335 * Returns a map of entries in the group specified, indexed by key.
336 * The returned map may be empty if the group is empty, or not found.
337 */
338 QMap<QString, QString> entryMap(const QString &aGroup = QString()) const;
339
340 /*!
341 * Sets the name of the application config file.
342 * \since 5.0
343 */
344 static void setMainConfigName(const QString &str);
345
346 /*!
347 * Get the name of application config file.
348 * \since 5.93
349 */
350 static QString mainConfigName();
351
352protected:
353 bool hasGroupImpl(const QString &groupName) const override;
354 KConfigGroup groupImpl(const QString &groupName) override;
355 const KConfigGroup groupImpl(const QString &groupName) const override;
356 void deleteGroupImpl(const QString &groupName, WriteConfigFlags flags = Normal) override;
357 bool isGroupImmutableImpl(const QString &groupName) const override;
358
359 friend class KConfigGroup;
360 friend class KConfigGroupPrivate;
361 friend class KSharedConfig;
362
363 /*
364 * Virtual hook, used to add new "virtual" functions while maintaining
365 * binary compatibility. Unused in this class.
366 */
367 void virtual_hook(int id, void *data) override;
368
369 KConfigPrivate *const d_ptr;
370
371 KCONFIGCORE_NO_EXPORT explicit KConfig(KConfigPrivate &d);
372
373private:
374 friend class KConfigTest;
375
376 Q_DISABLE_COPY(KConfig)
377
378 Q_DECLARE_PRIVATE(KConfig)
379};
380Q_DECLARE_OPERATORS_FOR_FLAGS(KConfig::OpenFlags)
381
382#endif // KCONFIG_H
383

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