1/*
2 This file is part of the KDE libraries
3 Copyright (c) 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
4 Copyright (c) 2001 Waldo Bastian <bastian@kde.org>
5 Copyright (c) 1999 Preston Brown <pbrown@kde.org>
6 Copyright (c) 1997 Matthias Kalle Dalheimer <kalle@kde.org>
7
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public
10 License as published by the Free Software Foundation; either
11 version 2 of the License, or (at your option) any later version.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Library General Public License for more details.
17
18 You should have received a copy of the GNU Library General Public License
19 along with this library; see the file COPYING.LIB. If not, write to
20 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 Boston, MA 02110-1301, USA.
22*/
23
24#ifndef KCONFIG_H
25#define KCONFIG_H
26
27#include "kconfigbase.h"
28
29#include <kdecore_export.h>
30
31#include <QtCore/QString>
32#include <QtCore/QVariant>
33#include <QtCore/QByteArray>
34#include <QtCore/QList>
35
36class KConfigGroup;
37class KComponentData;
38class KEntryMap;
39class KConfigPrivate;
40
41/**
42 * \class KConfig kconfig.h <KConfig>
43 *
44 * \brief The central class of the KDE configuration data system.
45 *
46 * Quickstart:
47 *
48 * Get the default application config object via KGlobal::config().
49 *
50 * Load a specific configuration file:
51 * \code
52 * KConfig config( "/etc/kderc", KConfig::SimpleConfig );
53 * \endcode
54 *
55 * Load the configuration of a specific component (taking into account
56 * possible custom directories in KStandardDirs):
57 * \code
58 * KConfig config( componentData(), "pluginrc" );
59 * \endcode
60 *
61 * In general it is recommended to use KSharedConfig instead of
62 * creating multiple instances of KConfig to avoid the overhead of
63 * separate objects or concerns about synchronizing writes to disk
64 * even if the configuration object is updated from multiple code paths.
65 * KSharedConfig provides a set of open methods as counterparts for the
66 * KConfig constructors.
67 *
68 * \sa KSharedConfig, KConfigGroup, <a href="http://techbase.kde.org/index.php?title=Development/Tutorials/KConfig">the techbase HOWTO on KConfig</a>.
69 */
70class KDECORE_EXPORT KConfig : public KConfigBase
71{
72public:
73 /**
74 * Determines how the system-wide and user's global settings will affect
75 * the reading of the configuration.
76 *
77 * If CascadeConfig is selected, system-wide configuration sources are used
78 * to provide defaults for the settings accessed through this object, or
79 * possibly to override those settings in certain cases.
80 *
81 * IncludeGlobals does the same, but with the global settings sources.
82 *
83 * Note that the main configuration source overrides the cascaded sources,
84 * which override those provided to addConfigSources(), which override the
85 * global sources. The exception is that if a key or group is marked as
86 * being immutable, it will not be overridden.
87 *
88 * Note that all values other than IncludeGlobals and CascadeConfig are
89 * convenience definitions for the basic mode.
90 * Do @em not combine them with anything.
91 */
92 enum OpenFlag {
93 IncludeGlobals = 0x01, ///< Blend kdeglobals into the config object.
94 CascadeConfig = 0x02, ///< Cascade to system-wide config files.
95
96 SimpleConfig = 0x00, ///< Just a single config file.
97 NoCascade = IncludeGlobals, ///< Include user's globals, but omit system settings.
98 NoGlobals = CascadeConfig, ///< Cascade to system settings, but omit user's globals.
99 FullConfig = IncludeGlobals|CascadeConfig ///< Fully-fledged config, including globals and cascading to system settings
100 };
101 Q_DECLARE_FLAGS(OpenFlags, OpenFlag)
102
103 /**
104 * Creates a KConfig object to manipulate a configuration file for the
105 * current application.
106 *
107 * If an absolute path is specified for @p file, that file will be used
108 * as the store for the configuration settings. If a non-absolute path
109 * is provided, the file will be looked for in the standard directory
110 * specified by resourceType. If no path is provided, a default
111 * configuration file will be used based on the name of the main
112 * application component.
113 *
114 * @p mode determines whether the user or global settings will be allowed
115 * to influence the values returned by this object. See OpenFlags for
116 * more details.
117 *
118 * @note You probably want to use KSharedConfig::openConfig instead.
119 *
120 * @param file the name of the file. If an empty string is passed in
121 * and SimpleConfig is passed in for the OpenFlags, then an in-memory
122 * KConfig object is created which will not write out to file nor which
123 * requires any file in the filesystem at all.
124 * @param mode how global settings should affect the configuration
125 * options exposed by this KConfig object
126 * @param resourceType The standard directory to look for the configuration
127 * file in (see KStandardDirs)
128 *
129 * @sa KSharedConfig::openConfig(const QString&, OpenFlags, const char*)
130 */
131 explicit KConfig(const QString& file = QString(), OpenFlags mode = FullConfig,
132 const char* resourceType = "config");
133
134 /**
135 * Creates a KConfig object to manipulate the configuration for a specific
136 * component.
137 *
138 * If an absolute path is specified for @p file, that file will be used
139 * as the store for the configuration settings. If a non-absolute path
140 * is provided, the file will be looked for in the standard directory
141 * specified by resourceType. If no path is provided, a default
142 * configuration file will be used based on the component's name.
143 *
144 * @p mode determines whether the user or global settings will be allowed
145 * to influence the values returned by this object. See KConfig::OpenFlags for
146 * more details.
147 *
148 * @note You probably want to use KSharedConfig::openConfig instead.
149 *
150 * @param componentData the component that you wish to load a configuration
151 * file for
152 * @param file overrides the configuration file name if not empty; if it is empty
153 * and SimpleConfig is passed in for the OpenFlags, then an in-memory
154 * KConfig object is created which will not write out to file nor which
155 * requires any file in the filesystem at all.
156 * @param mode how global settings should affect the configuration
157 * options exposed by this KConfig object.
158 * See OpenFlags
159 * @param resourceType The standard directory to look for the configuration
160 * file in
161 *
162 * @sa KSharedConfig::openConfig(const KComponentData&, const QString&, OpenFlags, const char*)
163 */
164 explicit KConfig(const KComponentData& componentData, const QString& file = QString(),
165 OpenFlags mode = FullConfig, const char* resourceType = "config");
166
167 /**
168 * @internal
169 *
170 * Creates a KConfig object using the specified backend. If the backend can not
171 * be found or loaded, then the standard configuration parser is used as a fallback.
172 *
173 * @param file the file to be parsed
174 * @param backend the backend to load
175 * @param resourceType where to look for the file if an absolute path is not provided
176 *
177 * @since 4.1
178 */
179 KConfig(const QString& file, const QString& backend, const char* resourceType = "config");
180
181 virtual ~KConfig();
182
183 /**
184 * Returns the component data this configuration is for.
185 */
186 const KComponentData &componentData() const; // krazy:exclude=constref
187
188 /**
189 * Returns the filename used to store the configuration.
190 */
191 QString name() const;
192
193 /// @reimp
194 void sync();
195
196 /// Returns true if sync has any changes to write out.
197 /// @since 4.12
198 bool isDirty() const;
199
200 /// @reimp
201 void markAsClean();
202
203 /// @{ configuration object state
204 /// @reimp
205 AccessMode accessMode() const;
206
207 /**
208 * Whether the configuration can be written to.
209 *
210 * If @p warnUser is true and the configuration cannot be
211 * written to (ie: this method returns @c false), a warning
212 * message box will be shown to the user telling them to
213 * contact their system administrator to get the problem fixed.
214 *
215 * The most likely cause for this method returning @c false
216 * is that the user does not have write permission for the
217 * configuration file.
218 *
219 * @param warnUser whether to show a warning message to the user
220 * if the configuration cannot be written to
221 *
222 * @returns true if the configuration can be written to, false
223 * if the configuration cannot be written to
224 */
225 bool isConfigWritable(bool warnUser);
226 /// @}
227
228 /**
229 * Copies all entries from this config object to a new config
230 * object that will save itself to @p file.
231 *
232 * The configuration will not actually be saved to @p file
233 * until the returned object is destroyed, or sync() is called
234 * on it.
235 *
236 * Do not forget to delete the returned KConfig object if
237 * @p config was 0.
238 *
239 * @param file the new config object will save itself to
240 * @param config if not 0, copy to the given KConfig object rather
241 * than creating a new one
242 *
243 * @return @p config if it was set, otherwise a new KConfig object
244 */
245 KConfig* copyTo(const QString &file, KConfig *config = 0) const;
246
247 /**
248 * Ensures that the configuration file contains a certain update.
249 *
250 * If the configuration file does not contain the update @p id
251 * as contained in @p updateFile, kconf_update is run to update
252 * the configuration file.
253 *
254 * If you install config update files with critical fixes
255 * you may wish to use this method to verify that a critical
256 * update has indeed been performed to catch the case where
257 * a user restores an old config file from backup that has
258 * not been updated yet.
259 *
260 * @param id the update to check
261 * @param updateFile the file containing the update
262 */
263 void checkUpdate(const QString &id, const QString &updateFile);
264
265 /**
266 * Updates the state of this object to match the persistent storage.
267 */
268 void reparseConfiguration();
269
270 /// @{ extra config files
271 /**
272 * Adds the list of configuration sources to the merge stack.
273 *
274 * Currently only files are accepted as configuration sources.
275 *
276 * The first entry in @p sources is treated as the most general and will
277 * be overridden by the second entry. The settings in the final entry
278 * in @p sources will override all the other sources provided in the list.
279 *
280 * The settings in @p sources will also be overridden by the sources
281 * provided by any previous calls to addConfigSources().
282 *
283 * The settings in the global configuration sources will be overridden by
284 * the sources provided to this method (@see IncludeGlobals).
285 * All the sources provided to any call to this method will be overridden
286 * by any files that cascade from the source provided to the constructor
287 * (@see CascadeConfig), which will in turn be
288 * overridden by the source provided to the constructor (either explicitly
289 * or implicity via a KComponentData).
290 *
291 * Note that only the most specific file, ie: the file provided to the
292 * constructor, will be written to by this object.
293 *
294 * The state is automatically updated by this method, so there is no need to call
295 * reparseConfiguration().
296 *
297 * @param sources A list of extra config sources.
298 */
299 void addConfigSources(const QStringList &sources);
300
301 /// @}
302 /// @{ locales
303 /**
304 * Returns the current locale.
305 */
306 QString locale() const;
307 /**
308 * Sets the locale to @p aLocale.
309 *
310 * The global locale is used by default.
311 *
312 * @note If set to the empty string, @b no locale will be matched. This effectively disables
313 * reading translated entries.
314 *
315 * @return @c true if locale was changed, @c false if the call had no
316 * effect (eg: @p aLocale was already the current locale for this
317 * object)
318 */
319 bool setLocale(const QString& aLocale);
320 /// @}
321
322 /// @{ defaults
323 /**
324 * When set, all readEntry calls return the system-wide (default) values
325 * instead of the user's settings.
326 *
327 * This is off by default.
328 *
329 * @param b whether to read the system-wide defaults instead of the
330 * user's settings
331 */
332 void setReadDefaults(bool b);
333 /**
334 * @returns @c true if the system-wide defaults will be read instead of the
335 * user's settings
336 */
337 bool readDefaults() const;
338 /// @}
339
340 /// @{ immutability
341 /// @reimp
342 bool isImmutable() const;
343 /// @}
344
345 /// @{ global
346 /**
347 * @deprecated
348 *
349 * Forces all following write-operations to be performed on @c kdeglobals,
350 * independent of the @c Global flag in writeEntry().
351 *
352 * @param force true to force writing to kdeglobals
353 * @see forceGlobal
354 */
355#ifndef KDE_NO_DEPRECATED
356 KDE_DEPRECATED void setForceGlobal(bool force);
357#endif
358 /**
359 * @deprecated
360 *
361 * Returns whether all entries are being written to @c kdeglobals.
362 *
363 * @return @c true if all entries are being written to @c kdeglobals
364 * @see setForceGlobal
365 * @deprecated
366 */
367#ifndef KDE_NO_DEPRECATED
368 KDE_DEPRECATED bool forceGlobal() const;
369#endif
370 /// @}
371
372 /// @reimp
373 QStringList groupList() const;
374
375 /**
376 * Returns a map (tree) of entries in a particular group.
377 *
378 * The entries are all returned as strings.
379 *
380 * @param aGroup The group to get entries from.
381 *
382 * @return A map of entries in the group specified, indexed by key.
383 * The returned map may be empty if the group is empty, or not found.
384 * @see QMap
385 */
386 QMap<QString, QString> entryMap(const QString &aGroup=QString()) const;
387
388protected:
389 virtual bool hasGroupImpl(const QByteArray &group) const;
390 virtual KConfigGroup groupImpl( const QByteArray &b);
391 virtual const KConfigGroup groupImpl(const QByteArray &b) const;
392 virtual void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags = Normal);
393 virtual bool isGroupImmutableImpl(const QByteArray& aGroup) const;
394
395 friend class KConfigGroup;
396 friend class KConfigGroupPrivate;
397
398 /** Virtual hook, used to add new "virtual" functions while maintaining
399 * binary compatibility. Unused in this class.
400 */
401 virtual void virtual_hook( int id, void* data );
402
403 KConfigPrivate *const d_ptr;
404
405 KConfig(KConfigPrivate &d);
406
407private:
408 friend class KConfigTest;
409
410 QStringList keyList(const QString& aGroup=QString()) const;
411
412 Q_DISABLE_COPY(KConfig)
413
414 Q_DECLARE_PRIVATE(KConfig)
415};
416Q_DECLARE_OPERATORS_FOR_FLAGS( KConfig::OpenFlags )
417
418#endif // KCONFIG_H
419