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  QVariant minValue() const override;
462  QVariant maxValue() const override;
463  void setDefault() override;
464  void swapDefault() override;
465  // KF6 TODO - fix this
466  // Ideally we would do this in an overload of KConfigSkeletonItem, but
467  // given we can't, I've shadowed the method. This isn't pretty, but given
468  // the docs say it should generally only be used from auto generated code,
469  // should be fine.
472  void setGroup(const KConfigGroup &cg);
473  KConfigGroup configGroup(KConfig *config) const;
474  // END TODO
475 
476 private:
477  inline void invokeNotifyFunction()
478  {
479  // call the pointer to member function using the strange ->* operator
480  (mObject->*mTargetFunction)(mUserData);
481  }
482 
483 private:
485  NotifyFunction mTargetFunction;
486  QObject *mObject;
487  quint64 mUserData;
488 };
489 
490 /**
491  * \class KCoreConfigSkeleton kcoreconfigskeleton.h <KCoreConfigSkeleton>
492  *
493  * @short Class for handling preferences settings for an application.
494  * @author Cornelius Schumacher
495  *
496  * This class provides an interface to preferences settings. Preferences items
497  * can be registered by the addItem() function corresponding to the data type of
498  * the setting. KCoreConfigSkeleton then handles reading and writing of config files and
499  * setting of default values.
500  *
501  * Normally you will subclass KCoreConfigSkeleton, add data members for the preferences
502  * settings and register the members in the constructor of the subclass.
503  *
504  * Example:
505  * \code
506  * class MyPrefs : public KCoreConfigSkeleton
507  * {
508  * public:
509  * MyPrefs()
510  * {
511  * setCurrentGroup("MyGroup");
512  * addItemBool("MySetting1", mMyBool, false);
513  * addItemPoint("MySetting2", mMyPoint, QPoint(100, 200));
514  *
515  * setCurrentGroup("MyOtherGroup");
516  * addItemDouble("MySetting3", mMyDouble, 3.14);
517  * }
518  *
519  * bool mMyBool;
520  * QPoint mMyPoint;
521  * double mMyDouble;
522  * }
523  * \endcode
524  *
525  * It might be convenient in many cases to make this subclass of KCoreConfigSkeleton a
526  * singleton for global access from all over the application without passing
527  * references to the KCoreConfigSkeleton object around.
528  *
529  * You can write the data to the configuration file by calling @ref save()
530  * and read the data from the configuration file by calling @ref readConfig().
531  * If you want to watch for config changes, use @ref configChanged() signal.
532  *
533  * If you have items, which are not covered by the existing addItem() functions
534  * you can add customized code for reading, writing and default setting by
535  * implementing the functions @ref usrUseDefaults(), @ref usrRead() and
536  * @ref usrSave().
537  *
538  * Internally preferences settings are stored in instances of subclasses of
539  * @ref KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses
540  * for your own types and call the generic @ref addItem() to register them.
541  *
542  * In many cases you don't have to write the specific KCoreConfigSkeleton
543  * subclasses yourself, but you can use \ref kconfig_compiler to automatically
544  * generate the C++ code from an XML description of the configuration options.
545  *
546  * Use KConfigSkeleton if you need GUI types as well.
547  *
548  * @see KConfigSkeletonItem
549  */
550 class KCONFIGCORE_EXPORT KCoreConfigSkeleton : public QObject
551 {
552  Q_OBJECT
553 public:
554  /**
555  * Class for handling a string preferences item.
556  */
557  class KCONFIGCORE_EXPORT ItemString : public KConfigSkeletonGenericItem<QString>
558  {
559  public:
560  /** The type of string that is held in this item */
561  enum Type {
562  Normal, ///< A normal string
563  Password, ///< A password string
564  Path, ///< A path to a file or directory
565  };
566 
567  /**
568  * @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem
569  * @param type The type of string held by the item
570  */
571  ItemString(const QString &_group,
572  const QString &_key,
573  QString &reference,
574  const QString &defaultValue = QLatin1String(""), // NOT QString() !!
575  Type type = Normal);
576 
577  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
578  void writeConfig(KConfig *config) override;
579 
580  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
581  void readConfig(KConfig *config) override;
582 
583  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
584  void setProperty(const QVariant &p) override;
585 
586  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
587  bool isEqual(const QVariant &p) const override;
588 
589  /** @copydoc KConfigSkeletonItem::property() const */
590  QVariant property() const override;
591 
592  private:
593  Type mType;
594  };
595 
596  /**
597  * Class for handling a password preferences item.
598  */
599  class KCONFIGCORE_EXPORT ItemPassword : public ItemString
600  {
601  public:
602  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
603  ItemPassword(const QString &_group, const QString &_key, QString &reference,
604  const QString &defaultValue = QLatin1String("")); // NOT QString() !!
605  };
606 
607  /**
608  * Class for handling a path preferences item.
609  */
610  class KCONFIGCORE_EXPORT ItemPath : public ItemString
611  {
612  public:
613  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
614  ItemPath(const QString &_group, const QString &_key, QString &reference, const QString &defaultValue = QString());
615  };
616 
617  /**
618  * Class for handling a url preferences item.
619  */
620  class KCONFIGCORE_EXPORT ItemUrl : public KConfigSkeletonGenericItem<QUrl>
621  {
622  public:
623  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
624  ItemUrl(const QString &_group, const QString &_key, QUrl &reference, const QUrl &defaultValue = QUrl());
625 
626  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
627  void writeConfig(KConfig *config) override;
628 
629  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
630  void readConfig(KConfig *config) override;
631 
632  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
633  void setProperty(const QVariant &p) override;
634 
635  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
636  bool isEqual(const QVariant &p) const override;
637 
638  /** @copydoc KConfigSkeletonItem::property() const */
639  QVariant property() const override;
640  };
641 
642  /**
643  * Class for handling a QVariant preferences item.
644  */
645  class KCONFIGCORE_EXPORT ItemProperty : public KConfigSkeletonGenericItem<QVariant>
646  {
647  public:
648  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
649  ItemProperty(const QString &_group, const QString &_key, QVariant &reference, const QVariant &defaultValue = QVariant());
650 
651  void readConfig(KConfig *config) override;
652  void setProperty(const QVariant &p) override;
653 
654  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
655  bool isEqual(const QVariant &p) const override;
656 
657  /** @copydoc KConfigSkeletonItem::property() const */
658  QVariant property() const override;
659  };
660 
661  /**
662  * Class for handling a bool preferences item.
663  */
664  class KCONFIGCORE_EXPORT ItemBool : public KConfigSkeletonGenericItem<bool>
665  {
666  public:
667  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
668  ItemBool(const QString &_group, const QString &_key, bool &reference, bool defaultValue = true);
669 
670  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
671  void readConfig(KConfig *config) override;
672 
673  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
674  void setProperty(const QVariant &p) override;
675 
676  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
677  bool isEqual(const QVariant &p) const override;
678 
679  /** @copydoc KConfigSkeletonItem::property() const */
680  QVariant property() const override;
681  };
682 
683  /**
684  * Class for handling a 32-bit integer preferences item.
685  */
686  class KCONFIGCORE_EXPORT ItemInt : public KConfigSkeletonGenericItem<qint32>
687  {
688  public:
689  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
690  ItemInt(const QString &_group, const QString &_key, qint32 &reference, qint32 defaultValue = 0);
691 
692  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
693  void readConfig(KConfig *config) override;
694 
695  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
696  void setProperty(const QVariant &p) override;
697 
698  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
699  bool isEqual(const QVariant &p) const override;
700 
701  /** @copydoc KConfigSkeletonItem::property() */
702  QVariant property() const override;
703 
704  /** Get the minimum value that is allowed to be stored in this item */
705  QVariant minValue() const override;
706 
707  /** Get the maximum value this is allowed to be stored in this item */
708  QVariant maxValue() const override;
709 
710  /**
711  * Set the minimum value for the item.
712  * @see minValue()
713  */
714  void setMinValue(qint32);
715 
716  /**
717  * Set the maximum value for the item.
718  * @see maxValue
719  */
720  void setMaxValue(qint32);
721 
722  private:
723  bool mHasMin : 1;
724  bool mHasMax : 1;
725  qint32 mMin;
726  qint32 mMax;
727  };
728 
729  /**
730  * Class for handling a 64-bit integer preferences item.
731  */
732  class KCONFIGCORE_EXPORT ItemLongLong : public KConfigSkeletonGenericItem<qint64>
733  {
734  public:
735  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
736  ItemLongLong(const QString &_group, const QString &_key, qint64 &reference, qint64 defaultValue = 0);
737 
738  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
739  void readConfig(KConfig *config) override;
740 
741  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
742  void setProperty(const QVariant &p) override;
743 
744  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
745  bool isEqual(const QVariant &p) const override;
746 
747  /** @copydoc KConfigSkeletonItem::property() */
748  QVariant property() const override;
749 
750  /** @copydoc ItemInt::minValue() */
751  QVariant minValue() const override;
752 
753  /** @copydoc ItemInt::maxValue() */
754  QVariant maxValue() const override;
755 
756  /** @copydoc ItemInt::setMinValue(qint32) */
757  void setMinValue(qint64);
758 
759  /** @copydoc ItemInt::setMaxValue(qint32) */
760  void setMaxValue(qint64);
761 
762  private:
763  bool mHasMin : 1;
764  bool mHasMax : 1;
765  qint64 mMin;
766  qint64 mMax;
767  };
768 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
769  typedef KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use ItemLongLong") ItemLongLong ItemInt64;
770 #endif
771 
772  /**
773  * Class for handling enums.
774  */
775  class KCONFIGCORE_EXPORT ItemEnum : public ItemInt
776  {
777  public:
778  struct Choice {
779  QString name;
780  QString label;
781  QString toolTip;
782  QString whatsThis;
783  };
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 @p name
806  */
807  QString valueForChoice(const QString &name) const;
808 
809  /**
810  * Stores a choice value for @p 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  ~KCoreConfigSkeleton() override;
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 @p item with a given @p name.
1208  *
1209  * If @p name is a null string, take the name from KConfigSkeletonItem::key().
1210  *
1211  * @note All names must be unique but multiple entries can have
1212  * the same key if they reside in different groups.
1213  *
1214  * KCoreConfigSkeleton takes ownership of @p item.
1215  */
1216  void addItem(KConfigSkeletonItem *item, const QString &name = QString());
1217 
1218  /**
1219  * Register an item of type QString.
1220  *
1221  * @param name Name used to identify this setting. Names must be unique.
1222  * @param reference Pointer to the variable, which is set by readConfig()
1223  * calls and read by save() calls.
1224  * @param defaultValue Default value, which is used when the config file
1225  * does not yet contain the key of this item.
1226  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1227  * @return The created item
1228  */
1229  ItemString *addItemString(const QString &name,
1230  QString &reference,
1231  const QString &defaultValue = QLatin1String(""), // NOT QString() !!
1232  const QString &key = QString());
1233 
1234  /**
1235  * Register a password item of type QString. The string value is written
1236  * encrypted to the config file.
1237  *
1238  * @note The current encryption scheme is very weak.
1239  *
1240  * @param name Name used to identify this setting. Names must be unique.
1241  * @param reference Pointer to the variable, which is set by readConfig()
1242  * calls and read by save() calls.
1243  * @param defaultValue Default value, which is used when the config file
1244  * does not yet contain the key of this item.
1245  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1246  * @return The created item
1247  */
1248  ItemPassword *addItemPassword(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1249 
1250  /**
1251  * Register a path item of type QString. The string value is interpreted
1252  * as a path. This means, dollar expansion is activated for this value, so
1253  * that e.g. @c $HOME gets expanded.
1254  *
1255  * @param name Name used to identify this setting. Names must be unique.
1256  * @param reference Pointer to the variable, which is set by readConfig()
1257  * calls and read by save() calls.
1258  * @param defaultValue Default value, which is used when the config file
1259  * does not yet contain the key of this item.
1260  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1261  * @return The created item
1262  */
1263  ItemPath *addItemPath(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1264 
1265  /**
1266  * Register a property item of type QVariant.
1267  *
1268  * @note The following QVariant types are allowed:
1269  * String, StringList, Font, Point, Rect, Size,
1270  * Color, Int, UInt, Bool, Double, DateTime and Date.
1271  *
1272  * @param name Name used to identify this setting. Names must be unique.
1273  * @param reference Pointer to the variable, which is set by readConfig()
1274  * calls and read by save() calls.
1275  * @param defaultValue Default value, which is used when the config file
1276  * does not yet contain the key of this item.
1277  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1278  * @return The created item
1279  */
1280  ItemProperty *addItemProperty(const QString &name, QVariant &reference, const QVariant &defaultValue = QVariant(), const QString &key = QString());
1281  /**
1282  * Register an item of type @c bool.
1283  *
1284  * @param name Name used to identify this setting. Names must be unique.
1285  * @param reference Pointer to the variable, which is set by readConfig()
1286  * calls and read by save() calls.
1287  * @param defaultValue Default value, which is used when the config file
1288  * does not yet contain the key of this item.
1289  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1290  * @return The created item
1291  */
1292  ItemBool *addItemBool(const QString &name, bool &reference, bool defaultValue = false, const QString &key = QString());
1293 
1294  /**
1295  * Register an item of type @c qint32.
1296  *
1297  * @param name Name used to identify this setting. Names must be unique.
1298  * @param reference Pointer to the variable, which is set by readConfig()
1299  * calls and read by save() calls.
1300  * @param defaultValue Default value, which is used when the config file
1301  * does not yet contain the key of this item.
1302  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1303  * @return The created item
1304  */
1305  ItemInt *addItemInt(const QString &name, qint32 &reference, qint32 defaultValue = 0, const QString &key = QString());
1306 
1307  /**
1308  * Register an item of type @c quint32.
1309  *
1310  * @param name Name used to identify this setting. Names must be unique.
1311  * @param reference Pointer to the variable, which is set by readConfig()
1312  * calls and read by save() calls.
1313  * @param defaultValue Default value, which is used when the config file
1314  * does not yet contain the key of this item.
1315  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1316  * @return The created item
1317  */
1318  ItemUInt *addItemUInt(const QString &name, quint32 &reference, quint32 defaultValue = 0, const QString &key = QString());
1319 
1320  /**
1321  * Register an item of type @c qint64.
1322  *
1323  * @param name Name used to identify this setting. Names must be unique.
1324  * @param reference Pointer to the variable, which is set by readConfig()
1325  * calls and read by save() calls.
1326  * @param defaultValue Default value, which is used when the config file
1327  * does not yet contain the key of this item.
1328  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1329  * @return The created item
1330  */
1331  ItemLongLong *addItemLongLong(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString());
1332 
1333 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1334  /**
1335  * @deprecated Since 5.0, use addItemLongLong().
1336  */
1337  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::addItemLongLong(...)")
1338  ItemLongLong *addItemInt64(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString());
1339 #endif
1340 
1341  /**
1342  * Register an item of type @c quint64.
1343  *
1344  * @param name Name used to identify this setting. Names must be unique.
1345  * @param reference Pointer to the variable, which is set by readConfig()
1346  * calls and read by save() calls.
1347  * @param defaultValue Default value, which is used when the config file
1348  * does not yet contain the key of this item.
1349  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1350  * @return The created item
1351  */
1352  ItemULongLong *addItemULongLong(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString());
1353 
1354 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1355  /**
1356  * @deprecated Since 5.0, use addItemULongLong().
1357  */
1358  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::addItemULongLong(...)")
1359  ItemULongLong *addItemUInt64(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString());
1360 #endif
1361 
1362  /**
1363  * Register an item of type @c double.
1364  *
1365  * @param name Name used to identify this setting. Names must be unique.
1366  * @param reference Pointer to the variable, which is set by readConfig()
1367  * calls and read by save() calls.
1368  * @param defaultValue Default value, which is used when the config file
1369  * does not yet contain the key of this item.
1370  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1371  * @return The created item
1372  */
1373  ItemDouble *addItemDouble(const QString &name, double &reference, double defaultValue = 0.0, const QString &key = QString());
1374 
1375  /**
1376  * Register an item of type QRect.
1377  *
1378  * @param name Name used to identify this setting. Names must be unique.
1379  * @param reference Pointer to the variable, which is set by readConfig()
1380  * calls and read by save() calls.
1381  * @param defaultValue Default value, which is used when the config file
1382  * does not yet contain the key of this item.
1383  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1384  * @return The created item
1385  */
1386  ItemRect *addItemRect(const QString &name, QRect &reference, const QRect &defaultValue = QRect(), const QString &key = QString());
1387 
1388  /**
1389  * Register an item of type QPoint.
1390  *
1391  * @param name Name used to identify this setting. Names must be unique.
1392  * @param reference Pointer to the variable, which is set by readConfig()
1393  * calls and read by save() calls.
1394  * @param defaultValue Default value, which is used when the config file
1395  * does not yet contain the key of this item.
1396  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1397  * @return The created item
1398  */
1399  ItemPoint *addItemPoint(const QString &name, QPoint &reference, const QPoint &defaultValue = QPoint(), const QString &key = QString());
1400 
1401  /**
1402  * Register an item of type QSize.
1403  *
1404  * @param name Name used to identify this setting. Names must be unique.
1405  * @param reference Pointer to the variable, which is set by readConfig()
1406  * calls and read by save() calls.
1407  * @param defaultValue Default value, which is used when the config file
1408  * does not yet contain the key of this item.
1409  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1410  * @return The created item
1411  */
1412  ItemSize *addItemSize(const QString &name, QSize &reference, const QSize &defaultValue = QSize(), const QString &key = QString());
1413 
1414  /**
1415  * Register an item of type QDateTime.
1416  *
1417  * @param name Name used to identify this setting. Names must be unique.
1418  * @param reference Pointer to the variable, which is set by readConfig()
1419  * calls and read by save() calls.
1420  * @param defaultValue Default value, which is used when the config file
1421  * does not yet contain the key of this item.
1422  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1423  * @return The created item
1424  */
1425  ItemDateTime *addItemDateTime(const QString &name, QDateTime &reference, const QDateTime &defaultValue = QDateTime(), const QString &key = QString());
1426 
1427  /**
1428  * Register an item of type QStringList.
1429  *
1430  * @param name Name used to identify this setting. Names must be unique.
1431  * @param reference Pointer to the variable, which is set by readConfig()
1432  * calls and read by save() calls.
1433  * @param defaultValue Default value, which is used when the config file
1434  * does not yet contain the key of this item.
1435  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1436  * @return The created item
1437  */
1438  ItemStringList *
1439  addItemStringList(const QString &name, QStringList &reference, const QStringList &defaultValue = QStringList(), const QString &key = QString());
1440 
1441  /**
1442  * Register an item of type QList<int>.
1443  *
1444  * @param name Name used to identify this setting. Names must be unique.
1445  * @param reference Pointer to the variable, which is set by readConfig()
1446  * calls and read by save() calls.
1447  * @param defaultValue Default value, which is used when the config file
1448  * does not yet contain the key of this item.
1449  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1450  * @return The created item
1451  */
1452  ItemIntList *addItemIntList(const QString &name, QList<int> &reference, const QList<int> &defaultValue = QList<int>(), const QString &key = QString());
1453 
1454  /**
1455  * Return the @ref KConfig object used for reading and writing the settings.
1456  */
1457  KConfig *config();
1458 
1459  /**
1460  * Return the @ref KConfig object used for reading and writing the settings.
1461  */
1462  const KConfig *config() const;
1463 
1464  /**
1465  * Return the @ref KConfig object used for reading and writing the settings.
1466  * @since 5.0
1467  */
1468  KSharedConfig::Ptr sharedConfig() const;
1469 
1470  /**
1471  * Set the @ref KSharedConfig object used for reading and writing the settings.
1472  */
1473  void setSharedConfig(KSharedConfig::Ptr pConfig);
1474 
1475  /**
1476  * Return list of items managed by this KCoreConfigSkeleton object.
1477  */
1478  KConfigSkeletonItem::List items() const;
1479 
1480  /**
1481  * Removes and deletes an item by name
1482  * @param name the name of the item to remove
1483  */
1484  void removeItem(const QString &name);
1485 
1486  /**
1487  * Removes and deletes all items
1488  */
1489  void clearItems();
1490 
1491  /**
1492  * Return whether a certain item is immutable
1493  * @since 4.4
1494  */
1495  Q_INVOKABLE bool isImmutable(const QString &name) const;
1496 
1497  /**
1498  * Lookup item by name
1499  * @since 4.4
1500  */
1501  KConfigSkeletonItem *findItem(const QString &name) const;
1502 
1503  /**
1504  * Specify whether this object should reflect the actual values or the
1505  * default values.
1506  * This method is implemented by usrUseDefaults(), which can be overridden
1507  * in derived classes if you have special requirements and can call
1508  * usrUseDefaults() directly.
1509  * If you don't have control whether useDefaults() or usrUseDefaults() is
1510  * called override useDefaults() directly.
1511  * @param b @c true to make this object reflect the default values,
1512  * @c false to make it reflect the actual values.
1513  * @return The state prior to this call
1514  */
1515  virtual bool useDefaults(bool b);
1516 
1517 public Q_SLOTS:
1518  /**
1519  * Write preferences to config file. The values of all registered items are
1520  * written to disk.
1521  * This method calls usrSave() after writing the settings from the
1522  * registered items to the KConfig. You can override usrSave()
1523  * in derived classes if you have special requirements.
1524  */
1525  bool save();
1526 
1527 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1528  /**
1529  * @deprecated since 5.0, call save() instead.
1530  */
1531  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::save()")
1532  void writeConfig()
1533  {
1534  save();
1535  }
1536 #endif
1537 
1538 Q_SIGNALS:
1539  /**
1540  * This signal is emitted when the configuration change.
1541  */
1542  void configChanged();
1543 
1544 protected:
1545  /**
1546  * Implemented by subclasses that use special defaults.
1547  * It replaces the default values with the actual values and
1548  * vice versa. Called from @ref useDefaults()
1549  * @param b @c true to make this object reflect the default values,
1550  * @c false to make it reflect the actual values.
1551  * @return The state prior to this call
1552  */
1553  virtual bool usrUseDefaults(bool b);
1554 
1555  /**
1556  * Perform the actual setting of default values.
1557  * Override in derived classes to set special default values.
1558  * Called from @ref setDefaults()
1559  */
1560  virtual void usrSetDefaults();
1561 
1562  /**
1563  * Perform the actual reading of the configuration file.
1564  * Override in derived classes to read special config values.
1565  * Called from @ref read()
1566  */
1567  virtual void usrRead();
1568 
1569  /**
1570  * Perform the actual writing of the configuration file.
1571  * Override in derived classes to write special config values.
1572  * Called from @ref save()
1573  */
1574  virtual bool usrSave();
1575 
1576 #if KCONFIGCORE_BUILD_DEPRECATED_SINCE(5, 0)
1577  /**
1578  * @deprecated since 5.0, override usrRead instead. This method is still called from usrRead
1579  * for compatibility.
1580  */
1581  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Override KCoreConfigSkeleton::usrRead()")
1582  virtual void usrReadConfig();
1583 #endif
1584 
1585 #if KCONFIGCORE_BUILD_DEPRECATED_SINCE(5, 0)
1586  /**
1587  * @deprecated since 5.0, override usrSave instead. This method is still called from usrSave
1588  * for compatibility.
1589  */
1590  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Override KCoreConfigSkeleton::usrSave()")
1591  virtual bool usrWriteConfig();
1592 #endif
1593 
1594 private:
1595  KCoreConfigSkeletonPrivate *const d;
1596  friend class KConfigSkeleton;
1597 };
1598 
1599 #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-2023 The KDE developers.
Generated on Fri Jan 27 2023 07:54:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.