KConfig

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

KDE's Doxygen guidelines are available online.