KConfigSkeleton Class Reference

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

#include <kconfigskeleton.h>


Classes
class	ItemBool
	Class for handling a bool preferences item. More...
class	ItemColor
	Class for handling a color preferences item. More...
class	ItemDateTime
	Class for handling a QDateTime preferences item. More...
class	ItemDouble
	Class for handling a floating point preference item. More...
class	ItemEnum
	Class for handling enums. More...
class	ItemFont
	Class for handling a font preferences item. More...
class	ItemInt
	Class for handling an integer preferences item. More...
class	ItemInt64
	Class for handling an 64-bit integer preferences item. More...
class	ItemIntList
	Class for handling an integer list preferences item. More...
class	ItemLong
	Class for hanlding a long integer preferences item. More...
class	ItemPassword
	Class for handling a password preferences item. More...
class	ItemPath
	Class for handling a path preferences item. More...
class	ItemPathList
	Class for handling a path list preferences item. More...
class	ItemPoint
	Class for handling a QPoint preferences item. More...
class	ItemProperty
	Class for handling a QVariant preferences item. More...
class	ItemRect
	Class for handling a QRect preferences item. More...
class	ItemSize
	Class for handling a QSize preferences item. More...
class	ItemString
	Class for handling a string preferences item. More...
class	ItemStringList
	Class for handling a string list preferences item. More...
class	ItemUInt
	Class for handling an unsingend integer preferences item. More...
class	ItemUInt64
	Class for handling unsigned 64-bit integer preferences item. More...
class	ItemULong
	Class for handling an unsigned long integer preferences item. More...
Public Member Functions
void	addItem (KConfigSkeletonItem *, const QString &name=QString::null)
ItemBool *	addItemBool (const QString &name, bool &reference, bool defaultValue=false, const QString &key=QString::null)
ItemColor *	addItemColor (const QString &name, QColor &reference, const QColor &defaultValue=QColor(128, 128, 128), const QString &key=QString::null)
ItemDateTime *	addItemDateTime (const QString &name, QDateTime &reference, const QDateTime &defaultValue=QDateTime(), const QString &key=QString::null)
ItemDouble *	addItemDouble (const QString &name, double &reference, double defaultValue=0.0, const QString &key=QString::null)
ItemFont *	addItemFont (const QString &name, QFont &reference, const QFont &defaultValue=KGlobalSettings::generalFont(), const QString &key=QString::null)
ItemInt *	addItemInt (const QString &name, int &reference, int defaultValue=0, const QString &key=QString::null)
ItemInt64 *	addItemInt64 (const QString &name, Q_INT64 &reference, Q_INT64 defaultValue=0, const QString &key=QString::null)
ItemIntList *	addItemIntList (const QString &name, QValueList< int > &reference, const QValueList< int > &defaultValue=QValueList< int >(), const QString &key=QString::null)
ItemLong *	addItemLong (const QString &name, long &reference, long defaultValue=0, const QString &key=QString::null)
ItemPassword *	addItemPassword (const QString &name, QString &reference, const QString &defaultValue=QString::fromLatin1(""), const QString &key=QString::null)
ItemPath *	addItemPath (const QString &name, QString &reference, const QString &defaultValue=QString::fromLatin1(""), const QString &key=QString::null)
ItemPoint *	addItemPoint (const QString &name, QPoint &reference, const QPoint &defaultValue=QPoint(), const QString &key=QString::null)
ItemProperty *	addItemProperty (const QString &name, QVariant &reference, const QVariant &defaultValue=QVariant(), const QString &key=QString::null)
ItemRect *	addItemRect (const QString &name, QRect &reference, const QRect &defaultValue=QRect(), const QString &key=QString::null)
ItemSize *	addItemSize (const QString &name, QSize &reference, const QSize &defaultValue=QSize(), const QString &key=QString::null)
ItemString *	addItemString (const QString &name, QString &reference, const QString &defaultValue=QString::fromLatin1(""), const QString &key=QString::null)
ItemStringList *	addItemStringList (const QString &name, QStringList &reference, const QStringList &defaultValue=QStringList(), const QString &key=QString::null)
ItemUInt *	addItemUInt (const QString &name, unsigned int &reference, unsigned int defaultValue=0, const QString &key=QString::null)
ItemUInt64 *	addItemUInt64 (const QString &name, Q_UINT64 &reference, Q_UINT64 defaultValue=0, const QString &key=QString::null)
ItemULong *	addItemULong (const QString &name, unsigned long &reference, unsigned long defaultValue=0, const QString &key=QString::null)
KConfig *	config () const
QString	currentGroup ()
KConfigSkeletonItem *	findItem (const QString &name)
bool	isImmutable (const QString &name)
KConfigSkeletonItem::List	items () const
	KConfigSkeleton (KSharedConfig::Ptr config)
	KConfigSkeleton (const QString &configname=QString::null)
