kdecore Library API Documentation

KConfigSkeleton Class Reference

Class for handling preferences settings for an application. More...

#include <kconfigskeleton.h>

List of all members.

Public Member Functions

 KConfigSkeleton (const QString &configname=QString::null)
 KConfigSkeleton (KSharedConfig::Ptr config)
virtual ~KConfigSkeleton ()
void setDefaults ()
void readConfig ()
void writeConfig ()
void setCurrentGroup (const QString &group)
QString currentGroup ()
void addItem (KConfigSkeletonItem *, const QString &name=QString::null)
ItemStringaddItemString (const QString &name, QString &reference, const QString &defaultValue=QString::fromLatin1(""), const QString &key=QString::null)
ItemPasswordaddItemPassword (const QString &name, QString &reference, const QString &defaultValue=QString::fromLatin1(""), const QString &key=QString::null)
ItemPathaddItemPath (const QString &name, QString &reference, const QString &defaultValue=QString::fromLatin1(""), const QString &key=QString::null)
ItemPropertyaddItemProperty (const QString &name, QVariant &reference, const QVariant &defaultValue=QVariant(), const QString &key=QString::null)
ItemBooladdItemBool (const QString &name, bool &reference, bool defaultValue=false, const QString &key=QString::null)
ItemIntaddItemInt (const QString &name, int &reference, int defaultValue=0, const QString &key=QString::null)
ItemUIntaddItemUInt (const QString &name, unsigned int &reference, unsigned int defaultValue=0, const QString &key=QString::null)
ItemLongaddItemLong (const QString &name, long &reference, long defaultValue=0, const QString &key=QString::null)
ItemULongaddItemULong (const QString &name, unsigned long &reference, unsigned long defaultValue=0, const QString &key=QString::null)
ItemInt64addItemInt64 (const QString &name, Q_INT64 &reference, Q_INT64 defaultValue=0, const QString &key=QString::null)
ItemUInt64addItemUInt64 (const QString &name, Q_UINT64 &reference, Q_UINT64 defaultValue=0, const QString &key=QString::null)
ItemDoubleaddItemDouble (const QString &name, double &reference, double defaultValue=0.0, const QString &key=QString::null)
ItemColoraddItemColor (const QString &name, QColor &reference, const QColor &defaultValue=QColor(128, 128, 128), const QString &key=QString::null)
ItemFontaddItemFont (const QString &name, QFont &reference, const QFont &defaultValue=KGlobalSettings::generalFont(), const QString &key=QString::null)
ItemRectaddItemRect (const QString &name, QRect &reference, const QRect &defaultValue=QRect(), const QString &key=QString::null)
ItemPointaddItemPoint (const QString &name, QPoint &reference, const QPoint &defaultValue=QPoint(), const QString &key=QString::null)
ItemSizeaddItemSize (const QString &name, QSize &reference, const QSize &defaultValue=QSize(), const QString &key=QString::null)
ItemDateTimeaddItemDateTime (const QString &name, QDateTime &reference, const QDateTime &defaultValue=QDateTime(), const QString &key=QString::null)
ItemStringListaddItemStringList (const QString &name, QStringList &reference, const QStringList &defaultValue=QStringList(), const QString &key=QString::null)
ItemIntListaddItemIntList (const QString &name, QValueList< int > &reference, const QValueList< int > &defaultValue=QValueList< int >(), const QString &key=QString::null)
KConfigconfig () const
KConfigSkeletonItem::List items () const
bool isImmutable (const QString &name)
KConfigSkeletonItemfindItem (const QString &name)
bool useDefaults (bool b)

Protected Member Functions

virtual void usrUseDefaults (bool)
virtual void usrSetDefaults ()
virtual void usrReadConfig ()
virtual void usrWriteConfig ()


Detailed Description

Class for handling preferences settings for an application.

Author:
Cornelius Schumacher
See also:
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:

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; }

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 writeConfig() and read the data from the configuration file by calling 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 usrUseDefaults(), usrReadConfig() and usrWriteConfig().

Internally preferences settings are stored in instances of subclasses of KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses for your own types and call the generic addItem() to register them.

