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  KCONFIGCORE_NO_EXPORT 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?
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);
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);
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 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 103)
800  // Source compatibility with 4.x
801  typedef KCONFIGCORE_DEPRECATED_VERSION_BELATED(5, 103, 5, 0, "Use Choice") Choice Choice2;
802  /**
803  * @deprecated since 5.0, use choices() const.
804  */
805  KCONFIGCORE_DEPRECATED_VERSION_BELATED(5, 103, 5, 0, "Use choices().")
806  QList<Choice> choices2() const;
807 #endif
808 
809  /**
810  * Returns the value for for the choice with the given @p name
811  */
812  QString valueForChoice(const QString &name) const;
813 
814  /**
815  * Stores a choice value for @p name
816  */
817  void setValueForChoice(const QString &name, const QString &valueForChoice);
818 
819  private:
820  QList<Choice> mChoices;
821  };
822 
823  /**
824  * Class for handling an unsigned 32-bit integer preferences item.
825  */
826  class KCONFIGCORE_EXPORT ItemUInt : public KConfigSkeletonGenericItem<quint32>
827  {
828  public:
829  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
830  ItemUInt(const QString &_group, const QString &_key, quint32 &reference, quint32 defaultValue = 0);
831 
832  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
833  void readConfig(KConfig *config) override;
834 
835  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
836  void setProperty(const QVariant &p) override;
837 
838  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
839  bool isEqual(const QVariant &p) const override;
840 
841  /** @copydoc KConfigSkeletonItem::property() */
842  QVariant property() const override;
843 
844  /** @copydoc ItemInt::minValue() */
845  QVariant minValue() const override;
846 
847  /** @copydoc ItemInt::maxValue() */
848  QVariant maxValue() const override;
849 
850  /** @copydoc ItemInt::setMinValue(qint32) */
851  void setMinValue(quint32);
852 
853  /** @copydoc ItemInt::setMaxValue(qint32) */
854  void setMaxValue(quint32);
855 
856  private:
857  bool mHasMin : 1;
858  bool mHasMax : 1;
859  quint32 mMin;
860  quint32 mMax;
861  };
862 
863  /**
864  * Class for handling unsigned 64-bit integer preferences item.
865  */
866  class KCONFIGCORE_EXPORT ItemULongLong : public KConfigSkeletonGenericItem<quint64>
867  {
868  public:
869  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
870  ItemULongLong(const QString &_group, const QString &_key, quint64 &reference, quint64 defaultValue = 0);
871 
872  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
873  void readConfig(KConfig *config) override;
874 
875  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
876  void setProperty(const QVariant &p) override;
877 
878  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
879  bool isEqual(const QVariant &p) const override;
880 
881  /** @copydoc KConfigSkeletonItem::property() */
882  QVariant property() const override;
883 
884  /** @copydoc ItemInt::minValue() */
885  QVariant minValue() const override;
886 
887  /** @copydoc ItemInt::maxValue() */
888  QVariant maxValue() const override;
889 
890  /** @copydoc ItemInt::setMinValue(qint32) */
891  void setMinValue(quint64);
892 
893  /** @copydoc ItemInt::setMaxValue(qint32) */
894  void setMaxValue(quint64);
895 
896  private:
897  bool mHasMin : 1;
898  bool mHasMax : 1;
899  quint64 mMin;
900  quint64 mMax;
901  };
902 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
903  typedef KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use ItemULongLong") ItemULongLong ItemUInt64;
904 #endif
905 
906  /**
907  * Class for handling a floating point preference item.
908  */
909  class KCONFIGCORE_EXPORT ItemDouble : public KConfigSkeletonGenericItem<double>
910  {
911  public:
912  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
913  ItemDouble(const QString &_group, const QString &_key, double &reference, double defaultValue = 0);
914 
915  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
916  void readConfig(KConfig *config) override;
917 
918  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
919  void setProperty(const QVariant &p) override;
920 
921  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
922  bool isEqual(const QVariant &p) const override;
923 
924  /** @copydoc KConfigSkeletonItem::property() */
925  QVariant property() const override;
926 
927  /** @copydoc ItemInt::minValue() */
928  QVariant minValue() const override;
929 
930  /** @copydoc ItemInt::maxValue() */
931  QVariant maxValue() const override;
932 
933  /** @copydoc ItemInt::setMinValue() */
934  void setMinValue(double);
935 
936  /** @copydoc ItemInt::setMaxValue() */
937  void setMaxValue(double);
938 
939  private:
940  bool mHasMin : 1;
941  bool mHasMax : 1;
942  double mMin;
943  double mMax;
944  };
945 
946  /**
947  * Class for handling a QRect preferences item.
948  */
949  class KCONFIGCORE_EXPORT ItemRect : public KConfigSkeletonGenericItem<QRect>
950  {
951  public:
952  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
953  ItemRect(const QString &_group, const QString &_key, QRect &reference, const QRect &defaultValue = QRect());
954 
955  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
956  void readConfig(KConfig *config) override;
957 
958  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
959  void setProperty(const QVariant &p) override;
960 
961  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
962  bool isEqual(const QVariant &p) const override;
963 
964  /** @copydoc KConfigSkeletonItem::property() */
965  QVariant property() const override;
966  };
967 
968  /**
969  * Class for handling a QPoint preferences item.
970  */
971  class KCONFIGCORE_EXPORT ItemPoint : public KConfigSkeletonGenericItem<QPoint>
972  {
973  public:
974  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
975  ItemPoint(const QString &_group, const QString &_key, QPoint &reference, const QPoint &defaultValue = QPoint());
976 
977  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
978  void readConfig(KConfig *config) override;
979 
980  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
981  void setProperty(const QVariant &p) override;
982 
983  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
984  bool isEqual(const QVariant &p) const override;
985 
986  /** @copydoc KConfigSkeletonItem::property() */
987  QVariant property() const override;
988  };
989 
990  /**
991  * Class for handling a QSize preferences item.
992  */
993  class KCONFIGCORE_EXPORT ItemSize : public KConfigSkeletonGenericItem<QSize>
994  {
995  public:
996  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
997  ItemSize(const QString &_group, const QString &_key, QSize &reference, const QSize &defaultValue = QSize());
998 
999  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1000  void readConfig(KConfig *config) override;
1001 
1002  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1003  void setProperty(const QVariant &p) override;
1004 
1005  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1006  bool isEqual(const QVariant &p) const override;
1007 
1008  /** @copydoc KConfigSkeletonItem::property() */
1009  QVariant property() const override;
1010  };
1011 
1012  /**
1013  * Class for handling a QDateTime preferences item.
1014  */
1015  class KCONFIGCORE_EXPORT ItemDateTime : public KConfigSkeletonGenericItem<QDateTime>
1016  {
1017  public:
1018  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1019  ItemDateTime(const QString &_group, const QString &_key, QDateTime &reference, const QDateTime &defaultValue = QDateTime());
1020 
1021  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1022  void readConfig(KConfig *config) override;
1023 
1024  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1025  void setProperty(const QVariant &p) override;
1026 
1027  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1028  bool isEqual(const QVariant &p) const override;
1029 
1030  /** @copydoc KConfigSkeletonItem::property() */
1031  QVariant property() const override;
1032  };
1033 
1034  /**
1035  * Class for handling a string list preferences item.
1036  */
1037  class KCONFIGCORE_EXPORT ItemStringList : public KConfigSkeletonGenericItem<QStringList>
1038  {
1039  public:
1040  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1041  ItemStringList(const QString &_group, const QString &_key, QStringList &reference, const QStringList &defaultValue = QStringList());
1042 
1043  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1044  void readConfig(KConfig *config) override;
1045 
1046  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1047  void setProperty(const QVariant &p) override;
1048 
1049  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1050  bool isEqual(const QVariant &p) const override;
1051 
1052  /** @copydoc KConfigSkeletonItem::property() */
1053  QVariant property() const override;
1054  };
1055 
1056  /**
1057  * Class for handling a path list preferences item.
1058  */
1059  class KCONFIGCORE_EXPORT ItemPathList : public ItemStringList
1060  {
1061  public:
1062  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1063  ItemPathList(const QString &_group, const QString &_key, QStringList &reference, const QStringList &defaultValue = QStringList());
1064 
1065  /** @copydoc KConfigSkeletonItem::readConfig */
1066  void readConfig(KConfig *config) override;
1067  /** @copydoc KConfigSkeletonItem::writeConfig */
1068  void writeConfig(KConfig *config) override;
1069  };
1070 
1071  /**
1072  * Class for handling a url list preferences item.
1073  */
1074  class KCONFIGCORE_EXPORT ItemUrlList : public KConfigSkeletonGenericItem<QList<QUrl>>
1075  {
1076  public:
1077  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1078  ItemUrlList(const QString &_group, const QString &_key, QList<QUrl> &reference, const QList<QUrl> &defaultValue = QList<QUrl>());
1079 
1080  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1081  void readConfig(KConfig *config) override;
1082 
1083  /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
1084  void writeConfig(KConfig *config) override;
1085 
1086  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1087  void setProperty(const QVariant &p) override;
1088 
1089  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1090  bool isEqual(const QVariant &p) const override;
1091 
1092  /** @copydoc KConfigSkeletonItem::property() */
1093  QVariant property() const override;
1094  };
1095 
1096  /**
1097  * Class for handling an integer list preferences item.
1098  */
1099  class KCONFIGCORE_EXPORT ItemIntList : public KConfigSkeletonGenericItem<QList<int>>
1100  {
1101  public:
1102  /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
1103  ItemIntList(const QString &_group, const QString &_key, QList<int> &reference, const QList<int> &defaultValue = QList<int>());
1104 
1105  /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
1106  void readConfig(KConfig *config) override;
1107 
1108  /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
1109  void setProperty(const QVariant &p) override;
1110 
1111  /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
1112  bool isEqual(const QVariant &p) const override;
1113 
1114  /** @copydoc KConfigSkeletonItem::property() */
1115  QVariant property() const override;
1116  };
1117 
1118 public:
1119  /**
1120  * Constructor.
1121  *
1122  * @param configname name of config file. If no name is given, the default
1123  * config file as returned by KSharedConfig::openConfig() is used
1124  * @param parent the parent object (see QObject documentation)
1125  */
1126  explicit KCoreConfigSkeleton(const QString &configname = QString(), QObject *parent = nullptr);
1127 
1128  /**
1129  * Constructor.
1130  *
1131  * @param config configuration object to use
1132  * @param parent the parent object (see QObject documentation)
1133  */
1134  explicit KCoreConfigSkeleton(KSharedConfig::Ptr config, QObject *parent = nullptr);
1135 
1136  /**
1137  * Destructor
1138  */
1139  ~KCoreConfigSkeleton() override;
1140 
1141  /**
1142  * Set all registered items to their default values.
1143  * This method calls usrSetDefaults() after setting the defaults for the
1144  * registered items. You can override usrSetDefaults() in derived classes
1145  * if you have special requirements.
1146  * If you need more fine-grained control of setting the default values of
1147  * the registered items you can override setDefaults() in a derived class.
1148  */
1149  virtual void setDefaults();
1150 
1151  /**
1152  * Read preferences from config file. All registered items are set to the
1153  * values read from disk.
1154  * This method calls usrRead() after reading the settings of the
1155  * registered items from the KConfig. You can override usrRead()
1156  * in derived classes if you have special requirements.
1157  */
1158  void load();
1159 
1160 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1161  /**
1162  * @deprecated since 5.0, call load() instead (to reload from disk) or just read()
1163  * if the underlying KConfig object is already up-to-date.
1164  */
1165  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::load() or KCoreConfigSkeleton::read()")
1166  void readConfig()
1167  {
1168  load();
1169  }
1170 #endif
1171 
1172  /**
1173  * Read preferences from the KConfig object.
1174  * This method assumes that the KConfig object was previously loaded,
1175  * i.e. it uses the in-memory values from KConfig without reloading from disk.
1176  *
1177  * This method calls usrRead() after reading the settings of the
1178  * registered items from the KConfig. You can override usrRead()
1179  * in derived classes if you have special requirements.
1180  * @since 5.0
1181  */
1182  void read();
1183 
1184  /**
1185  * Indicates if all the registered items are set to their default value.
1186  *
1187  * @since 5.64
1188  */
1189  bool isDefaults() const;
1190 
1191  /**
1192  * Indicates if any registered item has a different value than the
1193  * previously loaded value.
1194  *
1195  * @since 5.64
1196  */
1197  bool isSaveNeeded() const;
1198 
1199  /**
1200  * Set the config file group for subsequent addItem() calls. It is valid
1201  * until setCurrentGroup() is called with a new argument. Call this before
1202  * you add any items. The default value is "No Group".
1203  */
1204  void setCurrentGroup(const QString &group);
1205 
1206  /**
1207  * Returns the current group used for addItem() calls.
1208  */
1209  QString currentGroup() const;
1210 
1211  /**
1212  * Register a custom @ref KConfigSkeletonItem @p item with a given @p name.
1213  *
1214  * If @p name is a null string, take the name from KConfigSkeletonItem::key().
1215  *
1216  * @note All names must be unique but multiple entries can have
1217  * the same key if they reside in different groups.
1218  *
1219  * KCoreConfigSkeleton takes ownership of @p item.
1220  */
1221  void addItem(KConfigSkeletonItem *item, const QString &name = QString());
1222 
1223  /**
1224  * Register an item of type QString.
1225  *
1226  * @param name Name used to identify this setting. Names must be unique.
1227  * @param reference Pointer to the variable, which is set by readConfig()
1228  * calls and read by save() calls.
1229  * @param defaultValue Default value, which is used when the config file
1230  * does not yet contain the key of this item.
1231  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1232  * @return The created item
1233  */
1234  ItemString *addItemString(const QString &name,
1235  QString &reference,
1236  const QString &defaultValue = QLatin1String(""), // NOT QString() !!
1237  const QString &key = QString());
1238 
1239  /**
1240  * Register a password item of type QString. The string value is written
1241  * encrypted to the config file.
1242  *
1243  * @note The current encryption scheme is very weak.
1244  *
1245  * @param name Name used to identify this setting. Names must be unique.
1246  * @param reference Pointer to the variable, which is set by readConfig()
1247  * calls and read by save() calls.
1248  * @param defaultValue Default value, which is used when the config file
1249  * does not yet contain the key of this item.
1250  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1251  * @return The created item
1252  */
1253  ItemPassword *addItemPassword(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1254 
1255  /**
1256  * Register a path item of type QString. The string value is interpreted
1257  * as a path. This means, dollar expansion is activated for this value, so
1258  * that e.g. @c $HOME gets expanded.
1259  *
1260  * @param name Name used to identify this setting. Names must be unique.
1261  * @param reference Pointer to the variable, which is set by readConfig()
1262  * calls and read by save() calls.
1263  * @param defaultValue Default value, which is used when the config file
1264  * does not yet contain the key of this item.
1265  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1266  * @return The created item
1267  */
1268  ItemPath *addItemPath(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1269 
1270  /**
1271  * Register a property item of type QVariant.
1272  *
1273  * @note The following QVariant types are allowed:
1274  * String, StringList, Font, Point, Rect, Size,
1275  * Color, Int, UInt, Bool, Double, DateTime and Date.
1276  *
1277  * @param name Name used to identify this setting. Names must be unique.
1278  * @param reference Pointer to the variable, which is set by readConfig()
1279  * calls and read by save() calls.
1280  * @param defaultValue Default value, which is used when the config file
1281  * does not yet contain the key of this item.
1282  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1283  * @return The created item
1284  */
1285  ItemProperty *addItemProperty(const QString &name, QVariant &reference, const QVariant &defaultValue = QVariant(), const QString &key = QString());
1286  /**
1287  * Register an item of type @c bool.
1288  *
1289  * @param name Name used to identify this setting. Names must be unique.
1290  * @param reference Pointer to the variable, which is set by readConfig()
1291  * calls and read by save() calls.
1292  * @param defaultValue Default value, which is used when the config file
1293  * does not yet contain the key of this item.
1294  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1295  * @return The created item
1296  */
1297  ItemBool *addItemBool(const QString &name, bool &reference, bool defaultValue = false, const QString &key = QString());
1298 
1299  /**
1300  * Register an item of type @c qint32.
1301  *
1302  * @param name Name used to identify this setting. Names must be unique.
1303  * @param reference Pointer to the variable, which is set by readConfig()
1304  * calls and read by save() calls.
1305  * @param defaultValue Default value, which is used when the config file
1306  * does not yet contain the key of this item.
1307  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1308  * @return The created item
1309  */
1310  ItemInt *addItemInt(const QString &name, qint32 &reference, qint32 defaultValue = 0, const QString &key = QString());
1311 
1312  /**
1313  * Register an item of type @c quint32.
1314  *
1315  * @param name Name used to identify this setting. Names must be unique.
1316  * @param reference Pointer to the variable, which is set by readConfig()
1317  * calls and read by save() calls.
1318  * @param defaultValue Default value, which is used when the config file
1319  * does not yet contain the key of this item.
1320  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1321  * @return The created item
1322  */
1323  ItemUInt *addItemUInt(const QString &name, quint32 &reference, quint32 defaultValue = 0, const QString &key = QString());
1324 
1325  /**
1326  * Register an item of type @c qint64.
1327  *
1328  * @param name Name used to identify this setting. Names must be unique.
1329  * @param reference Pointer to the variable, which is set by readConfig()
1330  * calls and read by save() calls.
1331  * @param defaultValue Default value, which is used when the config file
1332  * does not yet contain the key of this item.
1333  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1334  * @return The created item
1335  */
1336  ItemLongLong *addItemLongLong(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString());
1337 
1338 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1339  /**
1340  * @deprecated Since 5.0, use addItemLongLong().
1341  */
1342  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::addItemLongLong(...)")
1343  ItemLongLong *addItemInt64(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString());
1344 #endif
1345 
1346  /**
1347  * Register an item of type @c quint64.
1348  *
1349  * @param name Name used to identify this setting. Names must be unique.
1350  * @param reference Pointer to the variable, which is set by readConfig()
1351  * calls and read by save() calls.
1352  * @param defaultValue Default value, which is used when the config file
1353  * does not yet contain the key of this item.
1354  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1355  * @return The created item
1356  */
1357  ItemULongLong *addItemULongLong(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString());
1358 
1359 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1360  /**
1361  * @deprecated Since 5.0, use addItemULongLong().
1362  */
1363  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::addItemULongLong(...)")
1364  ItemULongLong *addItemUInt64(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString());
1365 #endif
1366 
1367  /**
1368  * Register an item of type @c double.
1369  *
1370  * @param name Name used to identify this setting. Names must be unique.
1371  * @param reference Pointer to the variable, which is set by readConfig()
1372  * calls and read by save() calls.
1373  * @param defaultValue Default value, which is used when the config file
1374  * does not yet contain the key of this item.
1375  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1376  * @return The created item
1377  */
1378  ItemDouble *addItemDouble(const QString &name, double &reference, double defaultValue = 0.0, const QString &key = QString());
1379 
1380  /**
1381  * Register an item of type QRect.
1382  *
1383  * @param name Name used to identify this setting. Names must be unique.
1384  * @param reference Pointer to the variable, which is set by readConfig()
1385  * calls and read by save() calls.
1386  * @param defaultValue Default value, which is used when the config file
1387  * does not yet contain the key of this item.
1388  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1389  * @return The created item
1390  */
1391  ItemRect *addItemRect(const QString &name, QRect &reference, const QRect &defaultValue = QRect(), const QString &key = QString());
1392 
1393  /**
1394  * Register an item of type QPoint.
1395  *
1396  * @param name Name used to identify this setting. Names must be unique.
1397  * @param reference Pointer to the variable, which is set by readConfig()
1398  * calls and read by save() calls.
1399  * @param defaultValue Default value, which is used when the config file
1400  * does not yet contain the key of this item.
1401  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1402  * @return The created item
1403  */
1404  ItemPoint *addItemPoint(const QString &name, QPoint &reference, const QPoint &defaultValue = QPoint(), const QString &key = QString());
1405 
1406  /**
1407  * Register an item of type QSize.
1408  *
1409  * @param name Name used to identify this setting. Names must be unique.
1410  * @param reference Pointer to the variable, which is set by readConfig()
1411  * calls and read by save() calls.
1412  * @param defaultValue Default value, which is used when the config file
1413  * does not yet contain the key of this item.
1414  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1415  * @return The created item
1416  */
1417  ItemSize *addItemSize(const QString &name, QSize &reference, const QSize &defaultValue = QSize(), const QString &key = QString());
1418 
1419  /**
1420  * Register an item of type QDateTime.
1421  *
1422  * @param name Name used to identify this setting. Names must be unique.
1423  * @param reference Pointer to the variable, which is set by readConfig()
1424  * calls and read by save() calls.
1425  * @param defaultValue Default value, which is used when the config file
1426  * does not yet contain the key of this item.
1427  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1428  * @return The created item
1429  */
1430  ItemDateTime *addItemDateTime(const QString &name, QDateTime &reference, const QDateTime &defaultValue = QDateTime(), const QString &key = QString());
1431 
1432  /**
1433  * Register an item of type QStringList.
1434  *
1435  * @param name Name used to identify this setting. Names must be unique.
1436  * @param reference Pointer to the variable, which is set by readConfig()
1437  * calls and read by save() calls.
1438  * @param defaultValue Default value, which is used when the config file
1439  * does not yet contain the key of this item.
1440  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1441  * @return The created item
1442  */
1443  ItemStringList *
1444  addItemStringList(const QString &name, QStringList &reference, const QStringList &defaultValue = QStringList(), const QString &key = QString());
1445 
1446  /**
1447  * Register an item of type QList<int>.
1448  *
1449  * @param name Name used to identify this setting. Names must be unique.
1450  * @param reference Pointer to the variable, which is set by readConfig()
1451  * calls and read by save() calls.
1452  * @param defaultValue Default value, which is used when the config file
1453  * does not yet contain the key of this item.
1454  * @param key Key used in config file. If @p key is a null string, @p name is used as key.
1455  * @return The created item
1456  */
1457  ItemIntList *addItemIntList(const QString &name, QList<int> &reference, const QList<int> &defaultValue = QList<int>(), const QString &key = QString());
1458 
1459  /**
1460  * Return the @ref KConfig object used for reading and writing the settings.
1461  */
1462  KConfig *config();
1463 
1464  /**
1465  * Return the @ref KConfig object used for reading and writing the settings.
1466  */
1467  const KConfig *config() const;
1468 
1469  /**
1470  * Return the @ref KConfig object used for reading and writing the settings.
1471  * @since 5.0
1472  */
1473  KSharedConfig::Ptr sharedConfig() const;
1474 
1475  /**
1476  * Set the @ref KSharedConfig object used for reading and writing the settings.
1477  */
1478  void setSharedConfig(KSharedConfig::Ptr pConfig);
1479 
1480  /**
1481  * Return list of items managed by this KCoreConfigSkeleton object.
1482  */
1483  KConfigSkeletonItem::List items() const;
1484 
1485  /**
1486  * Removes and deletes an item by name
1487  * @param name the name of the item to remove
1488  */
1489  void removeItem(const QString &name);
1490 
1491  /**
1492  * Removes and deletes all items
1493  */
1494  void clearItems();
1495 
1496  /**
1497  * Return whether a certain item is immutable
1498  * @since 4.4
1499  */
1500  Q_INVOKABLE bool isImmutable(const QString &name) const;
1501 
1502  /**
1503  * Lookup item by name
1504  * @since 4.4
1505  */
1506  KConfigSkeletonItem *findItem(const QString &name) const;
1507 
1508  /**
1509  * Specify whether this object should reflect the actual values or the
1510  * default values.
1511  * This method is implemented by usrUseDefaults(), which can be overridden
1512  * in derived classes if you have special requirements and can call
1513  * usrUseDefaults() directly.
1514  * If you don't have control whether useDefaults() or usrUseDefaults() is
1515  * called override useDefaults() directly.
1516  * @param b @c true to make this object reflect the default values,
1517  * @c false to make it reflect the actual values.
1518  * @return The state prior to this call
1519  */
1520  virtual bool useDefaults(bool b);
1521 
1522 public Q_SLOTS:
1523  /**
1524  * Write preferences to config file. The values of all registered items are
1525  * written to disk.
1526  * This method calls usrSave() after writing the settings from the
1527  * registered items to the KConfig. You can override usrSave()
1528  * in derived classes if you have special requirements.
1529  */
1530  bool save();
1531 
1532 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(5, 0)
1533  /**
1534  * @deprecated since 5.0, call save() instead.
1535  */
1536  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Use KCoreConfigSkeleton::save()")
1537  void writeConfig()
1538  {
1539  save();
1540  }
1541 #endif
1542 
1543 Q_SIGNALS:
1544  /**
1545  * This signal is emitted when the configuration change.
1546  */
1547  void configChanged();
1548 
1549 protected:
1550  /**
1551  * Implemented by subclasses that use special defaults.
1552  * It replaces the default values with the actual values and
1553  * vice versa. Called from @ref useDefaults()
1554  * @param b @c true to make this object reflect the default values,
1555  * @c false to make it reflect the actual values.
1556  * @return The state prior to this call
1557  */
1558  virtual bool usrUseDefaults(bool b);
1559 
1560  /**
1561  * Perform the actual setting of default values.
1562  * Override in derived classes to set special default values.
1563  * Called from @ref setDefaults()
1564  */
1565  virtual void usrSetDefaults();
1566 
1567  /**
1568  * Perform the actual reading of the configuration file.
1569  * Override in derived classes to read special config values.
1570  * Called from @ref read()
1571  */
1572  virtual void usrRead();
1573 
1574  /**
1575  * Perform the actual writing of the configuration file.
1576  * Override in derived classes to write special config values.
1577  * Called from @ref save()
1578  */
1579  virtual bool usrSave();
1580 
1581 #if KCONFIGCORE_BUILD_DEPRECATED_SINCE(5, 0)
1582  /**
1583  * @deprecated since 5.0, override usrRead instead. This method is still called from usrRead
1584  * for compatibility.
1585  */
1586  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Override KCoreConfigSkeleton::usrRead()")
1587  virtual void usrReadConfig();
1588 #endif
1589 
1590 #if KCONFIGCORE_BUILD_DEPRECATED_SINCE(5, 0)
1591  /**
1592  * @deprecated since 5.0, override usrSave instead. This method is still called from usrSave
1593  * for compatibility.
1594  */
1595  KCONFIGCORE_DEPRECATED_VERSION(5, 0, "Override KCoreConfigSkeleton::usrSave()")
1596  virtual bool usrWriteConfig();
1597 #endif
1598 
1599 private:
1600  KCoreConfigSkeletonPrivate *const d;
1601  friend class KConfigSkeleton;
1602 };
1603 
1604 #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.
KSharedConfigPtr config()
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 Thu Nov 30 2023 04:10:19 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.