]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/config.h
Use wxCOMPtr throughout wxWebViewIE to simplify the code and reduce the chance of...
[wxWidgets.git] / interface / wx / config.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: config.h
3 // Purpose: interface of wxConfigBase
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxConfigBase
11
12 wxConfigBase defines the basic interface of all config classes. It cannot
13 be used by itself (it is an abstract base class) and you will always use
14 one of its derivations: wxFileConfig, wxRegConfig or any other.
15
16 However, usually you don't even need to know the precise nature of the
17 class you're working with but you would just use the wxConfigBase methods.
18 This allows you to write the same code regardless of whether you're working
19 with the registry under Windows or text-based config files under Unix.
20 To make writing the portable code even easier, wxWidgets provides a typedef
21 wxConfig which is mapped onto the native wxConfigBase implementation on the
22 given platform: i.e. wxRegConfig under Windows and wxFileConfig otherwise.
23
24 See @ref overview_config for a description of all features of this class.
25
26 It is highly recommended to use static functions Get() and/or Set(), so
27 please have a look at them.
28
29 Related Include Files:
30
31 @li @c <wx/config.h> - Let wxWidgets choose a wxConfig class for your
32 platform.
33 @li @c <wx/confbase.h> - Base config class.
34 @li @c <wx/fileconf.h> - wxFileConfig class.
35 @li @c <wx/msw/regconf.h> - wxRegConfig class, see also wxRegKey.
36
37
38 @section configbase_example Example
39
40 Here is how you would typically use this class:
41
42 @code
43 // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances
44 // portability of the code
45 wxConfig *config = new wxConfig("MyAppName");
46
47 wxString str;
48 if ( config->Read("LastPrompt", &str) ) {
49 // last prompt was found in the config file/registry and its value is
50 // now in str
51 // ...
52 }
53 else {
54 // no last prompt...
55 }
56
57 // another example: using default values and the full path instead of just
58 // key name: if the key is not found , the value 17 is returned
59 long value = config->ReadLong("/LastRun/CalculatedValues/MaxValue", 17);
60
61 // at the end of the program we would save everything back
62 config->Write("LastPrompt", str);
63 config->Write("/LastRun/CalculatedValues/MaxValue", value);
64
65 // the changes will be written back automatically
66 delete config;
67 @endcode
68
69 This basic example, of course, doesn't show all wxConfig features, such as
70 enumerating, testing for existence and deleting the entries and groups of
71 entries in the config file, its abilities to automatically store the
72 default values or expand the environment variables on the fly. However, the
73 main idea is that using this class is easy and that it should normally do
74 what you expect it to.
75
76 @note In the documentation of this class, the words "config file" also mean
77 "registry hive" for wxRegConfig and, generally speaking, might mean
78 any physical storage where a wxConfigBase-derived class stores its
79 data.
80
81
82 @section configbase_static Static Functions
83
84 The static functions provided deal with the "default" config object.
85 Although its usage is not at all mandatory it may be convenient to use a
86 global config object instead of creating and deleting the local config
87 objects each time you need one (especially because creating a wxFileConfig
88 object might be a time consuming operation). In this case, you may create
89 this global config object in the very start of the program and Set() it as
90 the default. Then, from anywhere in your program, you may access it using
91 the Get() function. This global wxConfig object will be deleted by
92 wxWidgets automatically if it exists. Note that this implies that if you do
93 delete this object yourself (usually in wxApp::OnExit()) you must use
94 Set(@NULL) to prevent wxWidgets from deleting it the second time.
95
96 As it happens, you may even further simplify the procedure described above:
97 you may forget about calling Set(). When Get() is called and there is no
98 current object, it will create one using Create() function. To disable this
99 behaviour DontCreateOnDemand() is provided.
100
101 @note You should use either Set() or Get() because wxWidgets library itself
102 would take advantage of it and could save various information in it.
103 For example wxFontMapper or Unix version of wxFileDialog have the
104 ability to use wxConfig class.
105
106
107 @section configbase_paths Path Management
108
109 As explained in the @ref overview_config "config overview", the config
110 classes support a file system-like hierarchy of keys (files) and groups
111 (directories). As in the file system case, to specify a key in the config
112 class you must use a path to it. Config classes also support the notion of
113 the current group, which makes it possible to use the relative paths. To
114 clarify all this, here is an example (it is only for the sake of
115 demonstration, it doesn't do anything sensible!):
116
117 @code
118 wxConfig *config = new wxConfig("FooBarApp");
119
120 // right now the current path is '/'
121 conf->Write("RootEntry", 1);
122
123 // go to some other place: if the group(s) don't exist, they will be created
124 conf->SetPath("/Group/Subgroup");
125
126 // create an entry in subgroup
127 conf->Write("SubgroupEntry", 3);
128
129 // '..' is understood
130 conf->Write("../GroupEntry", 2);
131 conf->SetPath("..");
132
133 wxASSERT( conf->ReadLong("Subgroup/SubgroupEntry", 0) == 3 );
134
135 // use absolute path: it is allowed, too
136 wxASSERT( conf->ReadLong("/RootEntry", 0) == 1 );
137 @endcode
138
139 It is highly recommended that you restore the path to its old value on
140 function exit:
141
142 @code
143 void foo(wxConfigBase *config)
144 {
145 wxString strOldPath = config->GetPath();
146
147 config->SetPath("/Foo/Data");
148 // ...
149
150 config->SetPath(strOldPath);
151 }
152 @endcode
153
154 Otherwise the assert in the following example will surely fail (we suppose
155 here that the foo() function is the same as above except that it doesn’t
156 save and restore the path):
157
158 @code
159 void bar(wxConfigBase *config)
160 {
161 config->Write("Test", 17);
162
163 foo(config);
164
165 // we're reading "/Foo/Data/Test" here! -1 will probably be returned...
166 wxASSERT( config->ReadLong("Test", -1) == 17 );
167 }
168 @endcode
169
170 Finally, the path separator in wxConfigBase and derived classes is always
171 "/", regardless of the platform (i.e. it is not "\\" under Windows).
172
173
174 @section configbase_enumeration Enumeration
175
176 The enumeration functions allow you to enumerate all entries and groups in
177 the config file. All functions here return @false when there are no more
178 items.
179
180 You must pass the same index to GetNext() and GetFirst() (don't modify it).
181 Please note that it is not the index of the current item (you will have
182 some great surprises with wxRegConfig if you assume this) and you shouldn't
183 even look at it: it is just a "cookie" which stores the state of the
184 enumeration. It can't be stored inside the class because it would prevent
185 you from running several enumerations simultaneously, that's why you must
186 pass it explicitly.
187
188 Having said all this, enumerating the config entries/groups is very simple:
189
190 @code
191 wxConfigBase *config = ...;
192 wxArrayString aNames;
193
194 // enumeration variables
195 wxString str;
196 long dummy;
197
198 // first enum all entries
199 bool bCont = config->GetFirstEntry(str, dummy);
200 while ( bCont ) {
201 aNames.Add(str);
202
203 bCont = GetConfig()->GetNextEntry(str, dummy);
204 }
205
206 // ... we have all entry names in aNames...
207
208 // now all groups...
209 bCont = GetConfig()->GetFirstGroup(str, dummy);
210 while ( bCont ) {
211 aNames.Add(str);
212
213 bCont = GetConfig()->GetNextGroup(str, dummy);
214 }
215
216 // ... we have all group (and entry) names in aNames...
217 @endcode
218
219 There are also functions to get the number of entries/subgroups without
220 actually enumerating them, but you will probably never need them.
221
222
223 @section configbase_keyaccess Key Access
224
225 The key access functions are the core of wxConfigBase class: they allow you
226 to read and write config file data. All Read() functions take a default
227 value which will be returned if the specified key is not found in the
228 config file.
229
230 Currently, supported types of data are: wxString, @c long, @c double,
231 @c bool, wxColour and any other types for which the functions
232 wxToString() and wxFromString() are defined.
233
234 Try not to read long values into string variables and vice versa:
235 although it just might work with wxFileConfig, you will get a system
236 error with wxRegConfig because in the Windows registry the different
237 types of entries are indeed used.
238
239 Final remark: the @a szKey parameter for all these functions can
240 contain an arbitrary path (either relative or absolute), not just the
241 key name.
242
243 @library{wxbase}
244 @category{cfg}
245
246 @see wxConfigPathChanger
247 */
248 class wxConfigBase : public wxObject
249 {
250 public:
251 /**
252 This is the default and only constructor of the wxConfigBase class, and
253 derived classes.
254
255 @param appName
256 The application name. If this is empty, the class will normally use
257 wxApp::GetAppName() to set it. The application name is used in the
258 registry key on Windows, and can be used to deduce the local
259 filename parameter if that is missing.
260 @param vendorName
261 The vendor name. If this is empty, it is assumed that no vendor
262 name is wanted, if this is optional for the current config class.
263 The vendor name is appended to the application name for
264 wxRegConfig.
265 @param localFilename
266 Some config classes require a local filename. If this is not
267 present, but required, the application name will be used instead.
268 @param globalFilename
269 Some config classes require a global filename. If this is not
270 present, but required, the application name will be used instead.
271 @param style
272 Can be one of @c wxCONFIG_USE_LOCAL_FILE and @c wxCONFIG_USE_GLOBAL_FILE.
273 @n The style interpretation depends on the config class and is ignored
274 by some implementations. For wxFileConfig, these styles determine
275 whether a local or global config file is created or used: if
276 @c wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the
277 global config file and if @c wxCONFIG_USE_LOCAL_FILE is used, settings
278 are read from and written to local config file (if they are both
279 set, global file is read first, then local file, overwriting global
280 settings). If the flag is present but the parameter is empty, the
281 parameter will be set to a default. If the parameter is present but
282 the style flag not, the relevant flag will be added to the style.
283 For wxRegConfig, the GLOBAL flag refers to the @c HKLM key while LOCAL
284 one is for the usual @c HKCU one.
285 @n For wxFileConfig you can also add @c wxCONFIG_USE_RELATIVE_PATH by
286 logically or'ing it to either of the _FILE options to tell
287 wxFileConfig to use relative instead of absolute paths.
288 @n On non-VMS Unix systems, the default local configuration file is
289 "~/.appname". However, this path may be also used as user data
290 directory (see wxStandardPaths::GetUserDataDir()) if the
291 application has several data files. In this case
292 @c wxCONFIG_USE_SUBDIR flag, which changes the default local
293 configuration file to "~/.appname/appname" should be used. Notice
294 that this flag is ignored if @a localFilename is provided.
295 @c wxCONFIG_USE_SUBDIR is new since wxWidgets version 2.8.2.
296 @n For wxFileConfig, you can also add
297 @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS which will turn off character
298 escaping for the values of entries stored in the config file: for
299 example a foo key with some backslash characters will be stored as
300 "foo=C:\mydir" instead of the usual storage of "foo=C:\\mydir".
301 @n The @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your
302 config file must be read or written to by a non-wxWidgets program
303 (which might not understand the escape characters). Note, however,
304 that if @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is
305 now your application's responsibility to ensure that there is no
306 newline or other illegal characters in a value, before writing that
307 value to the file.
308 @param conv
309 This parameter is only used by wxFileConfig when compiled in
310 Unicode mode. It specifies the encoding in which the configuration
311 file is written.
312
313 @remarks By default, environment variable expansion is on and recording
314 defaults is off.
315 */
316 wxConfigBase(const wxString& appName = wxEmptyString,
317 const wxString& vendorName = wxEmptyString,
318 const wxString& localFilename = wxEmptyString,
319 const wxString& globalFilename = wxEmptyString,
320 long style = 0,
321 const wxMBConv& conv = wxConvAuto());
322
323 /**
324 Empty but ensures that dtor of all derived classes is virtual.
325 */
326 virtual ~wxConfigBase();
327
328
329 /**
330 @name Path Management
331
332 See @ref configbase_paths
333 */
334 //@{
335
336 /**
337 Retrieve the current path (always as absolute path).
338 */
339 virtual const wxString& GetPath() const = 0;
340
341 /**
342 Set current path: if the first character is '/', it is the absolute
343 path, otherwise it is a relative path. '..' is supported. If @a strPath
344 doesn't exist, it is created.
345
346 @see wxConfigPathChanger
347 */
348 virtual void SetPath(const wxString& strPath) = 0;
349
350 //@}
351
352
353 /**
354 @name Enumeration
355
356 See @ref configbase_enumeration
357 */
358 //@{
359
360 /**
361 Gets the first entry.
362
363 @beginWxPerlOnly
364 In wxPerl this method takes no parameters and returns a 3-element
365 list (continue_flag, string, index_for_getnextentry).
366 @endWxPerlOnly
367 */
368 virtual bool GetFirstEntry(wxString& str, long& index) const = 0;
369
370 /**
371 Gets the first group.
372
373 @beginWxPerlOnly
374 In wxPerl this method takes no parameters and returns a 3-element
375 list (continue_flag, string, index_for_getnextentry).
376 @endWxPerlOnly
377 */
378 virtual bool GetFirstGroup(wxString& str, long& index) const = 0;
379
380 /**
381 Gets the next entry.
382
383 @beginWxPerlOnly
384 In wxPerl this method only takes the @a index parameter and
385 returns a 3-element list (continue_flag, string,
386 index_for_getnextentry).
387 @endWxPerlOnly
388 */
389 virtual bool GetNextEntry(wxString& str, long& index) const = 0;
390
391 /**
392 Gets the next group.
393
394 @beginWxPerlOnly
395 In wxPerl this method only takes the @a index parameter and
396 returns a 3-element list (continue_flag, string,
397 index_for_getnextentry).
398 @endWxPerlOnly
399 */
400 virtual bool GetNextGroup(wxString& str, long& index) const = 0;
401
402 /**
403 Get number of entries in the current group.
404 */
405 virtual size_t GetNumberOfEntries(bool bRecursive = false) const = 0;
406
407 /**
408 Get number of entries/subgroups in the current group, with or without
409 its subgroups.
410 */
411 virtual size_t GetNumberOfGroups(bool bRecursive = false) const = 0;
412
413 //@}
414
415
416 enum EntryType
417 {
418 Type_Unknown,
419 Type_String,
420 Type_Boolean,
421 Type_Integer,
422 Type_Float
423 };
424
425 /**
426 @name Tests of Existence
427 */
428 //@{
429
430 /**
431 @return @true if either a group or an entry with a given name exists.
432 */
433 bool Exists(const wxString& strName) const;
434
435 /**
436 Returns the type of the given entry or @e Unknown if the entry doesn't
437 exist. This function should be used to decide which version of Read()
438 should be used because some of wxConfig implementations will complain
439 about type mismatch otherwise: e.g., an attempt to read a string value
440 from an integer key with wxRegConfig will fail.
441 */
442 virtual wxConfigBase::EntryType GetEntryType(const wxString& name) const;
443
444 /**
445 @return @true if the entry by this name exists.
446 */
447 virtual bool HasEntry(const wxString& strName) const = 0;
448
449 /**
450 @return @true if the group by this name exists.
451 */
452 virtual bool HasGroup(const wxString& strName) const = 0;
453
454 //@}
455
456
457 /**
458 @name Miscellaneous Functions
459 */
460 //@{
461
462 /**
463 Returns the application name.
464 */
465 wxString GetAppName() const;
466
467 /**
468 Returns the vendor name.
469 */
470 wxString GetVendorName() const;
471
472 //@}
473
474
475 /**
476 @name Key Access
477
478 See @ref configbase_keyaccess
479 */
480 //@{
481
482 /**
483 Permanently writes all changes (otherwise, they're only written from
484 object's destructor).
485 */
486 virtual bool Flush(bool bCurrentOnly = false) = 0;
487
488 /**
489 Read a string from the key, returning @true if the value was read. If
490 the key was not found, @a str is not changed.
491
492 @beginWxPerlOnly
493 Not supported by wxPerl.
494 @endWxPerlOnly
495 */
496 bool Read(const wxString& key, wxString* str) const;
497 /**
498 Read a string from the key. The default value is returned if the key
499 was not found.
500
501 @return @true if value was really read, @false if the default was used.
502
503 @beginWxPerlOnly
504 Not supported by wxPerl.
505 @endWxPerlOnly
506 */
507 bool Read(const wxString& key, wxString* str,
508 const wxString& defaultVal) const;
509 /**
510 Another version of Read(), returning the string value directly.
511
512 @beginWxPerlOnly
513 In wxPerl, this can be called as:
514 - Read(key): returns the empty string if no key is found
515 - Read(key, default): returns the default value if no key is found
516 @endWxPerlOnly
517 */
518 const wxString Read(const wxString& key,
519 const wxString& defaultVal) const;
520 /**
521 Reads a long value, returning @true if the value was found. If the
522 value was not found, @a l is not changed.
523
524 @beginWxPerlOnly
525 Not supported by wxPerl.
526 @endWxPerlOnly
527 */
528 bool Read(const wxString& key, long* l) const;
529 /**
530 Reads a long value, returning @true if the value was found. If the
531 value was not found, @a defaultVal is used instead.
532
533 @beginWxPerlOnly
534 In wxPerl, this can be called as:
535 - ReadInt(key): returns the 0 if no key is found
536 - ReadInt(key, default): returns the default value if no key is found
537 @endWxPerlOnly
538 */
539 bool Read(const wxString& key, long* l,
540 long defaultVal) const;
541 /**
542 Reads a double value, returning @true if the value was found. If the
543 value was not found, @a d is not changed.
544
545 @beginWxPerlOnly
546 Not supported by wxPerl.
547 @endWxPerlOnly
548 */
549 bool Read(const wxString& key, double* d) const;
550 /**
551 Reads a double value, returning @true if the value was found. If the
552 value was not found, @a defaultVal is used instead.
553
554 @beginWxPerlOnly
555 In wxPerl, this can be called as:
556 - ReadFloat(key): returns the 0.0 if no key is found
557 - ReadFloat(key, default): returns the default value if no key is found
558 @endWxPerlOnly
559 */
560 bool Read(const wxString& key, double* d,
561 double defaultVal) const;
562
563 /**
564 Reads a float value, returning @true if the value was found.
565
566 If the value was not found, @a f is not changed.
567
568 Notice that the value is read as a double but must be in a valid range
569 for floats for the function to return @true.
570
571 @since 2.9.1
572
573 @beginWxPerlOnly
574 Not supported by wxPerl.
575 @endWxPerlOnly
576 */
577 bool Read(const wxString& key, float* f) const;
578 /**
579 Reads a float value, returning @true if the value was found.
580
581 If the value was not found, @a defaultVal is used instead.
582
583 Notice that the value is read as a double but must be in a valid range
584 for floats for the function to return @true.
585
586 @since 2.9.1
587
588 @beginWxPerlOnly
589 Not supported by wxPerl.
590 @endWxPerlOnly
591 */
592 bool Read(const wxString& key, float* f, float defaultVal) const;
593
594 /**
595 Reads a boolean value, returning @true if the value was found. If the
596 value was not found, @a b is not changed.
597
598 @since 2.9.1
599
600 @beginWxPerlOnly
601 Not supported by wxPerl.
602 @endWxPerlOnly
603 */
604 bool Read(const wxString& key, bool* b) const;
605 /**
606 Reads a boolean value, returning @true if the value was found. If the
607 value was not found, @a defaultVal is used instead.
608
609 @beginWxPerlOnly
610 In wxPerl, this can be called as:
611 - ReadBool(key): returns false if no key is found
612 - ReadBool(key, default): returns the default value if no key is found
613 @endWxPerlOnly
614 */
615 bool Read(const wxString& key, bool* d,
616 bool defaultVal) const;
617 /**
618 Reads a binary block, returning @true if the value was found. If the
619 value was not found, @a buf is not changed.
620 */
621 bool Read(const wxString& key, wxMemoryBuffer* buf) const;
622 /**
623 Reads a value of type T, for which function wxFromString() is defined,
624 returning @true if the value was found. If the value was not found,
625 @a value is not changed.
626 */
627 bool Read(const wxString& key, T* value) const;
628 /**
629 Reads a value of type T, for which function wxFromString() is defined,
630 returning @true if the value was found. If the value was not found,
631 @a defaultVal is used instead.
632 */
633 bool Read(const wxString& key, T* value,
634 const T& defaultVal) const;
635
636 /**
637 Reads a bool value from the key and returns it. @a defaultVal is
638 returned if the key is not found.
639 */
640 bool ReadBool(const wxString& key, bool defaultVal) const;
641
642 /**
643 Reads a double value from the key and returns it. @a defaultVal is
644 returned if the key is not found.
645 */
646 double ReadDouble(const wxString& key, double defaultVal) const;
647
648 /**
649 Reads a long value from the key and returns it. @a defaultVal is
650 returned if the key is not found.
651 */
652 long ReadLong(const wxString& key, long defaultVal) const;
653
654 /**
655 Reads a value of type T (for which the function wxFromString() must be
656 defined) from the key and returns it. @a defaultVal is returned if the
657 key is not found.
658 */
659 T ReadObject(const wxString& key, T const& defaultVal) const;
660
661 /**
662 Writes the wxString value to the config file and returns @true on
663 success.
664 */
665 bool Write(const wxString& key, const wxString& value);
666 /**
667 Writes the long value to the config file and returns @true on success.
668 */
669 bool Write(const wxString& key, long value);
670 /**
671 Writes the double value to the config file and returns @true on
672 success.
673
674 Notice that if floating point numbers are saved as strings (as is the
675 case with the configuration files used by wxFileConfig), this function
676 uses the C locale for writing out the number, i.e. it will always use a
677 period as the decimal separator, irrespectively of the current locale.
678 This behaviour is new since wxWidgets 2.9.1 as the current locale was
679 used before, but the change should be transparent because both C and
680 current locales are tried when reading the numbers back.
681 */
682 bool Write(const wxString& key, double value);
683 /**
684 Writes the bool value to the config file and returns @true on success.
685 */
686 bool Write(const wxString& key, bool value);
687 /**
688 Writes the wxMemoryBuffer value to the config file and returns @true on
689 success.
690 */
691 bool Write(const wxString& key, const wxMemoryBuffer& buf);
692 /**
693 Writes the specified value to the config file and returns @true on
694 success. The function wxToString() must be defined for type @e T.
695 */
696 bool Write(const wxString& key, T const& buf);
697
698 //@}
699
700
701 /**
702 @name Rename Entries/Groups
703
704 These functions allow renaming entries or subgroups of the current
705 group. They will return @false on error, typically because either the
706 entry/group with the original name doesn't exist, because the
707 entry/group with the new name already exists or because the function is
708 not supported in this wxConfig implementation.
709 */
710 //@{
711
712 /**
713 Renames an entry in the current group. The entries names (both the old
714 and the new one) shouldn't contain backslashes, i.e. only simple names
715 and not arbitrary paths are accepted by this function.
716
717 @return @false if @a oldName doesn't exist or if @a newName already
718 exists.
719 */
720 virtual bool RenameEntry(const wxString& oldName,
721 const wxString& newName) = 0;
722
723 /**
724 Renames a subgroup of the current group. The subgroup names (both the
725 old and the new one) shouldn't contain backslashes, i.e. only simple
726 names and not arbitrary paths are accepted by this function.
727
728 @return @false if @a oldName doesn't exist or if @a newName already
729 exists.
730 */
731 virtual bool RenameGroup(const wxString& oldName,
732 const wxString& newName) = 0;
733
734 //@}
735
736
737 /**
738 @name Delete Entries/Groups
739
740 These functions delete entries and/or groups of entries from the config
741 file. DeleteAll() is especially useful if you want to erase all traces
742 of your program presence: for example, when you uninstall it.
743 */
744 //@{
745
746 /**
747 Delete the whole underlying object (disk file, registry key, ...).
748 Primarily for use by uninstallation routine.
749 */
750 virtual bool DeleteAll() = 0;
751
752 /**
753 Deletes the specified entry and the group it belongs to if it was the
754 last key in it and the second parameter is @true.
755 */
756 virtual bool DeleteEntry(const wxString& key,
757 bool bDeleteGroupIfEmpty = true) = 0;
758
759 /**
760 Delete the group (with all subgroups). If the current path is under the
761 group being deleted it is changed to its deepest still existing
762 component. E.g. if the current path is @c "/A/B/C/D" and the group @c C
763 is deleted, the path becomes @c "/A/B".
764 */
765 virtual bool DeleteGroup(const wxString& key) = 0;
766
767 //@}
768
769
770 /**
771 @name Options
772
773 Some aspects of wxConfigBase behaviour can be changed during run-time.
774 The first of them is the expansion of environment variables in the
775 string values read from the config file: for example, if you have the
776 following in your config file:
777
778 @code
779 # config file for my program
780 UserData = $HOME/data
781
782 # the following syntax is valud only under Windows
783 UserData = %windir%\\data.dat
784 @endcode
785
786 The call to Read("UserData") will return something like
787 @c "/home/zeitlin/data" on linux for example.
788
789 Although this feature is very useful, it may be annoying if you read a
790 value which containts '$' or '%' symbols (% is used for environment
791 variables expansion under Windows) which are not used for environment
792 variable expansion. In this situation you may call
793 SetExpandEnvVars(@false) just before reading this value and
794 SetExpandEnvVars(@true) just after. Another solution would be to prefix
795 the offending symbols with a backslash.
796 */
797 //@{
798
799 /**
800 Returns @true if we are expanding environment variables in key values.
801 */
802 bool IsExpandingEnvVars() const;
803
804 /**
805 Returns @true if we are writing defaults back to the config file.
806 */
807 bool IsRecordingDefaults() const;
808
809 /**
810 Determine whether we wish to expand environment variables in key
811 values.
812 */
813 void SetExpandEnvVars(bool bDoIt = true);
814
815 /**
816 Sets whether defaults are recorded to the config file whenever an
817 attempt to read the value which is not present in it is done.
818
819 If on (default is off) all default values for the settings used by the
820 program are written back to the config file. This allows the user to
821 see what config options may be changed and is probably useful only for
822 wxFileConfig.
823 */
824 void SetRecordDefaults(bool bDoIt = true);
825
826 //@}
827
828
829 /**
830 Create a new config object and sets it as the current one.
831
832 This function will create the most appropriate implementation of
833 wxConfig available for the current platform. By default this means that
834 the system registry will be used for storing the configuration
835 information under MSW and a file under the user home directory (see
836 wxStandardPaths::GetUserConfigDir()) elsewhere.
837
838 If you prefer to use the configuration files everywhere, you can define
839 @c wxUSE_CONFIG_NATIVE to 0 when compiling wxWidgets. Or you can simply
840 always create wxFileConfig explicitly.
841
842 Finally, if you want to create a custom wxConfig subclass you may
843 change this function behaviour by overriding wxAppTraits::CreateConfig()
844 to create it. An example when this could be useful could be an
845 application which could be installed either normally (in which case the
846 default behaviour of using wxRegConfig is appropriate) or in a
847 "portable" way in which case a wxFileConfig with a file in the program
848 directory would be used and the choice would be done in CreateConfig()
849 at run-time.
850 */
851 static wxConfigBase* Create();
852
853 /**
854 Calling this function will prevent @e Get() from automatically creating
855 a new config object if the current one is @NULL. It might be useful to
856 call it near the program end to prevent "accidental" creation of a new
857 config object.
858 */
859 static void DontCreateOnDemand();
860
861 /**
862 Get the current config object. If there is no current object and
863 @a CreateOnDemand is @true, this creates one (using Create()) unless
864 DontCreateOnDemand() was called previously.
865 */
866 static wxConfigBase* Get(bool CreateOnDemand = true);
867
868 /**
869 Sets the config object as the current one, returns the pointer to the
870 previous current object (both the parameter and returned value may be
871 @NULL).
872 */
873 static wxConfigBase* Set(wxConfigBase* pConfig);
874 };
875
876
877 /**
878 @class wxConfigPathChanger
879
880 A handy little class which changes the current path in a wxConfig object and restores it in dtor.
881 Declaring a local variable of this type, it's possible to work in a specific directory
882 and ensure that the path is automatically restored when the function returns.
883
884 For example:
885 @code
886 // this function loads somes settings from the given wxConfig object;
887 // the path selected inside it is left unchanged
888 bool LoadMySettings(wxConfigBase* cfg)
889 {
890 wxConfigPathChanger changer(cfg, "/Foo/Data/SomeString");
891 wxString str;
892 if ( !config->Read("SomeString", &str) ) {
893 wxLogError("Couldn't read SomeString!");
894 return false;
895 // NOTE: without wxConfigPathChanger it would be easy to forget to
896 // set the old path back into the wxConfig object before this return!
897 }
898
899 // do something useful with SomeString...
900
901 return true; // again: wxConfigPathChanger dtor will restore the original wxConfig path
902 }
903 @endcode
904
905 @library{wxbase}
906 @category{cfg}
907 */
908 class WXDLLIMPEXP_BASE wxConfigPathChanger
909 {
910 public:
911
912 /**
913 Changes the path of the given wxConfigBase object so that the key @a strEntry is accessible
914 (for read or write).
915
916 In other words, the ctor uses wxConfigBase::SetPath() with everything which precedes the
917 last slash of @a strEntry, so that:
918 @code
919 wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/SomeKeyName");
920 @endcode
921 has the same effect of:
922 @code
923 wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/");
924 @endcode
925 */
926 wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry);
927
928 /**
929 Restores the path selected, inside the wxConfig object passed to the ctor, to the path which was
930 selected when the wxConfigPathChanger ctor was called.
931 */
932 ~wxConfigPathChanger();
933
934 /**
935 Returns the name of the key which was passed to the ctor.
936 The "name" is just anything which follows the last slash of the string given to the ctor.
937 */
938 const wxString& Name() const;
939
940 /**
941 This method must be called if the original path inside the wxConfig object
942 (i.e. the current path at the moment of creation of this wxConfigPathChanger object)
943 could have been deleted, thus preventing wxConfigPathChanger from restoring the not
944 existing (any more) path.
945
946 If the original path doesn't exist any more, the path will be restored to
947 the deepest still existing component of the old path.
948 */
949 void UpdateIfDeleted();
950 };
951