KDECore

KCoreConfigSkeleton Class Reference

#include <KCoreConfigSkeleton>

Inheritance diagram for KCoreConfigSkeleton:

[legend]

List of all members.

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. KCoreConfigSkeleton then handles reading and writing of config files and setting of default values.

Normally you will subclass KCoreConfigSkeleton, add data members for the preferences settings and register the members in the constructor of the subclass.

Example:

 class MyPrefs : public KCoreConfigSkeleton
 {
   public:
     MyPrefs()
     {
       setCurrentGroup("MyGroup");
       addItemBool("MySetting1", mMyBool, false);
       addItemPoint("MySetting2", mMyPoint, QPoint(100, 200));

       setCurrentGroup("MyOtherGroup");
       addItemDouble("MySetting3", mMyDouble, 3.14);
     }

     bool mMyBool;
     QPoint mMyPoint;
     double mMyDouble;
 }

It might be convenient in many cases to make this subclass of KCoreConfigSkeleton a singleton for global access from all over the application without passing references to the KCoreConfigSkeleton 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 want to watch for config changes, use configChanged() signal.

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 KCoreConfigSkeleton subclasses yourself, but you can use The KDE Configuration Compiler to automatically generate the C++ code from an XML description of the configuration options.

Use KConfigSkeleton if you need GUI types as well.

Definition at line 366 of file kcoreconfigskeleton.h.


Public Types
typedef ItemLongLong	ItemInt64
typedef ItemULongLong	ItemUInt64
Signals
void	configChanged ()
Public Member Functions
void	addItem (KConfigSkeletonItem *, const QString &name=QString())
ItemBool *	addItemBool (const QString &name, bool &reference, bool defaultValue=false, const QString &key=QString())
ItemDateTime *	addItemDateTime (const QString &name, QDateTime &reference, const QDateTime &defaultValue=QDateTime(), const QString &key=QString())
ItemDouble *	addItemDouble (const QString &name, double &reference, double defaultValue=0.0, const QString &key=QString())
ItemInt *	addItemInt (const QString &name, qint32 &reference, qint32 defaultValue=0, const QString &key=QString())
ItemLongLong *	addItemInt64 (const QString &name, qint64 &reference, qint64 defaultValue=0, const QString &key=QString())
ItemIntList *	addItemIntList (const QString &name, QList< int > &reference, const QList< int > &defaultValue=QList< int >(), const QString &key=QString())
ItemLongLong *	addItemLongLong (const QString &name, qint64 &reference, qint64 defaultValue=0, const QString &key=QString())
ItemPassword *	addItemPassword (const QString &name, QString &reference, const QString &defaultValue=QLatin1String(""), const QString &key=QString())
ItemPath *	addItemPath (const QString &name, QString &reference, const QString &defaultValue=QLatin1String(""), const QString &key=QString())
ItemPoint *	addItemPoint (const QString &name, QPoint &reference, const QPoint &defaultValue=QPoint(), const QString &key=QString())
ItemProperty *	addItemProperty (const QString &name, QVariant &reference, const QVariant &defaultValue=QVariant(), const QString &key=QString())
ItemRect *	addItemRect (const QString &name, QRect &reference, const QRect &defaultValue=QRect(), const QString &key=QString())
ItemSize *	addItemSize (const QString &name, QSize &reference, const QSize &defaultValue=QSize(), const QString &key=QString())
ItemString *	addItemString (const QString &name, QString &reference, const QString &defaultValue=QLatin1String(""), const QString &key=QString())
ItemStringList *	addItemStringList (const QString &name, QStringList &reference, const QStringList &defaultValue=QStringList(), const QString &key=QString())
ItemUInt *	addItemUInt (const QString &name, quint32 &reference, quint32 defaultValue=0, const QString &key=QString())
ItemULongLong *	addItemUInt64 (const QString &name, quint64 &reference, quint64 defaultValue=0, const QString &key=QString())
ItemULongLong *	addItemULongLong (const QString &name, quint64 &reference, quint64 defaultValue=0, const QString &key=QString())
const KConfig *	config () const
KConfig *	config ()
QString	currentGroup () const
KConfigSkeletonItem *	findItem (const QString &name)
bool	isImmutable (const QString &name)
KConfigSkeletonItem::List	items () const
	KCoreConfigSkeleton (KSharedConfig::Ptr config, QObject *parent=0)
	KCoreConfigSkeleton (const QString &configname=QString(), QObject *parent=0)
