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 ~KCoreConfigSkeleton() override;
1222
1223 /*!
1224 * Set all registered items to their default values.
1225 *
1226 * This method calls usrSetDefaults() after setting the defaults for the
1227 * registered items. You can override usrSetDefaults() in derived classes
1228 * if you have special requirements.
1229 *
1230 * If you need more fine-grained control of setting the default values of
1231 * the registered items you can override setDefaults() in a derived class.
1232 */
1233 virtual void setDefaults();
1234
1235 /*!
1236 * Read preferences from config file. All registered items are set to the
1237 * values read from disk.
1238 *
1239 * This method calls usrRead() after reading the settings of the
1240 * registered items from the KConfig. You can override usrRead()
1241 * in derived classes if you have special requirements.
1242 */
1243 void load();
1244
1245 /*!
1246 * Read preferences from the KConfig object.
1247 * This method assumes that the KConfig object was previously loaded,
1248 * i.e. it uses the in-memory values from KConfig without reloading from disk.
1249 *
1250 * This method calls usrRead() after reading the settings of the
1251 * registered items from the KConfig. You can override usrRead()
1252 * in derived classes if you have special requirements.
1253 * \since 5.0
1254 */
1255 void read();
1256
1257 /*!
1258 * Indicates if all the registered items are set to their default value.
1259 *
1260 * \since 5.64
1261 */
1262 bool isDefaults() const;
1263
1264 /*!
1265 * Indicates if any registered item has a different value than the
1266 * previously loaded value.
1267 *
1268 * \since 5.64
1269 */
1270 bool isSaveNeeded() const;
1271
1272 /*!
1273 * Set the config file group for subsequent addItem() calls. It is valid
1274 * until setCurrentGroup() is called with a new argument. Call this before
1275 * you add any items. The default value is "No Group".
1276 */
1277 void setCurrentGroup(const QString &group);
1278
1279 /*!
1280 * Returns the current group used for addItem() calls.
1281 */
1282 QString currentGroup() const;
1283
1284 /*!
1285 * Register a custom KConfigSkeletonItem \a item with a given \a name.
1286 *
1287 * If \a name is a null string, take the name from KConfigSkeletonItem::key().
1288 *
1289 * \note All names must be unique but multiple entries can have
1290 * the same key if they reside in different groups.
1291 *
1292 * KCoreConfigSkeleton takes ownership of \a item.
1293 */
1294 void addItem(KConfigSkeletonItem *item, const QString &name = QString());
1295
1296 /*!
1297 * Register an item of type QString.
1298 *
1299 * \a name Name used to identify this setting. Names must be unique.
1300 *
1301 * \a reference Pointer to the variable, which is set by readConfig()
1302 * calls and read by save() calls.
1303 *
1304 * \a defaultValue Default value, which is used when the config file
1305 * does not yet contain the key of this item.
1306 *
1307 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1308 *
1309 * Returns the created item
1310 */
1311 ItemString *addItemString(const QString &name,
1312 QString &reference,
1313 const QString &defaultValue = QLatin1String(""), // NOT QString() !!
1314 const QString &key = QString());
1315
1316 /*!
1317 * Register a password item of type QString. The string value is written
1318 * encrypted to the config file.
1319 *
1320 * \note The current encryption scheme is very weak.
1321 *
1322 * \a name Name used to identify this setting. Names must be unique.
1323 *
1324 * \a reference Pointer to the variable, which is set by readConfig()
1325 * calls and read by save() calls.
1326 *
1327 * \a defaultValue Default value, which is used when the config file
1328 * does not yet contain the key of this item.
1329 *
1330 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1331 *
1332 * Returns the created item
1333 */
1334 ItemPassword *addItemPassword(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1335
1336 /*!
1337 * Register a path item of type QString. The string value is interpreted
1338 * as a path. This means, dollar expansion is activated for this value, so
1339 * that e.g. \c $HOME gets expanded.
1340 *
1341 * \a name Name used to identify this setting. Names must be unique.
1342 *
1343 * \a reference Pointer to the variable, which is set by readConfig()
1344 * calls and read by save() calls.
1345 *
1346 * \a defaultValue Default value, which is used when the config file
1347 * does not yet contain the key of this item.
1348 *
1349 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1350 *
1351 * Returns the created item
1352 */
1353 ItemPath *addItemPath(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString());
1354
1355 /*!
1356 * Register a property item of type QVariant.
1357 *
1358 * \note The following QVariant types are allowed:
1359 * String, StringList, Font, Point, PointF, Rect, RectF, Size, SizeF,
1360 * Color, Int, UInt, Bool, Double, DateTime and Date.
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 ItemProperty *addItemProperty(const QString &name, QVariant &reference, const QVariant &defaultValue = QVariant(), const QString &key = QString());
1375 /*!
1376 * Register an item of type \c bool.
1377 *
1378 * \a name Name used to identify this setting. Names must be unique.
1379 *
1380 * \a reference Pointer to the variable, which is set by readConfig()
1381 * calls and read by save() calls.
1382 *
1383 * \a defaultValue Default value, which is used when the config file
1384 * does not yet contain the key of this item.
1385 *
1386 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1387 *
1388 * Returns the created item
1389 */
1390 ItemBool *addItemBool(const QString &name, bool &reference, bool defaultValue = false, const QString &key = QString());
1391
1392 /*!
1393 * Register an item of type \c qint32.
1394 *
1395 * \a name Name used to identify this setting. Names must be unique.
1396 *
1397 * \a reference Pointer to the variable, which is set by readConfig()
1398 * calls and read by save() calls.
1399 *
1400 * \a defaultValue Default value, which is used when the config file
1401 * does not yet contain the key of this item.
1402 *
1403 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1404 *
1405 * Returns the created item
1406 */
1407 ItemInt *addItemInt(const QString &name, qint32 &reference, qint32 defaultValue = 0, const QString &key = QString());
1408
1409 /*!
1410 * Register an item of type \c quint32.
1411 *
1412 * \a name Name used to identify this setting. Names must be unique.
1413 *
1414 * \a reference Pointer to the variable, which is set by readConfig()
1415 * calls and read by save() calls.
1416 *
1417 * \a defaultValue Default value, which is used when the config file
1418 * does not yet contain the key of this item.
1419 *
1420 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1421 *
1422 * Returns the created item
1423 */
1424 ItemUInt *addItemUInt(const QString &name, quint32 &reference, quint32 defaultValue = 0, const QString &key = QString());
1425
1426 /*!
1427 * Register an item of type \c qint64.
1428 *
1429 * \a name Name used to identify this setting. Names must be unique.
1430 *
1431 * \a reference Pointer to the variable, which is set by readConfig()
1432 * calls and read by save() calls.
1433 *
1434 * \a defaultValue Default value, which is used when the config file
1435 * does not yet contain the key of this item.
1436 *
1437 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1438 *
1439 * Returns the created item
1440 */
1441 ItemLongLong *addItemLongLong(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString());
1442
1443 /*!
1444 * Register an item of type \c quint64.
1445 *
1446 * \a name Name used to identify this setting. Names must be unique.
1447 *
1448 * \a reference Pointer to the variable, which is set by readConfig()
1449 * calls and read by save() calls.
1450 *
1451 * \a defaultValue Default value, which is used when the config file
1452 * does not yet contain the key of this item.
1453 *
1454 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1455 *
1456 * Returns the created item
1457 */
1458 ItemULongLong *addItemULongLong(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString());
1459
1460 /*!
1461 * Register an item of type \c double.
1462 *
1463 * \a name Name used to identify this setting. Names must be unique.
1464 *
1465 * \a reference Pointer to the variable, which is set by readConfig()
1466 * calls and read by save() calls.
1467 *
1468 * \a defaultValue Default value, which is used when the config file
1469 * does not yet contain the key of this item.
1470 *
1471 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1472 *
1473 * Returns the created item
1474 */
1475 ItemDouble *addItemDouble(const QString &name, double &reference, double defaultValue = 0.0, const QString &key = QString());
1476
1477 /*!
1478 * Register an item of type QRect.
1479 *
1480 * \a name Name used to identify this setting. Names must be unique.
1481 *
1482 * \a reference Pointer to the variable, which is set by readConfig()
1483 * calls and read by save() calls.
1484 *
1485 * \a defaultValue Default value, which is used when the config file
1486 * does not yet contain the key of this item.
1487 *
1488 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1489 *
1490 * Returns the created item
1491 */
1492 ItemRect *addItemRect(const QString &name, QRect &reference, const QRect &defaultValue = QRect(), const QString &key = QString());
1493
1494 /*!
1495 * Register an item of type QRectF.
1496 *
1497 * \a name Name used to identify this setting. Names must be unique.
1498 *
1499 * \a reference Pointer to the variable, which is set by readConfig()
1500 * calls and read by save() calls.
1501 *
1502 * \a defaultValue Default value, which is used when the config file
1503 * does not yet contain the key of this item.
1504 *
1505 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1506 *
1507 * Returns the created item
1508 */
1509 ItemRectF *addItemRectF(const QString &name, QRectF &reference, const QRectF &defaultValue = QRectF(), const QString &key = QString());
1510
1511 /*!
1512 * Register an item of type QPoint.
1513 *
1514 * \a name Name used to identify this setting. Names must be unique.
1515 *
1516 * \a reference Pointer to the variable, which is set by readConfig()
1517 * calls and read by save() calls.
1518 *
1519 * \a defaultValue Default value, which is used when the config file
1520 * does not yet contain the key of this item.
1521 *
1522 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1523 *
1524 * Returns the created item
1525 */
1526 ItemPoint *addItemPoint(const QString &name, QPoint &reference, const QPoint &defaultValue = QPoint(), const QString &key = QString());
1527
1528 /*!
1529 * Register an item of type QPointF.
1530 *
1531 * \a name Name used to identify this setting. Names must be unique.
1532 *
1533 * \a reference Pointer to the variable, which is set by readConfig()
1534 * calls and read by save() calls.
1535 *
1536 * \a defaultValue Default value, which is used when the config file
1537 * does not yet contain the key of this item.
1538 *
1539 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1540 *
1541 * Returns the created item
1542 */
1543 ItemPointF *addItemPointF(const QString &name, QPointF &reference, const QPointF &defaultValue = QPointF(), const QString &key = QString());
1544
1545 /*!
1546 * Register an item of type QSize.
1547 *
1548 * \a name Name used to identify this setting. Names must be unique.
1549 *
1550 * \a reference Pointer to the variable, which is set by readConfig()
1551 * calls and read by save() calls.
1552 *
1553 * \a defaultValue Default value, which is used when the config file
1554 * does not yet contain the key of this item.
1555 *
1556 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1557 *
1558 * Returns the created item
1559 */
1560 ItemSize *addItemSize(const QString &name, QSize &reference, const QSize &defaultValue = QSize(), const QString &key = QString());
1561
1562 /*!
1563 * Register an item of type QSizeF.
1564 *
1565 * \a name Name used to identify this setting. Names must be unique.
1566 *
1567 * \a reference Pointer to the variable, which is set by readConfig()
1568 * calls and read by save() calls.
1569 *
1570 * \a defaultValue Default value, which is used when the config file
1571 * does not yet contain the key of this item.
1572 *
1573 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1574 *
1575 * Returns the created item
1576 */
1577 ItemSizeF *addItemSizeF(const QString &name, QSizeF &reference, const QSizeF &defaultValue = QSizeF(), const QString &key = QString());
1578
1579 /*!
1580 * Register an item of type QDateTime.
1581 *
1582 * \a name Name used to identify this setting. Names must be unique.
1583 *
1584 * \a reference Pointer to the variable, which is set by readConfig()
1585 * calls and read by save() calls.
1586 *
1587 * \a defaultValue Default value, which is used when the config file
1588 * does not yet contain the key of this item.
1589 *
1590 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1591 *
1592 * Returns the created item
1593 */
1594 ItemDateTime *addItemDateTime(const QString &name, QDateTime &reference, const QDateTime &defaultValue = QDateTime(), const QString &key = QString());
1595
1596 /*!
1597 * Register an item of type QTime.
1598 *
1599 * \a name Name used to identify this setting. Names must be unique.
1600 *
1601 * \a reference Pointer to the variable, which is set by readConfig()
1602 * calls and read by save() calls.
1603 *
1604 * \a defaultValue Default value, which is used when the config file
1605 * does not yet contain the key of this item.
1606 *
1607 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1608 *
1609 * Returns the created item
1610 *
1611 * \since 6.16
1612 */
1613 ItemTime *addItemTime(const QString &name, QTime &reference, QTime defaultValue = QTime(), const QString &key = QString());
1614
1615 /*!
1616 * Register an item of type QStringList.
1617 *
1618 * \a name Name used to identify this setting. Names must be unique.
1619 *
1620 * \a reference Pointer to the variable, which is set by readConfig()
1621 * calls and read by save() calls.
1622 *
1623 * \a defaultValue Default value, which is used when the config file
1624 * does not yet contain the key of this item.
1625 *
1626 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1627 *
1628 * Returns the created item
1629 */
1630 ItemStringList *
1631 addItemStringList(const QString &name, QStringList &reference, const QStringList &defaultValue = QStringList(), const QString &key = QString());
1632
1633 /*!
1634 * Register an item of type QList<int>.
1635 *
1636 * \a name Name used to identify this setting. Names must be unique.
1637 *
1638 * \a reference Pointer to the variable, which is set by readConfig()
1639 * calls and read by save() calls.
1640 *
1641 * \a defaultValue Default value, which is used when the config file
1642 * does not yet contain the key of this item.
1643 *
1644 * \a key Key used in config file. If \a key is a null string, \a name is used as key.
1645 *
1646 * Returns the created item
1647 */
1648 ItemIntList *addItemIntList(const QString &name, QList<int> &reference, const QList<int> &defaultValue = QList<int>(), const QString &key = QString());
1649
1650 /*!
1651 * Return the KConfig object used for reading and writing the settings.
1652 */
1653 KConfig *config();
1654
1655 /*!
1656 * Return the KConfig object used for reading and writing the settings.
1657 */
1658 const KConfig *config() const;
1659
1660 /*!
1661 * Return the KConfig object used for reading and writing the settings.
1662 * \since 5.0
1663 */
1664 KSharedConfig::Ptr sharedConfig() const;
1665
1666 /*!
1667 * Set the KSharedConfig object used for reading and writing the settings.
1668 */
1669 void setSharedConfig(KSharedConfig::Ptr pConfig);
1670
1671 /*!
1672 * Return list of items managed by this KCoreConfigSkeleton object.
1673 */
1674 KConfigSkeletonItem::List items() const;
1675
1676 /*!
1677 * Removes and deletes an item by name
1678 *
1679 * \a name the name of the item to remove
1680 */
1681 void removeItem(const QString &name);
1682
1683 /*!
1684 * Removes and deletes all items
1685 */
1686 void clearItems();
1687
1688 /*!
1689 * Return whether a certain item is immutable
1690 * \since 4.4
1691 */
1692 Q_INVOKABLE bool isImmutable(const QString &name) const;
1693
1694 /*!
1695 * Lookup item by name
1696 * \since 4.4
1697 */
1698 KConfigSkeletonItem *findItem(const QString &name) const;
1699
1700 /*!
1701 * Specify whether this object should reflect the actual values or the
1702 * default values.
1703 * This method is implemented by usrUseDefaults(), which can be overridden
1704 * in derived classes if you have special requirements and can call
1705 * usrUseDefaults() directly.
1706 * If you don't have control whether useDefaults() or usrUseDefaults() is
1707 * called override useDefaults() directly.
1708 *
1709 * \a b \c true to make this object reflect the default values,
1710 * \c false to make it reflect the actual values.
1711 * Returns the state prior to this call
1712 */
1713 virtual bool useDefaults(bool b);
1714
1715public Q_SLOTS:
1716 /*!
1717 * Write preferences to config file. The values of all registered items are
1718 * written to disk.
1719 * This method calls usrSave() after writing the settings from the
1720 * registered items to the KConfig. You can override usrSave()
1721 * in derived classes if you have special requirements.
1722 */
1723 bool save();
1724
1725Q_SIGNALS:
1726 /*!
1727 * This signal is emitted when the configuration change.
1728 */
1729 void configChanged();
1730
1731protected:
1732 /*!
1733 * Implemented by subclasses that use special defaults.
1734 * It replaces the default values with the actual values and
1735 * vice versa. Called from useDefaults()
1736 *
1737 * \a b \c true to make this object reflect the default values,
1738 * \c false to make it reflect the actual values.
1739 *
1740 * Returns the state prior to this call
1741 */
1742 virtual bool usrUseDefaults(bool b);
1743
1744 /*!
1745 * Perform the actual setting of default values.
1746 * Override in derived classes to set special default values.
1747 * Called from setDefaults()
1748 */
1749 virtual void usrSetDefaults();
1750
1751 /*!
1752 * Perform the actual reading of the configuration file.
1753 * Override in derived classes to read special config values.
1754 * Called from read()
1755 */
1756 virtual void usrRead();
1757
1758 /*!
1759 * Perform the actual writing of the configuration file.
1760 * Override in derived classes to write special config values.
1761 * Called from save()
1762 */
1763 virtual bool usrSave();
1764
1765private:
1766 KCoreConfigSkeletonPrivate *const d;
1767 friend class KConfigSkeleton;
1768};
1769
1770Q_DECLARE_TYPEINFO(KCoreConfigSkeleton::ItemEnum::Choice, Q_RELOCATABLE_TYPE);
1771
1772#endif
1773

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