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

source code of kconfig/src/core/kcoreconfigskeleton.h