KConfig

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

KDE's Doxygen guidelines are available online.