libkdepim Library API Documentation

KPrefs Class Reference

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

#include <kprefs.h>

List of all members.

Public Member Functions

 KPrefs (const QString &configname=QString::null)
 Constructor.

virtual ~KPrefs ()
 Destructor.

void setDefaults ()
 Set preferences to default values.

void readConfig ()
 Read preferences from config file.

void writeConfig ()
 Write preferences to config file.

void addItem (KPrefsItem *)
 Register a custom KPrefsItem.

void addItemBool (const QString &key, bool *reference, bool defaultValue=false)
 Register an item of type bool.

void addItemInt (const QString &key, int *reference, int defaultValue=0)
 Register an item of type int.

void addItemColor (const QString &key, QColor *reference, const QColor &defaultValue=QColor(128, 128, 128))
 Register an item of type QColor.

void addItemFont (const QString &key, QFont *reference, const QFont &defaultValue=QFont("helvetica", 12))
 Register an item of type QFont.

void addItemString (const QString &key, QString *reference, const QString &defaultValue="")
 Register an item of type QString.

void addItemPassword (const QString &key, QString *reference, const QString &defaultValue="")
 Register a password item of type QString.

void addItemStringList (const QString &key, QStringList *reference, const QStringList &defaultValue=QStringList())
 Register an item of type QStringList.

void addItemIntList (const QString &key, QValueList< int > *reference, const QValueList< int > &defaultValue=QValueList< int >())
 Register an item of type QValueList<int>.


Static Public Member Functions

void setCurrentGroup (const QString &group)
 Set the config file group for subsequent addItem() calls.


Protected Member Functions

virtual void usrSetDefaults ()
 Implemented by subclasses that use special defaults.

virtual void usrReadConfig ()
 Implemented by subclasses that read special config values.

virtual void usrWriteConfig ()
 Implemented by subclasses that write special config values.

KConfig * config () const
 Return the KConfig object used for reading and writing the settings.


Detailed Description

Class for handling preferences settings for an application.

Author:
Cornelius Schumacher
See also:
KPrefsItem
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. KPrefs then handles reading and writing of config files and setting of default values.

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

Example:

class MyPrefs : public KPrefs { 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 KPrefs a singleton for global access from all over the application without passing references to the KPrefs object around.

You can set all values to default values by calling setDefaults(), 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 usrSetDefaults(), usrReadConfig() and usrWriteConfig().

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

Definition at line 130 of file kprefs.h.


Constructor & Destructor Documentation

KPrefs::KPrefs 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 348 of file kprefs.cpp.

References QString::isEmpty(), and QPtrList< KPrefsItem >::setAutoDelete().

KPrefs::~KPrefs  )  [virtual]
 

Destructor.

Definition at line 362 of file kprefs.cpp.


Member Function Documentation

void KPrefs::setDefaults  ) 
 

Set preferences to default values.

All registered items are set to their default values.

Definition at line 380 of file kprefs.cpp.

References QPtrList< KPrefsItem >::first(), QPtrList< KPrefsItem >::next(), KPrefsItem::setDefault(), and usrSetDefaults().

Referenced by KPrefsDialog::setDefaults().

void KPrefs::readConfig  ) 
 

Read preferences from config file.

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

Definition at line 390 of file kprefs.cpp.

References QPtrList< KPrefsItem >::first(), QPtrList< KPrefsItem >::next(), KPrefsItem::readConfig(), and usrReadConfig().

void KPrefs::writeConfig  ) 
 

Write preferences to config file.

The values of all registered items are written to disk.

Definition at line 400 of file kprefs.cpp.

References QPtrList< KPrefsItem >::first(), QPtrList< KPrefsItem >::next(), usrWriteConfig(), and KPrefsItem::writeConfig().

Referenced by KPrefsDialog::writeConfig().

void KPrefs::setCurrentGroup const QString group  )  [static]
 

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 369 of file kprefs.cpp.

void KPrefs::addItem KPrefsItem  ) 
 

Register a custom KPrefsItem.

Definition at line 413 of file kprefs.cpp.

References QPtrList< KPrefsItem >::append().

Referenced by addItemBool(), addItemColor(), addItemFont(), addItemInt(), addItemIntList(), addItemPassword(), addItemString(), and addItemStringList().

void KPrefs::addItemBool const QString key,
bool *  reference,
bool  defaultValue = false
 

Register an item of type bool.

Parameters:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 418 of file kprefs.cpp.

References addItem().

void KPrefs::addItemInt const QString key,
int *  reference,
int  defaultValue = 0
 

Register an item of type int.

Parameters:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 423 of file kprefs.cpp.

References addItem().

void KPrefs::addItemColor const QString key,
QColor reference,
const QColor defaultValue = QColor(128, 128, 128)
 

Register an item of type QColor.

Parameters:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 428 of file kprefs.cpp.

References addItem().

void KPrefs::addItemFont const QString key,
QFont reference,
const QFont defaultValue = QFont("helvetica", 12)
 

Register an item of type QFont.

Parameters:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 433 of file kprefs.cpp.

References addItem().

void KPrefs::addItemString const QString key,
QString reference,
const QString defaultValue = ""
 

Register an item of type QString.

Parameters:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 438 of file kprefs.cpp.

References addItem().

void KPrefs::addItemPassword const QString key,
QString reference,
const QString defaultValue = ""
 

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:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 443 of file kprefs.cpp.

References addItem().

void KPrefs::addItemStringList const QString key,
QStringList reference,
const QStringList defaultValue = QStringList()
 

Register an item of type QStringList.

Parameters:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 448 of file kprefs.cpp.

References addItem().

void KPrefs::addItemIntList const QString key,
QValueList< int > *  reference,
const QValueList< int > &  defaultValue = QValueList< int >()
 

Register an item of type QValueList<int>.

Parameters:
key Key used in config file.
reference Pointer to the variable, which is set by readConfig() and setDefaults() calls and read by writeConfig() calls.
defaultValue Default value, which is used by setDefaults() and when the config file does not yet contain the key of this item.

Definition at line 454 of file kprefs.cpp.

References addItem().

virtual void KPrefs::usrSetDefaults  )  [inline, protected, virtual]
 

Implemented by subclasses that use special defaults.

Definition at line 278 of file kprefs.h.

Referenced by setDefaults().

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

Implemented by subclasses that read special config values.

Definition at line 282 of file kprefs.h.

Referenced by readConfig().

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

Implemented by subclasses that write special config values.

Definition at line 286 of file kprefs.h.

Referenced by writeConfig().

KConfig * KPrefs::config  )  const [protected]
 

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

Definition at line 375 of file kprefs.cpp.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.4.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Sat Oct 18 02:47:00 2003 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001