In many cases you don't have to write the specific KConfigSkeleton subclasses yourself, but you can use The KDE Configuration Compiler to automatically generate the C++ code from an XML description of the configuration options.

Definition at line 361 of file kconfigskeleton.h.


Constructor & Destructor Documentation

KConfigSkeleton::KConfigSkeleton const QString configname = QString::null  ) 
 

Constructor.

Parameters:
configname name of config file. If no name is given, the default config file as returned by kapp()->config() is used.

Definition at line 847 of file kconfigskeleton.cpp.

References endl(), KConfigSkeleton(), and KGlobal::sharedConfig().

Referenced by KConfigSkeleton().

KConfigSkeleton::KConfigSkeleton KSharedConfig::Ptr  config  ) 
 

Constructor.

Parameters:
config configuration object to use.

Definition at line 862 of file kconfigskeleton.cpp.

References endl(), and KConfigSkeleton().

KConfigSkeleton::~KConfigSkeleton  )  [virtual]
 

Destructor.

Definition at line 870 of file kconfigskeleton.cpp.


Member Function Documentation

void KConfigSkeleton::setDefaults  ) 
 

Set all registered items to their default values.

Definition at line 905 of file kconfigskeleton.cpp.

void KConfigSkeleton::readConfig  ) 
 

Read preferences from config file.

All registered items are set to the values read from disk.

Definition at line 915 of file kconfigskeleton.cpp.

References endl(), and usrReadConfig().

Referenced by writeConfig().

void KConfigSkeleton::writeConfig  ) 
 

Write preferences to config file.

The values of all registered items are written to disk.

Definition at line 928 of file kconfigskeleton.cpp.

References endl(), readConfig(), and usrWriteConfig().

Referenced by KConfigDialogManager::updateSettings().

void KConfigSkeleton::setCurrentGroup const QString group  ) 
 

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".

Definition at line 879 of file kconfigskeleton.cpp.

References setCurrentGroup().

Referenced by setCurrentGroup().

QString KConfigSkeleton::currentGroup  )  [inline]
 

Returns the current group used for addItem() calls.

Definition at line 818 of file kconfigskeleton.h.

void KConfigSkeleton::addItem KConfigSkeletonItem ,
const QString name = QString::null
 

Register a custom 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.

Definition at line 945 of file kconfigskeleton.cpp.

References addItem(), KConfigSkeletonItem::key(), KConfigSkeletonItem::name(), KConfigSkeletonItem::readDefault(), and KConfigSkeletonItem::setName().

Referenced by addItem(), addItemBool(), addItemColor(), addItemDateTime(), addItemDouble(), addItemFont(), addItemInt(), addItemInt64(), addItemIntList(), addItemLong(), addItemPassword(), addItemPath(), addItemPoint(), addItemProperty(), addItemRect(), addItemSize(), addItemString(), addItemStringList(), addItemUInt(), addItemUInt64(), and addItemULong().

KConfigSkeleton::ItemString * KConfigSkeleton::addItemString const QString name,
QString reference,
const QString defaultValue = QString::fromLatin1(""),
const QString key = QString::null
 

Register an item of type QString.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 953 of file kconfigskeleton.cpp.

References addItem(), and addItemString().

Referenced by addItemString().

KConfigSkeleton::ItemPassword * KConfigSkeleton::addItemPassword const QString name,
QString reference,
const QString defaultValue = QString::fromLatin1(""),
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.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 964 of file kconfigskeleton.cpp.

References addItem(), and addItemPassword().

Referenced by addItemPassword().

KConfigSkeleton::ItemPath * KConfigSkeleton::addItemPath 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.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 974 of file kconfigskeleton.cpp.

References addItem(), and addItemPath().

Referenced by addItemPath().

KConfigSkeleton::ItemProperty * KConfigSkeleton::addItemProperty const QString name,
QVariant reference,
const QVariant defaultValue = QVariant(),
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.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 984 of file kconfigskeleton.cpp.

References addItem(), and addItemProperty().

Referenced by addItemProperty().

