1 | /* |
2 | This file is part of the KDE libraries |
3 | Copyright (c) 2006, 2007 Thomas Braxton <kde.braxton@gmail.com> |
4 | Copyright (c) 1999 Preston Brown <pbrown@kde.org> |
5 | Copyright (c) 1997 Matthias Kalle Dalheimer <kalle@kde.org> |
6 | Copyright (c) 2001 Waldo Bastian <bastian@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 KCONFIGGROUP_H |
25 | #define KCONFIGGROUP_H |
26 | |
27 | #include "kconfigbase.h" |
28 | |
29 | #include <kdecore_export.h> |
30 | |
31 | #include <QtCore/QExplicitlySharedDataPointer> |
32 | #include <QtCore/QVariant> |
33 | #include <QtCore/QStringList> |
34 | |
35 | class KConfig; |
36 | class KConfigGroupPrivate; |
37 | class KSharedConfig; |
38 | template <typename T> class KSharedPtr; |
39 | typedef KSharedPtr<KSharedConfig> KSharedConfigPtr; |
40 | |
41 | /** |
42 | * \class KConfigGroup kconfiggroup.h <KConfigGroup> |
43 | * |
44 | * A class for one specific group in a KConfig object. |
45 | * |
46 | * If you want to access the top-level entries of a KConfig |
47 | * object, which are not associated with any group, use an |
48 | * empty group name. |
49 | * |
50 | * A KConfigGroup will be read-only if it is constructed from a |
51 | * const config object or from another read-only group. |
52 | */ |
53 | class KDECORE_EXPORT KConfigGroup : public KConfigBase |
54 | { |
55 | public: |
56 | /** |
57 | * Constructs an invalid group. |
58 | * |
59 | * \see isValid |
60 | */ |
61 | KConfigGroup(); |
62 | |
63 | /** |
64 | * Construct a config group corresponding to @p group in @p master. |
65 | * |
66 | * This allows the creation of subgroups by passing another |
67 | * group as @p master. |
68 | * |
69 | * @p group is the group name encoded in UTF-8. |
70 | */ |
71 | KConfigGroup(KConfigBase *master, const QString &group); |
72 | /** Overload for KConfigGroup(KConfigBase*,const QString&) */ |
73 | KConfigGroup(KConfigBase *master, const char *group); |
74 | |
75 | /** |
76 | * Construct a read-only config group. |
77 | * |
78 | * A read-only group will silently ignore any attempts to write to it. |
79 | * |
80 | * This allows the creation of subgroups by passing an existing group |
81 | * as @p master. |
82 | */ |
83 | KConfigGroup(const KConfigBase *master, const QString &group); |
84 | /** Overload for KConfigGroup(const KConfigBase*,const QString&) */ |
85 | KConfigGroup(const KConfigBase *master, const char *group); |
86 | |
87 | /** Overload for KConfigGroup(const KConfigBase*,const QString&) */ |
88 | KConfigGroup(const KSharedConfigPtr &master, const QString &group); |
89 | /** Overload for KConfigGroup(const KConfigBase*,const QString&) */ |
90 | KConfigGroup(const KSharedConfigPtr &master, const char *group); |
91 | |
92 | /** |
93 | * Creates a read-only copy of a read-only group. |
94 | */ |
95 | KConfigGroup(const KConfigGroup &); |
96 | KConfigGroup &operator=(const KConfigGroup &); |
97 | |
98 | ~KConfigGroup(); |
99 | |
100 | /** |
101 | * Whether the group is valid. |
102 | * |
103 | * A group is invalid if it was constructed without arguments. |
104 | * |
105 | * You should not call any functions on an invalid group. |
106 | * |
107 | * @return @c true if the group is valid, @c false if it is invalid. |
108 | */ |
109 | bool isValid() const; |
110 | |
111 | /** |
112 | * The name of this group. |
113 | * |
114 | * The root group is named "<default>". |
115 | */ |
116 | QString name() const; |
117 | |
118 | /** |
119 | * Check whether the containing KConfig object acutally contains a |
120 | * group with this name. |
121 | */ |
122 | bool exists() const; |
123 | |
124 | /** |
125 | * @reimp |
126 | * |
127 | * Syncs the parent config. |
128 | */ |
129 | void sync(); |
130 | |
131 | /// @reimp |
132 | void markAsClean(); |
133 | |
134 | /// @reimp |
135 | AccessMode accessMode() const; |
136 | |
137 | /** |
138 | * Return the config object that this group belongs to |
139 | */ |
140 | KConfig* config(); |
141 | /** |
142 | * Return the config object that this group belongs to |
143 | */ |
144 | const KConfig* config() const; |
145 | |
146 | /** |
147 | * Changes the group of the object |
148 | * |
149 | * @deprecated |
150 | * Create another KConfigGroup from the parent of this group instead. |
151 | */ |
152 | #ifndef KDE_NO_DEPRECATED |
153 | KDE_DEPRECATED void changeGroup(const QString &group); |
154 | #endif |
155 | /** |
156 | * Overload for changeGroup(const QString&) |
157 | * |
158 | * @deprecated |
159 | * Create another KConfigGroup from the parent of this group instead. |
160 | */ |
161 | #ifndef KDE_NO_DEPRECATED |
162 | KDE_DEPRECATED void changeGroup(const char *group); |
163 | #endif |
164 | |
165 | /** |
166 | * Copies the entries in this group to another configuration object |
167 | * |
168 | * @note @p other can be either another group or a different file. |
169 | * |
170 | * @param other the configuration object to copy this group's entries to |
171 | * @param pFlags the flags to use when writing the entries to the |
172 | * other configuration object |
173 | * |
174 | * @since 4.1 |
175 | */ |
176 | void copyTo(KConfigBase *other, WriteConfigFlags pFlags = Normal) const; |
177 | |
178 | /** |
179 | * Changes the configuration object that this group belongs to |
180 | * |
181 | * @note @p other can be another group, the top-level KConfig object or |
182 | * a different KConfig object entirely. |
183 | * |
184 | * If @p parent is already the parent of this group, this method will have |
185 | * no effect. |
186 | * |
187 | * @param parent the config object to place this group under |
188 | * @param pFlags the flags to use in determining which storage source to |
189 | * write the data to |
190 | * |
191 | * @since 4.1 |
192 | */ |
193 | void reparent(KConfigBase *parent, WriteConfigFlags pFlags = Normal); |
194 | |
195 | /** |
196 | * Returns the group that this group belongs to |
197 | * |
198 | * @return the parent group, or an invalid group if this is a top-level |
199 | * group |
200 | * |
201 | * @since 4.1 |
202 | */ |
203 | KConfigGroup parent() const; |
204 | |
205 | /** |
206 | * @reimp |
207 | */ |
208 | QStringList groupList() const; |
209 | |
210 | /** |
211 | * Returns a list of keys this group contains |
212 | */ |
213 | QStringList keyList() const; |
214 | |
215 | /** |
216 | * Delete all entries in the entire group |
217 | * |
218 | * @param pFlags flags passed to KConfig::deleteGroup |
219 | * |
220 | * @see deleteEntry() |
221 | */ |
222 | void deleteGroup(WriteConfigFlags pFlags = Normal); |
223 | using KConfigBase::deleteGroup; |
224 | |
225 | /** |
226 | * Reads the value of an entry specified by @p pKey in the current group |
227 | * |
228 | * This template method makes it possible to write |
229 | * QString foo = readEntry("...", QString("default")); |
230 | * and the same with all other types supported by QVariant. |
231 | * |
232 | * The return type of the method is simply the same as the type of the default value. |
233 | * |
234 | * @note readEntry("...", Qt::white) will not compile because Qt::white is an enum. |
235 | * You must turn it into readEntry("...", QColor(Qt::white)). |
236 | * |
237 | * @note Only the following QVariant types are allowed : String, |
238 | * StringList, List, Font, Point, Rect, Size, Color, Int, UInt, Bool, |
239 | * Double, LongLong, ULongLong, DateTime and Date. |
240 | * |
241 | * @param key The key to search for |
242 | * @param aDefault A default value returned if the key was not found |
243 | * @return The value for this key, or @p aDefault. |
244 | * |
245 | * @see writeEntry(), deleteEntry(), hasKey() |
246 | */ |
247 | template <typename T> |
248 | inline T readEntry(const QString &key, const T &aDefault) const |
249 | { return readCheck(key.toUtf8().constData(), aDefault); } |
250 | /** Overload for readEntry(const QString&, const T&) const */ |
251 | template <typename T> |
252 | inline T readEntry(const char *key, const T &aDefault) const |
253 | { return readCheck(key, aDefault); } |
254 | |
255 | /** |
256 | * Reads the value of an entry specified by @p key in the current group |
257 | * |
258 | * @param key the key to search for |
259 | * @param aDefault a default value returned if the key was not found |
260 | * @return the value for this key, or @p aDefault if the key was not found |
261 | * |
262 | * @see writeEntry(), deleteEntry(), hasKey() |
263 | */ |
264 | QVariant readEntry(const QString &key, const QVariant &aDefault) const; |
265 | /** Overload for readEntry(const QString&, const QVariant&) */ |
266 | QVariant readEntry(const char *key, const QVariant &aDefault) const; |
267 | |
268 | /** |
269 | * Reads the string value of an entry specified by @p key in the current group |
270 | * |
271 | * If you want to read a path, please use readPathEntry(). |
272 | * |
273 | * @param key the key to search for |
274 | * @param aDefault a default value returned if the key was not found |
275 | * @return the value for this key, or @p aDefault if the key was not found |
276 | * |
277 | * @see readPathEntry(), writeEntry(), deleteEntry(), hasKey() |
278 | */ |
279 | QString readEntry(const QString &key, const QString &aDefault) const; |
280 | /** Overload for readEntry(const QString&, const QString&) */ |
281 | QString readEntry(const char *key, const QString &aDefault) const; |
282 | |
283 | /** Overload for readEntry(const QString&, const QString&) */ |
284 | QString readEntry(const QString &key, const char *aDefault = 0) const; |
285 | /** Overload for readEntry(const QString&, const QString&) */ |
286 | QString readEntry(const char *key, const char *aDefault = 0) const; |
287 | |
288 | /** |
289 | * @copydoc readEntry(const char*, const QStringList&) const |
290 | * |
291 | * @warning This function doesn't convert the items returned |
292 | * to any type. It's actually a list of QVariant::String's. If you |
293 | * want the items converted to a specific type use |
294 | * readEntry(const char*, const QList<T>&) const |
295 | */ |
296 | QVariantList readEntry(const QString &key, const QVariantList &aDefault) const; |
297 | /** Overload for readEntry(const QString&, const QVariantList&) */ |
298 | QVariantList readEntry(const char *key, const QVariantList &aDefault) const; |
299 | |
300 | /** |
301 | * Reads a list of strings from the config object |
302 | * |
303 | * @param key The key to search for |
304 | * @param aDefault The default value to use if the key does not exist |
305 | * @return The list, or @p aDefault if @p key does not exist |
306 | * |
307 | * @see readXdgListEntry(), writeEntry(), deleteEntry(), hasKey() |
308 | */ |
309 | QStringList readEntry(const QString &key, const QStringList &aDefault) const; |
310 | /** Overload for readEntry(const QString&, const QStringList&) */ |
311 | QStringList readEntry(const char *key, const QStringList &aDefault) const; |
312 | |
313 | /** |
314 | * Reads a list of values from the config object |
315 | * |
316 | * @param key the key to search for |
317 | * @param aDefault the default value to use if the key does not exist |
318 | * @return the list, or @p aDefault if @p key does not exist |
319 | * |
320 | * @see readXdgListEntry(), writeEntry(), deleteEntry(), hasKey() |
321 | */ |
322 | template<typename T> |
323 | inline QList<T> readEntry(const QString &key, const QList<T> &aDefault) const |
324 | { return readListCheck(key.toUtf8().constData(), aDefault); } |
325 | /** Overload for readEntry(const QString&, const QList<T>&) */ |
326 | template<typename T> |
327 | inline QList<T> readEntry(const char *key, const QList<T> &aDefault) const |
328 | { return readListCheck(key, aDefault); } |
329 | |
330 | /** |
331 | * Reads a list of strings from the config object, following XDG |
332 | * desktop entry spec separator semantics |
333 | * |
334 | * @param pKey the key to search for |
335 | * @param aDefault the default value to use if the key does not exist |
336 | * @return the list, or @p aDefault if @p pKey does not exist |
337 | * |
338 | * @see readEntry(const QString&, const QStringList&) const |
339 | */ |
340 | QStringList readXdgListEntry(const QString &pKey, const QStringList &aDefault = QStringList()) const; |
341 | /** Overload for readXdgListEntry(const QString&, const QStringList&) */ |
342 | QStringList readXdgListEntry(const char *pKey, const QStringList &aDefault = QStringList()) const; |
343 | |
344 | /** |
345 | * Reads a path |
346 | * |
347 | * Read the value of an entry specified by @p pKey in the current group |
348 | * and interpret it as a path. This means, dollar expansion is activated |
349 | * for this value, so that e.g. $HOME gets expanded. |
350 | * |
351 | * @param pKey The key to search for. |
352 | * @param aDefault A default value returned if the key was not found. |
353 | * @return The value for this key. Can be QString() if @p aDefault is null. |
354 | */ |
355 | QString readPathEntry(const QString &pKey, const QString &aDefault) const; |
356 | /** Overload for readPathEntry(const QString&, const QString&) */ |
357 | QString readPathEntry(const char *key, const QString &aDefault) const; |
358 | |
359 | /** |
360 | * Reads a list of paths |
361 | * |
362 | * Read the value of an entry specified by @p pKey in the current group |
363 | * and interpret it as a list of paths. This means, dollar expansion is activated |
364 | * for this value, so that e.g. $HOME gets expanded. |
365 | * |
366 | * @param pKey the key to search for |
367 | * @param aDefault a default value returned if the key was not found |
368 | * @return the list, or @p aDefault if the key does not exist |
369 | */ |
370 | QStringList readPathEntry(const QString &pKey, const QStringList &aDefault) const; |
371 | /** Overload for readPathEntry(const QString&, const QStringList&) */ |
372 | QStringList readPathEntry(const char *key, const QStringList &aDefault) const; |
373 | |
374 | /** |
375 | * Reads an untranslated string entry |
376 | * |
377 | * You should not normally need to use this. |
378 | * |
379 | * @param pKey the key to search for |
380 | * @param aDefault a default value returned if the key was not found |
381 | * @return the value for this key, or @p aDefault if the key does not exist |
382 | */ |
383 | QString readEntryUntranslated(const QString &pKey, |
384 | const QString &aDefault = QString()) const; |
385 | /** Overload for readEntryUntranslated(const QString&, const QString&) */ |
386 | QString readEntryUntranslated(const char *key, |
387 | const QString &aDefault = QString()) const; |
388 | |
389 | /** |
390 | * Writes a value to the configuration object. |
391 | * |
392 | * @param key the key to write to |
393 | * @param value the value to write |
394 | * @param pFlags the flags to use when writing this entry |
395 | * |
396 | * @see readEntry(), writeXdgListEntry(), deleteEntry() |
397 | */ |
398 | void writeEntry(const QString &key, const QVariant &value, |
399 | WriteConfigFlags pFlags = Normal); |
400 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
401 | void writeEntry(const char *key, const QVariant &value, |
402 | WriteConfigFlags pFlags = Normal); |
403 | |
404 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
405 | void writeEntry(const QString &key, const QString &value, |
406 | WriteConfigFlags pFlags = Normal); |
407 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
408 | void writeEntry(const char *key, const QString &value, |
409 | WriteConfigFlags pFlags = Normal); |
410 | |
411 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
412 | void writeEntry(const QString &key, const QByteArray &value, |
413 | WriteConfigFlags pFlags = Normal); |
414 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
415 | void writeEntry(const char *key, const QByteArray &value, |
416 | WriteConfigFlags pFlags = Normal); |
417 | |
418 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
419 | void writeEntry(const QString &key, const char *value, WriteConfigFlags pFlags = Normal); |
420 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
421 | void writeEntry(const char *key, const char *value, WriteConfigFlags pFlags = Normal); |
422 | |
423 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
424 | template <typename T> |
425 | inline void writeEntry(const char *key, const T &value, WriteConfigFlags pFlags = Normal) |
426 | { writeCheck( key, value, pFlags ); } |
427 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
428 | template <typename T> |
429 | inline void writeEntry(const QString &key, const T &value, WriteConfigFlags pFlags = Normal) |
430 | { writeCheck( key.toUtf8().constData(), value, pFlags ); } |
431 | |
432 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
433 | void writeEntry(const QString &key, const QStringList &value, |
434 | WriteConfigFlags pFlags = Normal); |
435 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
436 | void writeEntry(const char *key, const QStringList &value, |
437 | WriteConfigFlags pFlags = Normal); |
438 | |
439 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
440 | void writeEntry(const QString &key, const QVariantList &value, |
441 | WriteConfigFlags pFlags = Normal); |
442 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
443 | void writeEntry(const char *key, const QVariantList &value, |
444 | WriteConfigFlags pFlags = Normal); |
445 | |
446 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
447 | template <typename T> |
448 | inline void writeEntry(const QString &key, const QList<T> &value, WriteConfigFlags pFlags = Normal) |
449 | { writeListCheck( key.toUtf8().constData(), value, pFlags ); } |
450 | /** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */ |
451 | template <typename T> |
452 | inline void writeEntry(const char *key, const QList<T> &value, WriteConfigFlags pFlags = Normal) |
453 | { writeListCheck( key, value, pFlags ); } |
454 | |
455 | /** |
456 | * Writes a list of strings to the config object, following XDG |
457 | * desktop entry spec separator semantics |
458 | * |
459 | * @param pKey the key to write to |
460 | * @param value the list to write |
461 | * @param pFlags the flags to use when writing this entry |
462 | * |
463 | * @see writeEntry(), readXdgListEntry() |
464 | */ |
465 | void writeXdgListEntry(const QString &pKey, const QStringList &value, |
466 | WriteConfigFlags pFlags = Normal); |
467 | /** Overload for writeXdgListEntry(const QString&, const QStringList&, WriteConfigFlags) */ |
468 | void writeXdgListEntry(const char *pKey, const QStringList &value, |
469 | WriteConfigFlags pFlags = Normal); |
470 | |
471 | /** |
472 | * Writes a file path to the configuration |
473 | * |
474 | * If the path is located under $HOME, the user's home directory |
475 | * is replaced with $HOME in the persistent storage. |
476 | * The path should therefore be read back with readPathEntry() |
477 | * |
478 | * @param pKey the key to write to |
479 | * @param path the path to write |
480 | * @param pFlags the flags to use when writing this entry |
481 | * |
482 | * @see writeEntry(), readPathEntry() |
483 | */ |
484 | void writePathEntry(const QString &pKey, const QString &path, |
485 | WriteConfigFlags pFlags = Normal); |
486 | /** Overload for writePathEntry(const QString&, const QString&, WriteConfigFlags) */ |
487 | void writePathEntry(const char *pKey, const QString &path, |
488 | WriteConfigFlags pFlags = Normal); |
489 | |
490 | /** |
491 | * Writes a list of paths to the configuration |
492 | * |
493 | * If any of the paths are located under $HOME, the user's home directory |
494 | * is replaced with $HOME in the persistent storage. |
495 | * The paths should therefore be read back with readPathEntry() |
496 | * |
497 | * @param pKey the key to write to |
498 | * @param value the list to write |
499 | * @param pFlags the flags to use when writing this entry |
500 | * |
501 | * @see writeEntry(), readPathEntry() |
502 | */ |
503 | void writePathEntry(const QString &pKey, const QStringList &value, |
504 | WriteConfigFlags pFlags = Normal); |
505 | /** Overload for writePathEntry(const QString&, const QStringList&, WriteConfigFlags) */ |
506 | void writePathEntry(const char *pKey, const QStringList &value, |
507 | WriteConfigFlags pFlags = Normal); |
508 | |
509 | /** |
510 | * Deletes the entry specified by @p pKey in the current group |
511 | * |
512 | * This also hides system wide defaults. |
513 | * |
514 | * @param pKey the key to delete |
515 | * @param pFlags the flags to use when deleting this entry |
516 | * |
517 | * @see deleteGroup(), readEntry(), writeEntry() |
518 | */ |
519 | void deleteEntry(const QString &pKey, WriteConfigFlags pFlags = Normal); |
520 | /** Overload for deleteEntry(const QString&, WriteConfigFlags) */ |
521 | void deleteEntry(const char *pKey, WriteConfigFlags pFlags = Normal); |
522 | |
523 | /** |
524 | * Checks whether the key has an entry in this group |
525 | * |
526 | * Use this to determine if a key is not specified for the current |
527 | * group (hasKey() returns false). |
528 | * |
529 | * If this returns @c false for a key, readEntry() (and its variants) |
530 | * will return the default value passed to them. |
531 | * |
532 | * @param key the key to search for |
533 | * @return @c true if the key is defined in this group by any of the |
534 | * configuration sources, @c false otherwise |
535 | * |
536 | * @see readEntry() |
537 | */ |
538 | bool hasKey(const QString &key) const; |
539 | /** Overload for hasKey(const QString&) const */ |
540 | bool hasKey(const char *key) const; |
541 | |
542 | /** |
543 | * Whether this group may be changed |
544 | * |
545 | * @return @c false if the group may be changed, @c true otherwise |
546 | */ |
547 | bool isImmutable() const; |
548 | |
549 | /** |
550 | * Checks if it is possible to change the given entry |
551 | * |
552 | * If isImmutable() returns @c true, then this method will return |
553 | * @c true for all inputs. |
554 | * |
555 | * @param key the key to check |
556 | * @return @c false if the key may be changed using this configuration |
557 | * group object, @c true otherwise |
558 | */ |
559 | bool isEntryImmutable(const QString &key) const; |
560 | /** Overload for isEntryImmutable(const QString&) const */ |
561 | bool isEntryImmutable(const char *key) const; |
562 | |
563 | /** |
564 | * Reverts an entry to the default settings. |
565 | * |
566 | * Reverts the entry with key @p key in the current group in the |
567 | * application specific config file to either the system wide (default) |
568 | * value or the value specified in the global KDE config file. |
569 | * |
570 | * To revert entries in the global KDE config file, the global KDE config |
571 | * file should be opened explicitly in a separate config object. |
572 | * |
573 | * @note This is @em not the same as deleting the key, as instead the |
574 | * global setting will be copied to the configuration file that this |
575 | * object manipulates. |
576 | * |
577 | * @param key The key of the entry to revert. |
578 | */ |
579 | void revertToDefault(const QString &key); |
580 | /** Overload for revertToDefault(const QString&) */ |
581 | void revertToDefault(const char* key); |
582 | |
583 | /** |
584 | * Whether a default is specified for an entry in either the |
585 | * system wide configuration file or the global KDE config file |
586 | * |
587 | * If an application computes a default value at runtime for |
588 | * a certain entry, e.g. like: |
589 | * \code |
590 | * QColor computedDefault = qApp->palette().color(QPalette::Active, QPalette::Text) |
591 | * QColor color = config->readEntry(key, computedDefault); |
592 | * \endcode |
593 | * then it may wish to make the following check before |
594 | * writing back changes: |
595 | * \code |
596 | * if ( (value == computedDefault) && !config->hasDefault(key) ) |
597 | * config->revertToDefault(key) |
598 | * else |
599 | * config->writeEntry(key, value) |
600 | * \endcode |
601 | * |
602 | * This ensures that as long as the entry is not modified to differ from |
603 | * the computed default, the application will keep using the computed default |
604 | * and will follow changes the computed default makes over time. |
605 | * |
606 | * @param key the key of the entry to check |
607 | * @return @c true if the global or system settings files specify a default |
608 | * for @p key in this group, @c false otherwise |
609 | */ |
610 | bool hasDefault(const QString &key) const; |
611 | /** Overload for hasDefault(const QString&) const */ |
612 | bool hasDefault(const char *key) const; |
613 | |
614 | /** |
615 | * Returns a map (tree) of entries for all entries in this group |
616 | * |
617 | * Only the actual entry string is returned, none of the |
618 | * other internal data should be included. |
619 | * |
620 | * @return a map of entries in this group, indexed by key |
621 | */ |
622 | QMap<QString, QString> entryMap() const; |
623 | |
624 | protected: |
625 | bool hasGroupImpl(const QByteArray &group) const; |
626 | KConfigGroup groupImpl(const QByteArray &b); |
627 | const KConfigGroup groupImpl(const QByteArray &b) const; |
628 | void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags); |
629 | bool isGroupImmutableImpl(const QByteArray &aGroup) const; |
630 | |
631 | private: |
632 | QExplicitlySharedDataPointer<KConfigGroupPrivate> d; |
633 | |
634 | template<typename T> |
635 | inline T readCheck(const char *key, const T &defaultValue) const; |
636 | |
637 | template<typename T> |
638 | inline QList<T> readListCheck(const char *key, const QList<T> &defaultValue) const; |
639 | |
640 | template<typename T> |
641 | inline void writeCheck(const char *key, const T &value, WriteConfigFlags pFlags); |
642 | |
643 | template<typename T> |
644 | inline void writeListCheck(const char *key, const QList<T> &value, WriteConfigFlags pFlags); |
645 | |
646 | friend class KConfigGroupPrivate; |
647 | |
648 | /** |
649 | * Return the data in @p value converted to a QVariant |
650 | * |
651 | * @param pKey the name of the entry being converted, this is only used for error |
652 | * reporting |
653 | * @param value the UTF-8 data to be converted |
654 | * @param aDefault the default value if @p pKey is not found |
655 | * @return @p value converted to QVariant, or @p aDefault if @p value is invalid or cannot be converted. |
656 | */ |
657 | static QVariant convertToQVariant(const char *pKey, const QByteArray &value, const QVariant &aDefault); |
658 | friend class KServicePrivate; // XXX yeah, ugly^5 |
659 | }; |
660 | |
661 | #define KCONFIGGROUP_ENUMERATOR_ERROR(ENUM) \ |
662 | "The Qt MetaObject system does not seem to know about \"" ENUM \ |
663 | "\" please use Q_ENUMS or Q_FLAGS to register it." |
664 | |
665 | /** |
666 | * To add support for your own enums in KConfig, you can declare them with Q_ENUMS() |
667 | * in a QObject subclass (which will make moc generate the code to turn the |
668 | * enum into a string and vice-versa), and then (in the cpp code) |
669 | * use the macro |
670 | * <code>KCONFIGGROUP_DECLARE_ENUM_QOBJECT(MyClass, MyEnum)</code> |
671 | * |
672 | * After that, you can use readEntry(group, key, value) and writeEntry(group, key, value[, flags]). |
673 | * Note that those are global functions, NOT member functions of KConfigGroup. |
674 | * |
675 | */ |
676 | #define KCONFIGGROUP_DECLARE_ENUM_QOBJECT(Class, Enum) \ |
677 | inline Class::Enum readEntry(const KConfigGroup& group, const char* key, const Class::Enum& def) \ |
678 | { \ |
679 | const QMetaObject* M_obj = &Class::staticMetaObject; \ |
680 | const int M_index = M_obj->indexOfEnumerator(#Enum); \ |
681 | kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Enum) << endl; \ |
682 | const QMetaEnum M_enum = M_obj->enumerator(M_index); \ |
683 | const QByteArray M_data = group.readEntry(key, QByteArray(M_enum.valueToKey(def)));\ |
684 | return static_cast<Class::Enum>(M_enum.keyToValue(M_data.constData())); \ |
685 | } \ |
686 | inline void writeEntry(KConfigGroup& group, const char* key, const Class::Enum& value, KConfigBase::WriteConfigFlags flags = KConfigBase::Normal)\ |
687 | { \ |
688 | const QMetaObject* M_obj = &Class::staticMetaObject; \ |
689 | const int M_index = M_obj->indexOfEnumerator(#Enum); \ |
690 | kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Enum) << endl; \ |
691 | const QMetaEnum M_enum = M_obj->enumerator(M_index); \ |
692 | group.writeEntry(key, QByteArray(M_enum.valueToKey(value)), flags); \ |
693 | } |
694 | |
695 | /** |
696 | * Similar to KCONFIGGROUP_DECLARE_ENUM_QOBJECT but for flags declared with Q_FLAGS() |
697 | * (where multiple values can be set at the same time) |
698 | */ |
699 | #define KCONFIGGROUP_DECLARE_FLAGS_QOBJECT(Class, Flags) \ |
700 | inline Class::Flags readEntry(const KConfigGroup& group, const char* key, const Class::Flags& def) \ |
701 | { \ |
702 | const QMetaObject* M_obj = &Class::staticMetaObject; \ |
703 | const int M_index = M_obj->indexOfEnumerator(#Flags); \ |
704 | kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Flags) << endl; \ |
705 | const QMetaEnum M_enum = M_obj->enumerator(M_index); \ |
706 | const QByteArray M_data = group.readEntry(key, QByteArray(M_enum.valueToKeys(def)));\ |
707 | return static_cast<Class::Flags>(M_enum.keysToValue(M_data.constData())); \ |
708 | } \ |
709 | inline void writeEntry(KConfigGroup& group, const char* key, const Class::Flags& value, KConfigBase::WriteConfigFlags flags = KConfigBase::Normal)\ |
710 | { \ |
711 | const QMetaObject* M_obj = &Class::staticMetaObject; \ |
712 | const int M_index = M_obj->indexOfEnumerator(#Flags); \ |
713 | kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Flags) << endl; \ |
714 | const QMetaEnum M_enum = M_obj->enumerator(M_index); \ |
715 | group.writeEntry(key, QByteArray(M_enum.valueToKeys(value)), flags); \ |
716 | } |
717 | |
718 | #include "conversion_check.h" |
719 | |
720 | template <typename T> |
721 | T KConfigGroup::readCheck(const char *key, const T &defaultValue) const |
722 | { |
723 | ConversionCheck::to_QVariant<T>(); |
724 | return qvariant_cast<T>(readEntry(key, qVariantFromValue(defaultValue))); |
725 | } |
726 | |
727 | template <typename T> |
728 | QList<T> KConfigGroup::readListCheck(const char *key, const QList<T> &defaultValue) const |
729 | { |
730 | ConversionCheck::to_QVariant<T>(); |
731 | ConversionCheck::to_QString<T>(); |
732 | |
733 | QVariantList data; |
734 | |
735 | Q_FOREACH(const T& value, defaultValue) |
736 | data.append(qVariantFromValue(value)); |
737 | |
738 | QList<T> list; |
739 | Q_FOREACH (const QVariant &value, readEntry<QVariantList>(key, data)) { |
740 | Q_ASSERT(qVariantCanConvert<T>(value)); |
741 | list.append(qvariant_cast<T>(value)); |
742 | } |
743 | |
744 | return list; |
745 | } |
746 | |
747 | template <typename T> |
748 | void KConfigGroup::writeCheck(const char *key, const T &value, |
749 | WriteConfigFlags pFlags) |
750 | { |
751 | ConversionCheck::to_QVariant<T>(); |
752 | writeEntry(key, qVariantFromValue(value), pFlags); |
753 | } |
754 | |
755 | template <typename T> |
756 | void KConfigGroup::writeListCheck(const char *key, const QList<T> &list, |
757 | WriteConfigFlags pFlags) |
758 | { |
759 | ConversionCheck::to_QVariant<T>(); |
760 | ConversionCheck::to_QString<T>(); |
761 | QVariantList data; |
762 | Q_FOREACH(const T &value, list) { |
763 | data.append(qVariantFromValue(value)); |
764 | } |
765 | |
766 | writeEntry(key, data, pFlags); |
767 | } |
768 | |
769 | #endif // KCONFIGGROUP_H |
770 | |