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

KDE's Doxygen guidelines are available online.