summaryrefslogtreecommitdiffabout
path: root/libkdepim/kprefs.h
Unidiff
Diffstat (limited to 'libkdepim/kprefs.h') (more/less context) (show whitespace changes)
-rw-r--r--libkdepim/kprefs.h301
1 files changed, 301 insertions, 0 deletions
diff --git a/libkdepim/kprefs.h b/libkdepim/kprefs.h
new file mode 100644
index 0000000..7014bb8
--- a/dev/null
+++ b/libkdepim/kprefs.h
@@ -0,0 +1,301 @@
1/*
2 This file is part of KOrganizer.
3 Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
19*/
20#ifndef _KPREFS_H
21#define _KPREFS_H
22// $Id$
23
24#include <qptrlist.h>
25#include <qcolor.h>
26#include <qfont.h>
27#include <qstringlist.h>
28
29class KConfig;
30
31/**
32 @short Class for storing a preferences setting
33 @author Cornelius Schumacher
34 @see KPref
35
36 This class represents one preferences setting as used by @ref KPrefs.
37 Subclasses of KPrefsItem implement storage functions for a certain type of
38 setting. Normally you don't have to use this class directly. Use the special
39 addItem() functions of KPrefs instead. If you subclass this class you will
40 have to register instances with the function KPrefs::addItem().
41*/
42class KPrefsItem {
43 public:
44 /**
45 Constructor.
46
47 @param group Config file group.
48 @param name Config file key.
49 */
50 KPrefsItem(const QString &group,const QString &name) :
51 mGroup(group),mName(name) {}
52 /**
53 Destructor.
54 */
55 virtual ~KPrefsItem() {}
56
57 /**
58 This function is called by @ref KPrefs to set this setting to its default
59 value.
60 */
61 virtual void setDefault() = 0;
62 /**
63 This function is called by @ref KPrefs to read the value for this setting
64 from a config file.
65 value.
66 */
67 virtual void readConfig(KConfig *) = 0;
68 /**
69 This function is called by @ref KPrefs to write the value of this setting
70 to a config file.
71 */
72 virtual void writeConfig(KConfig *) = 0;
73
74 protected:
75 QString mGroup;
76 QString mName;
77};
78
79/**
80 @short Class for handling preferences settings for an application.
81 @author Cornelius Schumacher
82 @see KPrefsItem
83
84 This class provides an interface to preferences settings. Preferences items
85 can be registered by the addItem() function corresponding to the data type of
86 the seetting. KPrefs then handles reading and writing of config files and
87 setting of default values.
88
89 Normally you will subclass KPrefs, add data members for the preferences
90 settings and register the members in the constructor of the subclass.
91
92 Example:
93 <pre>
94 class MyPrefs : public KPrefs {
95 public:
96 MyPrefs()
97 {
98 setCurrentGroup("MyGroup");
99 addItemBool("MySetting1",&mMyBool,false);
100 addItemColor("MySetting2",&mMyColor,QColor(1,2,3));
101
102 setCurrentGroup("MyOtherGroup");
103 addItemFont("MySetting3",&mMyFont,QFont("helvetica",12));
104 }
105
106 bool mMyBool;
107 QColor mMyColor;
108 QFont mMyFont;
109 }
110 </pre>
111
112 It might be convenient in many cases to make this subclass of KPrefs a
113 singleton for global access from all over the application without passing
114 references to the KPrefs object around.
115
116 You can set all values to default values by calling @ref setDefaults(), write
117 the data to the configuration file by calling @ref writeConfig() and read the
118 data from the configuration file by calling @ref readConfig().
119
120 If you have items, which are not covered by the existing addItem() functions
121 you can add customized code for reading, writing and default setting by
122 implementing the functions @ref usrSetDefaults(), @ref usrReadConfig() and
123 @ref usrWriteConfig().
124
125 Internally preferences settings are stored in instances of subclasses of
126 @ref KPrefsItem. You can also add KPrefsItem subclasses for your own types
127 and call the generic @ref addItem() to register them.
128*/
129
130class KPrefs {
131 public:
132 /**
133 Constructor.
134
135 @param configname name of config file. If no name is given, the default
136 config file as returned by kapp()->config() is used.
137 */
138 KPrefs(const QString &configname=QString::null);
139 /**
140 Destructor
141 */
142 virtual ~KPrefs();
143
144 /**
145 Set preferences to default values. All registered items are set to their
146 default values.
147 */
148 void setDefaults();
149
150 /**
151 Read preferences from config file. All registered items are set to the
152 values read from disk.
153 */
154 void readConfig();
155
156 /**
157 Write preferences to config file. The values of all registered items are
158 written to disk.
159 */
160 void writeConfig();
161
162 /**
163 Set the config file group for subsequent addItem() calls. It is valid
164 until setCurrentGroup() is called with a new argument. Call this before
165 you add any items. The default value is "No Group".
166 */
167 static void setCurrentGroup(const QString &group);
168
169 /**
170 Register a custom @ref KPrefsItem.
171 */
172 void addItem(KPrefsItem *);
173
174 /**
175 Register an item of type bool.
176
177 @param key Key used in config file.
178 @param reference Pointer to the variable, which is set by readConfig()
179 and setDefaults() calls and read by writeConfig() calls.
180 @param defaultValue Default value, which is used by setDefaults() and
181 when the config file does not yet contain the key of
182 this item.
183 */
184 void addItemBool(const QString &key,bool *reference,
185 bool defaultValue=false);
186 /**
187 Register an item of type int.
188
189 @param key Key used in config file.
190 @param reference Pointer to the variable, which is set by readConfig()
191 and setDefaults() calls and read by writeConfig() calls.
192 @param defaultValue Default value, which is used by setDefaults() and
193 when the config file does not yet contain the key of
194 this item.
195 */
196 void addItemInt(const QString &key,int *reference,
197 int defaultValue=0);
198 /**
199 Register an item of type QColor.
200
201 @param key Key used in config file.
202 @param reference Pointer to the variable, which is set by readConfig()
203 and setDefaults() calls and read by writeConfig() calls.
204 @param defaultValue Default value, which is used by setDefaults() and
205 when the config file does not yet contain the key of
206 this item.
207 */
208 void addItemColor(const QString &key,QColor *reference,
209 const QColor &defaultValue=QColor(128,128,128));
210 /**
211 Register an item of type QFont.
212
213 @param key Key used in config file.
214 @param reference Pointer to the variable, which is set by readConfig()
215 and setDefaults() calls and read by writeConfig() calls.
216 @param defaultValue Default value, which is used by setDefaults() and
217 when the config file does not yet contain the key of
218 this item.
219 */
220 void addItemFont(const QString &key,QFont *reference,
221 const QFont &defaultValue=QFont("helvetica",12));
222 /**
223 Register an item of type QString.
224
225 @param key Key used in config file.
226 @param reference Pointer to the variable, which is set by readConfig()
227 and setDefaults() calls and read by writeConfig() calls.
228 @param defaultValue Default value, which is used by setDefaults() and
229 when the config file does not yet contain the key of
230 this item.
231 */
232 void addItemString(const QString &key,QString *reference,
233 const QString &defaultValue="");
234 /**
235 Register a password item of type QString. The string value is written
236 encrypted to the config file. Note that the current encryption scheme
237 is very weak.
238
239 @param key Key used in config file.
240 @param reference Pointer to the variable, which is set by readConfig()
241 and setDefaults() calls and read by writeConfig() calls.
242 @param defaultValue Default value, which is used by setDefaults() and
243 when the config file does not yet contain the key of
244 this item.
245 */
246 void addItemPassword(const QString &key,QString *reference,
247 const QString &defaultValue="");
248 /**
249 Register an item of type QStringList.
250
251 @param key Key used in config file.
252 @param reference Pointer to the variable, which is set by readConfig()
253 and setDefaults() calls and read by writeConfig() calls.
254 @param defaultValue Default value, which is used by setDefaults() and
255 when the config file does not yet contain the key of
256 this item.
257 */
258 void addItemStringList(const QString &key,QStringList *reference,
259 const QStringList &defaultValue=QStringList());
260
261 /**
262 Register an item of type QValueList<int>.
263
264 @param key Key used in config file.
265 @param reference Pointer to the variable, which is set by readConfig()
266 and setDefaults() calls and read by writeConfig() calls.
267 @param defaultValue Default value, which is used by setDefaults() and
268 when the config file does not yet contain the key of
269 this item.
270 */
271 void addItemIntList(const QString &key,QValueList<int> *reference,
272 const QValueList<int> &defaultValue=QValueList<int>());
273
274 protected:
275 /**
276 Implemented by subclasses that use special defaults.
277 */
278 virtual void usrSetDefaults() {};
279 /**
280 Implemented by subclasses that read special config values.
281 */
282 virtual void usrReadConfig() {};
283 /**
284 Implemented by subclasses that write special config values.
285 */
286 virtual void usrWriteConfig() {};
287
288 /**
289 Return the @ref KConfig object used for reading and writing the settings.
290 */
291 KConfig *config() const;
292
293 private:
294 static QString *mCurrentGroup;
295
296 KConfig *mConfig; // pointer to KConfig object
297
298 QPtrList<KPrefsItem> mItems;
299};
300
301#endif