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 | |
36 | class KConfigGroup; |
37 | class KComponentData; |
38 | class KEntryMap; |
39 | class 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 | */ |
70 | class KDECORE_EXPORT KConfig : public KConfigBase |
71 | { |
72 | public: |
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 | |
388 | protected: |
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 | |
407 | private: |
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 | }; |
416 | Q_DECLARE_OPERATORS_FOR_FLAGS( KConfig::OpenFlags ) |
417 | |
418 | #endif // KCONFIG_H |
419 | |