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

KDE's Doxygen guidelines are available online.