]>
git.saurik.com Git - wxWidgets.git/blob - interface/config.h
cf51780a470369d78f86b02242d229cf928a40be
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: documentation for wxConfigBase class
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
13 wxConfigBase class defines the basic interface of all config classes. It can
14 not be used by itself (it is an abstract base class) and you will always use one
15 of its derivations: wxFileConfig,
16 wxRegConfig or any other.
18 However, usually you don't even need to know the precise nature of the class
19 you're working with but you would just use the wxConfigBase methods. This
20 allows you to write the same code regardless of whether you're working with
21 the registry under Win32 or text-based config files under Unix (or even
22 Windows 3.1 .INI files if you're really unlucky). To make writing the portable
23 code even easier, wxWidgets provides a typedef wxConfig
24 which is mapped onto the native wxConfigBase implementation on the given
25 platform: i.e. wxRegConfig under Win32 and
26 wxFileConfig otherwise.
28 See @ref overview_wxconfigoverview "config overview" for the descriptions of all
29 features of this class.
31 It is highly recommended to use static functions @e Get() and/or @e Set(),
32 so please have a @ref overview_wxconfigstaticfunctions "look at them."
37 class wxConfigBase
: public wxObject
43 This is the default and only constructor of the wxConfigBase class, and
47 The application name. If this is empty, the class will
48 normally use wxApp::GetAppName to set it. The
49 application name is used in the registry key on Windows, and can be used to
50 deduce the local filename parameter if that is missing.
53 The vendor name. If this is empty, it is assumed that
54 no vendor name is wanted, if this is optional for the current config class.
55 The vendor name is appended to the application name for wxRegConfig.
58 Some config classes require a local filename. If this
59 is not present, but required, the application name will be used instead.
62 Some config classes require a global filename. If
63 this is not present, but required, the application name will be used instead.
66 Can be one of wxCONFIG_USE_LOCAL_FILE and
67 wxCONFIG_USE_GLOBAL_FILE. The style interpretation depends on the config
68 class and is ignored by some implementations. For wxFileConfig, these styles
69 determine whether a local or global config file is created or used: if
70 wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the global
71 config file and if wxCONFIG_USE_LOCAL_FILE is used, settings are read from
72 and written to local config file (if they are both set, global file is read
73 first, then local file, overwriting global settings). If the
74 flag is present but the parameter is empty, the parameter will be set to a
75 default. If the parameter is present but the style flag not, the relevant flag
76 will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM
77 key while LOCAL one is for the usual HKCU one.
79 For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by logically
80 or'ing it to either of the _FILE options to tell wxFileConfig to use relative
81 instead of absolute paths.
83 On non-VMS Unix systems, the default local configuration file is ~/.appname.
84 However, this path may be also used as user data directory
85 (see wxStandardPaths::GetUserDataDir) if
86 the application has several data files. In this case wxCONFIG_USE_SUBDIR
87 flag, which changes the default local configuration file to ~/.appname/appname
88 should be used. Notice that this flag is ignored if localFilename is
89 provided. This function is new since wxWidgets version 2.8.2
91 For wxFileConfig, you can also add wxCONFIG_USE_NO_ESCAPE_CHARACTERS which
92 will turn off character escaping for the values of entries stored in the config
93 file: for example a foo key with some backslash characters will be stored
94 as foo=C:\mydir instead of the usual storage of
97 The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your config
98 file must be read or written to by a non-wxWidgets program (which might not
99 understand the escape characters). Note, however, that if
100 wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is now
101 your application's responsibility to ensure that there is no newline or
102 other illegal characters in a value, before writing that value to the file.
105 This parameter is only used by wxFileConfig when compiled
106 in Unicode mode. It specifies the encoding in which the configuration file
109 @remarks By default, environment variable expansion is on and recording
112 wxConfigBase(const wxString
& appName
= wxEmptyString
,
113 const wxString
& vendorName
= wxEmptyString
,
114 const wxString
& localFilename
= wxEmptyString
,
115 const wxString
& globalFilename
= wxEmptyString
,
119 Empty but ensures that dtor of all derived classes is virtual.
124 @ref ctor() wxConfigBase
126 @ref dtor() ~wxConfigBase
131 Create a new config object: this function will create the "best"
132 implementation of wxConfig available for the current platform, see comments
133 near the definition of wxCONFIG_WIN32_NATIVE for details. It returns the
134 created object and also sets it as the current one.
136 static wxConfigBase
* Create();
139 The functions in this section delete entries and/or groups of entries from the
140 config file. @e DeleteAll() is especially useful if you want to erase all
141 traces of your program presence: for example, when you uninstall it.
152 Delete the whole underlying object (disk file, registry key, ...). Primarly
153 for use by uninstallation routine.
158 Deletes the specified entry and the group it belongs to if it was the last key
159 in it and the second parameter is @true.
161 bool DeleteEntry(const wxString
& key
,
162 bool bDeleteGroupIfEmpty
= @
true);
165 Delete the group (with all subgroups). If the current path is under the group
166 being deleted it is changed to its deepest still existing component. E.g. if
167 the current path is @c /A/B/C/D and the group @c C is deleted the
168 path becomes @c /A/B.
170 bool DeleteGroup(const wxString
& key
);
173 Calling this function will prevent @e Get() from automatically creating a
174 new config object if the current one is @NULL. It might be useful to call it
175 near the program end to prevent "accidental" creation of a new config object.
177 void DontCreateOnDemand();
180 The functions in this section allow to enumerate all entries and groups in the
181 config file. All functions here return @false when there are no more items.
183 You must pass the same index to GetNext and GetFirst (don't modify it).
184 Please note that it is @b not the index of the current item (you will have
185 some great surprises with wxRegConfig if you assume this) and you shouldn't
186 even look at it: it is just a "cookie" which stores the state of the
187 enumeration. It can't be stored inside the class because it would prevent you
188 from running several enumerations simultaneously, that's why you must pass it
191 Having said all this, enumerating the config entries/groups is very simple:
192 There are also functions to get the number of entries/subgroups without
193 actually enumerating them, but you will probably never need them.
210 returns @true if either a group or an entry with a given name exists
212 bool Exists(wxString
& strName
);
215 permanently writes all changes (otherwise, they're only written from object's
218 bool Flush(bool bCurrentOnly
= @
false);
221 Get the current config object. If there is no current object and
222 @e CreateOnDemand is @true, creates one
223 (using @e Create) unless DontCreateOnDemand was called previously.
225 #define static wxConfigBase * Get(bool CreateOnDemand = @true) /* implementation is private */
228 Returns the application name.
230 wxString
GetAppName();
233 Returns the type of the given entry or @e Unknown if the entry doesn't
234 exist. This function should be used to decide which version of Read() should
235 be used because some of wxConfig implementations will complain about type
236 mismatch otherwise: e.g., an attempt to read a string value from an integer
237 key with wxRegConfig will fail.
239 The result is an element of enum EntryType:
241 enum wxConfigBase::EntryType
GetEntryType(const wxString
& name
);
244 Gets the first entry.
246 bool GetFirstEntry(wxString
& str
, long& index
);
249 Gets the first group.
251 bool GetFirstGroup(wxString
& str
, long& index
);
256 bool GetNextEntry(wxString
& str
, long& index
);
261 bool GetNextGroup(wxString
& str
, long& index
);
266 uint
GetNumberOfEntries(bool bRecursive
= @
false);
269 Get number of entries/subgroups in the current group, with or without its
272 uint
GetNumberOfGroups(bool bRecursive
= @
false);
275 Retrieve the current path (always as absolute path).
277 const wxString
GetPath();
280 Returns the vendor name.
282 wxString
GetVendorName();
285 returns @true if the entry by this name exists
287 bool HasEntry(wxString
& strName
);
290 returns @true if the group by this name exists
292 bool HasGroup(const wxString
& strName
);
295 Returns @true if we are expanding environment variables in key values.
297 bool IsExpandingEnvVars();
300 Returns @true if we are writing defaults back to the config file.
302 bool IsRecordingDefaults();
305 These function are the core of wxConfigBase class: they allow you to read and
306 write config file data. All @e Read function take a default value which
307 will be returned if the specified key is not found in the config file.
309 Currently, supported types of data are:
310 wxString, @e long, @e double, @e bool,
311 wxColour and any other types,
312 for which functions wxToString
313 and wxFromString are defined.
315 Try not to read long values into string variables and vice versa: although it
316 just might work with wxFileConfig, you will get a system error with
317 wxRegConfig because in the Windows registry the different types of entries are
320 Final remark: the @e szKey parameter for all these functions can contain an
321 arbitrary path (either relative or absolute), not just the key name.
336 wxFileConfig::SetUmask
341 Some aspects of wxConfigBase behaviour can be changed during run-time. The
342 first of them is the expansion of environment variables in the string values
343 read from the config file: for example, if you have the following in your
345 the call to @c config-Read("UserData") will return something like
346 @c "/home/zeitlin/data" if you're lucky enough to run a Linux system ;-)
348 Although this feature is very useful, it may be annoying if you read a value
349 which containts '$' or '%' symbols (% is used for environment variables
350 expansion under Windows) which are not used for environment variable
351 expansion. In this situation you may call SetExpandEnvVars(@false) just before
352 reading this value and SetExpandEnvVars(@true) just after. Another solution
353 would be to prefix the offending symbols with a backslash.
355 The following functions control this option:
363 IsRecordingDefaults()
368 As explained in @ref overview_wxconfigoverview "config overview", the config
370 support a file system-like hierarchy of keys (files) and groups (directories).
371 As in the file system case, to specify a key in the config class you must use
372 a path to it. Config classes also support the notion of the current group,
373 which makes it possible to use the relative paths. To clarify all this, here
374 is an example (it is only for the sake of demonstration, it doesn't do anything
376 @e Warning: it is probably a good idea to always restore the path to its
377 old value on function exit:
378 because otherwise the assert in the following example will surely fail
379 (we suppose here that @e foo() function is the same as above except that it
380 doesn't save and restore the path):
381 Finally, the path separator in wxConfigBase and derived classes is always '/',
382 regardless of the platform (i.e. it is @b not '\\' under Windows).
392 Reads a value of type T, for which function
393 wxFromString is defined,
394 returning @true if the value was found.
395 If the value was not found, @e defaultVal is used instead.
397 bool Read(const wxStringkey, T* value) const;
401 @b Read(key, default="")
406 @b ReadInt(key, default=0)
411 @b ReadFloat(key, default=0.0)
414 Returns a floating point number
416 @b ReadBool(key, default=0)
421 bool Read(const wxString
& key
, wxString
* str
);
422 bool Read(const wxString
& key
, wxString
* str
,
423 const wxString
& defaultVal
);
424 wxString
Read(const wxString
& key
,
426 wxString
& defaultVal
);
427 bool Read(const wxString
& key
, long* l
);
428 bool Read(const wxString
& key
, long* l
, long defaultVal
);
429 bool Read(const wxString
& key
, double* d
);
430 bool Read(const wxString
& key
, double* d
, double defaultVal
);
431 bool Read(const wxString
& key
, bool* b
);
432 bool Read(const wxString
& key
, bool* d
, bool defaultVal
);
433 bool Read(const wxString
& key
, wxMemoryBuffer
* buf
);
434 bool Read(const wxString
& key
, T
* value
);
435 bool Read(const wxString
& key
, T
* value
,
436 T
const& defaultVal
);
440 Reads a bool value from the key and returns it. @e defaultVal is returned
441 if the key is not found.
443 long ReadBool(const wxString
& key
, bool defaultVal
);
446 Reads a double value from the key and returns it. @e defaultVal is returned
447 if the key is not found.
449 long ReadDouble(const wxString
& key
, double defaultVal
);
452 Reads a long value from the key and returns it. @e defaultVal is returned
453 if the key is not found.
455 long ReadLong(const wxString
& key
, long defaultVal
);
458 Reads a value of type T, for which function
459 wxFromString is defined, from the key and returns it.
460 @e defaultVal is returned if the key is not found.
462 T
ReadObject(const wxString
& key
, T
const& defaultVal
);
465 The functions in this section allow to rename entries or subgroups of the
466 current group. They will return @false on error. typically because either the
467 entry/group with the original name doesn't exist, because the entry/group with
468 the new name already exists or because the function is not supported in this
469 wxConfig implementation.
478 Renames an entry in the current group. The entries names (both the old and
479 the new one) shouldn't contain backslashes, i.e. only simple names and not
480 arbitrary paths are accepted by this function.
482 Returns @false if @e oldName doesn't exist or if @e newName already
485 bool RenameEntry(const wxString
& oldName
,
486 const wxString
& newName
);
489 Renames a subgroup of the current group. The subgroup names (both the old and
490 the new one) shouldn't contain backslashes, i.e. only simple names and not
491 arbitrary paths are accepted by this function.
493 Returns @false if @e oldName doesn't exist or if @e newName already
496 bool RenameGroup(const wxString
& oldName
,
497 const wxString
& newName
);
500 Sets the config object as the current one, returns the pointer to the previous
501 current object (both the parameter and returned value may be @NULL)
503 #define static wxConfigBase * Set(wxConfigBase * pConfig) /* implementation is private */
506 Determine whether we wish to expand environment variables in key values.
508 void SetExpandEnvVars(bool bDoIt
= @
true);
511 Set current path: if the first character is '/', it is the absolute path,
512 otherwise it is a relative path. '..' is supported. If strPath doesn't
515 void SetPath(const wxString
& strPath
);
518 Sets whether defaults are recorded to the config file whenever an attempt to
519 read the value which is not present in it is done.
521 If on (default is off) all default values for the settings used by the program
522 are written back to the config file. This allows the user to see what config
523 options may be changed and is probably useful only for wxFileConfig.
525 void SetRecordDefaults(bool bDoIt
= @
true);
528 These functions deal with the "default" config object. Although its usage is
529 not at all mandatory it may be convenient to use a global config object
530 instead of creating and deleting the local config objects each time you need
531 one (especially because creating a wxFileConfig object might be a time
532 consuming operation). In this case, you may create this global config object
533 in the very start of the program and @e Set() it as the default. Then, from
534 anywhere in your program, you may access it using the @e Get() function.
535 This global wxConfig object will be deleted by wxWidgets automatically if it
536 exists. Note that this implies that if you do delete this object yourself
537 (usually in wxApp::OnExit) you must use @e Set(@NULL)
538 to prevent wxWidgets from deleting it the second time.
540 As it happens, you may even further simplify the procedure described above:
541 you may forget about calling @e Set(). When @e Get() is called and there
542 is no current object, it will create one using @e Create() function. To
543 disable this behaviour @e DontCreateOnDemand() is provided.
545 @b Note: You should use either @e Set() or @e Get() because wxWidgets
546 library itself would take advantage of it and could save various information
547 in it. For example wxFontMapper or Unix version
548 of wxFileDialog have the ability to use wxConfig class.
573 These functions write the specified value to the config file and return @true
574 on success. In the last one, function wxToString must be
575 defined for type @e T.
584 @b WriteInt(key, value)
589 @b WriteFloat(key, value)
592 Writes a floating point number
594 @b WriteBool(key, value)
599 bool Write(const wxString
& key
, const wxString
& value
);
600 bool Write(const wxString
& key
, long value
);
601 bool Write(const wxString
& key
, double value
);
602 bool Write(const wxString
& key
, bool value
);
603 bool Write(const wxString
& key
, const wxMemoryBuffer
& buf
);
604 bool Write(const wxString
& key
, const T
& buf
);