KConfig

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

KDE's Doxygen guidelines are available online.