]> git.saurik.com Git - wxWidgets.git/blob - include/wx/confbase.h
cleanup
[wxWidgets.git] / include / wx / confbase.h
1 ///////////////////////////////////////////////////////////////////////////////
2 // Name: confbase.h
3 // Purpose: declaration of the base class of all config implementations
4 // (see also: fileconf.h and msw/regconf.h and iniconf.h)
5 // Author: Karsten Ballüder & Vadim Zeitlin
6 // Modified by:
7 // Created: 07.04.98 (adapted from appconf.h)
8 // RCS-ID: $Id$
9 // Copyright: (c) 1997 Karsten Ballüder Ballueder@usa.net
10 // Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
11 // Licence: wxWindows licence
12 ///////////////////////////////////////////////////////////////////////////////
13
14 #ifndef _WX_CONFBASE_H_
15 #define _WX_CONFBASE_H_
16
17 #include "wx/defs.h"
18 #include "wx/string.h"
19 #include "wx/object.h"
20 #include "wx/base64.h"
21
22 class WXDLLIMPEXP_FWD_BASE wxArrayString;
23
24 // ----------------------------------------------------------------------------
25 // constants
26 // ----------------------------------------------------------------------------
27
28 /// shall we be case sensitive in parsing variable names?
29 #ifndef wxCONFIG_CASE_SENSITIVE
30 #define wxCONFIG_CASE_SENSITIVE 0
31 #endif
32
33 /// separates group and entry names (probably shouldn't be changed)
34 #ifndef wxCONFIG_PATH_SEPARATOR
35 #define wxCONFIG_PATH_SEPARATOR _T('/')
36 #endif
37
38 /// introduces immutable entries
39 // (i.e. the ones which can't be changed from the local config file)
40 #ifndef wxCONFIG_IMMUTABLE_PREFIX
41 #define wxCONFIG_IMMUTABLE_PREFIX _T('!')
42 #endif
43
44 #if wxUSE_CONFIG
45
46 #include "wx/string.h"
47
48 /// should we use registry instead of configuration files under Windows?
49 // (i.e. whether wxConfigBase::Create() will create a wxFileConfig (if it's
50 // false) or wxRegConfig (if it's true and we're under Win32))
51 #ifndef wxUSE_CONFIG_NATIVE
52 #define wxUSE_CONFIG_NATIVE 1
53 #endif
54
55 // Style flags for constructor style parameter
56 enum
57 {
58 wxCONFIG_USE_LOCAL_FILE = 1,
59 wxCONFIG_USE_GLOBAL_FILE = 2,
60 wxCONFIG_USE_RELATIVE_PATH = 4,
61 wxCONFIG_USE_NO_ESCAPE_CHARACTERS = 8,
62 wxCONFIG_USE_SUBDIR = 16
63 };
64
65 // ----------------------------------------------------------------------------
66 // abstract base class wxConfigBase which defines the interface for derived
67 // classes
68 //
69 // wxConfig organizes the items in a tree-like structure (modeled after the
70 // Unix/Dos filesystem). There are groups (directories) and keys (files).
71 // There is always one current group given by the current path.
72 //
73 // Keys are pairs "key_name = value" where value may be of string or integer
74 // (long) type (TODO doubles and other types such as wxDate coming soon).
75 // ----------------------------------------------------------------------------
76
77 class WXDLLIMPEXP_BASE wxConfigBase : public wxObject
78 {
79 public:
80 // constants
81 // the type of an entry
82 enum EntryType
83 {
84 Type_Unknown,
85 Type_String,
86 Type_Boolean,
87 Type_Integer, // use Read(long *)
88 Type_Float // use Read(double *)
89 };
90
91 // static functions
92 // sets the config object, returns the previous pointer
93 static wxConfigBase *Set(wxConfigBase *pConfig);
94 // get the config object, creates it on demand unless DontCreateOnDemand
95 // was called
96 static wxConfigBase *Get(bool createOnDemand = true)
97 { if ( createOnDemand && (!ms_pConfig) ) Create(); return ms_pConfig; }
98 // create a new config object: this function will create the "best"
99 // implementation of wxConfig available for the current platform, see
100 // comments near definition wxUSE_CONFIG_NATIVE for details. It returns
101 // the created object and also sets it as ms_pConfig.
102 static wxConfigBase *Create();
103 // should Get() try to create a new log object if the current one is NULL?
104 static void DontCreateOnDemand() { ms_bAutoCreate = false; }
105
106 // ctor & virtual dtor
107 // ctor (can be used as default ctor too)
108 //
109 // Not all args will always be used by derived classes, but including
110 // them all in each class ensures compatibility. If appName is empty,
111 // uses wxApp name
112 wxConfigBase(const wxString& appName = wxEmptyString,
113 const wxString& vendorName = wxEmptyString,
114 const wxString& localFilename = wxEmptyString,
115 const wxString& globalFilename = wxEmptyString,
116 long style = 0);
117
118 // empty but ensures that dtor of all derived classes is virtual
119 virtual ~wxConfigBase();
120
121 // path management
122 // set current path: if the first character is '/', it's the absolute path,
123 // otherwise it's a relative path. '..' is supported. If the strPath
124 // doesn't exist it is created.
125 virtual void SetPath(const wxString& strPath) = 0;
126 // retrieve the current path (always as absolute path)
127 virtual const wxString& GetPath() const = 0;
128
129 // enumeration: all functions here return false when there are no more items.
130 // you must pass the same lIndex to GetNext and GetFirst (don't modify it)
131 // enumerate subgroups
132 virtual bool GetFirstGroup(wxString& str, long& lIndex) const = 0;
133 virtual bool GetNextGroup (wxString& str, long& lIndex) const = 0;
134 // enumerate entries
135 virtual bool GetFirstEntry(wxString& str, long& lIndex) const = 0;
136 virtual bool GetNextEntry (wxString& str, long& lIndex) const = 0;
137 // get number of entries/subgroups in the current group, with or without
138 // it's subgroups
139 virtual size_t GetNumberOfEntries(bool bRecursive = false) const = 0;
140 virtual size_t GetNumberOfGroups(bool bRecursive = false) const = 0;
141
142 // tests of existence
143 // returns true if the group by this name exists
144 virtual bool HasGroup(const wxString& strName) const = 0;
145 // same as above, but for an entry
146 virtual bool HasEntry(const wxString& strName) const = 0;
147 // returns true if either a group or an entry with a given name exist
148 bool Exists(const wxString& strName) const
149 { return HasGroup(strName) || HasEntry(strName); }
150
151 // get the entry type
152 virtual EntryType GetEntryType(const wxString& name) const
153 {
154 // by default all entries are strings
155 return HasEntry(name) ? Type_String : Type_Unknown;
156 }
157
158 // key access: returns true if value was really read, false if default used
159 // (and if the key is not found the default value is returned.)
160
161 // read a string from the key
162 bool Read(const wxString& key, wxString *pStr) const;
163 bool Read(const wxString& key, wxString *pStr, const wxString& defVal) const;
164
165 // read a number (long)
166 bool Read(const wxString& key, long *pl) const;
167 bool Read(const wxString& key, long *pl, long defVal) const;
168
169 // read an int (wrapper around `long' version)
170 bool Read(const wxString& key, int *pi) const;
171 bool Read(const wxString& key, int *pi, int defVal) const;
172
173 // read a double
174 bool Read(const wxString& key, double* val) const;
175 bool Read(const wxString& key, double* val, double defVal) const;
176
177 // read a bool
178 bool Read(const wxString& key, bool* val) const;
179 bool Read(const wxString& key, bool* val, bool defVal) const;
180
181 #if wxUSE_BASE64
182 // read a binary data block
183 bool Read(const wxString& key, wxMemoryBuffer* data) const
184 { return DoReadBinary(key, data); }
185 // no default version since it does not make sense for binary data
186 #endif // wxUSE_BASE64
187
188 // Causes ambiguities in VC++ 6 and OpenVMS (at least)
189 #if ( (!defined(__VISUALC__) || __VISUALC__ > 1200) && !defined( __VMS ) && !defined (__DMC__))
190 // read other types, for which wxFromString is defined
191 template <typename T>
192 bool Read(const wxString& key, T* value) const
193 {
194 wxString s;
195 if ( !Read(key, &s) )
196 return false;
197 return wxFromString(s, value);
198 }
199
200 template <typename T>
201 bool Read(const wxString& key, T* value, const T& defVal) const
202 {
203 const bool found = Read(key, value);
204 if ( !found )
205 {
206 if (IsRecordingDefaults())
207 ((wxConfigBase *)this)->Write(key, defVal);
208 *value = defVal;
209 }
210 return found;
211 }
212 #endif
213
214 // convenience functions returning directly the value
215 wxString Read(const wxString& key,
216 const wxString& defVal = wxEmptyString) const
217 { wxString s; (void)Read(key, &s, defVal); return s; }
218
219 // we have to provide a separate version for C strings as otherwise the
220 // template Read() would be used
221 wxString Read(const wxString& key, const char* defVal) const
222 { return Read(key, wxString(defVal)); }
223 #if wxUSE_WCHAR_T
224 wxString Read(const wxString& key, const wchar_t* defVal) const
225 { return Read(key, wxString(defVal)); }
226 #endif
227
228 long ReadLong(const wxString& key, long defVal) const
229 { long l; (void)Read(key, &l, defVal); return l; }
230
231 double ReadDouble(const wxString& key, double defVal) const
232 { double d; (void)Read(key, &d, defVal); return d; }
233
234 bool ReadBool(const wxString& key, bool defVal) const
235 { bool b; (void)Read(key, &b, defVal); return b; }
236
237 template <typename T>
238 T ReadObject(const wxString& key, T const& defVal) const
239 { T t; (void)Read(key, &t, defVal); return t; }
240
241 // for compatibility with wx 2.8
242 long Read(const wxString& key, long defVal) const
243 { return ReadLong(key, defVal); }
244
245
246 // write the value (return true on success)
247 bool Write(const wxString& key, const wxString& value)
248 { return DoWriteString(key, value); }
249
250 bool Write(const wxString& key, long value)
251 { return DoWriteLong(key, value); }
252
253 bool Write(const wxString& key, double value)
254 { return DoWriteDouble(key, value); }
255
256 bool Write(const wxString& key, bool value)
257 { return DoWriteBool(key, value); }
258
259 #if wxUSE_BASE64
260 bool Write(const wxString& key, const wxMemoryBuffer& buf)
261 { return DoWriteBinary(key, buf); }
262 #endif // wxUSE_BASE64
263
264 // we have to provide a separate version for C strings as otherwise they
265 // would be converted to bool and not to wxString as expected!
266 bool Write(const wxString& key, const char *value)
267 { return Write(key, wxString(value)); }
268 bool Write(const wxString& key, const unsigned char *value)
269 { return Write(key, wxString(value)); }
270 #if wxUSE_WCHAR_T
271 bool Write(const wxString& key, const wchar_t *value)
272 { return Write(key, wxString(value)); }
273 #endif
274
275
276 // we also have to provide specializations for other types which we want to
277 // handle using the specialized DoWriteXXX() instead of the generic template
278 // version below
279 bool Write(const wxString& key, short value)
280 { return DoWriteLong(key, value); }
281
282 bool Write(const wxString& key, unsigned short value)
283 { return DoWriteLong(key, value); }
284
285 bool Write(const wxString& key, unsigned int value)
286 { return DoWriteLong(key, value); }
287
288 bool Write(const wxString& key, int value)
289 { return DoWriteLong(key, value); }
290
291 bool Write(const wxString& key, unsigned long value)
292 { return DoWriteLong(key, value); }
293
294 bool Write(const wxString& key, float value)
295 { return DoWriteDouble(key, value); }
296
297 // Causes ambiguities in VC++ 6 and OpenVMS (at least)
298 #if ( (!defined(__VISUALC__) || __VISUALC__ > 1200) && !defined( __VMS ) && !defined (__DMC__))
299 // for other types, use wxToString()
300 template <typename T>
301 bool Write(const wxString& key, T const& value)
302 { return Write(key, wxToString(value)); }
303 #endif
304
305 // permanently writes all changes
306 virtual bool Flush(bool bCurrentOnly = false) = 0;
307
308 // renaming, all functions return false on failure (probably because the new
309 // name is already taken by an existing entry)
310 // rename an entry
311 virtual bool RenameEntry(const wxString& oldName,
312 const wxString& newName) = 0;
313 // rename a group
314 virtual bool RenameGroup(const wxString& oldName,
315 const wxString& newName) = 0;
316
317 // delete entries/groups
318 // deletes the specified entry and the group it belongs to if
319 // it was the last key in it and the second parameter is true
320 virtual bool DeleteEntry(const wxString& key,
321 bool bDeleteGroupIfEmpty = true) = 0;
322 // delete the group (with all subgroups)
323 virtual bool DeleteGroup(const wxString& key) = 0;
324 // delete the whole underlying object (disk file, registry key, ...)
325 // primarily for use by uninstallation routine.
326 virtual bool DeleteAll() = 0;
327
328 // options
329 // we can automatically expand environment variables in the config entries
330 // (this option is on by default, you can turn it on/off at any time)
331 bool IsExpandingEnvVars() const { return m_bExpandEnvVars; }
332 void SetExpandEnvVars(bool bDoIt = true) { m_bExpandEnvVars = bDoIt; }
333 // recording of default values
334 void SetRecordDefaults(bool bDoIt = true) { m_bRecordDefaults = bDoIt; }
335 bool IsRecordingDefaults() const { return m_bRecordDefaults; }
336 // does expansion only if needed
337 wxString ExpandEnvVars(const wxString& str) const;
338
339 // misc accessors
340 wxString GetAppName() const { return m_appName; }
341 wxString GetVendorName() const { return m_vendorName; }
342
343 // Used wxIniConfig to set members in constructor
344 void SetAppName(const wxString& appName) { m_appName = appName; }
345 void SetVendorName(const wxString& vendorName) { m_vendorName = vendorName; }
346
347 void SetStyle(long style) { m_style = style; }
348 long GetStyle() const { return m_style; }
349
350 protected:
351 static bool IsImmutable(const wxString& key)
352 { return !key.IsEmpty() && key[0] == wxCONFIG_IMMUTABLE_PREFIX; }
353
354 // return the path without trailing separator, if any: this should be called
355 // to sanitize paths referring to the group names before passing them to
356 // wxConfigPathChanger as "/foo/bar/" should be the same as "/foo/bar" and it
357 // isn't interpreted in the same way by it (and this can't be changed there
358 // as it's not the same for the entries names)
359 static wxString RemoveTrailingSeparator(const wxString& key);
360
361 // do read/write the values of different types
362 virtual bool DoReadString(const wxString& key, wxString *pStr) const = 0;
363 virtual bool DoReadLong(const wxString& key, long *pl) const = 0;
364 virtual bool DoReadDouble(const wxString& key, double* val) const;
365 virtual bool DoReadBool(const wxString& key, bool* val) const;
366 #if wxUSE_BASE64
367 virtual bool DoReadBinary(const wxString& key, wxMemoryBuffer* buf) const = 0;
368 #endif // wxUSE_BASE64
369
370 virtual bool DoWriteString(const wxString& key, const wxString& value) = 0;
371 virtual bool DoWriteLong(const wxString& key, long value) = 0;
372 virtual bool DoWriteDouble(const wxString& key, double value);
373 virtual bool DoWriteBool(const wxString& key, bool value);
374 #if wxUSE_BASE64
375 virtual bool DoWriteBinary(const wxString& key, const wxMemoryBuffer& buf) = 0;
376 #endif // wxUSE_BASE64
377
378 private:
379 // are we doing automatic environment variable expansion?
380 bool m_bExpandEnvVars;
381 // do we record default values?
382 bool m_bRecordDefaults;
383
384 // static variables
385 static wxConfigBase *ms_pConfig;
386 static bool ms_bAutoCreate;
387
388 // Application name and organisation name
389 wxString m_appName;
390 wxString m_vendorName;
391
392 // Style flag
393 long m_style;
394
395 DECLARE_ABSTRACT_CLASS(wxConfigBase)
396 };
397
398 // a handy little class which changes current path to the path of given entry
399 // and restores it in dtor: so if you declare a local variable of this type,
400 // you work in the entry directory and the path is automatically restored
401 // when the function returns
402 // Taken out of wxConfig since not all compilers can cope with nested classes.
403 class WXDLLIMPEXP_BASE wxConfigPathChanger
404 {
405 public:
406 // ctor/dtor do path changing/restoring of the path
407 wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry);
408 ~wxConfigPathChanger();
409
410 // get the key name
411 const wxString& Name() const { return m_strName; }
412
413 // this method must be called if the original path (i.e. the current path at
414 // the moment of creation of this object) could have been deleted to prevent
415 // us from restoring the not existing (any more) path
416 //
417 // if the original path doesn't exist any more, the path will be restored to
418 // the deepest still existing component of the old path
419 void UpdateIfDeleted();
420
421 private:
422 wxConfigBase *m_pContainer; // object we live in
423 wxString m_strName, // name of entry (i.e. name only)
424 m_strOldPath; // saved path
425 bool m_bChanged; // was the path changed?
426
427 DECLARE_NO_COPY_CLASS(wxConfigPathChanger)
428 };
429
430
431 // ----------------------------------------------------------------------------
432 // the native wxConfigBase implementation
433 // ----------------------------------------------------------------------------
434
435 // under Windows we prefer to use the native implementation
436 // wxIniConfig isn't native anywhere after droping win16 in wxWidgets 2.6
437 #if defined(__WXMSW__) && wxUSE_CONFIG_NATIVE
438 #define wxConfig wxRegConfig
439 #else // either we're under Unix or wish to use files even under Windows
440 #define wxConfig wxFileConfig
441 #endif
442
443 #endif // wxUSE_CONFIG
444
445 /*
446 Replace environment variables ($SOMETHING) with their values. The format is
447 $VARNAME or ${VARNAME} where VARNAME contains alphanumeric characters and
448 '_' only. '$' must be escaped ('\$') in order to be taken literally.
449 */
450
451 WXDLLIMPEXP_BASE wxString wxExpandEnvVars(const wxString &sz);
452
453 /*
454 Split path into parts removing '..' in progress
455 */
456 WXDLLIMPEXP_BASE void wxSplitPath(wxArrayString& aParts, const wxString& path);
457
458 #endif // _WX_CONFBASE_H_
459