diff options
Diffstat (limited to 'kdecore/kconfigskeleton.h')
| -rw-r--r-- | kdecore/kconfigskeleton.h | 1230 |
1 files changed, 1230 insertions, 0 deletions
diff --git a/kdecore/kconfigskeleton.h b/kdecore/kconfigskeleton.h new file mode 100644 index 000000000..44fdfc7fa --- /dev/null +++ b/kdecore/kconfigskeleton.h @@ -0,0 +1,1230 @@ +/* + * This file is part of KDE. + * + * Copyright (c) 2001,2002,2003 Cornelius Schumacher <schumacher@kde.org> + * Copyright (c) 2003 Waldo Bastian <bastian@kde.org> + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public License + * along with this library; see the file COPYING.LIB. If not, write to + * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + */ + +#ifndef _KCONFIGSKELETON_H +#define _KCONFIGSKELETON_H + +#include <qcolor.h> +#include <qdatetime.h> +#include <qfont.h> +#include <qpoint.h> +#include <qptrlist.h> +#include <qdict.h> +#include <qrect.h> +#include <qsize.h> +#include <qstringlist.h> +#include <qvariant.h> +#include <kconfig.h> +#include <kglobalsettings.h> + + /** + * @short Class for storing a preferences setting + * @author Cornelius Schumacher + * @see KConfigSkeleton + * + * This class represents one preferences setting as used by @ref KConfigSkeleton. + * Subclasses of KConfigSkeletonItem implement storage functions for a certain type of + * setting. Normally you don't have to use this class directly. Use the special + * addItem() functions of KConfigSkeleton instead. If you subclass this class you will + * have to register instances with the function KConfigSkeleton::addItem(). + */ + class KDECORE_EXPORT KConfigSkeletonItem + { + public: + typedef QValueList < KConfigSkeletonItem * >List; + typedef QDict < KConfigSkeletonItem > Dict; + typedef QDictIterator < KConfigSkeletonItem > DictIterator; + + /** + * Constructor. + * + * @param group Config file group. + * @param key Config file key. + */ + KConfigSkeletonItem(const QString & group, const QString & key) + :mGroup(group),mKey(key), mIsImmutable(true) + { + } + + /** + * Destructor. + */ + virtual ~KConfigSkeletonItem() + { + } + + /** + * Set config file group. + */ + void setGroup( const QString &group ) + { + mGroup = group; + } + + /** + * Return config file group. + */ + QString group() const + { + return mGroup; + } + + /** + * Set config file key. + */ + void setKey( const QString &key ) + { + mKey = key; + } + + /** + * Return config file key. + */ + QString key() const + { + return mKey; + } + + /** + * Set internal name of entry. + */ + void setName(const QString &name) + { + mName = name; + } + + /** + * Return internal name of entry. + */ + QString name() const + { + return mName; + } + + /** + Set label providing a translated one-line description of the item. + */ + void setLabel( const QString &l ) + { + mLabel = l; + } + + /** + Return label of item. See setLabel(). + */ + QString label() const + { + return mLabel; + } + + /** + Set WhatsThis description og item. + */ + void setWhatsThis( const QString &w ) + { + mWhatsThis = w; + } + + /** + Return WhatsThis description of item. See setWhatsThis(). + */ + QString whatsThis() const + { + return mWhatsThis; + } + + /** + * This function is called by @ref KConfigSkeleton to read the value for this setting + * from a config file. + * value. + */ + virtual void readConfig(KConfig *) = 0; + + /** + * This function is called by @ref KConfigSkeleton to write the value of this setting + * to a config file. + */ + virtual void writeConfig(KConfig *) = 0; + + /** + * Read global default value. + */ + virtual void readDefault(KConfig *) = 0; + + /** + * Set item to @p p + */ + virtual void setProperty(const QVariant &p) = 0; + + /** + * Return item as property + */ + virtual QVariant property() const = 0; + + /** + * Return minimum value of item or invalid if not specified + */ + virtual QVariant minValue() const { return QVariant(); } + + /** + * Return maximum value of item or invalid if not specified + */ + virtual QVariant maxValue() const { return QVariant(); } + + /** + Sets the current value to the default value. + */ + virtual void setDefault() = 0; + + /** + * Exchanges the current value with the default value + * Used by KConfigSkeleton::useDefaults(bool); + */ + virtual void swapDefault() = 0; + + /** + * Return if the entry can be modified. + */ + bool isImmutable() const + { + return mIsImmutable; + } + + protected: + /** + * sets mIsImmutable to true if mKey in config is immutable + * @param config KConfig to check if mKey is immutable in + */ + void readImmutability(KConfig *config); + + QString mGroup; + QString mKey; + QString mName; + + private: + bool mIsImmutable; + + QString mLabel; + QString mWhatsThis; + }; + + +template < typename T > class KConfigSkeletonGenericItem:public KConfigSkeletonItem + { + public: + KConfigSkeletonGenericItem(const QString & group, const QString & key, T & reference, + T defaultValue) + : KConfigSkeletonItem(group, key), mReference(reference), + mDefault(defaultValue), mLoadedValue(defaultValue) + { + } + + /** + * Set value of this KConfigSkeletonItem. + */ + void setValue(const T & v) + { + mReference = v; + } + + /** + * Return value of this KConfigSkeletonItem. + */ + T & value() + { + return mReference; + } + + /** + * Return const value of this KConfigSkeletonItem. + */ + const T & value() const + { + return mReference; + } + + /** + Set default value for this item. + */ + virtual void setDefaultValue( const T &v ) + { + mDefault = v; + } + + virtual void setDefault() + { + mReference = mDefault; + } + + virtual void writeConfig(KConfig * config) + { + if ( mReference != mLoadedValue ) // Is this needed? + { + config->setGroup(mGroup); + if ((mDefault == mReference) && !config->hasDefault( mKey)) + config->revertToDefault( mKey ); + else + config->writeEntry(mKey, mReference); + } + } + + void readDefault(KConfig * config) + { + config->setReadDefaults(true); + readConfig(config); + config->setReadDefaults(false); + mDefault = mReference; + } + + void swapDefault() + { + T tmp = mReference; + mReference = mDefault; + mDefault = tmp; + } + + protected: + T & mReference; + T mDefault; + T mLoadedValue; + }; + + /** + * @short Class for handling preferences settings for an application. + * @author Cornelius Schumacher + * @see KConfigSkeletonItem + * + * This class provides an interface to preferences settings. Preferences items + * can be registered by the addItem() function corresponding to the data type of + * the seetting. KConfigSkeleton then handles reading and writing of config files and + * setting of default values. + * + * Normally you will subclass KConfigSkeleton, add data members for the preferences + * settings and register the members in the constructor of the subclass. + * + * Example: + * \code + * class MyPrefs : public KConfigSkeleton + * { + * public: + * MyPrefs() + * { + * setCurrentGroup("MyGroup"); + * addItemBool("MySetting1",mMyBool,false); + * addItemColor("MySetting2",mMyColor,QColor(1,2,3)); + * + * setCurrentGroup("MyOtherGroup"); + * addItemFont("MySetting3",mMyFont,QFont("helvetica",12)); + * } + * + * bool mMyBool; + * QColor mMyColor; + * QFont mMyFont; + * } + * \endcode + * + * It might be convenient in many cases to make this subclass of KConfigSkeleton a + * singleton for global access from all over the application without passing + * references to the KConfigSkeleton object around. + * + * You can write the data to the configuration file by calling @ref writeConfig() + * and read the data from the configuration file by calling @ref readConfig(). + * + * If you have items, which are not covered by the existing addItem() functions + * you can add customized code for reading, writing and default setting by + * implementing the functions @ref usrUseDefaults(), @ref usrReadConfig() and + * @ref usrWriteConfig(). + * + * Internally preferences settings are stored in instances of subclasses of + * @ref KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses + * for your own types and call the generic @ref addItem() to register them. + * + * In many cases you don't have to write the specific KConfigSkeleton + * subclasses yourself, but you can use \ref kconfig_compiler to automatically + * generate the C++ code from an XML description of the configuration options. + */ +class KDECORE_EXPORT KConfigSkeleton +{ +public: + + /** + * Class for handling a string preferences item. + */ + class KDECORE_EXPORT ItemString:public KConfigSkeletonGenericItem < QString > + { + public: + enum Type { Normal, Password, Path }; + + ItemString(const QString & group, const QString & key, + QString & reference, + const QString & defaultValue = QString::fromLatin1(""), // NOT QString::null !! + Type type = Normal); + + void writeConfig(KConfig * config); + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + + private: + Type mType; + }; + + /** + * Class for handling a password preferences item. + */ + class KDECORE_EXPORT ItemPassword:public ItemString + { + public: + ItemPassword(const QString & group, const QString & key, + QString & reference, + const QString & defaultValue = QString::fromLatin1("")); // NOT QString::null !! + }; + + /** + * Class for handling a path preferences item. + */ + class KDECORE_EXPORT ItemPath:public ItemString + { + public: + ItemPath(const QString & group, const QString & key, + QString & reference, + const QString & defaultValue = QString::null); + }; + + + /** + * Class for handling a QVariant preferences item. + */ + class KDECORE_EXPORT ItemProperty:public KConfigSkeletonGenericItem < QVariant > + { + public: + ItemProperty(const QString & group, const QString & key, + QVariant & reference, QVariant defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a bool preferences item. + */ + class KDECORE_EXPORT ItemBool:public KConfigSkeletonGenericItem < bool > + { + public: + ItemBool(const QString & group, const QString & key, bool & reference, + bool defaultValue = true); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling an integer preferences item. + */ + class KDECORE_EXPORT ItemInt:public KConfigSkeletonGenericItem < int > + { + public: + ItemInt(const QString & group, const QString & key, int &reference, + int defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + QVariant minValue() const; + QVariant maxValue() const; + + void setMinValue(int); + void setMaxValue(int); + + private: + bool mHasMin : 1; + bool mHasMax : 1; + int mMin; + int mMax; + }; + + /** + * Class for handling an 64-bit integer preferences item. + */ + class KDECORE_EXPORT ItemInt64:public KConfigSkeletonGenericItem < Q_INT64 > + { + public: + ItemInt64(const QString & group, const QString & key, Q_INT64 &reference, + Q_INT64 defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + + QVariant minValue() const; + QVariant maxValue() const; + + void setMinValue(Q_INT64); + void setMaxValue(Q_INT64); + + private: + bool mHasMin : 1; + bool mHasMax : 1; + Q_INT64 mMin; + Q_INT64 mMax; + }; + + /** + * Class for handling enums. + */ + class KDECORE_EXPORT ItemEnum:public ItemInt + { + public: + struct Choice + { + QString name; + QString label; + QString whatsThis; + }; + + ItemEnum(const QString & group, const QString & key, int &reference, + const QValueList<Choice> &choices, int defaultValue = 0); + + QValueList<Choice> choices() const; + + void readConfig(KConfig * config); + void writeConfig(KConfig * config); + + private: + QValueList<Choice> mChoices; + }; + + + /** + * Class for handling an unsingend integer preferences item. + */ + class KDECORE_EXPORT ItemUInt:public KConfigSkeletonGenericItem < unsigned int > + { + public: + ItemUInt(const QString & group, const QString & key, + unsigned int &reference, unsigned int defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + QVariant minValue() const; + QVariant maxValue() const; + + void setMinValue(unsigned int); + void setMaxValue(unsigned int); + + private: + bool mHasMin : 1; + bool mHasMax : 1; + unsigned int mMin; + unsigned int mMax; + }; + + + /** + * Class for hanlding a long integer preferences item. + */ + class KDECORE_EXPORT ItemLong:public KConfigSkeletonGenericItem < long > + { + public: + ItemLong(const QString & group, const QString & key, long &reference, + long defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + QVariant minValue() const; + QVariant maxValue() const; + + void setMinValue(long); + void setMaxValue(long); + + private: + bool mHasMin : 1; + bool mHasMax : 1; + long mMin; + long mMax; + }; + + + /** + * Class for handling an unsigned long integer preferences item. + */ + class KDECORE_EXPORT ItemULong:public KConfigSkeletonGenericItem < unsigned long > + { + public: + ItemULong(const QString & group, const QString & key, + unsigned long &reference, unsigned long defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + QVariant minValue() const; + QVariant maxValue() const; + + void setMinValue(unsigned long); + void setMaxValue(unsigned long); + + private: + bool mHasMin : 1; + bool mHasMax : 1; + unsigned long mMin; + unsigned long mMax; + }; + + /** + * Class for handling unsigned 64-bit integer preferences item. + */ + class KDECORE_EXPORT ItemUInt64:public KConfigSkeletonGenericItem < Q_UINT64 > + { + public: + ItemUInt64(const QString & group, const QString & key, Q_UINT64 &reference, + Q_UINT64 defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + + QVariant minValue() const; + QVariant maxValue() const; + + void setMinValue(Q_UINT64); + void setMaxValue(Q_UINT64); + + private: + bool mHasMin : 1; + bool mHasMax : 1; + Q_UINT64 mMin; + Q_UINT64 mMax; + }; + + /** + * Class for handling a floating point preference item. + */ + class KDECORE_EXPORT ItemDouble:public KConfigSkeletonGenericItem < double > + { + public: + ItemDouble(const QString & group, const QString & key, + double &reference, double defaultValue = 0); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + QVariant minValue() const; + QVariant maxValue() const; + + void setMinValue(double); + void setMaxValue(double); + + private: + bool mHasMin : 1; + bool mHasMax : 1; + double mMin; + double mMax; + }; + + + /** + * Class for handling a color preferences item. + */ + class KDECORE_EXPORT ItemColor:public KConfigSkeletonGenericItem < QColor > + { + public: + ItemColor(const QString & group, const QString & key, + QColor & reference, + const QColor & defaultValue = QColor(128, 128, 128)); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a font preferences item. + */ + class KDECORE_EXPORT ItemFont:public KConfigSkeletonGenericItem < QFont > + { + public: + ItemFont(const QString & group, const QString & key, QFont & reference, + const QFont & defaultValue = KGlobalSettings::generalFont()); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a QRect preferences item. + */ + class KDECORE_EXPORT ItemRect:public KConfigSkeletonGenericItem < QRect > + { + public: + ItemRect(const QString & group, const QString & key, QRect & reference, + const QRect & defaultValue = QRect()); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a QPoint preferences item. + */ + class KDECORE_EXPORT ItemPoint:public KConfigSkeletonGenericItem < QPoint > + { + public: + ItemPoint(const QString & group, const QString & key, QPoint & reference, + const QPoint & defaultValue = QPoint()); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a QSize preferences item. + */ + class KDECORE_EXPORT ItemSize:public KConfigSkeletonGenericItem < QSize > + { + public: + ItemSize(const QString & group, const QString & key, QSize & reference, + const QSize & defaultValue = QSize()); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a QDateTime preferences item. + */ + class KDECORE_EXPORT ItemDateTime:public KConfigSkeletonGenericItem < QDateTime > + { + public: + ItemDateTime(const QString & group, const QString & key, + QDateTime & reference, + const QDateTime & defaultValue = QDateTime()); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a string list preferences item. + */ + class KDECORE_EXPORT ItemStringList:public KConfigSkeletonGenericItem < QStringList > + { + public: + ItemStringList(const QString & group, const QString & key, + QStringList & reference, + const QStringList & defaultValue = QStringList()); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + + /** + * Class for handling a path list preferences item. + */ + class KDECORE_EXPORT ItemPathList:public ItemStringList + { + public: + ItemPathList(const QString & group, const QString & key, + QStringList & reference, + const QStringList & defaultValue = QStringList()); + + void readConfig(KConfig * config); + void writeConfig(KConfig * config); + }; + + + /** + * Class for handling an integer list preferences item. + */ + class KDECORE_EXPORT ItemIntList:public KConfigSkeletonGenericItem < QValueList < int > > + { + public: + ItemIntList(const QString & group, const QString & key, + QValueList < int >&reference, + const QValueList < int >&defaultValue = QValueList < int >()); + + void readConfig(KConfig * config); + void setProperty(const QVariant & p); + QVariant property() const; + }; + + +public: + /** + * Constructor. + * + * @param configname name of config file. If no name is given, the default + * config file as returned by kapp()->config() is used. + */ + KConfigSkeleton(const QString & configname = QString::null); + + /** + * Constructor. + * + * @param config configuration object to use. + */ + KConfigSkeleton(KSharedConfig::Ptr config); + + /** + * Destructor + */ + virtual ~ KConfigSkeleton(); + + /** + Set all registered items to their default values. + */ + void setDefaults(); + + /** + * Read preferences from config file. All registered items are set to the + * values read from disk. + */ + void readConfig(); + + /** + * Write preferences to config file. The values of all registered items are + * written to disk. + */ + void writeConfig(); + + /** + * Set the config file group for subsequent addItem() calls. It is valid + * until setCurrentGroup() is called with a new argument. Call this before + * you add any items. The default value is "No Group". + */ + void setCurrentGroup(const QString & group); + + /** + * Returns the current group used for addItem() calls. + */ + QString currentGroup() // ### KDE 4.0: make const + { + return mCurrentGroup; + } + + /** + * Register a custom @ref KConfigSkeletonItem with a given name. If the name + * parameter is null, take the name from KConfigSkeletonItem::key(). + * Note that all names must be unique but that multiple entries can have + * the same key if they reside in different groups. + */ + void addItem(KConfigSkeletonItem *, const QString & name = QString::null ); + + /** + * Register an item of type QString. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemString *addItemString(const QString & name, QString & reference, + const QString & defaultValue = QString::fromLatin1(""), // NOT QString::null !! + const QString & key = QString::null); + + /** + * Register a password item of type QString. The string value is written + * encrypted to the config file. Note that the current encryption scheme + * is very weak. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemPassword *addItemPassword(const QString & name, QString & reference, + const QString & defaultValue = QString::fromLatin1(""), + const QString & key = QString::null); + + /** + * Register a path item of type QString. The string value is interpreted + * as a path. This means, dollar expension is activated for this value, so + * that e.g. $HOME gets expanded. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemPath *addItemPath(const QString & name, QString & reference, + const QString & defaultValue = QString::fromLatin1(""), + const QString & key = QString::null); + + /** + * Register a property item of type QVariant. Note that only the following + * QVariant types are allowed: String, StringList, Font, Point, Rect, Size, + * Color, Int, UInt, Bool, Double, DateTime and Date. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemProperty *addItemProperty(const QString & name, QVariant & reference, + const QVariant & defaultValue = QVariant(), + const QString & key = QString::null); + /** + * Register an item of type bool. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemBool *addItemBool(const QString & name, bool & reference, + bool defaultValue = false, + const QString & key = QString::null); + + /** + * Register an item of type int. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemInt *addItemInt(const QString & name, int &reference, int defaultValue = 0, + const QString & key = QString::null); + + /** + * Register an item of type unsigned int. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemUInt *addItemUInt(const QString & name, unsigned int &reference, + unsigned int defaultValue = 0, + const QString & key = QString::null); + + /** + * Register an item of type long. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemLong *addItemLong(const QString & name, long &reference, + long defaultValue = 0, + const QString & key = QString::null); + + /** + * Register an item of type unsigned long. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemULong *addItemULong(const QString & name, unsigned long &reference, + unsigned long defaultValue = 0, + const QString & key = QString::null); + + /** + * Register an item of type Q_INT64. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemInt64 *addItemInt64(const QString & name, Q_INT64 &reference, + Q_INT64 defaultValue = 0, + const QString & key = QString::null); + + /** + * Register an item of type Q_UINT64 + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemUInt64 *addItemUInt64(const QString & name, Q_UINT64 &reference, + Q_UINT64 defaultValue = 0, + const QString & key = QString::null); + + /** + * Register an item of type double. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemDouble *addItemDouble(const QString & name, double &reference, + double defaultValue = 0.0, + const QString & key = QString::null); + + /** + * Register an item of type QColor. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemColor *addItemColor(const QString & name, QColor & reference, + const QColor & defaultValue = QColor(128, 128, 128), + const QString & key = QString::null); + + /** + * Register an item of type QFont. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemFont *addItemFont(const QString & name, QFont & reference, + const QFont & defaultValue = + KGlobalSettings::generalFont(), + const QString & key = QString::null); + + /** + * Register an item of type QRect. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemRect *addItemRect(const QString & name, QRect & reference, + const QRect & defaultValue = QRect(), + const QString & key = QString::null); + + /** + * Register an item of type QPoint. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemPoint *addItemPoint(const QString & name, QPoint & reference, + const QPoint & defaultValue = QPoint(), + const QString & key = QString::null); + + /** + * Register an item of type QSize. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemSize *addItemSize(const QString & name, QSize & reference, + const QSize & defaultValue = QSize(), + const QString & key = QString::null); + + /** + * Register an item of type QDateTime. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemDateTime *addItemDateTime(const QString & name, QDateTime & reference, + const QDateTime & defaultValue = QDateTime(), + const QString & key = QString::null); + + /** + * Register an item of type QStringList. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemStringList *addItemStringList(const QString & name, QStringList & reference, + const QStringList & defaultValue = QStringList(), + const QString & key = QString::null); + + /** + * Register an item of type QValueList<int>. + * + * @param name Name used to indentify this setting. Names must be unique. + * @param reference Pointer to the variable, which is set by readConfig() + * calls and read by writeConfig() calls. + * @param defaultValue Default value, which is used when the config file + * does not yet contain the key of this item. + * @param key Key used in config file. If key is null, name is used as key. + * @return The created item + */ + ItemIntList *addItemIntList(const QString & name, QValueList < int >&reference, + const QValueList < int >&defaultValue = + QValueList < int >(), + const QString & key = QString::null); + + /** + * Return the @ref KConfig object used for reading and writing the settings. + */ + KConfig *config() const; + + /** + * Return list of items managed by this KConfigSkeleton object. + */ + KConfigSkeletonItem::List items() const + { + return mItems; + } + + /** + * Return whether a certain item is immutable + */ + bool isImmutable(const QString & name); + + /** + * Lookup item by name + */ + KConfigSkeletonItem * findItem(const QString & name); + + /** + * Indicate whether this object should reflect the actual + * values or the default values. + * @param b If true this object reflects the default values. + * @return The state prior to this call + */ + bool useDefaults(bool b); + +protected: + /** + * Implemented by subclasses that use special defaults. + * It should replace the default values with the actual + * values and vice versa. + */ + virtual void usrUseDefaults(bool) + { + } + + virtual void usrSetDefaults() + { + } + + /** + * Implemented by subclasses that read special config values. + */ + virtual void usrReadConfig() + { + } + + /** + * Implemented by subclasses that write special config values. + */ + virtual void usrWriteConfig() + { + } + +private: + QString mCurrentGroup; + + KSharedConfig::Ptr mConfig; // pointer to KConfig object + + KConfigSkeletonItem::List mItems; + KConfigSkeletonItem::Dict mItemDict; + + bool mUseDefaults; + + class Private; + Private *d; + +}; + +#endif |