1/*
2 * This file is part of KDE.
3 *
4 * Copyright (c) 2001,2002,2003 Cornelius Schumacher <schumacher@kde.org>
5 * Copyright (c) 2003 Waldo Bastian <bastian@kde.org>
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public License
18 * along with this library; see the file COPYING.LIB. If not, write to
19 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef KCORECONFIGSKELETON_H
24#define KCORECONFIGSKELETON_H
25
26#include <kdecore_export.h>
27
28#include <kurl.h>
29#include <ksharedconfig.h>
30#include <kconfiggroup.h>
31
32#include <QtCore/QDate>
33#include <QtCore/QHash>
34#include <QtCore/QRect>
35#include <QtCore/QStringList>
36#include <QtCore/QVariant>
37
38 class KConfigSkeletonItemPrivate;
39 /**
40 * \class KConfigSkeletonItem kcoreconfigskeleton.h <KConfigSkeletonItem>
41 *
42 * @short Class for storing a preferences setting
43 * @author Cornelius Schumacher
44 * @see KCoreConfigSkeleton
45 *
46 * This class represents one preferences setting as used by @ref KCoreConfigSkeleton.
47 * Subclasses of KConfigSkeletonItem implement storage functions for a certain type of
48 * setting. Normally you don't have to use this class directly. Use the special
49 * addItem() functions of KCoreConfigSkeleton instead. If you subclass this class you will
50 * have to register instances with the function KCoreConfigSkeleton::addItem().
51 */
52 class KDECORE_EXPORT KConfigSkeletonItem
53 {
54 public:
55 typedef QList < KConfigSkeletonItem * >List;
56 typedef QHash < QString, KConfigSkeletonItem* > Dict;
57 typedef QHash < QString, KConfigSkeletonItem* >::Iterator DictIterator;
58
59 /**
60 * Constructor.
61 *
62 * @param _group Config file group.
63 * @param _key Config file key.
64 */
65 KConfigSkeletonItem(const QString & _group, const QString & _key);
66
67 /**
68 * Destructor.
69 */
70 virtual ~KConfigSkeletonItem();
71
72 /**
73 * Set config file group.
74 */
75 void setGroup( const QString &_group );
76
77 /**
78 * Return config file group.
79 */
80 QString group() const;
81
82 /**
83 * Set config file key.
84 */
85 void setKey( const QString &_key );
86
87 /**
88 * Return config file key.
89 */
90 QString key() const;
91
92 /**
93 * Set internal name of entry.
94 */
95 void setName(const QString &_name);
96
97 /**
98 * Return internal name of entry.
99 */
100 QString name() const;
101
102 /**
103 Set label providing a translated one-line description of the item.
104 */
105 void setLabel( const QString &l );
106
107 /**
108 Return label of item. See setLabel().
109 */
110 QString label() const;
111
112 /**
113 Set ToolTip description of item.
114 @since 4.2
115 */
116 void setToolTip( const QString &t );
117
118 /**
119 Return ToolTip description of item. See setToolTip().
120 @since 4.2
121 */
122 QString toolTip() const;
123
124 /**
125 Set WhatsThis description of item.
126 */
127 void setWhatsThis( const QString &w );
128
129 /**
130 Return WhatsThis description of item. See setWhatsThis().
131 */
132 QString whatsThis() const;
133
134 /**
135 * This function is called by @ref KCoreConfigSkeleton to read the value for this setting
136 * from a config file.
137 */
138 virtual void readConfig(KConfig *) = 0;
139
140 /**
141 * This function is called by @ref KCoreConfigSkeleton to write the value of this setting
142 * to a config file.
143 */
144 virtual void writeConfig(KConfig *) = 0;
145
146 /**
147 * Read global default value.
148 */
149 virtual void readDefault(KConfig *) = 0;
150
151 /**
152 * Set item to @p p
153 */
154 virtual void setProperty(const QVariant &p) = 0;
155
156 /**
157 * Check whether the item is equal to p.
158 *
159 * Use this function to compare items that use custom types such as KUrl,
160 * because QVariant::operator== will not work for those.
161 *
162 * @param p QVariant to compare to
163 * @return true if the item is equal to p, false otherwise
164 */
165 virtual bool isEqual(const QVariant &p) const = 0;
166
167 /**
168 * Return item as property
169 */
170 virtual QVariant property() const = 0;
171
172 /**
173 * Return minimum value of item or invalid if not specified
174 */
175 virtual QVariant minValue() const;
176
177 /**
178 * Return maximum value of item or invalid if not specified
179 */
180 virtual QVariant maxValue() const;
181
182 /**
183 * Sets the current value to the default value.
184 */
185 virtual void setDefault() = 0;
186
187 /**
188 * Exchanges the current value with the default value
189 * Used by KCoreConfigSkeleton::useDefaults(bool);
190 */
191 virtual void swapDefault() = 0;
192
193 /**
194 * Return if the entry can be modified.
195 */
196 bool isImmutable() const;
197
198 protected:
199 /**
200 * sets mIsImmutable to true if mKey in config is immutable
201 * @param group KConfigGroup to check if mKey is immutable in
202 */
203 void readImmutability(const KConfigGroup &group);
204
205 QString mGroup; ///< The group name for this item
206 QString mKey; ///< The config key for this item
207 QString mName; ///< The name of this item
208
209 private:
210 KConfigSkeletonItemPrivate * const d;
211 };
212
213
214/**
215 * \class KConfigSkeletonGenericItem kcoreconfigskeleton.h <KConfigSkeletonGenericItem>
216 */
217template < typename T > class KConfigSkeletonGenericItem:public KConfigSkeletonItem
218 {
219 public:
220 /** @copydoc KConfigSkeletonItem(const QString&, const QString&)
221 @param reference The initial value to hold in the item
222 @param defaultValue The default value for the item
223 */
224 KConfigSkeletonGenericItem(const QString & _group, const QString & _key, T & reference,
225 T defaultValue)
226 : KConfigSkeletonItem(_group, _key), mReference(reference),
227 mDefault(defaultValue), mLoadedValue(defaultValue)
228 {
229 }
230
231 /**
232 * Set value of this KConfigSkeletonItem.
233 */
234 void setValue(const T & v)
235 {
236 mReference = v;
237 }
238
239 /**
240 * Return value of this KConfigSkeletonItem.
241 */
242 T & value()
243 {
244 return mReference;
245 }
246
247 /**
248 * Return const value of this KConfigSkeletonItem.
249 */
250 const T & value() const
251 {
252 return mReference;
253 }
254
255 /**
256 Set default value for this item.
257 */
258 virtual void setDefaultValue( const T &v )
259 {
260 mDefault = v;
261 }
262
263 /**
264 Set the value for this item to the default value
265 */
266 virtual void setDefault()
267 {
268 mReference = mDefault;
269 }
270
271 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig *) */
272 virtual void writeConfig(KConfig * config)
273 {
274 if ( mReference != mLoadedValue ) // Is this needed?
275 {
276 KConfigGroup cg(config, mGroup);
277 if ((mDefault == mReference) && !cg.hasDefault( mKey))
278 cg.revertToDefault( mKey );
279 else
280 cg.writeEntry(mKey, mReference);
281 }
282 }
283
284 /** @copydoc KConfigSkeletonItem::readDefault(KConfig*) */
285 void readDefault(KConfig * config)
286 {
287 config->setReadDefaults(true);
288 readConfig(config);
289 config->setReadDefaults(false);
290 mDefault = mReference;
291 }
292
293 /** @copydoc KConfigSkeletonItem::swapDefault() */
294 void swapDefault()
295 {
296 T tmp = mReference;
297 mReference = mDefault;
298 mDefault = tmp;
299 }
300
301 protected:
302 T & mReference; ///< Stores the value for this item
303 T mDefault; ///< The default value for this item
304 T mLoadedValue;
305 };
306
307 /**
308 * \class KCoreConfigSkeleton kcoreconfigskeleton.h <KCoreConfigSkeleton>
309 *
310 * @short Class for handling preferences settings for an application.
311 * @author Cornelius Schumacher
312 * @see KConfigSkeletonItem
313 *
314 * This class provides an interface to preferences settings. Preferences items
315 * can be registered by the addItem() function corresponding to the data type of
316 * the setting. KCoreConfigSkeleton then handles reading and writing of config files and
317 * setting of default values.
318 *
319 * Normally you will subclass KCoreConfigSkeleton, add data members for the preferences
320 * settings and register the members in the constructor of the subclass.
321 *
322 * Example:
323 * \code
324 * class MyPrefs : public KCoreConfigSkeleton
325 * {
326 * public:
327 * MyPrefs()
328 * {
329 * setCurrentGroup("MyGroup");
330 * addItemBool("MySetting1", mMyBool, false);
331 * addItemPoint("MySetting2", mMyPoint, QPoint(100, 200));
332 *
333 * setCurrentGroup("MyOtherGroup");
334 * addItemDouble("MySetting3", mMyDouble, 3.14);
335 * }
336 *
337 * bool mMyBool;
338 * QPoint mMyPoint;
339 * double mMyDouble;
340 * }
341 * \endcode
342 *
343 * It might be convenient in many cases to make this subclass of KCoreConfigSkeleton a
344 * singleton for global access from all over the application without passing
345 * references to the KCoreConfigSkeleton object around.
346 *
347 * You can write the data to the configuration file by calling @ref writeConfig()
348 * and read the data from the configuration file by calling @ref readConfig().
349 * If you want to watch for config changes, use @ref configChanged() signal.
350 *
351 * If you have items, which are not covered by the existing addItem() functions
352 * you can add customized code for reading, writing and default setting by
353 * implementing the functions @ref usrUseDefaults(), @ref usrReadConfig() and
354 * @ref usrWriteConfig().
355 *
356 * Internally preferences settings are stored in instances of subclasses of
357 * @ref KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses
358 * for your own types and call the generic @ref addItem() to register them.
359 *
360 * In many cases you don't have to write the specific KCoreConfigSkeleton
361 * subclasses yourself, but you can use \ref kconfig_compiler to automatically
362 * generate the C++ code from an XML description of the configuration options.
363 *
364 * Use KConfigSkeleton if you need GUI types as well.
365 */
366class KDECORE_EXPORT KCoreConfigSkeleton : public QObject
367{
368 Q_OBJECT
369public:
370 /**
371 * Class for handling a string preferences item.
372 */
373 class KDECORE_EXPORT ItemString:public KConfigSkeletonGenericItem < QString >
374 {
375 public:
376 enum Type { Normal, Password, Path };
377
378 /** @enum Type
379 The type of string that is held in this item
380
381 @var ItemString::Type ItemString::Normal
382 A normal string
383
384 @var ItemString::Type ItemString::Password
385 A password string
386
387 @var ItemString::Type ItemString::Path
388 A path to a file or directory
389 */
390
391
392 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem
393 @param type The type of string held by the item
394 */
395 ItemString(const QString & _group, const QString & _key,
396 QString & reference,
397 const QString & defaultValue = QLatin1String(""), // NOT QString() !!
398 Type type = Normal);
399
400 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
401 void writeConfig(KConfig * config);
402
403 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
404 void readConfig(KConfig * config);
405
406 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
407 void setProperty(const QVariant & p);
408
409 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
410 bool isEqual(const QVariant &p) const;
411
412 /** @copydoc KConfigSkeletonItem::property() const */
413 QVariant property() const;
414
415 private:
416 Type mType;
417 };
418
419 /**
420 * Class for handling a password preferences item.
421 */
422 class KDECORE_EXPORT ItemPassword:public ItemString
423 {
424 public:
425 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
426 ItemPassword(const QString & _group, const QString & _key,
427 QString & reference,
428 const QString & defaultValue = QLatin1String("")); // NOT QString() !!
429 };
430
431 /**
432 * Class for handling a path preferences item.
433 */
434 class KDECORE_EXPORT ItemPath:public ItemString
435 {
436 public:
437 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
438 ItemPath(const QString & _group, const QString & _key,
439 QString & reference,
440 const QString & defaultValue = QString());
441 };
442
443 /**
444 * Class for handling a url preferences item.
445 */
446 class KDECORE_EXPORT ItemUrl:public KConfigSkeletonGenericItem < KUrl >
447 {
448 public:
449
450 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem
451 */
452 ItemUrl(const QString & _group, const QString & _key,
453 KUrl & reference,
454 const KUrl & defaultValue = KUrl());
455
456 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
457 void writeConfig(KConfig * config);
458
459 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
460 void readConfig(KConfig * config);
461
462 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
463 void setProperty(const QVariant & p);
464
465 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
466 bool isEqual(const QVariant &p) const;
467
468 /** @copydoc KConfigSkeletonItem::property() const */
469 QVariant property() const;
470 };
471
472 /**
473 * Class for handling a QVariant preferences item.
474 */
475 class KDECORE_EXPORT ItemProperty:public KConfigSkeletonGenericItem < QVariant >
476 {
477 public:
478 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
479 ItemProperty(const QString & _group, const QString & _key,
480 QVariant & reference, const QVariant & defaultValue = 0);
481
482 void readConfig(KConfig * config);
483 void setProperty(const QVariant & p);
484
485 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
486 bool isEqual(const QVariant &p) const;
487
488 /** @copydoc KConfigSkeletonItem::property() const */
489 QVariant property() const;
490 };
491
492
493 /**
494 * Class for handling a bool preferences item.
495 */
496 class KDECORE_EXPORT ItemBool:public KConfigSkeletonGenericItem < bool >
497 {
498 public:
499 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
500 ItemBool(const QString & _group, const QString & _key, bool & reference,
501 bool defaultValue = true);
502
503 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
504 void readConfig(KConfig * config);
505
506 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
507 void setProperty(const QVariant & p);
508
509 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
510 bool isEqual(const QVariant &p) const;
511
512 /** @copydoc KConfigSkeletonItem::property() const */
513 QVariant property() const;
514 };
515
516
517 /**
518 * Class for handling a 32-bit integer preferences item.
519 */
520 class KDECORE_EXPORT ItemInt:public KConfigSkeletonGenericItem < qint32 >
521 {
522 public:
523 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
524 ItemInt(const QString & _group, const QString & _key, qint32 &reference,
525 qint32 defaultValue = 0);
526
527 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
528 void readConfig(KConfig * config);
529
530 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
531 void setProperty(const QVariant & p);
532
533 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
534 bool isEqual(const QVariant &p) const;
535
536 /** @copydoc KConfigSkeletonItem::property() */
537 QVariant property() const;
538
539 /** Get the minimum value that is allowed to be stored in this item */
540 QVariant minValue() const;
541
542 /** Get the maximum value this is allowed to be stored in this item */
543 QVariant maxValue() const;
544
545 /** Set the minimum value for the item
546 @sa minValue()
547 */
548 void setMinValue(qint32);
549
550 /** Set the maximum value for the item
551 @sa maxValue
552 */
553 void setMaxValue(qint32);
554
555 private:
556 bool mHasMin : 1;
557 bool mHasMax : 1;
558 qint32 mMin;
559 qint32 mMax;
560 };
561
562 /**
563 * Class for handling a 64-bit integer preferences item.
564 */
565 class KDECORE_EXPORT ItemLongLong:public KConfigSkeletonGenericItem < qint64 >
566 {
567 public:
568 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
569 ItemLongLong(const QString & _group, const QString & _key, qint64 &reference,
570 qint64 defaultValue = 0);
571
572 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
573 void readConfig(KConfig * config);
574
575 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
576 void setProperty(const QVariant & p);
577
578 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
579 bool isEqual(const QVariant &p) const;
580
581 /** @copydoc KConfigSkeletonItem::property() */
582 QVariant property() const;
583
584 /** @copydoc ItemInt::minValue() */
585 QVariant minValue() const;
586
587 /** @copydoc ItemInt::maxValue() */
588 QVariant maxValue() const;
589
590 /** @copydoc ItemInt::setMinValue(qint32) */
591 void setMinValue(qint64);
592
593 /** @copydoc ItemInt::setMaxValue(qint32) */
594 void setMaxValue(qint64);
595
596 private:
597 bool mHasMin : 1;
598 bool mHasMax : 1;
599 qint64 mMin;
600 qint64 mMax;
601 };
602#ifndef KDE_NO_DEPRECATED
603 typedef KDE_DEPRECATED ItemLongLong ItemInt64;
604#endif
605
606 /**
607 * Class for handling enums.
608 */
609 class KDECORE_EXPORT ItemEnum:public ItemInt
610 {
611 public:
612 //KDE5: remove the old Choice struct, rename Choice2 to Choice
613 struct Choice
614 {
615 QString name;
616 QString label;
617 QString whatsThis;
618 };
619
620 struct Choice2
621 {
622 QString name;
623 QString label;
624 QString toolTip;
625 QString whatsThis;
626 };
627
628 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem
629 @param choices The list of enums that can be stored in this item
630 */
631 ItemEnum(const QString & _group, const QString & _key, qint32 &reference,
632 const QList<Choice> &choices, qint32 defaultValue = 0);
633
634 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem
635 @param choices The list of enums that can be stored in this item
636 */
637 ItemEnum(const QString & _group, const QString & _key, qint32 &reference,
638 const QList<Choice2> &choices, qint32 defaultValue = 0);
639
640 QList<Choice> choices() const;
641 QList<Choice2> choices2() const;
642
643 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
644 void readConfig(KConfig * config);
645
646 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
647 void writeConfig(KConfig * config);
648
649 private:
650 QList<Choice2> mChoices;
651 };
652
653
654 /**
655 * Class for handling an unsigned 32-bit integer preferences item.
656 */
657 class KDECORE_EXPORT ItemUInt:public KConfigSkeletonGenericItem < quint32 >
658 {
659 public:
660 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
661 ItemUInt(const QString & _group, const QString & _key,
662 quint32 &reference, quint32 defaultValue = 0);
663
664 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
665 void readConfig(KConfig * config);
666
667 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
668 void setProperty(const QVariant & p);
669
670 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
671 bool isEqual(const QVariant &p) const;
672
673 /** @copydoc KConfigSkeletonItem::property() */
674 QVariant property() const;
675
676 /** @copydoc ItemInt::minValue() */
677 QVariant minValue() const;
678
679 /** @copydoc ItemInt::maxValue() */
680 QVariant maxValue() const;
681
682 /** @copydoc ItemInt::setMinValue(qint32) */
683 void setMinValue(quint32);
684
685 /** @copydoc ItemInt::setMaxValue(qint32) */
686 void setMaxValue(quint32);
687
688 private:
689 bool mHasMin : 1;
690 bool mHasMax : 1;
691 quint32 mMin;
692 quint32 mMax;
693 };
694
695 /**
696 * Class for handling unsigned 64-bit integer preferences item.
697 */
698 class KDECORE_EXPORT ItemULongLong:public KConfigSkeletonGenericItem < quint64 >
699 {
700 public:
701 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
702 ItemULongLong(const QString & _group, const QString & _key, quint64 &reference,
703 quint64 defaultValue = 0);
704
705 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
706 void readConfig(KConfig * config);
707
708 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
709 void setProperty(const QVariant & p);
710
711 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
712 bool isEqual(const QVariant &p) const;
713
714 /** @copydoc KConfigSkeletonItem::property() */
715 QVariant property() const;
716
717 /** @copydoc ItemInt::minValue() */
718 QVariant minValue() const;
719
720 /** @copydoc ItemInt::maxValue() */
721 QVariant maxValue() const;
722
723 /** @copydoc ItemInt::setMinValue(qint32) */
724 void setMinValue(quint64);
725
726 /** @copydoc ItemInt::setMaxValue(qint32) */
727 void setMaxValue(quint64);
728
729 private:
730 bool mHasMin : 1;
731 bool mHasMax : 1;
732 quint64 mMin;
733 quint64 mMax;
734 };
735#ifndef KDE_NO_DEPRECATED
736 typedef KDE_DEPRECATED ItemULongLong ItemUInt64;
737#endif
738
739 /**
740 * Class for handling a floating point preference item.
741 */
742 class KDECORE_EXPORT ItemDouble:public KConfigSkeletonGenericItem < double >
743 {
744 public:
745 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
746 ItemDouble(const QString & _group, const QString & _key,
747 double &reference, double defaultValue = 0);
748
749 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
750 void readConfig(KConfig * config);
751
752 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
753 void setProperty(const QVariant & p);
754
755 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
756 bool isEqual(const QVariant &p) const;
757
758 /** @copydoc KConfigSkeletonItem::property() */
759 QVariant property() const;
760
761 /** @copydoc ItemInt::minValue() */
762 QVariant minValue() const;
763
764 /** @copydoc ItemInt::maxValue() */
765 QVariant maxValue() const;
766
767 /** @copydoc ItemInt::setMinValue() */
768 void setMinValue(double);
769
770 /** @copydoc ItemInt::setMaxValue() */
771 void setMaxValue(double);
772
773 private:
774 bool mHasMin : 1;
775 bool mHasMax : 1;
776 double mMin;
777 double mMax;
778 };
779
780
781 /**
782 * Class for handling a QRect preferences item.
783 */
784 class KDECORE_EXPORT ItemRect:public KConfigSkeletonGenericItem < QRect >
785 {
786 public:
787 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
788 ItemRect(const QString & _group, const QString & _key, QRect & reference,
789 const QRect & defaultValue = QRect());
790
791 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
792 void readConfig(KConfig * config);
793
794 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
795 void setProperty(const QVariant & p);
796
797 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
798 bool isEqual(const QVariant &p) const;
799
800 /** @copydoc KConfigSkeletonItem::property() */
801 QVariant property() const;
802 };
803
804
805 /**
806 * Class for handling a QPoint preferences item.
807 */
808 class KDECORE_EXPORT ItemPoint:public KConfigSkeletonGenericItem < QPoint >
809 {
810 public:
811 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
812 ItemPoint(const QString & _group, const QString & _key, QPoint & reference,
813 const QPoint & defaultValue = QPoint());
814
815 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
816 void readConfig(KConfig * config);
817
818 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
819 void setProperty(const QVariant & p);
820
821 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
822 bool isEqual(const QVariant &p) const;
823
824 /** @copydoc KConfigSkeletonItem::property() */
825 QVariant property() const;
826 };
827
828
829 /**
830 * Class for handling a QSize preferences item.
831 */
832 class KDECORE_EXPORT ItemSize:public KConfigSkeletonGenericItem < QSize >
833 {
834 public:
835 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
836 ItemSize(const QString & _group, const QString & _key, QSize & reference,
837 const QSize & defaultValue = QSize());
838
839 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
840 void readConfig(KConfig * config);
841
842 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
843 void setProperty(const QVariant & p);
844
845 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
846 bool isEqual(const QVariant &p) const;
847
848 /** @copydoc KConfigSkeletonItem::property() */
849 QVariant property() const;
850 };
851
852
853 /**
854 * Class for handling a QDateTime preferences item.
855 */
856 class KDECORE_EXPORT ItemDateTime:public KConfigSkeletonGenericItem < QDateTime >
857 {
858 public:
859 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
860 ItemDateTime(const QString & _group, const QString & _key,
861 QDateTime & reference,
862 const QDateTime & defaultValue = QDateTime());
863
864 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
865 void readConfig(KConfig * config);
866
867 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
868 void setProperty(const QVariant & p);
869
870 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
871 bool isEqual(const QVariant &p) const;
872
873 /** @copydoc KConfigSkeletonItem::property() */
874 QVariant property() const;
875 };
876
877
878 /**
879 * Class for handling a string list preferences item.
880 */
881 class KDECORE_EXPORT ItemStringList:public KConfigSkeletonGenericItem < QStringList >
882 {
883 public:
884 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
885 ItemStringList(const QString & _group, const QString & _key,
886 QStringList & reference,
887 const QStringList & defaultValue = QStringList());
888
889 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
890 void readConfig(KConfig * config);
891
892 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
893 void setProperty(const QVariant & p);
894
895 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
896 bool isEqual(const QVariant &p) const;
897
898 /** @copydoc KConfigSkeletonItem::property() */
899 QVariant property() const;
900 };
901
902
903 /**
904 * Class for handling a path list preferences item.
905 */
906 class KDECORE_EXPORT ItemPathList:public ItemStringList
907 {
908 public:
909 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
910 ItemPathList(const QString & _group, const QString & _key,
911 QStringList & reference,
912 const QStringList & defaultValue = QStringList());
913
914 /** @copydoc KConfigSkeletonItem::readConfig */
915 void readConfig(KConfig * config);
916 /** @copydoc KConfigSkeletonItem::writeConfig */
917 void writeConfig(KConfig * config);
918 };
919
920 /**
921 * Class for handling a url list preferences item.
922 */
923 class KDECORE_EXPORT ItemUrlList:public KConfigSkeletonGenericItem < KUrl::List >
924 {
925 public:
926 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
927 ItemUrlList(const QString & _group, const QString & _key,
928 KUrl::List & reference,
929 const KUrl::List & defaultValue = KUrl::List());
930
931 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
932 void readConfig(KConfig * config);
933
934 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */
935 void writeConfig(KConfig * config);
936
937 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
938 void setProperty(const QVariant & p);
939
940 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
941 bool isEqual(const QVariant &p) const;
942
943 /** @copydoc KConfigSkeletonItem::property() */
944 QVariant property() const;
945 };
946
947 /**
948 * Class for handling an integer list preferences item.
949 */
950 class KDECORE_EXPORT ItemIntList:public KConfigSkeletonGenericItem < QList < int > >
951 {
952 public:
953 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */
954 ItemIntList(const QString & _group, const QString & _key,
955 QList < int >&reference,
956 const QList < int >&defaultValue = QList < int >());
957
958 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */
959 void readConfig(KConfig * config);
960
961 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */
962 void setProperty(const QVariant & p);
963
964 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */
965 bool isEqual(const QVariant &p) const;
966
967 /** @copydoc KConfigSkeletonItem::property() */
968 QVariant property() const;
969 };
970
971
972public:
973 /**
974 * Constructor.
975 *
976 * @param configname name of config file. If no name is given, the default
977 * config file as returned by KGlobal::config() is used
978 * @param parent the parent object (see QObject documentation)
979 */
980 explicit KCoreConfigSkeleton(const QString & configname = QString(), QObject* parent = 0);
981
982 /**
983 * Constructor.
984 *
985 * @param config configuration object to use
986 * @param parent the parent object (see QObject documentation)
987 */
988 explicit KCoreConfigSkeleton(KSharedConfig::Ptr config, QObject* parent = 0);
989
990 /**
991 * Destructor
992 */
993 virtual ~KCoreConfigSkeleton();
994
995 /**
996 * Set all registered items to their default values.
997 * This method calls usrSetDefaults() after setting the defaults for the
998 * registered items. You can overridde usrSetDefaults() in derived classes
999 * if you have special requirements.
1000 * If you need more fine-grained control of setting the default values of
1001 * the registered items you can override setDefaults() in a derived class.
1002 */
1003 virtual void setDefaults();
1004
1005 /**
1006 * Read preferences from config file. All registered items are set to the
1007 * values read from disk.
1008 * This method calls usrReadConfig() after reading the settings of the
1009 * registered items from the KConfig. You can overridde usrReadConfig()
1010 * in derived classes if you have special requirements.
1011 * If you need more fine-grained control of storing the settings from
1012 * the registered items you can override readConfig() in a derived class.
1013 */
1014 virtual void readConfig();
1015
1016 /**
1017 * Write preferences to config file. The values of all registered items are
1018 * written to disk.
1019 * This method calls usrWriteConfig() after writing the settings from the
1020 * registered items to the KConfig. You can overridde usrWriteConfig()
1021 * in derived classes if you have special requirements.
1022 * If you need more fine-grained control of storing the settings from
1023 * the registered items you can override writeConfig() in a derived class.
1024 */
1025 virtual void writeConfig();
1026
1027 /**
1028 * Set the config file group for subsequent addItem() calls. It is valid
1029 * until setCurrentGroup() is called with a new argument. Call this before
1030 * you add any items. The default value is "No Group".
1031 */
1032 void setCurrentGroup(const QString & group);
1033
1034 /**
1035 * Returns the current group used for addItem() calls.
1036 */
1037 QString currentGroup() const;
1038
1039 /**
1040 * Register a custom @ref KConfigSkeletonItem with a given name.
1041 *
1042 * If the name parameter is null, take the name from KConfigSkeletonItem::key().
1043 * Note that all names must be unique but that multiple entries can have
1044 * the same key if they reside in different groups.
1045 *
1046 * KCoreConfigSkeleton takes ownership of the KConfigSkeletonItem.
1047 */
1048 void addItem(KConfigSkeletonItem *, const QString & name = QString() );
1049
1050 /**
1051 * Register an item of type QString.
1052 *
1053 * @param name Name used to identify this setting. Names must be unique.
1054 * @param reference Pointer to the variable, which is set by readConfig()
1055 * calls and read by writeConfig() calls.
1056 * @param defaultValue Default value, which is used when the config file
1057 * does not yet contain the key of this item.
1058 * @param key Key used in config file. If key is null, name is used as key.
1059 * @return The created item
1060 */
1061 ItemString *addItemString(const QString & name, QString & reference,
1062 const QString & defaultValue = QLatin1String(""), // NOT QString() !!
1063 const QString & key = QString());
1064
1065 /**
1066 * Register a password item of type QString. The string value is written
1067 * encrypted to the config file. Note that the current encryption scheme
1068 * is very weak.
1069 *
1070 * @param name Name used to identify this setting. Names must be unique.
1071 * @param reference Pointer to the variable, which is set by readConfig()
1072 * calls and read by writeConfig() calls.
1073 * @param defaultValue Default value, which is used when the config file
1074 * does not yet contain the key of this item.
1075 * @param key Key used in config file. If key is null, name is used as key.
1076 * @return The created item
1077 */
1078 ItemPassword *addItemPassword(const QString & name, QString & reference,
1079 const QString & defaultValue = QLatin1String(""),
1080 const QString & key = QString());
1081
1082 /**
1083 * Register a path item of type QString. The string value is interpreted
1084 * as a path. This means, dollar expension is activated for this value, so
1085 * that e.g. $HOME gets expanded.
1086 *
1087 * @param name Name used to identify this setting. Names must be unique.
1088 * @param reference Pointer to the variable, which is set by readConfig()
1089 * calls and read by writeConfig() calls.
1090 * @param defaultValue Default value, which is used when the config file
1091 * does not yet contain the key of this item.
1092 * @param key Key used in config file. If key is null, name is used as key.
1093 * @return The created item
1094 */
1095 ItemPath *addItemPath(const QString & name, QString & reference,
1096 const QString & defaultValue = QLatin1String(""),
1097 const QString & key = QString());
1098
1099 /**
1100 * Register a property item of type QVariant. Note that only the following
1101 * QVariant types are allowed: String, StringList, Font, Point, Rect, Size,
1102 * Color, Int, UInt, Bool, Double, DateTime and Date.
1103 *
1104 * @param name Name used to identify this setting. Names must be unique.
1105 * @param reference Pointer to the variable, which is set by readConfig()
1106 * calls and read by writeConfig() calls.
1107 * @param defaultValue Default value, which is used when the config file
1108 * does not yet contain the key of this item.
1109 * @param key Key used in config file. If key is null, name is used as key.
1110 * @return The created item
1111 */
1112 ItemProperty *addItemProperty(const QString & name, QVariant & reference,
1113 const QVariant & defaultValue = QVariant(),
1114 const QString & key = QString());
1115 /**
1116 * Register an item of type bool.
1117 *
1118 * @param name Name used to identify this setting. Names must be unique.
1119 * @param reference Pointer to the variable, which is set by readConfig()
1120 * calls and read by writeConfig() calls.
1121 * @param defaultValue Default value, which is used when the config file
1122 * does not yet contain the key of this item.
1123 * @param key Key used in config file. If key is null, name is used as key.
1124 * @return The created item
1125 */
1126 ItemBool *addItemBool(const QString & name, bool & reference,
1127 bool defaultValue = false,
1128 const QString & key = QString());
1129
1130 /**
1131 * Register an item of type qint32.
1132 *
1133 * @param name Name used to identify this setting. Names must be unique.
1134 * @param reference Pointer to the variable, which is set by readConfig()
1135 * calls and read by writeConfig() calls.
1136 * @param defaultValue Default value, which is used when the config file
1137 * does not yet contain the key of this item.
1138 * @param key Key used in config file. If key is null, name is used as key.
1139 * @return The created item
1140 */
1141 ItemInt *addItemInt(const QString & name, qint32 &reference, qint32 defaultValue = 0,
1142 const QString & key = QString());
1143
1144 /**
1145 * Register an item of type quint32.
1146 *
1147 * @param name Name used to identify this setting. Names must be unique.
1148 * @param reference Pointer to the variable, which is set by readConfig()
1149 * calls and read by writeConfig() calls.
1150 * @param defaultValue Default value, which is used when the config file
1151 * does not yet contain the key of this item.
1152 * @param key Key used in config file. If key is null, name is used as key.
1153 * @return The created item
1154 */
1155 ItemUInt *addItemUInt(const QString & name, quint32 &reference,
1156 quint32 defaultValue = 0,
1157 const QString & key = QString());
1158
1159 /**
1160 * Register an item of type qint64.
1161 *
1162 * @param name Name used to identify this setting. Names must be unique.
1163 * @param reference Pointer to the variable, which is set by readConfig()
1164 * calls and read by writeConfig() calls.
1165 * @param defaultValue Default value, which is used when the config file
1166 * does not yet contain the key of this item.
1167 * @param key Key used in config file. If key is null, name is used as key.
1168 * @return The created item
1169 */
1170 ItemLongLong *addItemLongLong(const QString & name, qint64 &reference,
1171 qint64 defaultValue = 0,
1172 const QString & key = QString());
1173
1174 /**
1175 * @deprecated
1176 * Use addItemLongLong().
1177 */
1178#ifndef KDE_NO_DEPRECATED
1179 KDE_DEPRECATED ItemLongLong *addItemInt64( const QString& name, qint64 &reference,
1180 qint64 defaultValue = 0,
1181 const QString & key = QString());
1182#endif
1183
1184 /**
1185 * Register an item of type quint64
1186 *
1187 * @param name Name used to identify this setting. Names must be unique.
1188 * @param reference Pointer to the variable, which is set by readConfig()
1189 * calls and read by writeConfig() calls.
1190 * @param defaultValue Default value, which is used when the config file
1191 * does not yet contain the key of this item.
1192 * @param key Key used in config file. If key is null, name is used as key.
1193 * @return The created item
1194 */
1195 ItemULongLong *addItemULongLong(const QString & name, quint64 &reference,
1196 quint64 defaultValue = 0,
1197 const QString & key = QString());
1198
1199 /**
1200 * @deprecated
1201 * Use addItemULongLong().
1202 */
1203#ifndef KDE_NO_DEPRECATED
1204 KDE_DEPRECATED ItemULongLong *addItemUInt64(const QString & name, quint64 &reference,
1205 quint64 defaultValue = 0,
1206 const QString & key = QString());
1207#endif
1208
1209 /**
1210 * Register an item of type double.
1211 *
1212 * @param name Name used to identify this setting. Names must be unique.
1213 * @param reference Pointer to the variable, which is set by readConfig()
1214 * calls and read by writeConfig() calls.
1215 * @param defaultValue Default value, which is used when the config file
1216 * does not yet contain the key of this item.
1217 * @param key Key used in config file. If key is null, name is used as key.
1218 * @return The created item
1219 */
1220 ItemDouble *addItemDouble(const QString & name, double &reference,
1221 double defaultValue = 0.0,
1222 const QString & key = QString());
1223
1224 /**
1225 * Register an item of type QRect.
1226 *
1227 * @param name Name used to identify this setting. Names must be unique.
1228 * @param reference Pointer to the variable, which is set by readConfig()
1229 * calls and read by writeConfig() calls.
1230 * @param defaultValue Default value, which is used when the config file
1231 * does not yet contain the key of this item.
1232 * @param key Key used in config file. If key is null, name is used as key.
1233 * @return The created item
1234 */
1235 ItemRect *addItemRect(const QString & name, QRect & reference,
1236 const QRect & defaultValue = QRect(),
1237 const QString & key = QString());
1238
1239 /**
1240 * Register an item of type QPoint.
1241 *
1242 * @param name Name used to identify this setting. Names must be unique.
1243 * @param reference Pointer to the variable, which is set by readConfig()
1244 * calls and read by writeConfig() calls.
1245 * @param defaultValue Default value, which is used when the config file
1246 * does not yet contain the key of this item.
1247 * @param key Key used in config file. If key is null, name is used as key.
1248 * @return The created item
1249 */
1250 ItemPoint *addItemPoint(const QString & name, QPoint & reference,
1251 const QPoint & defaultValue = QPoint(),
1252 const QString & key = QString());
1253
1254 /**
1255 * Register an item of type QSize.
1256 *
1257 * @param name Name used to identify this setting. Names must be unique.
1258 * @param reference Pointer to the variable, which is set by readConfig()
1259 * calls and read by writeConfig() calls.
1260 * @param defaultValue Default value, which is used when the config file
1261 * does not yet contain the key of this item.
1262 * @param key Key used in config file. If key is null, name is used as key.
1263 * @return The created item
1264 */
1265 ItemSize *addItemSize(const QString & name, QSize & reference,
1266 const QSize & defaultValue = QSize(),
1267 const QString & key = QString());
1268
1269 /**
1270 * Register an item of type QDateTime.
1271 *
1272 * @param name Name used to identify this setting. Names must be unique.
1273 * @param reference Pointer to the variable, which is set by readConfig()
1274 * calls and read by writeConfig() calls.
1275 * @param defaultValue Default value, which is used when the config file
1276 * does not yet contain the key of this item.
1277 * @param key Key used in config file. If key is null, name is used as key.
1278 * @return The created item
1279 */
1280 ItemDateTime *addItemDateTime(const QString & name, QDateTime & reference,
1281 const QDateTime & defaultValue = QDateTime(),
1282 const QString & key = QString());
1283
1284 /**
1285 * Register an item of type QStringList.
1286 *
1287 * @param name Name used to identify this setting. Names must be unique.
1288 * @param reference Pointer to the variable, which is set by readConfig()
1289 * calls and read by writeConfig() calls.
1290 * @param defaultValue Default value, which is used when the config file
1291 * does not yet contain the key of this item.
1292 * @param key Key used in config file. If key is null, name is used as key.
1293 * @return The created item
1294 */
1295 ItemStringList *addItemStringList(const QString & name, QStringList & reference,
1296 const QStringList & defaultValue = QStringList(),
1297 const QString & key = QString());
1298
1299 /**
1300 * Register an item of type QList<int>.
1301 *
1302 * @param name Name used to identify this setting. Names must be unique.
1303 * @param reference Pointer to the variable, which is set by readConfig()
1304 * calls and read by writeConfig() calls.
1305 * @param defaultValue Default value, which is used when the config file
1306 * does not yet contain the key of this item.
1307 * @param key Key used in config file. If key is null, name is used as key.
1308 * @return The created item
1309 */
1310 ItemIntList *addItemIntList(const QString & name, QList < int >&reference,
1311 const QList < int >&defaultValue =
1312 QList < int >(),
1313 const QString & key = QString());
1314
1315 /**
1316 * Return the @ref KConfig object used for reading and writing the settings.
1317 */
1318 KConfig *config();
1319
1320 /**
1321 * Return the @ref KConfig object used for reading and writing the settings.
1322 */
1323 const KConfig *config() const;
1324
1325 /**
1326 * Set the @ref KSharedConfig object used for reading and writing the settings.
1327 */
1328 void setSharedConfig(KSharedConfig::Ptr pConfig);
1329
1330 /**
1331 * Return list of items managed by this KCoreConfigSkeleton object.
1332 */
1333 KConfigSkeletonItem::List items() const;
1334
1335 // KDE5 TODO: Remove this non-const version. Kept only for BC.
1336 /**
1337 * Return whether a certain item is immutable
1338 */
1339 bool isImmutable(const QString & name);
1340
1341 /**
1342 * Return whether a certain item is immutable
1343 * @since 4.4
1344 */
1345 bool isImmutable(const QString & name) const;
1346
1347 // KDE5 TODO: Remove this non-const version. Kept only for BC.
1348 /**
1349 * Lookup item by name
1350 */
1351 KConfigSkeletonItem * findItem(const QString & name);
1352
1353 /**
1354 * Lookup item by name
1355 * @since 4.4
1356 */
1357 KConfigSkeletonItem * findItem(const QString & name) const;
1358
1359 /**
1360 * Specify whether this object should reflect the actual values or the
1361 * default values.
1362 * This method is implemented by usrUseDefaults(), which can be overridden
1363 * in derived classes if you have special requirements and can call
1364 * usrUseDefaults() directly.
1365 * If you don't have control whether useDefaults() or usrUseDefaults() is
1366 * called override useDefaults() directly.
1367 * @param b true to make this object reflect the default values,
1368 * false to make it reflect the actual values.
1369 * @return The state prior to this call
1370 */
1371 virtual bool useDefaults(bool b);
1372
1373Q_SIGNALS:
1374 /**
1375 * This signal is emitted when the configuration change.
1376 */
1377 void configChanged();
1378
1379protected:
1380 /**
1381 * Implemented by subclasses that use special defaults.
1382 * It replaces the default values with the actual values and
1383 * vice versa. Called from @ref useDefaults()
1384 * @param b true to make this object reflect the default values,
1385 * false to make it reflect the actual values.
1386 * @return The state prior to this call
1387 */
1388 virtual bool usrUseDefaults(bool b);
1389
1390 /**
1391 * Perform the actual setting of default values.
1392 * Override in derived classes to set special default values.
1393 * Called from @ref setDefaults()
1394 */
1395 virtual void usrSetDefaults();
1396
1397 /**
1398 * Perform the actual reading of the configuration file.
1399 * Override in derived classes to read special config values.
1400 * Called from @ref readConfig()
1401 */
1402 virtual void usrReadConfig();
1403
1404 /**
1405 * Perform the actual writing of the configuration file.
1406 * Override in derived classes to write special config values.
1407 * Called from @ref writeConfig()
1408 */
1409 virtual void usrWriteConfig();
1410
1411private:
1412 class Private;
1413 Private * const d;
1414 friend class KConfigSkeleton;
1415
1416};
1417
1418#endif
1419