1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
4 SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org>
5 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
6 SPDX-FileCopyrightText: 2001 Waldo Bastian <bastian@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KCONFIGGROUP_H
12#define KCONFIGGROUP_H
13
14#include "kconfigbase.h"
15
16#include <kconfigcore_export.h>
17
18#include <QExplicitlySharedDataPointer>
19#include <QStringList>
20#include <QVariant>
21
22class KConfig;
23class KConfigGroupPrivate;
24class KSharedConfig;
25
26/*!
27 * \class KConfigGroup
28 * \inmodule KConfigCore
29 *
30 * \brief A class for one specific group in a KConfig object.
31 *
32 * If you want to access the top-level entries of a KConfig
33 * object, which are not associated with any group, use an
34 * empty group name.
35 *
36 * A KConfigGroup will be read-only if it is constructed from a
37 * const config object or from another read-only group.
38 */
39class KCONFIGCORE_EXPORT KConfigGroup : public KConfigBase
40{
41public:
42 /*!
43 * Constructs an invalid group.
44 *
45 * \sa isValid
46 */
47 KConfigGroup();
48
49 /*!
50 * Construct a config group corresponding to \a group in \a master.
51 *
52 * This allows the creation of subgroups by passing another
53 * group as \a master.
54 *
55 * \a group name of group
56 */
57 KConfigGroup(KConfigBase *master, const QString &group);
58
59 /*!
60 * Construct a read-only config group.
61 *
62 * A read-only group will silently ignore any attempts to write to it.
63 *
64 * This allows the creation of subgroups by passing an existing group
65 * as \a master.
66 */
67 KConfigGroup(const KConfigBase *master, const QString &group);
68
69 /*!
70 * \overload
71 * Overload for KConfigGroup(const KConfigBase*,const QString&)
72 */
73 KConfigGroup(const QExplicitlySharedDataPointer<KSharedConfig> &master, const QString &group);
74
75 KConfigGroup(const KConfigGroup &);
76 KConfigGroup &operator=(const KConfigGroup &);
77
78 ~KConfigGroup() override;
79
80 /*!
81 * Whether the group is valid.
82 *
83 * A group is invalid if it was constructed without arguments.
84 *
85 * You should not call any functions on an invalid group.
86 *
87 * Returns \c true if the group is valid, \c false if it is invalid.
88 */
89 bool isValid() const;
90
91 /*!
92 * The name of this group.
93 *
94 * The root group is named "<default>".
95 */
96 QString name() const;
97
98 /*!
99 * Check whether the containing KConfig object actually contains a
100 * group with this name.
101 */
102 bool exists() const;
103
104 /*!
105 * \reimp
106 *
107 * Syncs the parent config.
108 */
109 bool sync() override;
110
111 void markAsClean() override;
112
113 AccessMode accessMode() const override;
114
115 /*!
116 * Return the config object that this group belongs to
117 */
118 KConfig *config();
119 /*!
120 * Return the config object that this group belongs to
121 */
122 const KConfig *config() const;
123
124 /*!
125 * Copies the entries in this group to another configuration object
126 *
127 * \note \a other can be either another group or a different file.
128 *
129 * \a other the configuration object to copy this group's entries to
130 *
131 * \a pFlags the flags to use when writing the entries to the
132 * other configuration object
133 *
134 * \since 4.1
135 */
136 void copyTo(KConfigBase *other, WriteConfigFlags pFlags = Normal) const;
137
138 /*!
139 * Changes the configuration object that this group belongs to
140 *
141 * If \a parent is already the parent of this group, this method will have
142 * no effect.
143 *
144 * \a parent the config object to place this group under
145 *
146 * \a pFlags the flags to use in determining which storage source to
147 * write the data to
148 *
149 * \since 4.1
150 */
151 void reparent(KConfigBase *parent, WriteConfigFlags pFlags = Normal);
152
153 /*!
154 * Moves the key-value pairs from one config group to the other.
155 * In case the entries do not exist the key is ignored.
156 *
157 * \since 5.88
158 */
159 void moveValuesTo(const QList<const char *> &keys, KConfigGroup &other, WriteConfigFlags pFlags = Normal);
160
161 /*!
162 * Moves the key-value pairs from one config group to the other.
163 *
164 * \since 6.3
165 */
166 void moveValuesTo(KConfigGroup &other, WriteConfigFlags pFlags = Normal);
167
168 /*!
169 * Returns the group that this group belongs to
170 *
171 * Returns the parent group, or an invalid group if this is a top-level
172 * group
173 *
174 * \since 4.1
175 */
176 KConfigGroup parent() const;
177
178 QStringList groupList() const override;
179
180 /*!
181 * Returns a list of keys this group contains
182 */
183 QStringList keyList() const;
184
185 /*!
186 * Delete all entries in the entire group
187 *
188 * \a pFlags flags passed to KConfig::deleteGroup
189 *
190 * \sa deleteEntry()
191 */
192 void deleteGroup(WriteConfigFlags pFlags = Normal);
193 using KConfigBase::deleteGroup;
194
195 /*!
196 * Reads the value of an entry specified by \a pKey in the current group
197 *
198 * This template method makes it possible to write
199 * QString foo = readEntry("...", QString("default"));
200 * and the same with all other types supported by QVariant.
201 *
202 * The return type of the method is simply the same as the type of the default value.
203 *
204 * \note readEntry("...", Qt::white) will not compile because Qt::white is an enum.
205 * You must turn it into readEntry("...", QColor(Qt::white)).
206 *
207 * \note Only the following QVariant types are allowed : String,
208 * StringList, List, Font, Point, PointF, Rect, RectF, Size, SizeF, Color, Int, UInt, Bool,
209 * Double, LongLong, ULongLong, DateTime and Date.
210 *
211 * \a key The key to search for
212 *
213 * \a aDefault A default value returned if the key was not found
214 *
215 * Returns the value for this key, or \a aDefault.
216 *
217 * \sa writeEntry(), deleteEntry(), hasKey()
218 */
219 template<typename T>
220 T readEntry(const QString &key, const T &aDefault) const
221 {
222 return readEntry(key.toUtf8().constData(), aDefault);
223 }
224 /*!
225 * \overload
226 *
227 * Overload for readEntry<T>(const QString&, const T&) const
228 *
229 * \a key name of key, encoded in UTF-8
230 */
231 template<typename T>
232 T readEntry(const char *key, const T &aDefault) const;
233
234 /*!
235 * Reads the value of an entry specified by \a key in the current group
236 *
237 * \a key the key to search for
238 *
239 * \a aDefault a default value returned if the key was not found
240 *
241 * Returns the value for this key, or \a aDefault if the key was not found
242 *
243 * \sa writeEntry(), deleteEntry(), hasKey()
244 */
245 QVariant readEntry(const QString &key, const QVariant &aDefault) const;
246 /*!
247 * Overload for readEntry(const QString&, const QVariant&) const
248 * \a key name of key, encoded in UTF-8
249 */
250 QVariant readEntry(const char *key, const QVariant &aDefault) const;
251
252 /*!
253 * Reads the string value of an entry specified by \a key in the current group
254 *
255 * If you want to read a path, please use readPathEntry().
256 *
257 * \a key the key to search for
258 *
259 * \a aDefault a default value returned if the key was not found
260 *
261 * Returns the value for this key, or \a aDefault if the key was not found
262 *
263 * \sa readPathEntry(), writeEntry(), deleteEntry(), hasKey()
264 */
265 QString readEntry(const QString &key, const QString &aDefault) const;
266 /*!
267 * \overload
268 *
269 * Overload for readEntry(const QString&, const QString&) const
270 *
271 * \a key name of key, encoded in UTF-8
272 */
273 QString readEntry(const char *key, const QString &aDefault) const;
274
275 /*!
276 * \overload
277 *
278 * Overload for readEntry(const QString&, const QString&) const
279 */
280 QString readEntry(const QString &key, const char *aDefault = nullptr) const;
281 /*!
282 * \overload
283 *
284 * Overload for readEntry(const QString&, const QString&) const
285 *
286 * \a key name of key, encoded in UTF-8
287 */
288 QString readEntry(const char *key, const char *aDefault = nullptr) const;
289
290 /*!
291 * \sa readEntry()
292 *
293 * \warning This function doesn't convert the items returned
294 * to any type. It's actually a list of QVariant::String's. If you
295 * want the items converted to a specific type use
296 * readEntry(const char*, const QList<T>&) const
297 */
298 QVariantList readEntry(const QString &key, const QVariantList &aDefault) const;
299 /*!
300 * \overload
301 *
302 * Overload for readEntry(const QString&, const QVariantList&) const
303 *
304 * \a key name of key, encoded in UTF-8
305 */
306 QVariantList readEntry(const char *key, const QVariantList &aDefault) const;
307
308 /*!
309 * Reads a list of strings from the config object
310 *
311 * \a key The key to search for
312 *
313 * \a aDefault The default value to use if the key does not exist
314 *
315 * Returns the list, or \a aDefault if \a key does not exist
316 *
317 * \sa readXdgListEntry(), writeEntry(), deleteEntry(), hasKey()
318 */
319 QStringList readEntry(const QString &key, const QStringList &aDefault) const;
320 /*!
321 * \overload
322 *
323 * Overload for readEntry(const QString&, const QStringList&) const
324 *
325 * \a key name of key, encoded in UTF-8
326 */
327 QStringList readEntry(const char *key, const QStringList &aDefault) const;
328
329 /*!
330 * Reads a list of values from the config object
331 *
332 * \a key the key to search for
333 *
334 * \a aDefault the default value to use if the key does not exist
335 *
336 * Returns the list, or \a aDefault if \a key does not exist
337 *
338 * \sa readXdgListEntry(), writeEntry(), deleteEntry(), hasKey()
339 */
340 template<typename T>
341 QList<T> readEntry(const QString &key, const QList<T> &aDefault) const
342 {
343 return readEntry(key.toUtf8().constData(), aDefault);
344 }
345 /*!
346 * \overload
347 *
348 * Overload for readEntry<T>(const QString&, const QList<T>&) const
349 *
350 * \a key name of key, encoded in UTF-8
351 */
352 template<typename T>
353 QList<T> readEntry(const char *key, const QList<T> &aDefault) const;
354
355 /*!
356 * \overload
357 *
358 * Overload for readEntry(const QString&, std::chrono::duration<Rep, Period>)
359 *
360 * \a key name of key, encoded in UTF-8
361 *
362 * \since 6.22
363 */
364 template<typename Rep, typename Period>
365 std::chrono::duration<Rep, Period> readEntry(const char *key, std::chrono::duration<Rep, Period> defaultValue) const;
366
367 /*!
368 * Reads a std::chrono duration from the config object with the given \a key. If the config
369 * contains no specified \a key, the \a value will be returned instead.
370 *
371 * \since 6.22
372 */
373 template<typename Rep, typename Period>
374 std::chrono::duration<Rep, Period> readEntry(const QString &key, std::chrono::duration<Rep, Period> defaultValue) const;
375
376 /*!
377 * Reads a list of strings from the config object with semicolons separating
378 * them (i.e. following desktop entry spec separator semantics).
379 *
380 * \a pKey the key to search for
381 *
382 * \a aDefault the default value to use if the key does not exist
383 *
384 * Returns the list, or \a aDefault if \a pKey does not exist
385 *
386 * \sa readEntry(const QString&, const QStringList&)
387 */
388 QStringList readXdgListEntry(const QString &pKey, const QStringList &aDefault = QStringList()) const;
389 /*!
390 * Overload for readXdgListEntry(const QString&, const QStringList&) const
391 *
392 * \a key name of key, encoded in UTF-8
393 */
394 QStringList readXdgListEntry(const char *key, const QStringList &aDefault = QStringList()) const;
395
396 /*!
397 * Reads a path
398 *
399 * Read the value of an entry specified by \a pKey in the current group
400 * and interpret it as a path. This means, dollar expansion is activated
401 * for this value, so that e.g. $HOME gets expanded.
402 *
403 * \a pKey The key to search for.
404 *
405 * \a aDefault A default value returned if the key was not found.
406 *
407 * Returns The value for this key. Can be QString() if \a aDefault is null.
408 */
409 QString readPathEntry(const QString &pKey, const QString &aDefault) const;
410 /*!
411 * Overload for readPathEntry(const QString&, const QString&) const
412 *
413 * \a key name of key, encoded in UTF-8
414 */
415 QString readPathEntry(const char *key, const QString &aDefault) const;
416
417 /*!
418 * Reads a list of paths
419 *
420 * Read the value of an entry specified by \a pKey in the current group
421 * and interpret it as a list of paths. This means, dollar expansion is activated
422 * for this value, so that e.g. $HOME gets expanded.
423 *
424 * \a pKey the key to search for
425 *
426 * \a aDefault a default value returned if the key was not found
427 *
428 * Returns the list, or \a aDefault if the key does not exist
429 */
430 QStringList readPathEntry(const QString &pKey, const QStringList &aDefault) const;
431 /*!
432 * Overload for readPathEntry(const QString&, const QStringList&) const
433 *
434 * \a key name of key, encoded in UTF-8
435 */
436 QStringList readPathEntry(const char *key, const QStringList &aDefault) const;
437
438 /*!
439 * Reads an untranslated string entry
440 *
441 * You should not normally need to use this.
442 *
443 * \a pKey the key to search for
444 *
445 * \a aDefault a default value returned if the key was not found
446 *
447 * Returns the value for this key, or \a aDefault if the key does not exist
448 */
449 QString readEntryUntranslated(const QString &pKey, const QString &aDefault = QString()) const;
450 /*!
451 * \overload
452 *
453 * Overload for readEntryUntranslated(const QString&, const QString&) const
454 *
455 * \a key name of key, encoded in UTF-8
456 */
457 QString readEntryUntranslated(const char *key, const QString &aDefault = QString()) const;
458
459 /*!
460 * Writes a value to the configuration object.
461 *
462 * \a key the key to write to
463 *
464 * \a value the value to write
465 *
466 * \a pFlags the flags to use when writing this entry
467 *
468 * \sa readEntry(), writeXdgListEntry(), deleteEntry()
469 */
470 void writeEntry(const QString &key, const QVariant &value, WriteConfigFlags pFlags = Normal);
471 /*!
472 * \overload
473 *
474 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
475 * \a key name of key, encoded in UTF-8
476 */
477 void writeEntry(const char *key, const QVariant &value, WriteConfigFlags pFlags = Normal);
478
479 /*!
480 * \overload
481 *
482 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
483 */
484 void writeEntry(const QString &key, const QString &value, WriteConfigFlags pFlags = Normal);
485 /*!
486 * \overload
487 *
488 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
489 *
490 * \a key name of key, encoded in UTF-8
491 */
492 void writeEntry(const char *key, const QString &value, WriteConfigFlags pFlags = Normal);
493
494 /*!
495 * \overload
496 *
497 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
498 */
499 void writeEntry(const QString &key, const QByteArray &value, WriteConfigFlags pFlags = Normal);
500 /*!
501 * \overload
502 *
503 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
504 *
505 * \a key name of key, encoded in UTF-8
506 */
507 void writeEntry(const char *key, const QByteArray &value, WriteConfigFlags pFlags = Normal);
508
509 /*!
510 * \overload
511 *
512 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
513 */
514 void writeEntry(const QString &key, const char *value, WriteConfigFlags pFlags = Normal);
515 /*!
516 * \overload
517 *
518 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
519 *
520 * \a key name of key, encoded in UTF-8
521 */
522 void writeEntry(const char *key, const char *value, WriteConfigFlags pFlags = Normal);
523
524 /*!
525 * \overload
526 *
527 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
528 *
529 * \a key name of key, encoded in UTF-8
530 */
531 template<typename T>
532 void writeEntry(const char *key, const T &value, WriteConfigFlags pFlags = Normal);
533 /*!
534 * \overload
535 *
536 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
537 */
538 template<typename T>
539 void writeEntry(const QString &key, const T &value, WriteConfigFlags pFlags = Normal)
540 {
541 writeEntry(key.toUtf8().constData(), value, pFlags);
542 }
543
544 /*!
545 * \overload
546 *
547 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
548 */
549 void writeEntry(const QString &key, const QStringList &value, WriteConfigFlags pFlags = Normal);
550 /*!
551 * \overload
552 *
553 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
554 *
555 * \a key name of key, encoded in UTF-8
556 */
557 void writeEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags = Normal);
558
559 /*!
560 * \overload
561 *
562 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
563 */
564 void writeEntry(const QString &key, const QVariantList &value, WriteConfigFlags pFlags = Normal);
565 /*!
566 * \overload
567 *
568 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
569 *
570 * \a key name of key, encoded in UTF-8
571 */
572 void writeEntry(const char *key, const QVariantList &value, WriteConfigFlags pFlags = Normal);
573
574 /*!
575 * \overload
576 *
577 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
578 */
579 template<typename T>
580 void writeEntry(const QString &key, const QList<T> &value, WriteConfigFlags pFlags = Normal)
581 {
582 writeEntry(key.toUtf8().constData(), value, pFlags);
583 }
584 /*!
585 * \overload
586 *
587 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
588 *
589 * \a key name of key, encoded in UTF-8
590 */
591 template<typename T>
592 void writeEntry(const char *key, const QList<T> &value, WriteConfigFlags pFlags = Normal);
593
594 /*!
595 * \overload
596 *
597 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
598 *
599 * \since 6.22
600 */
601 template<typename Rep, typename Period>
602 void writeEntry(const QString &key, std::chrono::duration<Rep, Period> value, WriteConfigFlags pFlags = Normal);
603
604 /*!
605 * \overload
606 * Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
607 *
608 * \a key name of key, encoded in UTF-8
609 *
610 * \since 6.22
611 */
612 template<typename Rep, typename Period>
613 void writeEntry(const char *key, std::chrono::duration<Rep, Period> value, WriteConfigFlags pFlags = Normal);
614
615 /*!
616 * Writes a list of strings to the config object, following XDG
617 * desktop entry spec separator semantics
618 *
619 * \a pKey the key to write to
620 *
621 * \a value the list to write
622 *
623 * \a pFlags the flags to use when writing this entry
624 *
625 * \sa writeEntry(), readXdgListEntry()
626 */
627 void writeXdgListEntry(const QString &pKey, const QStringList &value, WriteConfigFlags pFlags = Normal);
628 /*!
629 * \overload
630 *
631 * Overload for writeXdgListEntry(const QString&, const QStringList&, WriteConfigFlags)
632 *
633 * \a key name of key, encoded in UTF-8
634 */
635 void writeXdgListEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags = Normal);
636
637 /*!
638 * Writes a file path to the configuration
639 *
640 * If the path is located under $HOME, the user's home directory
641 * is replaced with $HOME in the persistent storage.
642 * The path should therefore be read back with readPathEntry()
643 *
644 * \a pKey the key to write to
645 *
646 * \a path the path to write
647 *
648 * \a pFlags the flags to use when writing this entry
649 *
650 * \sa writeEntry(), readPathEntry()
651 */
652 void writePathEntry(const QString &pKey, const QString &path, WriteConfigFlags pFlags = Normal);
653 /*!
654 * \overload
655 *
656 * Overload for writePathEntry(const QString&, const QString&, WriteConfigFlags)
657 *
658 * \a key name of key, encoded in UTF-8
659 */
660 void writePathEntry(const char *Key, const QString &path, WriteConfigFlags pFlags = Normal);
661
662 /*!
663 * Writes a list of paths to the configuration
664 *
665 * If any of the paths are located under $HOME, the user's home directory
666 * is replaced with $HOME in the persistent storage.
667 * The paths should therefore be read back with readPathEntry()
668 *
669 * \a pKey the key to write to
670 *
671 * \a value the list to write
672 *
673 * \a pFlags the flags to use when writing this entry
674 *
675 * \sa writeEntry(), readPathEntry()
676 */
677 void writePathEntry(const QString &pKey, const QStringList &value, WriteConfigFlags pFlags = Normal);
678 /*!
679 * \overload
680 *
681 * Overload for writePathEntry(const QString&, const QStringList&, WriteConfigFlags)
682 *
683 * \a key name of key, encoded in UTF-8
684 */
685 void writePathEntry(const char *key, const QStringList &value, WriteConfigFlags pFlags = Normal);
686
687 /*!
688 * Deletes the entry specified by \a pKey in the current group
689 *
690 * This also hides system wide defaults.
691 *
692 * \a pKey the key to delete
693 *
694 * \a pFlags the flags to use when deleting this entry
695 *
696 * \sa deleteGroup(), readEntry(), writeEntry()
697 */
698 void deleteEntry(const QString &pKey, WriteConfigFlags pFlags = Normal);
699 /*!
700 * \overload
701 *
702 * Overload for deleteEntry(const QString&, WriteConfigFlags)
703 *
704 * \a key name of key, encoded in UTF-8
705 */
706 void deleteEntry(const char *key, WriteConfigFlags pFlags = Normal);
707
708 /*!
709 * Checks whether the key has an entry in this group
710 *
711 * Use this to determine if a key is not specified for the current
712 * group (hasKey() returns false).
713 *
714 * If this returns \c false for a key, readEntry() (and its variants)
715 * will return the default value passed to them.
716 *
717 * \a key the key to search for
718 *
719 * Returns \c true if the key is defined in this group by any of the
720 * configuration sources, \c false otherwise
721 *
722 * \sa readEntry()
723 */
724 bool hasKey(const QString &key) const;
725 /*!
726 * \overload
727 *
728 * Overload for hasKey(const QString&) const
729 *
730 * \a key name of key, encoded in UTF-8
731 */
732 bool hasKey(const char *key) const;
733
734 /*!
735 * Whether this group may be changed
736 *
737 * Returns \c false if the group may be changed, \c true otherwise
738 */
739 bool isImmutable() const override;
740
741 /*!
742 * Checks if it is possible to change the given entry
743 *
744 * If isImmutable() returns \c true, then this method will return
745 * \c true for all inputs.
746 *
747 * \a key the key to check
748 *
749 * Returns \c false if the key may be changed using this configuration
750 * group object, \c true otherwise
751 */
752 bool isEntryImmutable(const QString &key) const;
753 /*!
754 * \overload
755 *
756 * Overload for isEntryImmutable(const QString&) const
757 *
758 * \a key name of key, encoded in UTF-8
759 */
760 bool isEntryImmutable(const char *key) const;
761
762 /*!
763 * Reverts an entry to the default settings.
764 *
765 * Reverts the entry with key \a key in the current group in the
766 * application specific config file to either the system wide (default)
767 * value or the value specified in the global KDE config file.
768 *
769 * To revert entries in the global KDE config file, the global KDE config
770 * file should be opened explicitly in a separate config object.
771 *
772 * \note This is not the same as deleting the key, as instead the
773 * global setting will be copied to the configuration file that this
774 * object manipulates.
775 *
776 * \a key The key of the entry to revert.
777 */
778 void revertToDefault(const QString &key, WriteConfigFlags pFlag = WriteConfigFlags());
779
780 /*!
781 * Overload for revertToDefault(const QString&, WriteConfigFlags)
782 *
783 * \a key name of key, encoded in UTF-8
784 */
785 void revertToDefault(const char *key, WriteConfigFlags pFlag = WriteConfigFlags());
786
787 /*!
788 * Whether a default is specified for an entry in either the
789 * system wide configuration file or the global KDE config file
790 *
791 * If an application computes a default value at runtime for
792 * a certain entry, e.g. like:
793 * \code
794 * QColor computedDefault = qApp->palette().color(QPalette::Active, QPalette::Text);
795 * QColor color = group.readEntry(key, computedDefault);
796 * \endcode
797 * then it may wish to make the following check before
798 * writing back changes:
799 * \code
800 * if ( (value == computedDefault) && !group.hasDefault(key) )
801 * group.revertToDefault(key);
802 * else
803 * group.writeEntry(key, value);
804 * \endcode
805 *
806 * This ensures that as long as the entry is not modified to differ from
807 * the computed default, the application will keep using the computed default
808 * and will follow changes the computed default makes over time.
809 *
810 * \a key the key of the entry to check
811 *
812 * Returns \c true if the global or system settings files specify a default
813 * for \a key in this group, \c false otherwise
814 */
815 bool hasDefault(const QString &key) const;
816 /*!
817 * \overload
818 *
819 * Overload for hasDefault(const QString&) const
820 *
821 * \a key name of key, encoded in UTF-8
822 */
823 bool hasDefault(const char *key) const;
824
825 /*!
826 * Returns a map (tree) of entries for all entries in this group
827 *
828 * Only the actual entry string is returned, none of the
829 * other internal data should be included.
830 *
831 * Returns a map of entries in this group, indexed by key
832 */
833 QMap<QString, QString> entryMap() const;
834
835protected:
836 bool hasGroupImpl(const QString &groupName) const override;
837 KConfigGroup groupImpl(const QString &groupName) override;
838 const KConfigGroup groupImpl(const QString &groupName) const override;
839 void deleteGroupImpl(const QString &groupName, WriteConfigFlags flags) override;
840 bool isGroupImmutableImpl(const QString &groupName) const override;
841
842private:
843 QExplicitlySharedDataPointer<KConfigGroupPrivate> d;
844
845 friend class KConfigGroupPrivate;
846
847 /*!
848 * \internal
849 *
850 * Return the data in \a value converted to a QVariant
851 *
852 * \a pKey the name of the entry being converted, this is only used for error
853 * reporting
854 *
855 * \a value the UTF-8 data to be converted
856 *
857 * \a aDefault the default value if \a pKey is not found
858 *
859 * Returns \a value converted to QVariant, or \a aDefault if \a value is invalid or cannot be converted.
860 */
861 static QVariant convertToQVariant(const char *pKey, const QByteArray &value, const QVariant &aDefault);
862
863 KCONFIGCORE_NO_EXPORT void moveValue(const char *key, KConfigGroup &other, WriteConfigFlags pFlags);
864
865 // exported for usage by KServices' KService & KServiceAction
866 friend class KServicePrivate; // XXX yeah, ugly^5
867 friend class KServiceAction;
868};
869
870Q_DECLARE_TYPEINFO(KConfigGroup, Q_RELOCATABLE_TYPE);
871
872#define KCONFIGGROUP_ENUMERATOR_ERROR(ENUM) "The Qt MetaObject system does not seem to know about \"" ENUM "\" please use Q_ENUM or Q_FLAG to register it."
873
874/*!
875 * \macro KCONFIGGROUP_DECLARE_ENUM_QOBJECT(Class, Enum)
876 * \relates KConfigGroup
877 * To add support for your own enums in KConfig, you can declare them with Q_ENUM()
878 * in a QObject subclass (which will make moc generate the code to turn the
879 * enum into a string and vice-versa), and then (in the cpp code)
880 * use the macro
881 * \code
882 * KCONFIGGROUP_DECLARE_ENUM_QOBJECT(MyClass, MyEnum)
883 * \endcode
884 *
885 */
886#define KCONFIGGROUP_DECLARE_ENUM_QOBJECT(Class, Enum) \
887 template<> \
888 Class::Enum KConfigGroup::readEntry(const char *key, const Class::Enum &def) const \
889 { \
890 const QMetaObject *M_obj = &Class::staticMetaObject; \
891 const int M_index = M_obj->indexOfEnumerator(#Enum); \
892 if (M_index == -1) \
893 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Enum)); \
894 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
895 const QByteArray M_data = readEntry(key, QByteArray(M_enum.valueToKey(def))); \
896 return static_cast<Class::Enum>(M_enum.keyToValue(M_data.constData())); \
897 } \
898 template<> \
899 void KConfigGroup::writeEntry(const char *key, const Class::Enum &value, KConfigBase::WriteConfigFlags flags) \
900 { \
901 const QMetaObject *M_obj = &Class::staticMetaObject; \
902 const int M_index = M_obj->indexOfEnumerator(#Enum); \
903 if (M_index == -1) \
904 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Enum)); \
905 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
906 writeEntry(key, QByteArray(M_enum.valueToKey(value)), flags); \
907 }
908
909/*!
910 * \macro KCONFIGGROUP_DECLARE_FLAGS_QOBJECT(Class, Flags)
911 * \relates KConfigGroup
912 * Similar to KCONFIGGROUP_DECLARE_ENUM_QOBJECT but for flags declared with Q_FLAG()
913 * (where multiple values can be set at the same time)
914 */
915#define KCONFIGGROUP_DECLARE_FLAGS_QOBJECT(Class, Flags) \
916 template<> \
917 Class::Flags KConfigGroup::readEntry(const char *key, const Class::Flags &def) const \
918 { \
919 const QMetaObject *M_obj = &Class::staticMetaObject; \
920 const int M_index = M_obj->indexOfEnumerator(#Flags); \
921 if (M_index == -1) \
922 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Flags)); \
923 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
924 const QByteArray M_data = readEntry(key, QByteArray(M_enum.valueToKeys(def))); \
925 return static_cast<Class::Flags>(M_enum.keysToValue(M_data.constData())); \
926 } \
927 template<> \
928 void KConfigGroup::writeEntry(const char *key, const Class::Flags &value, KConfigBase::WriteConfigFlags flags) \
929 { \
930 const QMetaObject *M_obj = &Class::staticMetaObject; \
931 const int M_index = M_obj->indexOfEnumerator(#Flags); \
932 if (M_index == -1) \
933 qFatal(KCONFIGGROUP_ENUMERATOR_ERROR(#Flags)); \
934 const QMetaEnum M_enum = M_obj->enumerator(M_index); \
935 writeEntry(key, QByteArray(M_enum.valueToKeys(value)), flags); \
936 }
937
938#include "kconfigconversioncheck_p.h"
939
940template<typename T>
941T KConfigGroup::readEntry(const char *key, const T &defaultValue) const
942{
943 KConfigConversionCheck::to_QVariant<T>();
944 return qvariant_cast<T>(readEntry(key, QVariant::fromValue(defaultValue)));
945}
946
947template<typename T>
948QList<T> KConfigGroup::readEntry(const char *key, const QList<T> &defaultValue) const
949{
950 KConfigConversionCheck::to_QVariant<T>();
951 KConfigConversionCheck::to_QString<T>();
952
953 QVariantList data;
954
955 for (const T &value : defaultValue) {
956 data.append(QVariant::fromValue(value));
957 }
958
959 QList<T> list;
960 const auto variantList = readEntry<QVariantList>(key, defaultValue: data);
961 for (const QVariant &value : variantList) {
962 Q_ASSERT(value.canConvert<T>());
963 list.append(qvariant_cast<T>(value));
964 }
965
966 return list;
967}
968
969template<typename Rep, typename Period>
970std::chrono::duration<Rep, Period> KConfigGroup::readEntry(const char *key, std::chrono::duration<Rep, Period> value) const
971{
972 return std::chrono::duration<Rep, Period>(readEntry(key, value.count()));
973}
974
975template<typename Rep, typename Period>
976std::chrono::duration<Rep, Period> KConfigGroup::readEntry(const QString &key, std::chrono::duration<Rep, Period> value) const
977{
978 return std::chrono::duration<Rep, Period>(readEntry(key, value.count()));
979}
980
981template<typename T>
982void KConfigGroup::writeEntry(const char *key, const T &value, WriteConfigFlags pFlags)
983{
984 KConfigConversionCheck::to_QVariant<T>();
985 writeEntry(key, QVariant::fromValue(value), pFlags);
986}
987
988template<typename T>
989void KConfigGroup::writeEntry(const char *key, const QList<T> &list, WriteConfigFlags pFlags)
990{
991 KConfigConversionCheck::to_QVariant<T>();
992 KConfigConversionCheck::to_QString<T>();
993 QVariantList data;
994 for (const T &value : list) {
995 data.append(QVariant::fromValue(value));
996 }
997
998 writeEntry(key, value: data, pFlags);
999}
1000
1001template<typename Rep, typename Period>
1002void KConfigGroup::writeEntry(const QString &key, std::chrono::duration<Rep, Period> value, WriteConfigFlags pFlags)
1003{
1004 writeEntry(key, value.count(), pFlags);
1005}
1006
1007template<typename Rep, typename Period>
1008void KConfigGroup::writeEntry(const char *key, std::chrono::duration<Rep, Period> value, WriteConfigFlags pFlags)
1009{
1010 writeEntry(key, value.count(), pFlags);
1011}
1012
1013#endif // KCONFIGGROUP_H
1014

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