KConfigSkeleton::ItemBool * KConfigSkeleton::addItemBool const QString name,
bool &  reference,
bool  defaultValue = false,
const QString key = QString::null
 

Register an item of type bool.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 994 of file kconfigskeleton.cpp.

References addItem(), and addItemBool().

Referenced by addItemBool().

KConfigSkeleton::ItemInt * KConfigSkeleton::addItemInt const QString name,
int &  reference,
int  defaultValue = 0,
const QString key = QString::null
 

Register an item of type int.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1004 of file kconfigskeleton.cpp.

References addItem(), and addItemInt().

Referenced by addItemInt().

KConfigSkeleton::ItemUInt * KConfigSkeleton::addItemUInt const QString name,
unsigned int &  reference,
unsigned int  defaultValue = 0,
const QString key = QString::null
 

Register an item of type unsigned int.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1014 of file kconfigskeleton.cpp.

References addItem(), and addItemUInt().

Referenced by addItemUInt().

KConfigSkeleton::ItemLong * KConfigSkeleton::addItemLong const QString name,
long &  reference,
long  defaultValue = 0,
const QString key = QString::null
 

Register an item of type long.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1044 of file kconfigskeleton.cpp.

References addItem(), and addItemLong().

Referenced by addItemLong().

KConfigSkeleton::ItemULong * KConfigSkeleton::addItemULong const QString name,
unsigned long &  reference,
unsigned long  defaultValue = 0,
const QString key = QString::null
 

Register an item of type unsigned long.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1054 of file kconfigskeleton.cpp.

References addItem(), and addItemULong().

Referenced by addItemULong().

KConfigSkeleton::ItemInt64 * KConfigSkeleton::addItemInt64 const QString name,
Q_INT64 &  reference,
Q_INT64  defaultValue = 0,
const QString key = QString::null
 

Register an item of type Q_INT64.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1024 of file kconfigskeleton.cpp.

References addItem(), and addItemInt64().

Referenced by addItemInt64().

KConfigSkeleton::ItemUInt64 * KConfigSkeleton::addItemUInt64 const QString name,
Q_UINT64 &  reference,
Q_UINT64  defaultValue = 0,
const QString key = QString::null
 

Register an item of type Q_UINT64.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1034 of file kconfigskeleton.cpp.

References addItem(), and addItemUInt64().

Referenced by addItemUInt64().

KConfigSkeleton::ItemDouble * KConfigSkeleton::addItemDouble const QString name,
double &  reference,
double  defaultValue = 0.0,
const QString key = QString::null
 

Register an item of type double.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1064 of file kconfigskeleton.cpp.

References addItem(), and addItemDouble().

Referenced by addItemDouble().

KConfigSkeleton::ItemColor * KConfigSkeleton::addItemColor const QString name,
QColor reference,
const QColor defaultValue = QColor(128, 128, 128),
const QString key = QString::null
 

Register an item of type QColor.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1074 of file kconfigskeleton.cpp.

References addItem(), and addItemColor().

Referenced by addItemColor().

KConfigSkeleton::ItemFont * KConfigSkeleton::addItemFont const QString name,
QFont reference,
const QFont defaultValue = KGlobalSettings::generalFont(),
const QString key = QString::null
 

Register an item of type QFont.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1084 of file kconfigskeleton.cpp.

References addItem(), and addItemFont().

Referenced by addItemFont().

KConfigSkeleton::ItemRect * KConfigSkeleton::addItemRect const QString name,
QRect reference,
const QRect defaultValue = QRect(),
const QString key = QString::null
 

Register an item of type QRect.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1094 of file kconfigskeleton.cpp.

References addItem(), and addItemRect().

Referenced by addItemRect().

KConfigSkeleton::ItemPoint * KConfigSkeleton::addItemPoint const QString name,
QPoint reference,
const QPoint defaultValue = QPoint(),
const QString key = QString::null
 

Register an item of type QPoint.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1104 of file kconfigskeleton.cpp.

References addItem(), and addItemPoint().

Referenced by addItemPoint().

KConfigSkeleton::ItemSize * KConfigSkeleton::addItemSize const QString name,
QSize reference,
const QSize defaultValue = QSize(),
const QString key = QString::null
 