virtual void	readConfig ()
void	setCurrentGroup (const QString &group)
virtual void	setDefaults ()
void	setSharedConfig (KSharedConfig::Ptr pConfig)
virtual bool	useDefaults (bool b)
virtual void	writeConfig ()
virtual	~KCoreConfigSkeleton ()
Protected Member Functions
virtual void	usrReadConfig ()
virtual void	usrSetDefaults ()
virtual bool	usrUseDefaults (bool b)
virtual void	usrWriteConfig ()
Classes
class	ItemBool
	Class for handling a bool 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	ItemInt
	Class for handling a 32-bit integer preferences item. More...
class	ItemIntList
	Class for handling an integer list preferences item. More...
class	ItemLongLong
	Class for handling a 64-bit 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 unsigned 32-bit integer preferences item. More...
class	ItemULongLong
	Class for handling unsigned 64-bit integer preferences item. More...
class	ItemUrl
	Class for handling a url preferences item. More...
class	ItemUrlList
	Class for handling a url list preferences item. More...

Member Typedef Documentation

typedef ItemLongLong KCoreConfigSkeleton::ItemInt64

Definition at line 601 of file kcoreconfigskeleton.h.

typedef ItemULongLong KCoreConfigSkeleton::ItemUInt64

Definition at line 732 of file kcoreconfigskeleton.h.

Constructor & Destructor Documentation

KCoreConfigSkeleton::KCoreConfigSkeleton	(	const QString &	configname = `QString()`,
		QObject *	parent = `0`
	)			`[explicit]`

Constructor.

Parameters:

configname

name of config file. If no name is given, the default config file as returned by KGlobal::config() is used.

Definition at line 978 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::KCoreConfigSkeleton	(	KSharedConfig::Ptr	config,
		QObject *	parent = `0`
	)			`[explicit]`

Constructor.

Parameters:

config

configuration object to use.

Definition at line 994 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::~KCoreConfigSkeleton ( ) [virtual]

Destructor.

Definition at line 1003 of file kcoreconfigskeleton.cpp.

Member Function Documentation

void KCoreConfigSkeleton::addItem	(	KConfigSkeletonItem *	item,
		const QString &	name = `QString()`
	)

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.

KCoreConfigSkeleton takes ownership of the KConfigSkeletonItem.

