File indexing completed on 2024-05-12 03:54:27
0001 /* 0002 This file is part of KDE. 0003 0004 SPDX-FileCopyrightText: 2001, 2002, 2003 Cornelius Schumacher <schumacher@kde.org> 0005 SPDX-FileCopyrightText: 2003 Waldo Bastian <bastian@kde.org> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 0010 #ifndef KCORECONFIGSKELETON_H 0011 #define KCORECONFIGSKELETON_H 0012 0013 #include <kconfigcore_export.h> 0014 0015 #include <kconfiggroup.h> 0016 #include <ksharedconfig.h> 0017 0018 #include <QDate> 0019 #include <QHash> 0020 #include <QRect> 0021 #include <QStringList> 0022 #include <QUrl> 0023 #include <QVariant> 0024 0025 class KCoreConfigSkeletonPrivate; 0026 0027 class KConfigSkeletonItemPrivate; 0028 /** 0029 * \class KConfigSkeletonItem kcoreconfigskeleton.h <KCoreConfigSkeleton> 0030 * 0031 * @short Class for storing a preferences setting 0032 * @author Cornelius Schumacher 0033 * @see KCoreConfigSkeleton 0034 * 0035 * This class represents one preferences setting as used by @ref KCoreConfigSkeleton. 0036 * Subclasses of KConfigSkeletonItem implement storage functions for a certain type of 0037 * setting. Normally you don't have to use this class directly. Use the special 0038 * addItem() functions of KCoreConfigSkeleton instead. If you subclass this class you will 0039 * have to register instances with the function KCoreConfigSkeleton::addItem(). 0040 */ 0041 class KCONFIGCORE_EXPORT KConfigSkeletonItem 0042 { 0043 Q_DECLARE_PRIVATE(KConfigSkeletonItem) 0044 public: 0045 typedef QList<KConfigSkeletonItem *> List; 0046 typedef QHash<QString, KConfigSkeletonItem *> Dict; 0047 typedef QHash<QString, KConfigSkeletonItem *>::Iterator DictIterator; 0048 0049 /** 0050 * Constructor. 0051 * 0052 * @param _group Config file group. 0053 * @param _key Config file key. 0054 */ 0055 KConfigSkeletonItem(const QString &_group, const QString &_key); 0056 0057 /** 0058 * Destructor. 0059 */ 0060 virtual ~KConfigSkeletonItem(); 0061 0062 /** 0063 * Set config file group. 0064 */ 0065 void setGroup(const QString &_group); 0066 0067 /** 0068 * Return name of config file group. 0069 */ 0070 QString group() const; 0071 0072 /** 0073 * Set config file group but giving the KConfigGroup. 0074 * Allow the item to be in nested groups. 0075 * @since 5.68 0076 */ 0077 void setGroup(const KConfigGroup &cg); 0078 0079 /** 0080 * Return a KConfigGroup, the one provided by setGroup(const KConfigGroup&) if it's valid, 0081 * or make one from @p config and item's group. 0082 * @see setGroup(const QString &_group) 0083 * @see setGroup(KConfigGroup cg) 0084 * @since 5.68 0085 */ 0086 KConfigGroup configGroup(KConfig *config) const; 0087 0088 /** 0089 * Set config file key. 0090 */ 0091 void setKey(const QString &_key); 0092 0093 /** 0094 * Return config file key. 0095 */ 0096 QString key() const; 0097 0098 /** 0099 * Set internal name of entry. 0100 */ 0101 void setName(const QString &_name); 0102 0103 /** 0104 * Return internal name of entry. 0105 */ 0106 QString name() const; 0107 0108 /** 0109 * Set label providing a translated one-line description of the item. 0110 */ 0111 void setLabel(const QString &l); 0112 0113 /** 0114 * Return the label of the item. 0115 * @see setLabel() 0116 */ 0117 QString label() const; 0118 0119 /** 0120 * Set ToolTip description of item. 0121 * @since 4.2 0122 */ 0123 void setToolTip(const QString &t); 0124 0125 /** 0126 * Return ToolTip description of item. 0127 * @see setToolTip() 0128 * @since 4.2 0129 */ 0130 QString toolTip() const; 0131 0132 /** 0133 * Set WhatsThis description of item. 0134 */ 0135 void setWhatsThis(const QString &w); 0136 0137 /** 0138 * Return WhatsThis description of item. 0139 * @see setWhatsThis() 0140 */ 0141 QString whatsThis() const; 0142 0143 /** 0144 * The write flags to be used when writing configuration. 0145 * @since 5.58 0146 */ 0147 void setWriteFlags(KConfigBase::WriteConfigFlags flags); 0148 0149 /** 0150 * Return write flags to be used when writing configuration. 0151 * They should be passed to every call of KConfigGroup::writeEntry() and KConfigGroup::revertToDefault(). 0152 * @since 5.58 0153 */ 0154 KConfigBase::WriteConfigFlags writeFlags() const; 0155 0156 /** 0157 * This function is called by @ref KCoreConfigSkeleton to read the value for this setting 0158 * from a config file. 0159 */ 0160 virtual void readConfig(KConfig *) = 0; 0161 0162 /** 0163 * This function is called by @ref KCoreConfigSkeleton to write the value of this setting 0164 * to a config file. 0165 * Make sure to pass writeFlags() to every call of KConfigGroup::writeEntry() and KConfigGroup::revertToDefault(). 0166 */ 0167 virtual void writeConfig(KConfig *) = 0; 0168 0169 /** 0170 * Read global default value. 0171 */ 0172 virtual void readDefault(KConfig *) = 0; 0173 0174 /** 0175 * Set item to @p p 0176 */ 0177 virtual void setProperty(const QVariant &p) = 0; 0178 0179 /** 0180 * Check whether the item is equal to @p p. 0181 * 0182 * Use this function to compare items that use custom types, 0183 * because QVariant::operator== will not work for those. 0184 * 0185 * @param p QVariant to compare to 0186 * @return @c true if the item is equal to @p p, @c false otherwise 0187 */ 0188 virtual bool isEqual(const QVariant &p) const = 0; 0189 0190 /** 0191 * Return item as property 0192 */ 0193 virtual QVariant property() const = 0; 0194 0195 /** 0196 * Return minimum value of item or invalid if not specified 0197 */ 0198 virtual QVariant minValue() const; 0199 0200 /** 0201 * Return maximum value of item or invalid if not specified 0202 */ 0203 virtual QVariant maxValue() const; 0204 0205 /** 0206 * Sets the current value to the default value. 0207 */ 0208 virtual void setDefault() = 0; 0209 0210 /** 0211 * Exchanges the current value with the default value 0212 * Used by KCoreConfigSkeleton::useDefaults(bool); 0213 */ 0214 virtual void swapDefault() = 0; 0215 0216 /** 0217 * Return if the entry can be modified. 0218 */ 0219 bool isImmutable() const; 0220 0221 /** 0222 * Indicates if the item is set to its default value. 0223 * 0224 * @since 5.64 0225 */ 0226 bool isDefault() const; 0227 0228 /** 0229 * Indicates if the item has a different value than the 0230 * previously loaded value. 0231 * 0232 * @since 5.64 0233 */ 0234 bool isSaveNeeded() const; 0235 0236 /** 0237 * Returns the default value 0238 * @since 5.74 0239 */ 0240 QVariant getDefault() const; 0241 0242 protected: 0243 KCONFIGCORE_NO_EXPORT explicit KConfigSkeletonItem(KConfigSkeletonItemPrivate &dd, const QString &_group, const QString &_key); 0244 0245 /** 0246 * Sets mIsImmutable to @c true if mKey in config is immutable. 0247 * @param group KConfigGroup to check if mKey is immutable in 0248 */ 0249 void readImmutability(const KConfigGroup &group); 0250 0251 QString mGroup; ///< The group name for this item 0252 QString mKey; ///< The config key for this item 0253 QString mName; ///< The name of this item 0254 0255 // HACK: Necessary to avoid introducing new virtuals in KConfigSkeletonItem 0256 // KF6: Use proper pure virtuals in KConfigSkeletonItem 0257 void setIsDefaultImpl(const std::function<bool()> &impl); 0258 void setIsSaveNeededImpl(const std::function<bool()> &impl); 0259 void setGetDefaultImpl(const std::function<QVariant()> &impl); 0260 0261 KConfigSkeletonItemPrivate *const d_ptr; 0262 }; 0263 0264 class KPropertySkeletonItemPrivate; 0265 0266 /** 0267 * \class KPropertySkeletonItem kcoreconfigskeleton.h <KCoreConfigSkeleton> 0268 * 0269 * @short Class for proxying a QObject property as a preferences setting 0270 * @author Kevin Ottens 0271 * @see KConfigSkeletonItem 0272 * 0273 * This class represents one preferences setting as used by @ref KCoreConfigSkeleton. 0274 * Unlike other @ref KConfigSkeletonItem subclasses, this one won't store the preference 0275 * in KConfig but will use a QObject property as storage. 0276 * You will have to register instances of this class with the function KCoreConfigSkeleton::addItem(). 0277 * 0278 * @since 5.65 0279 */ 0280 class KCONFIGCORE_EXPORT KPropertySkeletonItem : public KConfigSkeletonItem 0281 { 0282 Q_DECLARE_PRIVATE(KPropertySkeletonItem) 0283 public: 0284 /** 0285 * Constructor 0286 * 0287 * @param object The QObject instance which we'll manage the property of 0288 * @param propertyName The name of the property in @p object which we'll manage 0289 * @param defaultValue The default value of the property 0290 */ 0291 KPropertySkeletonItem(QObject *object, const QByteArray &propertyName, const QVariant &defaultValue); 0292 0293 /** @copydoc KConfigSkeletonItem::property() */ 0294 QVariant property() const override; 0295 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant &) */ 0296 void setProperty(const QVariant &p) override; 0297 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) */ 0298 bool isEqual(const QVariant &p) const override; 0299 0300 /** @copydoc KConfigSkeletonItem::readConfig(KConfig *) */ 0301 void readConfig(KConfig *) override; 0302 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig *) */ 0303 void writeConfig(KConfig *) override; 0304 0305 /** @copydoc KConfigSkeletonItem::readDefault(KConfig *) */ 0306 void readDefault(KConfig *) override; 0307 /** @copydoc KConfigSkeletonItem::setDefault() */ 0308 void setDefault() override; 0309 /** @copydoc KConfigSkeletonItem::swapDefault() */ 0310 void swapDefault() override; 0311 0312 /** 0313 * Set a notify function, it will be invoked when the value of the property changes. 0314 * @since 5.68 0315 */ 0316 void setNotifyFunction(const std::function<void()> &impl); 0317 }; 0318 0319 /** 0320 * \class KConfigSkeletonGenericItem kcoreconfigskeleton.h <KCoreConfigSkeleton> 0321 * 0322 * @short Base class for storing a preferences setting of type @p T. 0323 */ 0324 template<typename T> 0325 class KConfigSkeletonGenericItem : public KConfigSkeletonItem 0326 { 0327 public: 0328 /** 0329 * @copydoc KConfigSkeletonItem(const QString&, const QString&) 0330 * @param reference The initial value to hold in the item 0331 * @param defaultValue The default value for the item 0332 */ 0333 KConfigSkeletonGenericItem(const QString &_group, const QString &_key, T &reference, T defaultValue) 0334 : KConfigSkeletonItem(_group, _key) 0335 , mReference(reference) 0336 , mDefault(defaultValue) 0337 , mLoadedValue(defaultValue) 0338 { 0339 setIsDefaultImpl([this] { 0340 return mReference == mDefault; 0341 }); 0342 setIsSaveNeededImpl([this] { 0343 return mReference != mLoadedValue; 0344 }); 0345 setGetDefaultImpl([this] { 0346 return QVariant::fromValue(mDefault); 0347 }); 0348 } 0349 0350 /** 0351 * Set value of this KConfigSkeletonItem. 0352 */ 0353 void setValue(const T &v) 0354 { 0355 mReference = v; 0356 } 0357 0358 /** 0359 * Return value of this KConfigSkeletonItem. 0360 */ 0361 T &value() 0362 { 0363 return mReference; 0364 } 0365 0366 /** 0367 * Return const value of this KConfigSkeletonItem. 0368 */ 0369 const T &value() const 0370 { 0371 return mReference; 0372 } 0373 0374 /** 0375 * Set default value for this item. 0376 */ 0377 virtual void setDefaultValue(const T &v) 0378 { 0379 mDefault = v; 0380 } 0381 0382 /** 0383 * Set the value for this item to the default value 0384 */ 0385 void setDefault() override 0386 { 0387 mReference = mDefault; 0388 } 0389 0390 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig *) */ 0391 void writeConfig(KConfig *config) override 0392 { 0393 if (mReference != mLoadedValue) { // Is this needed? 0394 KConfigGroup cg = configGroup(config); 0395 if ((mDefault == mReference) && !cg.hasDefault(mKey)) { 0396 cg.revertToDefault(mKey, writeFlags()); 0397 } else { 0398 cg.writeEntry(mKey, mReference, writeFlags()); 0399 } 0400 mLoadedValue = mReference; 0401 } 0402 } 0403 0404 /** @copydoc KConfigSkeletonItem::readDefault(KConfig*) */ 0405 void readDefault(KConfig *config) override 0406 { 0407 config->setReadDefaults(true); 0408 readConfig(config); 0409 config->setReadDefaults(false); 0410 mDefault = mReference; 0411 } 0412 0413 /** @copydoc KConfigSkeletonItem::swapDefault() */ 0414 void swapDefault() override 0415 { 0416 T tmp = mReference; 0417 mReference = mDefault; 0418 mDefault = tmp; 0419 } 0420 0421 protected: 0422 T &mReference; ///< Stores the value for this item 0423 T mDefault; ///< The default value for this item 0424 T mLoadedValue; 0425 }; 0426 0427 /** 0428 * \class KConfigCompilerSignallingItem kcoreconfigskeleton.h <KCoreConfigSkeleton> 0429 * 0430 * @author Alex Richardson 0431 * 0432 * This class wraps a @ref KConfigSkeletonItem and invokes a function whenever the value changes. 0433 * That function must take one quint64 parameter. Whenever the property value of the wrapped KConfigSkeletonItem 0434 * changes this function will be invoked with the stored user data passed in the constructor. 0435 * It does not call a function with the new value since this class is designed solely for the \ref kconfig_compiler generated 0436 * code and is therefore probably not suited for any other usecases. 0437 * 0438 * @see KConfigSkeletonItem 0439 */ 0440 class KCONFIGCORE_EXPORT KConfigCompilerSignallingItem : public KConfigSkeletonItem 0441 { 0442 public: 0443 typedef void (QObject::*NotifyFunction)(quint64 arg); 0444 /** 0445 * Constructor. 0446 * 0447 * @param item the KConfigSkeletonItem to wrap 0448 * @param targetFunction the method to invoke whenever the value of @p item changes 0449 * @param object The object on which the method is invoked. 0450 * @param userData This data will be passed to @p targetFunction on every property change 0451 */ 0452 KConfigCompilerSignallingItem(KConfigSkeletonItem *item, QObject *object, NotifyFunction targetFunction, quint64 userData); 0453 ~KConfigCompilerSignallingItem() override; 0454 0455 void readConfig(KConfig *) override; 0456 void writeConfig(KConfig *) override; 0457 void readDefault(KConfig *) override; 0458 void setProperty(const QVariant &p) override; 0459 bool isEqual(const QVariant &p) const override; 0460 QVariant property() const override; 0461 QVariant minValue() const override; 0462 QVariant maxValue() const override; 0463 void setDefault() override; 0464 void swapDefault() override; 0465 // KF6 TODO - fix this 0466 // Ideally we would do this in an overload of KConfigSkeletonItem, but 0467 // given we can't, I've shadowed the method. This isn't pretty, but given 0468 // the docs say it should generally only be used from auto generated code, 0469 // should be fine. 0470 void setWriteFlags(KConfigBase::WriteConfigFlags flags); 0471 KConfigBase::WriteConfigFlags writeFlags() const; 0472 void setGroup(const KConfigGroup &cg); 0473 KConfigGroup configGroup(KConfig *config) const; 0474 // END TODO 0475 0476 private: 0477 inline void invokeNotifyFunction() 0478 { 0479 // call the pointer to member function using the strange ->* operator 0480 (mObject->*mTargetFunction)(mUserData); 0481 } 0482 0483 private: 0484 QScopedPointer<KConfigSkeletonItem> mItem; 0485 NotifyFunction mTargetFunction; 0486 QObject *mObject; 0487 quint64 mUserData; 0488 }; 0489 0490 /** 0491 * \class KCoreConfigSkeleton kcoreconfigskeleton.h <KCoreConfigSkeleton> 0492 * 0493 * @short Class for handling preferences settings for an application. 0494 * @author Cornelius Schumacher 0495 * 0496 * This class provides an interface to preferences settings. Preferences items 0497 * can be registered by the addItem() function corresponding to the data type of 0498 * the setting. KCoreConfigSkeleton then handles reading and writing of config files and 0499 * setting of default values. 0500 * 0501 * Normally you will subclass KCoreConfigSkeleton, add data members for the preferences 0502 * settings and register the members in the constructor of the subclass. 0503 * 0504 * Example: 0505 * \code 0506 * class MyPrefs : public KCoreConfigSkeleton 0507 * { 0508 * public: 0509 * MyPrefs() 0510 * { 0511 * setCurrentGroup("MyGroup"); 0512 * addItemBool("MySetting1", mMyBool, false); 0513 * addItemPoint("MySetting2", mMyPoint, QPoint(100, 200)); 0514 * 0515 * setCurrentGroup("MyOtherGroup"); 0516 * addItemDouble("MySetting3", mMyDouble, 3.14); 0517 * } 0518 * 0519 * bool mMyBool; 0520 * QPoint mMyPoint; 0521 * double mMyDouble; 0522 * } 0523 * \endcode 0524 * 0525 * It might be convenient in many cases to make this subclass of KCoreConfigSkeleton a 0526 * singleton for global access from all over the application without passing 0527 * references to the KCoreConfigSkeleton object around. 0528 * 0529 * You can write the data to the configuration file by calling @ref save() 0530 * and read the data from the configuration file by calling @ref readConfig(). 0531 * If you want to watch for config changes, use @ref configChanged() signal. 0532 * 0533 * If you have items, which are not covered by the existing addItem() functions 0534 * you can add customized code for reading, writing and default setting by 0535 * implementing the functions @ref usrUseDefaults(), @ref usrRead() and 0536 * @ref usrSave(). 0537 * 0538 * Internally preferences settings are stored in instances of subclasses of 0539 * @ref KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses 0540 * for your own types and call the generic @ref addItem() to register them. 0541 * 0542 * In many cases you don't have to write the specific KCoreConfigSkeleton 0543 * subclasses yourself, but you can use \ref kconfig_compiler to automatically 0544 * generate the C++ code from an XML description of the configuration options. 0545 * 0546 * Use KConfigSkeleton if you need GUI types as well. 0547 * 0548 * @see KConfigSkeletonItem 0549 */ 0550 class KCONFIGCORE_EXPORT KCoreConfigSkeleton : public QObject 0551 { 0552 Q_OBJECT 0553 public: 0554 /** 0555 * Class for handling a string preferences item. 0556 */ 0557 class KCONFIGCORE_EXPORT ItemString : public KConfigSkeletonGenericItem<QString> 0558 { 0559 public: 0560 /** The type of string that is held in this item */ 0561 enum Type { 0562 Normal, ///< A normal string 0563 Password, ///< A password string 0564 Path, ///< A path to a file or directory 0565 }; 0566 0567 /** 0568 * @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem 0569 * @param type The type of string held by the item 0570 */ 0571 ItemString(const QString &_group, 0572 const QString &_key, 0573 QString &reference, 0574 const QString &defaultValue = QLatin1String(""), // NOT QString() !! 0575 Type type = Normal); 0576 0577 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */ 0578 void writeConfig(KConfig *config) override; 0579 0580 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0581 void readConfig(KConfig *config) override; 0582 0583 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0584 void setProperty(const QVariant &p) override; 0585 0586 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0587 bool isEqual(const QVariant &p) const override; 0588 0589 /** @copydoc KConfigSkeletonItem::property() const */ 0590 QVariant property() const override; 0591 0592 private: 0593 Type mType; 0594 }; 0595 0596 /** 0597 * Class for handling a password preferences item. 0598 */ 0599 class KCONFIGCORE_EXPORT ItemPassword : public ItemString 0600 { 0601 public: 0602 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0603 ItemPassword(const QString &_group, const QString &_key, QString &reference, 0604 const QString &defaultValue = QLatin1String("")); // NOT QString() !! 0605 }; 0606 0607 /** 0608 * Class for handling a path preferences item. 0609 */ 0610 class KCONFIGCORE_EXPORT ItemPath : public ItemString 0611 { 0612 public: 0613 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0614 ItemPath(const QString &_group, const QString &_key, QString &reference, const QString &defaultValue = QString()); 0615 }; 0616 0617 /** 0618 * Class for handling a url preferences item. 0619 */ 0620 class KCONFIGCORE_EXPORT ItemUrl : public KConfigSkeletonGenericItem<QUrl> 0621 { 0622 public: 0623 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0624 ItemUrl(const QString &_group, const QString &_key, QUrl &reference, const QUrl &defaultValue = QUrl()); 0625 0626 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */ 0627 void writeConfig(KConfig *config) override; 0628 0629 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0630 void readConfig(KConfig *config) override; 0631 0632 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0633 void setProperty(const QVariant &p) override; 0634 0635 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0636 bool isEqual(const QVariant &p) const override; 0637 0638 /** @copydoc KConfigSkeletonItem::property() const */ 0639 QVariant property() const override; 0640 }; 0641 0642 /** 0643 * Class for handling a QVariant preferences item. 0644 */ 0645 class KCONFIGCORE_EXPORT ItemProperty : public KConfigSkeletonGenericItem<QVariant> 0646 { 0647 public: 0648 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0649 ItemProperty(const QString &_group, const QString &_key, QVariant &reference, const QVariant &defaultValue = QVariant()); 0650 0651 void readConfig(KConfig *config) override; 0652 void setProperty(const QVariant &p) override; 0653 0654 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0655 bool isEqual(const QVariant &p) const override; 0656 0657 /** @copydoc KConfigSkeletonItem::property() const */ 0658 QVariant property() const override; 0659 }; 0660 0661 /** 0662 * Class for handling a bool preferences item. 0663 */ 0664 class KCONFIGCORE_EXPORT ItemBool : public KConfigSkeletonGenericItem<bool> 0665 { 0666 public: 0667 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0668 ItemBool(const QString &_group, const QString &_key, bool &reference, bool defaultValue = true); 0669 0670 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0671 void readConfig(KConfig *config) override; 0672 0673 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0674 void setProperty(const QVariant &p) override; 0675 0676 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0677 bool isEqual(const QVariant &p) const override; 0678 0679 /** @copydoc KConfigSkeletonItem::property() const */ 0680 QVariant property() const override; 0681 }; 0682 0683 /** 0684 * Class for handling a 32-bit integer preferences item. 0685 */ 0686 class KCONFIGCORE_EXPORT ItemInt : public KConfigSkeletonGenericItem<qint32> 0687 { 0688 public: 0689 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0690 ItemInt(const QString &_group, const QString &_key, qint32 &reference, qint32 defaultValue = 0); 0691 0692 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0693 void readConfig(KConfig *config) override; 0694 0695 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0696 void setProperty(const QVariant &p) override; 0697 0698 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0699 bool isEqual(const QVariant &p) const override; 0700 0701 /** @copydoc KConfigSkeletonItem::property() */ 0702 QVariant property() const override; 0703 0704 /** Get the minimum value that is allowed to be stored in this item */ 0705 QVariant minValue() const override; 0706 0707 /** Get the maximum value this is allowed to be stored in this item */ 0708 QVariant maxValue() const override; 0709 0710 /** 0711 * Set the minimum value for the item. 0712 * @see minValue() 0713 */ 0714 void setMinValue(qint32); 0715 0716 /** 0717 * Set the maximum value for the item. 0718 * @see maxValue 0719 */ 0720 void setMaxValue(qint32); 0721 0722 private: 0723 bool mHasMin : 1; 0724 bool mHasMax : 1; 0725 qint32 mMin; 0726 qint32 mMax; 0727 }; 0728 0729 /** 0730 * Class for handling a 64-bit integer preferences item. 0731 */ 0732 class KCONFIGCORE_EXPORT ItemLongLong : public KConfigSkeletonGenericItem<qint64> 0733 { 0734 public: 0735 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0736 ItemLongLong(const QString &_group, const QString &_key, qint64 &reference, qint64 defaultValue = 0); 0737 0738 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0739 void readConfig(KConfig *config) override; 0740 0741 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0742 void setProperty(const QVariant &p) override; 0743 0744 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0745 bool isEqual(const QVariant &p) const override; 0746 0747 /** @copydoc KConfigSkeletonItem::property() */ 0748 QVariant property() const override; 0749 0750 /** @copydoc ItemInt::minValue() */ 0751 QVariant minValue() const override; 0752 0753 /** @copydoc ItemInt::maxValue() */ 0754 QVariant maxValue() const override; 0755 0756 /** @copydoc ItemInt::setMinValue(qint32) */ 0757 void setMinValue(qint64); 0758 0759 /** @copydoc ItemInt::setMaxValue(qint32) */ 0760 void setMaxValue(qint64); 0761 0762 private: 0763 bool mHasMin : 1; 0764 bool mHasMax : 1; 0765 qint64 mMin; 0766 qint64 mMax; 0767 }; 0768 0769 /** 0770 * Class for handling enums. 0771 */ 0772 class KCONFIGCORE_EXPORT ItemEnum : public ItemInt 0773 { 0774 public: 0775 struct Choice { 0776 QString name; 0777 QString label; 0778 QString toolTip; 0779 QString whatsThis; 0780 QString value; 0781 }; 0782 0783 /** 0784 * @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem 0785 * @param choices The list of enums that can be stored in this item 0786 */ 0787 ItemEnum(const QString &_group, const QString &_key, qint32 &reference, const QList<Choice> &choices, qint32 defaultValue = 0); 0788 0789 QList<Choice> choices() const; 0790 0791 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0792 void readConfig(KConfig *config) override; 0793 0794 /** @copydoc KConfigSkeletonItem::writeConfig(KConfig*) */ 0795 void writeConfig(KConfig *config) override; 0796 0797 /** 0798 * Returns the value for the choice with the given @p name 0799 */ 0800 QString valueForChoice(const QString &name) const; 0801 0802 /** 0803 * Stores a choice value for @p name 0804 */ 0805 void setValueForChoice(const QString &name, const QString &valueForChoice); 0806 0807 private: 0808 QList<Choice> mChoices; 0809 }; 0810 0811 /** 0812 * Class for handling an unsigned 32-bit integer preferences item. 0813 */ 0814 class KCONFIGCORE_EXPORT ItemUInt : public KConfigSkeletonGenericItem<quint32> 0815 { 0816 public: 0817 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0818 ItemUInt(const QString &_group, const QString &_key, quint32 &reference, quint32 defaultValue = 0); 0819 0820 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0821 void readConfig(KConfig *config) override; 0822 0823 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0824 void setProperty(const QVariant &p) override; 0825 0826 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0827 bool isEqual(const QVariant &p) const override; 0828 0829 /** @copydoc KConfigSkeletonItem::property() */ 0830 QVariant property() const override; 0831 0832 /** @copydoc ItemInt::minValue() */ 0833 QVariant minValue() const override; 0834 0835 /** @copydoc ItemInt::maxValue() */ 0836 QVariant maxValue() const override; 0837 0838 /** @copydoc ItemInt::setMinValue(qint32) */ 0839 void setMinValue(quint32); 0840 0841 /** @copydoc ItemInt::setMaxValue(qint32) */ 0842 void setMaxValue(quint32); 0843 0844 private: 0845 bool mHasMin : 1; 0846 bool mHasMax : 1; 0847 quint32 mMin; 0848 quint32 mMax; 0849 }; 0850 0851 /** 0852 * Class for handling unsigned 64-bit integer preferences item. 0853 */ 0854 class KCONFIGCORE_EXPORT ItemULongLong : public KConfigSkeletonGenericItem<quint64> 0855 { 0856 public: 0857 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0858 ItemULongLong(const QString &_group, const QString &_key, quint64 &reference, quint64 defaultValue = 0); 0859 0860 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0861 void readConfig(KConfig *config) override; 0862 0863 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0864 void setProperty(const QVariant &p) override; 0865 0866 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0867 bool isEqual(const QVariant &p) const override; 0868 0869 /** @copydoc KConfigSkeletonItem::property() */ 0870 QVariant property() const override; 0871 0872 /** @copydoc ItemInt::minValue() */ 0873 QVariant minValue() const override; 0874 0875 /** @copydoc ItemInt::maxValue() */ 0876 QVariant maxValue() const override; 0877 0878 /** @copydoc ItemInt::setMinValue(qint32) */ 0879 void setMinValue(quint64); 0880 0881 /** @copydoc ItemInt::setMaxValue(qint32) */ 0882 void setMaxValue(quint64); 0883 0884 private: 0885 bool mHasMin : 1; 0886 bool mHasMax : 1; 0887 quint64 mMin; 0888 quint64 mMax; 0889 }; 0890 0891 /** 0892 * Class for handling a floating point preference item. 0893 */ 0894 class KCONFIGCORE_EXPORT ItemDouble : public KConfigSkeletonGenericItem<double> 0895 { 0896 public: 0897 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0898 ItemDouble(const QString &_group, const QString &_key, double &reference, double defaultValue = 0); 0899 0900 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0901 void readConfig(KConfig *config) override; 0902 0903 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0904 void setProperty(const QVariant &p) override; 0905 0906 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0907 bool isEqual(const QVariant &p) const override; 0908 0909 /** @copydoc KConfigSkeletonItem::property() */ 0910 QVariant property() const override; 0911 0912 /** @copydoc ItemInt::minValue() */ 0913 QVariant minValue() const override; 0914 0915 /** @copydoc ItemInt::maxValue() */ 0916 QVariant maxValue() const override; 0917 0918 /** @copydoc ItemInt::setMinValue() */ 0919 void setMinValue(double); 0920 0921 /** @copydoc ItemInt::setMaxValue() */ 0922 void setMaxValue(double); 0923 0924 private: 0925 bool mHasMin : 1; 0926 bool mHasMax : 1; 0927 double mMin; 0928 double mMax; 0929 }; 0930 0931 /** 0932 * Class for handling a QRect preferences item. 0933 */ 0934 class KCONFIGCORE_EXPORT ItemRect : public KConfigSkeletonGenericItem<QRect> 0935 { 0936 public: 0937 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0938 ItemRect(const QString &_group, const QString &_key, QRect &reference, const QRect &defaultValue = QRect()); 0939 0940 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0941 void readConfig(KConfig *config) override; 0942 0943 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0944 void setProperty(const QVariant &p) override; 0945 0946 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0947 bool isEqual(const QVariant &p) const override; 0948 0949 /** @copydoc KConfigSkeletonItem::property() */ 0950 QVariant property() const override; 0951 }; 0952 0953 /** 0954 * Class for handling a QRectF preferences item. 0955 */ 0956 class KCONFIGCORE_EXPORT ItemRectF : public KConfigSkeletonGenericItem<QRectF> 0957 { 0958 public: 0959 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0960 ItemRectF(const QString &_group, const QString &_key, QRectF &reference, const QRectF &defaultValue = QRectF()); 0961 0962 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0963 void readConfig(KConfig *config) override; 0964 0965 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0966 void setProperty(const QVariant &p) override; 0967 0968 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0969 bool isEqual(const QVariant &p) const override; 0970 0971 /** @copydoc KConfigSkeletonItem::property() */ 0972 QVariant property() const override; 0973 }; 0974 0975 /** 0976 * Class for handling a QPoint preferences item. 0977 */ 0978 class KCONFIGCORE_EXPORT ItemPoint : public KConfigSkeletonGenericItem<QPoint> 0979 { 0980 public: 0981 /** @copydoc KConfigSkeletonGenericItem::KConfigSkeletonGenericItem */ 0982 ItemPoint(const QString &_group, const QString &_key, QPoint &reference, const QPoint &defaultValue = QPoint()); 0983 0984 /** @copydoc KConfigSkeletonItem::readConfig(KConfig*) */ 0985 void readConfig(KConfig *config) override; 0986 0987 /** @copydoc KConfigSkeletonItem::setProperty(const QVariant&) */ 0988 void setProperty(const QVariant &p) override; 0989 0990 /** @copydoc KConfigSkeletonItem::isEqual(const QVariant &) const */ 0991 bool isEqual(const QVariant &p) const override; 0992 0993 /** @copydoc KConfigSkeletonItem::property() */ 0994 QVariant property() const override; 0995 }; 0996 0997 /** 0998 * Class for handling a QPointF preferences item. 0999 */ 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 1169 public: 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 1584 public 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 1594 Q_SIGNALS: 1595 /** 1596 * This signal is emitted when the configuration change. 1597 */ 1598 void configChanged(); 1599 1600 protected: 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 1632 private: 1633 KCoreConfigSkeletonPrivate *const d; 1634 friend class KConfigSkeleton; 1635 }; 1636 1637 Q_DECLARE_TYPEINFO(KCoreConfigSkeleton::ItemEnum::Choice, Q_RELOCATABLE_TYPE); 1638 1639 #endif