Register an item of type QSize.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1114 of file kconfigskeleton.cpp.

References addItem(), and addItemSize().

Referenced by addItemSize().

KConfigSkeleton::ItemDateTime * KConfigSkeleton::addItemDateTime const QString name,
QDateTime reference,
const QDateTime defaultValue = QDateTime(),
const QString key = QString::null
 

Register an item of type QDateTime.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1124 of file kconfigskeleton.cpp.

References addItem(), and addItemDateTime().

Referenced by addItemDateTime().

KConfigSkeleton::ItemStringList * KConfigSkeleton::addItemStringList const QString name,
QStringList reference,
const QStringList defaultValue = QStringList(),
const QString key = QString::null
 

Register an item of type QStringList.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1134 of file kconfigskeleton.cpp.

References addItem(), and addItemStringList().

Referenced by addItemStringList().

KConfigSkeleton::ItemIntList * KConfigSkeleton::addItemIntList const QString name,
QValueList< int > &  reference,
const QValueList< int > &  defaultValue = QValueList< int >(),
const QString key = QString::null
 

Register an item of type QValueList<int>.

Parameters:
name Name used to indentify this setting. Names must be unique.
reference Pointer to the variable, which is set by readConfig() calls and read by writeConfig() calls.
defaultValue Default value, which is used when the config file does not yet contain the key of this item.
key Key used in config file. If key is null, name is used as key.
Returns:
The created item

Definition at line 1144 of file kconfigskeleton.cpp.

References addItem(), and addItemIntList().

Referenced by addItemIntList().

KConfig * KConfigSkeleton::config  )  const
 

Return the KConfig object used for reading and writing the settings.

Definition at line 884 of file kconfigskeleton.cpp.

KConfigSkeletonItem::List KConfigSkeleton::items  )  const [inline]
 

Return list of items managed by this KConfigSkeleton object.

Definition at line 1145 of file kconfigskeleton.h.

bool KConfigSkeleton::isImmutable const QString name  ) 
 

Return whether a certain item is immutable.

Definition at line 1154 of file kconfigskeleton.cpp.

References findItem(), KConfigSkeletonItem::isImmutable(), and isImmutable().

Referenced by isImmutable().

KConfigSkeletonItem * KConfigSkeleton::findItem const QString name  ) 
 

Lookup item by name.

Definition at line 1160 of file kconfigskeleton.cpp.

References findItem().

Referenced by findItem(), KConfigDialogManager::hasChanged(), isImmutable(), KConfigDialogManager::parseChildren(), KConfigDialogManager::updateSettings(), and KConfigDialogManager::updateWidgets().

bool KConfigSkeleton::useDefaults bool  b  ) 
 

Indicate whether this object should reflect the actual values or the default values.

Parameters:
b If true this object reflects the default values.
Returns:
The state prior to this call

Definition at line 889 of file kconfigskeleton.cpp.

References useDefaults(), and usrUseDefaults().

Referenced by KConfigDialogManager::isDefault(), KConfigDialogManager::updateWidgetsDefault(), and useDefaults().

virtual void KConfigSkeleton::usrUseDefaults bool   )  [inline, protected, virtual]
 

Implemented by subclasses that use special defaults.

It should replace the default values with the actual values and vice versa.

Definition at line 1174 of file kconfigskeleton.h.

References usrUseDefaults().

Referenced by useDefaults(), and usrUseDefaults().

virtual void KConfigSkeleton::usrReadConfig  )  [inline, protected, virtual]
 

Implemented by subclasses that read special config values.

Definition at line 1185 of file kconfigskeleton.h.

Referenced by readConfig().

virtual void KConfigSkeleton::usrWriteConfig  )  [inline, protected, virtual]
 

Implemented by subclasses that write special config values.

Definition at line 1192 of file kconfigskeleton.h.

Referenced by writeConfig().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdecore Library Version 3.2.3.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Fri Oct 8 11:14:06 2004 by doxygen 1.3.7 written by Dimitri van Heesch, © 1997-2003