Definition at line 1108 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemBool * KCoreConfigSkeleton::addItemBool	(	const QString &	name,
		bool &	reference,
		bool	defaultValue = `false`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemDateTime * KCoreConfigSkeleton::addItemDateTime	(	const QString &	name,
		QDateTime &	reference,
		const QDateTime &	defaultValue = `QDateTime()`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1266 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemDouble * KCoreConfigSkeleton::addItemDouble	(	const QString &	name,
		double &	reference,
		double	defaultValue = `0.0`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1226 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemInt * KCoreConfigSkeleton::addItemInt	(	const QString &	name,
		qint32 &	reference,
		qint32	defaultValue = `0`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemLongLong * KCoreConfigSkeleton::addItemInt64	(	const QString &	name,
		qint64 &	reference,
		qint64	defaultValue = `0`,
		const QString &	key = `QString()`
	)

Definition at line 1198 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemIntList * KCoreConfigSkeleton::addItemIntList	(	const QString &	name,
		QList< int > &	reference,
		const QList< int > &	defaultValue = `QList < int >()`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1286 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemLongLong * KCoreConfigSkeleton::addItemLongLong	(	const QString &	name,
		qint64 &	reference,
		qint64	defaultValue = `0`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemPassword * KCoreConfigSkeleton::addItemPassword	(	const QString &	name,
		QString &	reference,
		const QString &	defaultValue = `QLatin1String("")`,
		const QString &	key = `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 identify 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 kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemPath * KCoreConfigSkeleton::addItemPath	(	const QString &	name,
		QString &	reference,
		const QString &	defaultValue = `QLatin1String("")`,
		const QString &	key = `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 identify 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 kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemPoint * KCoreConfigSkeleton::addItemPoint	(	const QString &	name,
		QPoint &	reference,
		const QPoint &	defaultValue = `QPoint()`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1246 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemProperty * KCoreConfigSkeleton::addItemProperty	(	const QString &	name,
		QVariant &	reference,
		const QVariant &	defaultValue = `QVariant()`,
		const QString &	key = `QString()`
	)

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 identify 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 kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemRect * KCoreConfigSkeleton::addItemRect	(	const QString &	name,
		QRect &	reference,
		const QRect &	defaultValue = `QRect()`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1236 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemSize * KCoreConfigSkeleton::addItemSize	(	const QString &	name,
		QSize &	reference,
		const QSize &	defaultValue = `QSize()`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1256 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemString * KCoreConfigSkeleton::addItemString	(	const QString &	name,
		QString &	reference,
		const QString &	defaultValue = `QLatin1String("")`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1117 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemStringList * KCoreConfigSkeleton::addItemStringList	(	const QString &	name,
		QStringList &	reference,
		const QStringList &	defaultValue = `QStringList()`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1276 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemUInt * KCoreConfigSkeleton::addItemUInt	(	const QString &	name,
		quint32 &	reference,
		quint32	defaultValue = `0`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemULongLong * KCoreConfigSkeleton::addItemUInt64	(	const QString &	name,
		quint64 &	reference,
		quint64	defaultValue = `0`,
		const QString &	key = `QString()`
	)

Definition at line 1217 of file kcoreconfigskeleton.cpp.

KCoreConfigSkeleton::ItemULongLong * KCoreConfigSkeleton::addItemULongLong	(	const QString &	name,
		quint64 &	reference,
		quint64	defaultValue = `0`,
		const QString &	key = `QString()`
	)

Parameters:

	name	Name used to identify 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 1207 of file kcoreconfigskeleton.cpp.

const KConfig * KCoreConfigSkeleton::config ( ) const

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

Definition at line 1023 of file kcoreconfigskeleton.cpp.

KConfig * KCoreConfigSkeleton::config ( )

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

Definition at line 1018 of file kcoreconfigskeleton.cpp.

void KCoreConfigSkeleton::configChanged ( ) [signal]

This signal is emitted when the configuration change.

QString KCoreConfigSkeleton::currentGroup ( ) const

Returns the current group used for addItem() calls.

Definition at line 1013 of file kcoreconfigskeleton.cpp.

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

Lookup item by name.

Definition at line 1302 of file kcoreconfigskeleton.cpp.

bool KCoreConfigSkeleton::isImmutable ( const QString & name )

Return whether a certain item is immutable.

Definition at line 1296 of file kcoreconfigskeleton.cpp.

KConfigSkeletonItem::List KCoreConfigSkeleton::items ( ) const

Return list of items managed by this KCoreConfigSkeleton object.

Definition at line 1033 of file kcoreconfigskeleton.cpp.

void KCoreConfigSkeleton::readConfig ( ) [virtual]

Read preferences from config file.

All registered items are set to the values read from disk. This method calls usrReadConfig() after reading the settings of the registered items from the KConfig. You can overridde usrReadConfig() in derived classes if you have special requirements. If you need more fine-grained control of storing the settings from the registered items you can override readConfig() in a derived class.

Definition at line 1062 of file kcoreconfigskeleton.cpp.

void KCoreConfigSkeleton::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 1008 of file kcoreconfigskeleton.cpp.

void KCoreConfigSkeleton::setDefaults ( ) [virtual]

Set all registered items to their default values.

This method calls usrSetDefaults() after setting the defaults for the registered items. You can overridde usrSetDefaults() in derived classes if you have special requirements. If you nee

KDECore

KCoreConfigSkeleton Class Reference

Detailed Description

Public Types

Signals

Public Member Functions

Protected Member Functions

Classes

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation