KConfig

kcoreconfigskeleton.h
1 /*
2  This file is part of KDE.
3 
4  SPDX-FileCopyrightText: 2001, 2002, 2003 Cornelius Schumacher <[email protected]>
5  SPDX-FileCopyrightText: 2003 Waldo Bastian <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-or-later
8 */
9 
10 #ifndef KCORECONFIGSKELETON_H
11 #define KCORECONFIGSKELETON_H
12 
13 #include <kconfigcore_export.h>
14 
15 #include <kconfiggroup.h>
16 #include <ksharedconfig.h>
17 
18 #include <QDate>
19 #include <QHash>
20 #include <QRect>
21 #include <QStringList>
22 #include <QUrl>
23 #include <QVariant>
24 
25 class KCoreConfigSkeletonPrivate;
26 
27 class KConfigSkeletonItemPrivate;
28 /**
29  * \class KConfigSkeletonItem kcoreconfigskeleton.h <KCoreConfigSkeleton>
30  *
31  * @short Class for storing a preferences setting
32  * @author Cornelius Schumacher
33  * @see KCoreConfigSkeleton
34  *
35  * This class represents one preferences setting as used by @ref KCoreConfigSkeleton.
36  * Subclasses of KConfigSkeletonItem implement storage functions for a certain type of
37  * setting. Normally you don't have to use this class directly. Use the special
38  * addItem() functions of KCoreConfigSkeleton instead. If you subclass this class you will
39  * have to register instances with the function KCoreConfigSkeleton::addItem().
40  */
41 class KCONFIGCORE_EXPORT KConfigSkeletonItem
42 {
43  Q_DECLARE_PRIVATE(KConfigSkeletonItem)
44 public:
48 
49  /**
50  * Constructor.
51  *
52  * @param _group Config file group.
53  * @param _key Config file key.
54  */
55  KConfigSkeletonItem(const QString &_group, const QString &_key);
56 
57  /**
58  * Destructor.
59  */
60  virtual ~KConfigSkeletonItem();
61 
62  /**
63  * Set config file group.
64  */
65  void setGroup(const QString &_group);
66 
67  /**
68  * Return name of config file group.
69  */
70  QString group() const;
71 
72  /**
73  * Set config file group but giving the KConfigGroup.
74  * Allow the item to be in nested groups.
75  * @since 5.68
76  */
77  void setGroup(const KConfigGroup &cg);
78 
79  /**
80  * Return a KConfigGroup, the one provided by setGroup(const KConfigGroup&) if it's valid,
81  * or make one from @p config and item's group.
82  * @see setGroup(const QString &_group)
83  * @see setGroup(KConfigGroup cg)
84  * @since 5.68
85  */
86  KConfigGroup configGroup(KConfig *config) const;
87 
88  /**
89  * Set config file key.
90  */
91  void setKey(const QString &_key);
92 
93  /**
94  * Return config file key.
95  */
96  QString key() const;
97 
98  /**
99  * Set internal name of entry.
100  */
101  void setName(const QString &_name);
102 
103  /**
104  * Return internal name of entry.
105  */
106  QString name() const;
107 
108  /**
109  * Set label providing a translated one-line description of the item.
110  */
111  void setLabel(const QString &l);
112 
113  /**
114  * Return the label of the item.
115  * @see setLabel()
116  */
117  QString label() const;
118 
119  /**
120  * Set ToolTip description of item.
121  * @since 4.2
122  */
123  void setToolTip(const QString &t);
124 
125  /**
126  * Return ToolTip description of item.
127  * @see setToolTip()
128  * @since 4.2
129  */
130  QString toolTip() const;
131 
132  /**
133  * Set WhatsThis description of item.
134  */
135  void setWhatsThis(const QString &w);
136 
137  /**
138  * Return WhatsThis description of item.
139  * @see setWhatsThis()
140  */
141  QString whatsThis() const;
142 
143  /**
144  * The write flags to be used when writing configuration.
145  * @since 5.58
146  */
147  void setWriteFlags(KConfigBase::WriteConfigFlags flags);
148 
149  /**
150  * Return write flags to be used when writing configuration.
151  * They should be passed to every call of KConfigGroup::writeEntry() and KConfigGroup::revertToDefault().
152  * @since 5.58
153  */
154  KConfigBase::WriteConfigFlags writeFlags() const;
155 
156  /**
157  * This function is called by @ref KCoreConfigSkeleton to read the value for this setting
158  * from a config file.
159  */
160  virtual void readConfig(KConfig *) = 0;
161 
162  /**
163  * This function is called by @ref KCoreConfigSkeleton to write the value of this setting
164  * to a config file.
165  * Make sure to pass writeFlags() to every call of KConfigGroup::writeEntry() and KConfigGroup::revertToDefault().
166  */
167  virtual void writeConfig(KConfig *) = 0;
168 
169  /**
170  * Read global default value.
171  */
172  virtual void readDefault(KConfig *) = 0;
173 
174  /**
175  * Set item to @p p
176  */
177  virtual void setProperty(const QVariant &p) = 0;
178 
179  /**
180  * Check whether the item is equal to @p p.
181  *
182  * Use this function to compare items that use custom types,
183  * because QVariant::operator== will not work for those.
184  *
185  * @param p QVariant to compare to
186  * @return @c true if the item is equal to @p p, @c false otherwise
187  */
188  virtual bool isEqual(const QVariant &p) const = 0;
189 
190  /**
191  * Return item as property
192  */
193  virtual QVariant property() const = 0;
194 
195  /**
196  * Return minimum value of item or invalid if not specified
197  */
198  virtual QVariant minValue() const;
199 
200  /**
201  * Return maximum value of item or invalid if not specified
202  */
203  virtual QVariant maxValue() const;
204 
205  /**
206  * Sets the current value to the default value.
207  */
208  virtual void setDefault() = 0;
209 
210  /**
211  * Exchanges the current value with the default value
212  * Used by KCoreConfigSkeleton::useDefaults(bool);
213  */
214  virtual void swapDefault() = 0;
215 
216  /**
217  * Return if the entry can be modified.
218  */
219  bool isImmutable() const;
220 
221  /**
222  * Indicates if the item is set to its default value.
223  *
224  * @since 5.64
225  */
226  bool isDefault() const;
227 
228  /**
229  * Indicates if the item has a different value than the
230  * previously loaded value.
231  *
232  * @since 5.64
233  */
234  bool isSaveNeeded() const;
235 
236  /**
237  * Returns the default value
238  * @since 5.74
239  */
240  QVariant getDefault() const;
241 
242 protected:
243  explicit KConfigSkeletonItem(KConfigSkeletonItemPrivate &dd, const QString &_group, const QString &_key);
244 
245  /**
246  * Sets mIsImmutable to @c true if mKey in config is immutable.
247  * @param group KConfigGroup to check if mKey is immutable in
248  */
249  void readImmutability(const KConfigGroup &group);
250 
251  QString mGroup; ///< The group name for this item
252  QString mKey; ///< The config key for this item
253  QString mName; ///< The name of this item
254 
255  // HACK: Necessary to avoid introducing new virtuals in KConfigSkeletonItem
256  // KF6: Use proper pure virtuals in KConfigSkeletonItem
257  void setIsDefaultImpl(const std::function<bool()> &impl);
258  void setIsSaveNeededImpl(const std::function<bool()> &impl);
259  void setGetDefaultImpl(const std::function<QVariant()> &impl);
260 
261  KConfigSkeletonItemPrivate *const d_ptr;
262 };
263 
264 class KPropertySkeletonItemPrivate;
265 
266 /**
267  * \class KPropertySkeletonItem kcoreconfigskeleton.h <KCoreConfigSkeleton>
268  *
269  * @short Class for proxying a QObject property as a preferences setting
270  * @author Kevin Ottens
271  * @see KConfigSkeletonItem
272  *
273  * This class represents one preferences setting as used by @ref KCoreConfigSkeleton.
274  * Unlike other @ref KConfigSkeletonItem subclasses, this one won't store the preference
275  * in KConfig but will use a QObject property as storage.
276  * You will have to register instances of this class with the function KCoreConfigSkeleton::addItem().
277  *
278  * @since 5.65
279  */
280 class KCONFIGCORE_EXPORT KPropertySkeletonItem : public KConfigSkeletonItem
281 {
282  Q_DECLARE_PRIVATE(KPropertySkeletonItem)
283 public:
284  /**
285  * Constructor
286  *
287  * @param object The QObject instance which we'll manage the property of
288  * @param propertyName The name of the property in @p object which we'll manage
289  * @param defaultValue The default value of the property
290  */
291  KPropertySkeletonItem(QObject *object, const QByteArray &propertyName, const QVariant &defaultValue);
292 
293  /** @copydoc KConfigSkeletonItem::property() */
294  QVariant property() const override;
295  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant &) */
296  void setProperty(const QVariant &p) override;
297  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) */
298  bool isEqual(const QVariant &p) const override;
299 
300  /** @copydoc KConfigSkeletonItem::readConfig(KConfig *) */
301  void readConfig(KConfig *) override;
302  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig *) */
303  void writeConfig(KConfig *) override;
304 
305  /** @copydoc KConfigSkeletonItem::readDefault(KConfig *) */
306  void readDefault(KConfig *) override;
307  /** @copydoc KConfigSkeletonItem::setDefault() */
308  void setDefault() override;
309  /** @copydoc KConfigSkeletonItem::swapDefault() */
310  void swapDefault() override;
311 
312  /**
313  * Set a notify function, it will be invoked when the value of the property changes.
314  * @since 5.68
315  */
316  void setNotifyFunction(const std::function<void()> &impl);
317 };
318 
319 /**
320  * \class KConfigSkeletonGenericItem kcoreconfigskeleton.h <KCoreConfigSkeleton>
321  *
322  * @short Base class for storing a preferences setting of type @p T.
323  */
324 template<typename T>
326 {
327 public:
328  /**
329  * @copydoc KConfigSkeletonItem(const QString&, const QString&)
330  * @param reference The initial value to hold in the item
331  * @param defaultValue The default value for the item
332  */
333  KConfigSkeletonGenericItem(const QString &_group, const QString &_key, T &reference, T defaultValue)
334  : KConfigSkeletonItem(_group, _key)
335  , mReference(reference)
336  , mDefault(defaultValue)
337  , mLoadedValue(defaultValue)
338  {
339  setIsDefaultImpl([this] {
340  return mReference == mDefault;
341  });
342  setIsSaveNeededImpl([this] {
343  return mReference != mLoadedValue;
344  });
345  setGetDefaultImpl([this] {
347  });
348  }
349 
350  /**
351  * Set value of this KConfigSkeletonItem.
352  */
353  void setValue(const T &v)
354  {
355  mReference = v;
356  }
357 
358  /**
359  * Return value of this KConfigSkeletonItem.
360  */
361  T &value()
362  {
363  return mReference;
364  }
365 
366  /**
367  * Return const value of this KConfigSkeletonItem.
368  */
369  const T &value() const
370  {
371  return mReference;
372  }
373 
374  /**
375  * Set default value for this item.
376  */
377  virtual void setDefaultValue(const T &v)
378  {
379  mDefault = v;
380  }
381 
382  /**
383  * Set the value for this item to the default value
384  */
385  void setDefault() override
386  {
388  }
389 
390  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig *) */
391  void writeConfig(KConfig *config) override
392  {
393  if (mReference != mLoadedValue) { // Is this needed?
394  KConfigGroup cg = configGroup(config);
395  if ((mDefault == mReference) && !cg.hasDefault(mKey)) {
397  } else {
399  }
400  mLoadedValue = mReference;
401  }
402  }
403 
404  /** @copydoc KConfigSkeletonItem::readDefault(KConfig*) */
405  void readDefault(KConfig *config) override
406  {
407  config->setReadDefaults(true);
408  readConfig(config);
409  config->setReadDefaults(false);
411  }
412 
413  /** @copydoc KConfigSkeletonItem::swapDefault() */
414  void swapDefault() override
415  {
416  T tmp = mReference;
418  mDefault = tmp;
419  }
420 
421 protected:
422  T &mReference; ///< Stores the value for this item
423  T mDefault; ///< The default value for this item
424  T mLoadedValue;
425 };
426 
427 /**
428  * \class KConfigCompilerSignallingItem kcoreconfigskeleton.h <KCoreConfigSkeleton>
429  *
430  * @author Alex Richardson
431  *
432  * This class wraps a @ref KConfigSkeletonItem and invokes a function whenever the value changes.
433  * That function must take one quint64 parameter. Whenever the property value of the wrapped KConfigSkeletonItem
434  * changes this function will be invoked with the stored user data passed in the constructor.
435  * It does not call a function with the new value since this class is designed solely for the \ref kconfig_compiler generated
436  * code and is therefore probably not suited for any other usecases.
437  *
438  * @see KConfigSkeletonItem
439  */
440 class KCONFIGCORE_EXPORT KConfigCompilerSignallingItem : public KConfigSkeletonItem
441 {
442 public:
443  typedef void (QObject::*NotifyFunction)(quint64 arg);
444  /**
445  * Constructor.
446  *
447  * @param item the KConfigSkeletonItem to wrap
448  * @param targetFunction the method to invoke whenever the value of @p item changes
449  * @param object The object on which the method is invoked.
450  * @param userData This data will be passed to @p targetFunction on every property change
451  */
452  KConfigCompilerSignallingItem(KConfigSkeletonItem *item, QObject *object, NotifyFunction targetFunction, quint64 userData);
453  ~KConfigCompilerSignallingItem() override;
454 
455  void readConfig(KConfig *) override;
456  void writeConfig(KConfig *) override;
457  void readDefault(KConfig *) override;
458  void setProperty(const QVariant &p) override;
459  bool isEqual(const QVariant &p) const override;
460  QVariant property() const override;
461  void setDefault() override;
462  void swapDefault() override;
463  // KF6 TODO - fix this
464  // Ideally we would do this in an overload of KConfigSkeletonItem, but
465  // given we can't, I've shadowed the method. This isn't pretty, but given
466  // the docs say it should generally only be used from auto generated code,
467  // should be fine.
470  void setGroup(const KConfigGroup &cg);
471  KConfigGroup configGroup(KConfig *config) const;
472  // END TODO
473 
474 private:
475  inline void invokeNotifyFunction()
476  {
477  // call the pointer to member function using the strange ->* operator
478  (mObject->*mTargetFunction)(mUserData);
479  }
480 
481 private:
483  NotifyFunction mTargetFunction;
484  QObject *mObject;
485  quint64 mUserData;
486 };
487 
488 /**
489  * \class KCoreConfigSkeleton kcoreconfigskeleton.h <KCoreConfigSkeleton>
490  *
491  * @short Class for handling preferences settings for an application.
492  * @author Cornelius Schumacher
493  *
494  * This class provides an interface to preferences settings. Preferences items
495  * can be registered by the addItem() function corresponding to the data type of
496  * the setting. KCoreConfigSkeleton then handles reading and writing of config files and
497  * setting of default values.
498  *
499  * Normally you will subclass KCoreConfigSkeleton, add data members for the preferences
500  * settings and register the members in the constructor of the subclass.
501  *
502  * Example:
503  * \code
504  * class MyPrefs : public KCoreConfigSkeleton
505  * {
506  * public:
507  * MyPrefs()
508  * {
509  * setCurrentGroup("MyGroup");
510  * addItemBool("MySetting1", mMyBool, false);
511  * addItemPoint("MySetting2", mMyPoint, QPoint(100, 200));
512  *
513  * setCurrentGroup("MyOtherGroup");
514  * addItemDouble("MySetting3", mMyDouble, 3.14);
515  * }
516  *
517  * bool mMyBool;
518  * QPoint mMyPoint;
519  * double mMyDouble;
520  * }
521  * \endcode
522  *
523  * It might be convenient in many cases to make this subclass of KCoreConfigSkeleton a
524  * singleton for global access from all over the application without passing
525  * references to the KCoreConfigSkeleton object around.
526  *
527  * You can write the data to the configuration file by calling @ref save()
528  * and read the data from the configuration file by calling @ref readConfig().
529  * If you want to watch for config changes, use @ref configChanged() signal.
530  *
531  * If you have items, which are not covered by the existing addItem() functions
532  * you can add customized code for reading, writing and default setting by
533  * implementing the functions @ref usrUseDefaults(), @ref usrRead() and
534  * @ref usrSave().
535  *
536  * Internally preferences settings are stored in instances of subclasses of
537  * @ref KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses
538  * for your own types and call the generic @ref addItem() to register them.
539  *
540  * In many cases you don't have to write the specific KCoreConfigSkeleton
541  * subclasses yourself, but you can use \ref kconfig_compiler to automatically
542  * generate the C++ code from an XML description of the configuration options.
543  *
544  * Use KConfigSkeleton if you need GUI types as well.
545  *
546  * @see KConfigSkeletonItem
547  */
548 class KCONFIGCORE_EXPORT KCoreConfigSkeleton : public QObject
549 {
550  Q_OBJECT
551 public:
552  /**
553  * Class for handling a string preferences item.
554  */
555  class KCONFIGCORE_EXPORT ItemString : public KConfigSkeletonGenericItem<QString>
556  {
557  public:
558  /** The type of string that is held in this item */
559  enum Type {
560  Normal, ///< A normal string
561  Password, ///< A password string
562  Path, ///< A path to a file or directory
563  };
564 
565  /**
566  * @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem
567  * @param type The type of string held by the item
568  */
569  ItemString(const QString &_group,
570  const QString &_key,
571  QString &reference,
572  const QString &defaultValue = QLatin1String(""), // NOT QString() !!
573  Type type = Normal);
574 
575  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
576  void writeConfig(KConfig *config) override;
577 
578  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
579  void readConfig(KConfig *config) override;
580 
581  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
582  void setProperty(const QVariant &p) override;
583 
584  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
585  bool isEqual(const QVariant &p) const override;
586 
587  /** @copydoc KConfigSkeletonItem::property() const */
588  QVariant property() const override;
589 
590  private:
591  Type mType;
592  };
593 
594  /**
595  * Class for handling a password preferences item.
596  */
597  class KCONFIGCORE_EXPORT ItemPassword : public ItemString
598  {
599  public:
600  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
601  ItemPassword(const QString &_group, const QString &_key, QString &reference,
602  const QString &defaultValue = QLatin1String("")); // NOT QString() !!
603  };
604 
605  /**
606  * Class for handling a path preferences item.
607  */
608  class KCONFIGCORE_EXPORT ItemPath : public ItemString
609  {
610  public:
611  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
612  ItemPath(const QString &_group, const QString &_key, QString &reference, const QString &defaultValue = QString());
613  };
614 
615  /**
616  * Class for handling a url preferences item.
617  */
618  class KCONFIGCORE_EXPORT ItemUrl : public KConfigSkeletonGenericItem<QUrl>
619  {
620  public:
621  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
622  ItemUrl(const QString &_group, const QString &_key, QUrl &reference, const QUrl &defaultValue = QUrl());
623 
624  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
625  void writeConfig(KConfig *config) override;
626 
627  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
628  void readConfig(KConfig *config) override;
629 
630  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
631  void setProperty(const QVariant &p) override;
632 
633  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
634  bool isEqual(const QVariant &p) const override;
635 
636  /** @copydoc KConfigSkeletonItem::property() const */
637  QVariant property() const override;
638  };
639 
640  /**
641  * Class for handling a QVariant preferences item.
642  */
643  class KCONFIGCORE_EXPORT ItemProperty : public KConfigSkeletonGenericItem<QVariant>
644  {
645  public:
646  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
647  ItemProperty(const QString &_group, const QString &_key, QVariant &reference, const QVariant &defaultValue = QVariant());
648 
649  void readConfig(KConfig *config) override;
650  void setProperty(const QVariant &p) override;
651 
652  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
653  bool isEqual(const QVariant &p) const override;
654 
655  /** @copydoc KConfigSkeletonItem::property() const */
656  QVariant property() const override;
657  };
658 
659  /**
660  * Class for handling a bool preferences item.
661  */
662  class KCONFIGCORE_EXPORT ItemBool : public KConfigSkeletonGenericItem<bool>
663  {
664  public:
665  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
666  ItemBool(const QString &_group, const QString &_key, bool &reference, bool defaultValue = true);
667 
668  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
669  void readConfig(KConfig *config) override;
670 
671  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
672  void setProperty(const QVariant &p) override;
673 
674  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
675  bool isEqual(const QVariant &p) const override;
676 
677  /** @copydoc KConfigSkeletonItem::property() const */
678  QVariant property() const override;
679  };
680 
681  /**
682  * Class for handling a 32-bit integer preferences item.
683  */
684  class KCONFIGCORE_EXPORT ItemInt : public KConfigSkeletonGenericItem<qint32>
685  {
686  public:
687  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
688  ItemInt(const QString &_group, const QString &_key, qint32 &reference, qint32 defaultValue = 0);
689 
690  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
691  void readConfig(KConfig *config) override;
692 
693  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
694  void setProperty(const QVariant &p) override;
695 
696  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
697  bool isEqual(const QVariant &p) const override;
698 
699  /** @copydoc KConfigSkeletonItem::property() */
700  QVariant property() const override;
701 
702  /** Get the minimum value that is allowed to be stored in this item */
703  QVariant minValue() const override;
704 
705  /** Get the maximum value this is allowed to be stored in this item */
706  QVariant maxValue() const override;
707 
708  /**
709  * Set the minimum value for the item.
710  * @see minValue()
711  */
712  void setMinValue(qint32);
713 
714  /**
715  * Set the maximum value for the item.
716  * @see maxValue
717  */
718  void setMaxValue(qint32);
719 
720  private:
721  bool mHasMin : 1;
722  bool mHasMax : 1;
723  qint32 mMin;
724  qint32 mMax;
725  };
726 
727  /**
728  * Class for handling a 64-bit integer preferences item.
729  */
730  class KCONFIGCORE_EXPORT ItemLongLong : public KConfigSkeletonGenericItem<qint64>
731  {
732  public:
733  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
734  ItemLongLong(const QString &_group, const QString &_key, qint64 &reference, qint64 defaultValue = 0);
735 
736  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
737  void readConfig(KConfig *config) override;
738 
739  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
740  void setProperty(const QVariant &p) override;
741 
742  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
743  bool isEqual(const QVariant &p) const override;
744 
745  /** @copydoc KConfigSkeletonItem::property() */
746  QVariant property() const override;
747 
748  /** @copydoc ItemInt::minValue() */
749  QVariant minValue() const override;
750 
751  /** @copydoc ItemInt::maxValue() */
752  QVariant maxValue() const override;
753 
754  /** @copydoc ItemInt::setMinValue(qint32) */
755  void setMinValue(qint64);
756 
757  /** @copydoc ItemInt::setMaxValue(qint32) */
758  void setMaxValue(qint64);
759 
760  private:
761  bool mHasMin : 1;
762  bool mHasMax : 1;
763  qint64 mMin;
764  qint64 mMax;
765  };
766 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
767  typedef KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use ItemLongLong") ItemLongLong ItemInt64;
768 #endif
769 
770  /**
771  * Class for handling enums.
772  */
773  class KCONFIGCORE_EXPORT ItemEnum : public ItemInt
774  {
775  public:
776  struct Choice {
777  QString name;
778  QString label;
779  QString toolTip;
780  QString whatsThis;
781  };
782 
783  /**
784  * @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem
785  * @param choices The list of enums that can be stored in this item
786  */
787  ItemEnum(const QString &_group, const QString &_key, qint32 &reference, const QList<Choice> &choices, qint32 defaultValue = 0);
788 
789  QList<Choice> choices() const;
790 
791  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
792  void readConfig(KConfig *config) override;
793 
794  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
795  void writeConfig(KConfig *config) override;
796 
797  // Source compatibility with 4.x
798  // TODO KF6 remove
799  typedef Choice Choice2;
800  QList<Choice> choices2() const;
801 
802  /**
803  * Returns the value for for the choice with the given @p name
804  */
805  QString valueForChoice(const QString &name) const;
806 
807  /**
808  * Stores a choice value for @p name
809  */
810  void setValueForChoice(const QString &name, const QString &valueForChoice);
811 
812  private:
813  QList<Choice> mChoices;
814  };
815 
816  /**
817  * Class for handling an unsigned 32-bit integer preferences item.
818  */
819  class KCONFIGCORE_EXPORT ItemUInt : public KConfigSkeletonGenericItem<quint32>
820  {
821  public:
822  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
823  ItemUInt(const QString &_group, const QString &_key, quint32 &reference, quint32 defaultValue = 0);
824 
825  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
826  void readConfig(KConfig *config) override;
827 
828  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
829  void setProperty(const QVariant &p) override;
830 
831  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
832  bool isEqual(const QVariant &p) const override;
833 
834  /** @copydoc KConfigSkeletonItem::property() */
835  QVariant property() const override;
836 
837  /** @copydoc ItemInt::minValue() */
838  QVariant minValue() const override;
839 
840  /** @copydoc ItemInt::maxValue() */
841  QVariant maxValue() const override;
842 
843  /** @copydoc ItemInt::setMinValue(qint32) */
844  void setMinValue(quint32);
845 
846  /** @copydoc ItemInt::setMaxValue(qint32) */
847  void setMaxValue(quint32);
848 
849  private:
850  bool mHasMin : 1;
851  bool mHasMax : 1;
852  quint32 mMin;
853  quint32 mMax;
854  };
855 
856  /**
857  * Class for handling unsigned 64-bit integer preferences item.
858  */
859  class KCONFIGCORE_EXPORT ItemULongLong : public KConfigSkeletonGenericItem<quint64>
860  {
861  public:
862  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
863  ItemULongLong(const QString &_group, const QString &_key, quint64 &reference, quint64 defaultValue = 0);
864 
865  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
866  void readConfig(KConfig *config) override;
867 
868  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
869  void setProperty(const QVariant &p) override;
870 
871  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
872  bool isEqual(const QVariant &p) const override;
873 
874  /** @copydoc KConfigSkeletonItem::property() */
875  QVariant property() const override;
876 
877  /** @copydoc ItemInt::minValue() */
878  QVariant minValue() const override;
879 
880  /** @copydoc ItemInt::maxValue() */
881  QVariant maxValue() const override;
882 
883  /** @copydoc ItemInt::setMinValue(qint32) */
884  void setMinValue(quint64);
885 
886  /** @copydoc ItemInt::setMaxValue(qint32) */
887  void setMaxValue(quint64);
888 
889  private:
890  bool mHasMin : 1;
891  bool mHasMax : 1;
892  quint64 mMin;
893  quint64 mMax;
894  };
895 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
896  typedef KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use ItemULongLong") ItemULongLong ItemUInt64;
897 #endif
898 
899  /**
900  * Class for handling a floating point preference item.
901  */
902  class KCONFIGCORE_EXPORT ItemDouble : public KConfigSkeletonGenericItem<double>
903  {
904  public:
905  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
906  ItemDouble(const QString &_group, const QString &_key, double &reference, double defaultValue = 0);
907 
908  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
909  void readConfig(KConfig *config) override;
910 
911  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
912  void setProperty(const QVariant &p) override;
913 
914  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
915  bool isEqual(const QVariant &p) const override;
916 
917  /** @copydoc KConfigSkeletonItem::property() */
918  QVariant property() const override;
919 
920  /** @copydoc ItemInt::minValue() */
921  QVariant minValue() const override;
922 
923  /** @copydoc ItemInt::maxValue() */
924  QVariant maxValue() const override;
925 
926  /** @copydoc ItemInt::setMinValue() */
927  void setMinValue(double);
928 
929  /** @copydoc ItemInt::setMaxValue() */
930  void setMaxValue(double);
931 
932  private:
933  bool mHasMin : 1;
934  bool mHasMax : 1;
935  double mMin;
936  double mMax;
937  };
938 
939  /**
940  * Class for handling a QRect preferences item.
941  */
942  class KCONFIGCORE_EXPORT ItemRect : public KConfigSkeletonGenericItem<QRect>
943  {
944  public:
945  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
946  ItemRect(const QString &_group, const QString &_key, QRect &reference, const QRect &defaultValue = QRect());
947 
948  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
949  void readConfig(KConfig *config) override;
950 
951  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
952  void setProperty(const QVariant &p) override;
953 
954  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
955  bool isEqual(const QVariant &p) const override;
956 
957  /** @copydoc KConfigSkeletonItem::property() */
958  QVariant property() const override;
959  };
960 
961  /**
962  * Class for handling a QPoint preferences item.
963  */
964  class KCONFIGCORE_EXPORT ItemPoint : public KConfigSkeletonGenericItem<QPoint>
965  {
966  public:
967  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
968  ItemPoint(const QString &_group, const QString &_key, QPoint &reference, const QPoint &defaultValue = QPoint());
969 
970  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
971  void readConfig(KConfig *config) override;
972 
973  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
974  void setProperty(const QVariant &p) override;
975 
976  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
977  bool isEqual(const QVariant &p) const override;
978 
979  /** @copydoc KConfigSkeletonItem::property() */
980  QVariant property() const override;
981  };
982 
983  /**
984  * Class for handling a QSize preferences item.
985  */
986  class KCONFIGCORE_EXPORT ItemSize : public KConfigSkeletonGenericItem<QSize>
987  {
988  public:
989  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
990  ItemSize(const QString &_group, const QString &_key, QSize &reference, const QSize &defaultValue = QSize());
991 
992  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
993  void readConfig(KConfig *config) override;
994 
995  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
996  void setProperty(const QVariant &p) override;
997 
998  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
999  bool isEqual(const QVariant &p) const override;
1000 
1001  /** @copydoc KConfigSkeletonItem::property() */
1002  QVariant property() const override;
1003  };
1004 
1005  /**
1006  * Class for handling a QDateTime preferences item.
1007  */
1008  class KCONFIGCORE_EXPORT ItemDateTime : public KConfigSkeletonGenericItem<QDateTime>
1009  {
1010  public:
1011  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1012  ItemDateTime(const QString &_group, const QString &_key, QDateTime &reference, const QDateTime &defaultValue = QDateTime());
1013 
1014  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1015  void readConfig(KConfig *config) override;
1016 
1017  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1018  void setProperty(const QVariant &p) override;
1019 
1020  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1021  bool isEqual(const QVariant &p) const override;
1022 
1023  /** @copydoc KConfigSkeletonItem::property() */
1024  QVariant property() const override;
1025  };
1026 
1027  /**
1028  * Class for handling a string list preferences item.
1029  */
1030  class KCONFIGCORE_EXPORT ItemStringList : public KConfigSkeletonGenericItem<QStringList>
1031  {
1032  public:
1033  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1034  ItemStringList(const QString &_group, const QString &_key, QStringList &reference, const QStringList &defaultValue = QStringList());
1035 
1036  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1037  void readConfig(KConfig *config) override;
1038 
1039  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1040  void setProperty(const QVariant &p) override;
1041 
1042  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1043  bool isEqual(const QVariant &p) const override;
1044 
1045  /** @copydoc KConfigSkeletonItem::property() */
1046  QVariant property() const override;
1047  };
1048 
1049  /**
1050  * Class for handling a path list preferences item.
1051  */
1052  class KCONFIGCORE_EXPORT ItemPathList : public ItemStringList
1053  {
1054  public:
1055  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1056  ItemPathList(const QString &_group, const QString &_key, QStringList &reference, const QStringList &defaultValue = QStringList());
1057 
1058  /** @copydoc KConfigSkeletonItem::readConfig */
1059  void readConfig(KConfig *config) override;
1060  /** @copydoc KConfigSkeletonItem::writeConfig */
1061  void writeConfig(KConfig *config) override;
1062  };
1063 
1064  /**
1065  * Class for handling a url list preferences item.
1066  */
1067  class KCONFIGCORE_EXPORT ItemUrlList : public KConfigSkeletonGenericItem<QList<QUrl>>
1068  {
1069  public:
1070  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1071  ItemUrlList(const QString &_group, const QString &_key, QList<QUrl> &reference, const QList<QUrl> &defaultValue = QList<QUrl>());
1072 
1073  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1074  void readConfig(KConfig *config) override;
1075 
1076  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
1077  void writeConfig(KConfig *config) override;
1078 
1079  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1080  void setProperty(const QVariant &p) override;
1081 
1082  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1083  bool isEqual(const QVariant &p) const override;
1084 
1085  /** @copydoc KConfigSkeletonItem::property() */
1086  QVariant property() const override;
1087  };
1088 
1089  /**
1090  * Class for handling an integer list preferences item.
1091  */
1092  class KCONFIGCORE_EXPORT ItemIntList : public KConfigSkeletonGenericItem<QList<int>>
1093  {
1094  public:
1095  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1096  ItemIntList(const QString &_group, const QString &_key, QList<int> &reference, const QList<int> &defaultValue = QList<int>());
1097 
1098  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1099  void readConfig(KConfig *config) override;
1100 
1101  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1102  void setProperty(const QVariant &p) override;
1103 
1104  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1105  bool isEqual(const QVariant &p) const override;
1106 
1107  /** @copydoc KConfigSkeletonItem::property() */
1108  QVariant property() const override;
1109  };
1110 
1111 public:
1112  /**
1113  * Constructor.
1114  *
1115  * @param configname name of config file. If no name is given, the default
1116  * config file as returned by KSharedConfig::openConfig() is used
1117  * @param parent the parent object (see QObject documentation)
1118  */
1119  explicit KCoreConfigSkeleton(const QString &configname = QString(), QObject *parent = nullptr);
1120 
1121  /**
1122  * Constructor.
1123  *
1124  * @param config configuration object to use
1125  * @param parent the parent object (see QObject documentation)
1126  */
1127  explicit KCoreConfigSkeleton(KSharedConfig::Ptr config, QObject *parent = nullptr);
1128 
1129  /**
1130  * Destructor
1131  */
1132  ~KCoreConfigSkeleton() override;
1133 
1134  /**
1135  * Set all registered items to their default values.
1136  * This method calls usrSetDefaults() after setting the defaults for the
1137  * registered items. You can override usrSetDefaults() in derived classes
1138  * if you have special requirements.
1139  * If you need more fine-grained control of setting the default values of
1140  * the registered items you can override setDefaults() in a derived class.
1141  */
1142  virtual void setDefaults();
1143 
1144  /**
1145  * Read preferences from config file. All registered items are set to the
1146  * values read from disk.
1147  * This method calls usrRead() after reading the settings of the
1148  * registered items from the KConfig. You can override usrRead()
1149  * in derived classes if you have special requirements.
1150  */
1151  void load();
1152 
1153 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1154  /**
1155  * @deprecated since 5.0, call load() instead (to reload from disk) or just read()
1156  * if the underlying KConfig object is already up-to-date.
1157  */
1158  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::load() or KCoreConfigSkeleton::read()")
1159  void readConfig()
1160  {
1161  load();
1162  }
1163 #endif
1164 
1165  /**
1166  * Read preferences from the KConfig object.
1167  * This method assumes that the KConfig object was previously loaded,
1168  * i.e. it uses the in-memory values from KConfig without reloading from disk.
1169  *
1170  * This method calls usrRead() after reading the settings of the
1171  * registered items from the KConfig. You can override usrRead()
1172  * in derived classes if you have special requirements.
1173  * @since 5.0
1174  */
1175  void read();
1176 
1177  /**
1178  * Indicates if all the registered items are set to their default value.
1179  *
1180  * @since 5.64
1181  */
1182  bool isDefaults() const;
1183 
1184  /**
1185  * Indicates if any registered item has a different value than the
1186  * previously loaded value.
1187  *
1188  * @since 5.64
1189  */
1190  bool isSaveNeeded() const;
1191 
1192  /**
1193  * Set the config file group for subsequent addItem() calls. It is valid
1194  * until setCurrentGroup() is called with a new argument. Call this before
1195  * you add any items. The default value is "No Group".
1196  */
1197  void setCurrentGroup(const QString &group);
1198 
1199  /**
1200  * Returns the current group used for addItem() calls.
1201  */
1202  QString currentGroup() const;
1203 
1204  /**
1205  * Register a custom @ref KConfigSkeletonItem @p item with a given @p name.
1206  *
1207  * If @p name is a null string, take the name from KConfigSkeletonItem::key().
1208  *
1209  * @note All names must be unique but multiple entries can have
1210  * the same key if they reside in different groups.
1211  *
1212  * KCoreConfigSkeleton takes ownership of @p item.
1213  */
1214  void addItem(KConfigSkeletonItem *item, const QString &name = QString());
1215 
1216  /**
1217  * Register an item of type QString.
1218  *
1219  * @param name Name used to identify this setting. Names must be unique.
1220  * @param reference Pointer to the variable, which is set by readConfig()
1221  * calls and read by save() calls.
1222  * @param defaultValue Default value, which is used when the config file
1223  * does not yet contain the key of this item.
1224  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1225  * @return The created item
1226  */
1227  ItemString *addItemString(const QString &name,
1228  QString &reference,
1229  const QString &defaultValue = QLatin1String(""), // NOT QString() !!
1230  const QString &key = QString());
1231 
1232  /**
1233  * Register a password item of type QString. The string value is written
1234  * encrypted to the config file.
1235  *
1236  * @note The current encryption scheme is very weak.
1237  *
1238  * @param name Name used to identify this setting. Names must be unique.
1239  * @param reference Pointer to the variable, which is set by readConfig()
1240  * calls and read by save() calls.
1241  * @param defaultValue Default value, which is used when the config file
1242  * does not yet contain the key of this item.
1243  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1244  * @return The created item
1245  */
1246  ItemPassword *addItemPassword(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1247 
1248  /**
1249  * Register a path item of type QString. The string value is interpreted
1250  * as a path. This means, dollar expansion is activated for this value, so
1251  * that e.g. @c $HOME gets expanded.
1252  *
1253  * @param name Name used to identify this setting. Names must be unique.
1254  * @param reference Pointer to the variable, which is set by readConfig()
1255  * calls and read by save() calls.
1256  * @param defaultValue Default value, which is used when the config file
1257  * does not yet contain the key of this item.
1258  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1259  * @return The created item
1260  */
1261  ItemPath *addItemPath(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1262 
1263  /**
1264  * Register a property item of type QVariant.
1265  *
1266  * @note The following QVariant types are allowed:
1267  * String, StringList, Font, Point, Rect, Size,
1268  * Color, Int, UInt, Bool, Double, DateTime and Date.
1269  *
1270  * @param name Name used to identify this setting. Names must be unique.
1271  * @param reference Pointer to the variable, which is set by readConfig()
1272  * calls and read by save() calls.
1273  * @param defaultValue Default value, which is used when the config file
1274  * does not yet contain the key of this item.
1275  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1276  * @return The created item
1277  */
1278  ItemProperty *addItemProperty(const QString &name, QVariant &reference, const QVariant &defaultValue = QVariant(), const QString &key = QString());
1279  /**
1280  * Register an item of type @c bool.
1281  *
1282  * @param name Name used to identify this setting. Names must be unique.
1283  * @param reference Pointer to the variable, which is set by readConfig()
1284  * calls and read by save() calls.
1285  * @param defaultValue Default value, which is used when the config file
1286  * does not yet contain the key of this item.
1287  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1288  * @return The created item
1289  */
1290  ItemBool *addItemBool(const QString &name, bool &reference, bool defaultValue = false, const QString &key = QString());
1291 
1292  /**
1293  * Register an item of type @c qint32.
1294  *
1295  * @param name Name used to identify this setting. Names must be unique.
1296  * @param reference Pointer to the variable, which is set by readConfig()
1297  * calls and read by save() calls.
1298  * @param defaultValue Default value, which is used when the config file
1299  * does not yet contain the key of this item.
1300  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1301  * @return The created item
1302  */
1303  ItemInt *addItemInt(const QString &name, qint32 &reference, qint32 defaultValue = 0, const QString &key = QString());
1304 
1305  /**
1306  * Register an item of type @c quint32.
1307  *
1308  * @param name Name used to identify this setting. Names must be unique.
1309  * @param reference Pointer to the variable, which is set by readConfig()
1310  * calls and read by save() calls.
1311  * @param defaultValue Default value, which is used when the config file
1312  * does not yet contain the key of this item.
1313  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1314  * @return The created item
1315  */
1316  ItemUInt *addItemUInt(const QString &name, quint32 &reference, quint32 defaultValue = 0, const QString &key = QString());
1317 
1318  /**
1319  * Register an item of type @c qint64.
1320  *
1321  * @param name Name used to identify this setting. Names must be unique.
1322  * @param reference Pointer to the variable, which is set by readConfig()
1323  * calls and read by save() calls.
1324  * @param defaultValue Default value, which is used when the config file
1325  * does not yet contain the key of this item.
1326  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1327  * @return The created item
1328  */
1329  ItemLongLong *addItemLongLong(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString());
1330 
1331 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1332  /**
1333  * @deprecated Since 5.0, use addItemLongLong().
1334  */
1335  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::addItemLongLong(...)")
1336  ItemLongLong *addItemInt64(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString());
1337 #endif
1338 
1339  /**
1340  * Register an item of type @c quint64.
1341  *
1342  * @param name Name used to identify this setting. Names must be unique.
1343  * @param reference Pointer to the variable, which is set by readConfig()
1344  * calls and read by save() calls.
1345  * @param defaultValue Default value, which is used when the config file
1346  * does not yet contain the key of this item.
1347  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1348  * @return The created item
1349  */
1350  ItemULongLong *addItemULongLong(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString());
1351 
1352 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1353  /**
1354  * @deprecated Since 5.0, use addItemULongLong().
1355  */
1356  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::addItemULongLong(...)")
1357  ItemULongLong *addItemUInt64(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString());
1358 #endif
1359 
1360  /**
1361  * Register an item of type @c double.
1362  *
1363  * @param name Name used to identify this setting. Names must be unique.
1364  * @param reference Pointer to the variable, which is set by readConfig()
1365  * calls and read by save() calls.
1366  * @param defaultValue Default value, which is used when the config file
1367  * does not yet contain the key of this item.
1368  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1369  * @return The created item
1370  */
1371  ItemDouble *addItemDouble(const QString &name, double &reference, double defaultValue = 0.0, const QString &key = QString());
1372 
1373  /**
1374  * Register an item of type QRect.
1375  *
1376  * @param name Name used to identify this setting. Names must be unique.
1377  * @param reference Pointer to the variable, which is set by readConfig()
1378  * calls and read by save() calls.
1379  * @param defaultValue Default value, which is used when the config file
1380  * does not yet contain the key of this item.
1381  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1382  * @return The created item
1383  */
1384  ItemRect *addItemRect(const QString &name, QRect &reference, const QRect &defaultValue = QRect(), const QString &key = QString());
1385 
1386  /**
1387  * Register an item of type QPoint.
1388  *
1389  * @param name Name used to identify this setting. Names must be unique.
1390  * @param reference Pointer to the variable, which is set by readConfig()
1391  * calls and read by save() calls.
1392  * @param defaultValue Default value, which is used when the config file
1393  * does not yet contain the key of this item.
1394  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1395  * @return The created item
1396  */
1397  ItemPoint *addItemPoint(const QString &name, QPoint &reference, const QPoint &defaultValue = QPoint(), const QString &key = QString());
1398 
1399  /**
1400  * Register an item of type QSize.
1401  *
1402  * @param name Name used to identify this setting. Names must be unique.
1403  * @param reference Pointer to the variable, which is set by readConfig()
1404  * calls and read by save() calls.
1405  * @param defaultValue Default value, which is used when the config file
1406  * does not yet contain the key of this item.
1407  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1408  * @return The created item
1409  */
1410  ItemSize *addItemSize(const QString &name, QSize &reference, const QSize &defaultValue = QSize(), const QString &key = QString());
1411 
1412  /**
1413  * Register an item of type QDateTime.
1414  *
1415  * @param name Name used to identify this setting. Names must be unique.
1416  * @param reference Pointer to the variable, which is set by readConfig()
1417  * calls and read by save() calls.
1418  * @param defaultValue Default value, which is used when the config file
1419  * does not yet contain the key of this item.
1420  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1421  * @return The created item
1422  */
1423  ItemDateTime *addItemDateTime(const QString &name, QDateTime &reference, const QDateTime &defaultValue = QDateTime(), const QString &key = QString());
1424 
1425  /**
1426  * Register an item of type QStringList.
1427  *
1428  * @param name Name used to identify this setting. Names must be unique.
1429  * @param reference Pointer to the variable, which is set by readConfig()
1430  * calls and read by save() calls.
1431  * @param defaultValue Default value, which is used when the config file
1432  * does not yet contain the key of this item.
1433  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1434  * @return The created item
1435  */
1436  ItemStringList *
1437  addItemStringList(const QString &name, QStringList &reference, const QStringList &defaultValue = QStringList(), const QString &key = QString());
1438 
1439  /**
1440  * Register an item of type QList<int>.
1441  *
1442  * @param name Name used to identify this setting. Names must be unique.
1443  * @param reference Pointer to the variable, which is set by readConfig()
1444  * calls and read by save() calls.
1445  * @param defaultValue Default value, which is used when the config file
1446  * does not yet contain the key of this item.
1447  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1448  * @return The created item
1449  */
1450  ItemIntList *addItemIntList(const QString &name, QList<int> &reference, const QList<int> &defaultValue = QList<int>(), const QString &key = QString());
1451 
1452  /**
1453  * Return the @ref KConfig object used for reading and writing the settings.
1454  */
1455  KConfig *config();
1456 
1457  /**
1458  * Return the @ref KConfig object used for reading and writing the settings.
1459  */
1460  const KConfig *config() const;
1461 
1462  /**
1463  * Return the @ref KConfig object used for reading and writing the settings.
1464  * @since 5.0
1465  */
1466  KSharedConfig::Ptr sharedConfig() const;
1467 
1468  /**
1469  * Set the @ref KSharedConfig object used for reading and writing the settings.
1470  */
1471  void setSharedConfig(KSharedConfig::Ptr pConfig);
1472 
1473  /**
1474  * Return list of items managed by this KCoreConfigSkeleton object.
1475  */
1476  KConfigSkeletonItem::List items() const;
1477 
1478  /**
1479  * Removes and deletes an item by name
1480  * @param name the name of the item to remove
1481  */
1482  void removeItem(const QString &name);
1483 
1484  /**
1485  * Removes and deletes all items
1486  */
1487  void clearItems();
1488 
1489  /**
1490  * Return whether a certain item is immutable
1491  * @since 4.4
1492  */
1493  Q_INVOKABLE bool isImmutable(const QString &name) const;
1494 
1495  /**
1496  * Lookup item by name
1497  * @since 4.4
1498  */
1499  KConfigSkeletonItem *findItem(const QString &name) const;
1500 
1501  /**
1502  * Specify whether this object should reflect the actual values or the
1503  * default values.
1504  * This method is implemented by usrUseDefaults(), which can be overridden
1505  * in derived classes if you have special requirements and can call
1506  * usrUseDefaults() directly.
1507  * If you don't have control whether useDefaults() or usrUseDefaults() is
1508  * called override useDefaults() directly.
1509  * @param b @c true to make this object reflect the default values,
1510  * @c false to make it reflect the actual values.
1511  * @return The state prior to this call
1512  */
1513  virtual bool useDefaults(bool b);
1514 
1515 public Q_SLOTS:
1516  /**
1517  * Write preferences to config file. The values of all registered items are
1518  * written to disk.
1519  * This method calls usrSave() after writing the settings from the
1520  * registered items to the KConfig. You can override usrSave()
1521  * in derived classes if you have special requirements.
1522  */
1523  bool save();
1524 
1525 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1526  /**
1527  * @deprecated since 5.0, call save() instead.
1528  */
1529  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::save()")
1530  void writeConfig()
1531  {
1532  save();
1533  }
1534 #endif
1535 
1536 Q_SIGNALS:
1537  /**
1538  * This signal is emitted when the configuration change.
1539  */
1540  void configChanged();
1541 
1542 protected:
1543  /**
1544  * Implemented by subclasses that use special defaults.
1545  * It replaces the default values with the actual values and
1546  * vice versa. Called from @ref useDefaults()
1547  * @param b @c true to make this object reflect the default values,
1548  * @c false to make it reflect the actual values.
1549  * @return The state prior to this call
1550  */
1551  virtual bool usrUseDefaults(bool b);
1552 
1553  /**
1554  * Perform the actual setting of default values.
1555  * Override in derived classes to set special default values.
1556  * Called from @ref setDefaults()
1557  */
1558  virtual void usrSetDefaults();
1559 
1560  /**
1561  * Perform the actual reading of the configuration file.
1562  * Override in derived classes to read special config values.
1563  * Called from @ref read()
1564  */
1565  virtual void usrRead();
1566 
1567  /**
1568  * Perform the actual writing of the configuration file.
1569  * Override in derived classes to write special config values.
1570  * Called from @ref save()
1571  */
1572  virtual bool usrSave();
1573 
1574 #if KCONFIGCORE_BUILD_DEPRECATED_SINCE(5, 0)
1575  /**
1576  * @deprecated since 5.0, override usrRead instead. This method is still called from usrRead
1577  * for compatibility.
1578  */
1579  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Override KCoreConfigSkeleton::usrRead()")
1580  virtual void usrReadConfig();
1581 #endif
1582 
1583 #if KCONFIGCORE_BUILD_DEPRECATED_SINCE(5, 0)
1584  /**
1585  * @deprecated since 5.0, override usrSave instead. This method is still called from usrSave
1586  * for compatibility.
1587  */
1588  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Override KCoreConfigSkeleton::usrSave()")
1589  virtual bool usrWriteConfig();
1590 #endif
1591 
1592 private:
1593  KCoreConfigSkeletonPrivate *const d;
1594  friend class KConfigSkeleton;
1595 };
1596 
1597 #endif
Class for handling a url preferences item.
QString mGroup
The group name for this item.
@ Path
A path to a file or directory.
virtual QVariant maxValue() const
Return maximum value of item or invalid if not specified.
Class for handling a url list preferences item.
virtual QVariant property() const =0
Return item as property.
void writeEntry(const QString &key, const QVariant &value, WriteConfigFlags pFlags=Normal)
Writes a value to the configuration object.
void readDefault(KConfig *config) override
Read global default value.
Class for handling preferences settings for an application.
void swapDefault() override
Exchanges the current value with the default value Used by KCoreConfigSkeleton::useDefaults(bool);.
Class for handling a floating point preference item.
QVariant fromValue(const T &value)
Class for handling a string preferences item.
virtual void setProperty(const QVariant &p)=0
Set item to p.
Class for handling preferences settings for an application.
void writeConfig(KConfig *config) override
This function is called by KCoreConfigSkeleton to write the value of this setting to a config file.
The central class of the KDE configuration data system.
Definition: kconfig.h:56
Class for handling a 64-bit integer preferences item.
QCA_EXPORT void setProperty(const QString &name, const QVariant &value)
T & mReference
Stores the value for this item.
void readConfig(KConfig *config) override
This function is called by KCoreConfigSkeleton to read the value for this setting from a config file.
Class for handling a QPoint preferences item.
Class for handling a QVariant preferences item.
bool hasDefault(const QString &key) const
Whether a default is specified for an entry in either the system wide configuration file or the globa...
virtual void writeConfig(KConfig *)=0
This function is called by KCoreConfigSkeleton to write the value of this setting to a config file.
KConfigGroup configGroup(KConfig *config) const
Return a KConfigGroup, the one provided by setGroup(const KConfigGroup&) if it's valid,...
Class for handling a QDateTime preferences item.
void setWriteFlags(KConfigBase::WriteConfigFlags flags)
The write flags to be used when writing configuration.
void readConfig(KConfig *config) override
This function is called by KCoreConfigSkeleton to read the value for this setting from a config file.
Class for handling a password preferences item.
T & value()
Return value of this KConfigSkeletonItem.
QString mKey
The config key for this item.
virtual void setDefault()=0
Sets the current value to the default value.
Class for handling unsigned 64-bit integer preferences item.
Class for handling a QSize preferences item.
void setValue(const T &v)
Set value of this KConfigSkeletonItem.
QString mName
The name of this item.
void setGroup(const QString &_group)
Set config file group.
Class for handling an unsigned 32-bit integer preferences item.
bool isSaveNeeded() const
Indicates if the item has a different value than the previously loaded value.
virtual void readConfig(KConfig *)=0
This function is called by KCoreConfigSkeleton to read the value for this setting from a config file.
virtual QVariant minValue() const
Return minimum value of item or invalid if not specified.
Base class for storing a preferences setting of type T.
Class for handling a string list preferences item.
KConfigBase::WriteConfigFlags writeFlags() const
Return write flags to be used when writing configuration.
virtual void readDefault(KConfig *)=0
Read global default value.
KConfigSkeletonGenericItem(const QString &_group, const QString &_key, T &reference, T defaultValue)
Constructor.
virtual void swapDefault()=0
Exchanges the current value with the default value Used by KCoreConfigSkeleton::useDefaults(bool);.
Class for handling a 32-bit integer preferences item.
Class for handling an integer list preferences item.
Class for storing a preferences setting.
Class for handling a QRect preferences item.
bool isImmutable() const
Return if the entry can be modified.
Type
The type of string that is held in this item.
void revertToDefault(const QString &key)
Reverts an entry to the default settings.
const T & value() const
Return const value of this KConfigSkeletonItem.
Class for handling enums.
Class for proxying a QObject property as a preferences setting.
Class for handling a path preferences item.
virtual bool isEqual(const QVariant &p) const =0
Check whether the item is equal to p.
void setDefault() override
Set the value for this item to the default value.
virtual void setDefaultValue(const T &v)
Set default value for this item.
Class for handling a bool preferences item.
T mDefault
The default value for this item.
Class for handling a path list preferences item.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Fri Jul 1 2022 05:30:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.