void	readConfig ()
void	setCurrentGroup (const QString &group)
void	setDefaults ()
bool	useDefaults (bool b)
void	writeConfig ()
virtual	~KConfigSkeleton ()
Protected Member Functions
virtual void	usrReadConfig ()
virtual void	usrSetDefaults ()
virtual void	usrUseDefaults (bool)
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 365 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 881 of file kconfigskeleton.cpp.

KConfigSkeleton::KConfigSkeleton ( KSharedConfig::Ptr config )

Constructor.

Parameters:

config

configuration object to use.

Definition at line 896 of file kconfigskeleton.cpp.

KConfigSkeleton::~KConfigSkeleton ( ) [virtual]

Destructor.

Definition at line 904 of file kconfigskeleton.cpp.

Member Function Documentation

void KConfigSkeleton::addItem	(	KConfigSkeletonItem *	item,
		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 988 of file kconfigskeleton.cpp.

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 1038 of file kconfigskeleton.cpp.

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 1118 of file kconfigskeleton.cpp.

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 1168 of file kconfigskeleton.cpp.

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 1108 of file kconfigskeleton.cpp.

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 1128 of file kconfigskeleton.cpp.

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 1048 of file kconfigskeleton.cpp.

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 1068 of file kconfigskeleton.cpp.

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 1188 of file kconfigskeleton.cpp.

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 1088 of file kconfigskeleton.cpp.

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 1008 of file kconfigskeleton.cpp.

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 1018 of file kconfigskeleton.cpp.

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 1148 of file kconfigskeleton.cpp.

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 1028 of file kconfigskeleton.cpp.

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 1138 of file kconfigskeleton.cpp.

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 1158 of file kconfigskeleton.cpp.

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 997 of file kconfigskeleton.cpp.

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 1178 of file kconfigskeleton.cpp.

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 1058 of file kconfigskeleton.cpp.

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 1078 of file kconfigskeleton.cpp.

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 1098 of file kconfigskeleton.cpp.

KConfig * KConfigSkeleton::config ( ) const

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

Definition at line 918 of file kconfigskeleton.cpp.

QString KConfigSkeleton::currentGroup ( ) [inline]

Returns the current group used for addItem() calls.

Definition at line 837 of file kconfigskeleton.h.

KConfigSkeletonItem * KConfigSkeleton::findItem ( const QString & name )

Lookup item by name.

Definition at line 1204 of file kconfigskeleton.cpp.

bool KConfigSkeleton::isImmutable ( const QString & name )

Return whether a certain item is immutable.

Definition at line 1198 of file kconfigskeleton.cpp.

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

Return list of items managed by this KConfigSkeleton object.

Definition at line 1164 of file kconfigskeleton.h.

void KConfigSkeleton::readConfig ( )

Read preferences from config file.

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

Definition at line 949 of file kconfigskeleton.cpp.

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 913 of file kconfigskeleton.cpp.

void KConfigSkeleton::setDefaults ( )

Set all registered items to their default values.

Definition at line 939 of file kconfigskeleton.cpp.

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 923 of file kconfigskeleton.cpp.

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

Implemented by subclasses that read special config values.

Definition at line 1204 of file kconfigskeleton.h.

virtual void KConfigSkeleton::usrSetDefaults ( ) [inline, protected, virtual]

Definition at line 1197 of file kconfigskeleton.h.

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 1193 of file kconfigskeleton.h.

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

Implemented by subclasses that write special config values.

Definition at line 1211 of file kconfigskeleton.h.

void KConfigSkeleton::writeConfig ( )

Write preferences to config file.

The values of all registered items are written to disk.

Definition at line 967 of file kconfigskeleton.cpp.

The documentation for this class was generated from the following files:

KDECore

KConfigSkeleton Class Reference

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

KDECore

API Reference