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