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 = config->GetNextEntry(str, dummy); 215 } 216 217 // ... we have all entry names in aNames... 218 219 // now all groups... 220 bCont = config->GetFirstGroup(str, dummy); 221 while ( bCont ) { 222 aNames.Add(str); 223 224 bCont = config->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 64-bit long long value, returning @true if the value was found. 554 If the value was not found, @a ll is not changed. 555 556 @since 3.1.5 557 558 @beginWxPerlOnly 559 Not supported by wxPerl. 560 @endWxPerlOnly 561 */ 562 bool Read(const wxString& key, wxLongLong_t* ll) const; 563 /** 564 Reads a 64-bit long long value, returning @true if the value was found. 565 If the value was not found, @a defaultVal is used instead. 566 567 @since 3.1.5 568 569 @beginWxPerlOnly 570 Not supported by wxPerl. 571 @endWxPerlOnly 572 */ 573 bool Read(const wxString& key, wxLongLong_t* ll, 574 /** 575 Reads a size_t value, returning @true if the value was found. 576 If the value was not found, @a value is not changed. 577 578 @since 3.1.5 579 580 @beginWxPerlOnly 581 Not supported by wxPerl. 582 @endWxPerlOnly 583 */ 584 bool Read(const wxString& key, size_t* value) const; 585 /** 586 Reads a size_t value, returning @true if the value was found. 587 If the value was not found, @a defaultVal is used instead. 588 589 @since 3.1.5 590 591 @beginWxPerlOnly 592 Not supported by wxPerl. 593 @endWxPerlOnly 594 */ 595 bool Read(const wxString& key, size_t* value, 596 size_t defaultVal) const; 597 /** 598 Reads a double value, returning @true if the value was found. If the 599 value was not found, @a d is not changed. 600 601 @beginWxPerlOnly 602 Not supported by wxPerl. 603 @endWxPerlOnly 604 */ 605 bool Read(const wxString& key, double* d) const; 606 /** 607 Reads a double value, returning @true if the value was found. If the 608 value was not found, @a defaultVal is used instead. 609 610 @beginWxPerlOnly 611 In wxPerl, this can be called as: 612 - ReadFloat(key): returns the 0.0 if no key is found 613 - ReadFloat(key, default): returns the default value if no key is found 614 @endWxPerlOnly 615 */ 616 bool Read(const wxString& key, double* d, 617 double defaultVal) const; 618 619 /** 620 Reads a float value, returning @true if the value was found. 621 622 If the value was not found, @a f is not changed. 623 624 Notice that the value is read as a double but must be in a valid range 625 for floats for the function to return @true. 626 627 @since 2.9.1 628 629 @beginWxPerlOnly 630 Not supported by wxPerl. 631 @endWxPerlOnly 632 */ 633 bool Read(const wxString& key, float* f) const; 634 /** 635 Reads a float value, returning @true if the value was found. 636 637 If the value was not found, @a defaultVal is used instead. 638 639 Notice that the value is read as a double but must be in a valid range 640 for floats for the function to return @true. 641 642 @since 2.9.1 643 644 @beginWxPerlOnly 645 Not supported by wxPerl. 646 @endWxPerlOnly 647 */ 648 bool Read(const wxString& key, float* f, float defaultVal) const; 649 650 /** 651 Reads a boolean value, returning @true if the value was found. If the 652 value was not found, @a b is not changed. 653 654 @since 2.9.1 655 656 @beginWxPerlOnly 657 Not supported by wxPerl. 658 @endWxPerlOnly 659 */ 660 bool Read(const wxString& key, bool* b) const; 661 /** 662 Reads a boolean value, returning @true if the value was found. If the 663 value was not found, @a defaultVal is used instead. 664 665 @beginWxPerlOnly 666 In wxPerl, this can be called as: 667 - ReadBool(key): returns false if no key is found 668 - ReadBool(key, default): returns the default value if no key is found 669 @endWxPerlOnly 670 */ 671 bool Read(const wxString& key, bool* d, 672 bool defaultVal) const; 673 /** 674 Reads a binary block, returning @true if the value was found. If the 675 value was not found, @a buf is not changed. 676 */ 677 bool Read(const wxString& key, wxMemoryBuffer* buf) const; 678 /** 679 Reads a value of type T, for which function wxFromString() is defined, 680 returning @true if the value was found. If the value was not found, 681 @a value is not changed. 682 */ 683 bool Read(const wxString& key, T* value) const; 684 /** 685 Reads a value of type T, for which function wxFromString() is defined, 686 returning @true if the value was found. If the value was not found, 687 @a defaultVal is used instead. 688 */ 689 bool Read(const wxString& key, T* value, 690 const T& defaultVal) const; 691 692 /** 693 Reads a bool value from the key and returns it. @a defaultVal is 694 returned if the key is not found. 695 */ 696 bool ReadBool(const wxString& key, bool defaultVal) const; 697 698 /** 699 Reads a double value from the key and returns it. @a defaultVal is 700 returned if the key is not found. 701 */ 702 double ReadDouble(const wxString& key, double defaultVal) const; 703 704 /** 705 Reads a long value from the key and returns it. @a defaultVal is 706 returned if the key is not found. 707 */ 708 long ReadLong(const wxString& key, long defaultVal) const; 709 710 /** 711 Reads a 64-bit long long value from the key and returns it. @a 712 defaultVal is returned if the key is not found. 713 714 @since 3.1.5 715 */ 716 wxLongLong_t ReadLongLong(const wxString& key, wxLongLong_t defaultVal) const; 717 718 /** 719 Reads a value of type T (for which the function wxFromString() must be 720 defined) from the key and returns it. @a defaultVal is returned if the 721 key is not found. 722 */ 723 T ReadObject(const wxString& key, T const& defaultVal) const; 724 725 /** 726 Writes the wxString value to the config file and returns @true on 727 success. 728 */ 729 bool Write(const wxString& key, const wxString& value); 730 /** 731 Writes the long value to the config file and returns @true on success. 732 */ 733 bool Write(const wxString& key, long value); 734 /** 735 Writes the 64-bit long long value to the config file and returns @true 736 on success. 737 738 @since 3.1.5 739 */ 740 bool Write(const wxString& key, wxLongLong_t value); 741 /** 742 Writes the double value to the config file and returns @true on 743 success. 744 745 Notice that if floating point numbers are saved as strings (as is the 746 case with the configuration files used by wxFileConfig), this function 747 uses the C locale for writing out the number, i.e. it will always use a 748 period as the decimal separator, irrespectively of the current locale. 749 This behaviour is new since wxWidgets 2.9.1 as the current locale was 750 used before, but the change should be transparent because both C and 751 current locales are tried when reading the numbers back. 752 */ 753 bool Write(const wxString& key, double value); 754 /** 755 Writes the bool value to the config file and returns @true on success. 756 */ 757 bool Write(const wxString& key, bool value); 758 /** 759 Writes the wxMemoryBuffer value to the config file and returns @true on 760 success. 761 */ 762 bool Write(const wxString& key, const wxMemoryBuffer& buf); 763 /** 764 Writes the specified value to the config file and returns @true on 765 success. The function wxToString() must be defined for type @e T. 766 */ 767 bool Write(const wxString& key, T const& buf); 768 769 //@} 770 771 772 /** 773 @name Rename Entries/Groups 774 775 These functions allow renaming entries or subgroups of the current 776 group. They will return @false on error, typically because either the 777 entry/group with the original name doesn't exist, because the 778 entry/group with the new name already exists or because the function is 779 not supported in this wxConfig implementation. 780 */ 781 //@{ 782 783 /** 784 Renames an entry in the current group. The entries names (both the old 785 and the new one) shouldn't contain backslashes, i.e. only simple names 786 and not arbitrary paths are accepted by this function. 787 788 @return @false if @a oldName doesn't exist or if @a newName already 789 exists. 790 */ 791 virtual bool RenameEntry(const wxString& oldName, 792 const wxString& newName) = 0; 793 794 /** 795 Renames a subgroup of the current group. The subgroup names (both the 796 old and the new one) shouldn't contain backslashes, i.e. only simple 797 names and not arbitrary paths are accepted by this function. 798 799 @return @false if @a oldName doesn't exist or if @a newName already 800 exists. 801 */ 802 virtual bool RenameGroup(const wxString& oldName, 803 const wxString& newName) = 0; 804 805 //@} 806 807 808 /** 809 @name Delete Entries/Groups 810 811 These functions delete entries and/or groups of entries from the config 812 file. DeleteAll() is especially useful if you want to erase all traces 813 of your program presence: for example, when you uninstall it. 814 */ 815 //@{ 816 817 /** 818 Delete the whole underlying object (disk file, registry key, ...). 819 Primarily for use by uninstallation routine. 820 */ 821 virtual bool DeleteAll() = 0; 822 823 /** 824 Deletes the specified entry and the group it belongs to if it was the 825 last key in it and the second parameter is @true. 826 */ 827 virtual bool DeleteEntry(const wxString& key, 828 bool bDeleteGroupIfEmpty = true) = 0; 829 830 /** 831 Delete the group (with all subgroups). If the current path is under the 832 group being deleted it is changed to its deepest still existing 833 component. E.g. if the current path is @c "/A/B/C/D" and the group @c C 834 is deleted, the path becomes @c "/A/B". 835 */ 836 virtual bool DeleteGroup(const wxString& key) = 0; 837 838 //@} 839 840 841 /** 842 @name Options 843 844 Some aspects of wxConfigBase behaviour can be changed during run-time. 845 The first of them is the expansion of environment variables in the 846 string values read from the config file: for example, if you have the 847 following in your config file: 848 849 @code 850 # config file for my program 851 UserData = $HOME/data 852 853 # the following syntax is valid only under Windows 854 UserData = %windir%\\data.dat 855 @endcode 856 857 The call to Read("UserData") will return something like 858 @c "/home/zeitlin/data" on linux for example. 859 860 Although this feature is very useful, it may be annoying if you read a 861 value which contains '$' or '%' symbols (% is used for environment 862 variables expansion under Windows) which are not used for environment 863 variable expansion. In this situation you may call 864 SetExpandEnvVars(@false) just before reading this value and 865 SetExpandEnvVars(@true) just after. Another solution would be to prefix 866 the offending symbols with a backslash. 867 */ 868 //@{ 869 870 /** 871 Returns @true if we are expanding environment variables in key values. 872 */ 873 bool IsExpandingEnvVars() const; 874 875 /** 876 Returns @true if we are writing defaults back to the config file. 877 */ 878 bool IsRecordingDefaults() const; 879 880 /** 881 Determine whether we wish to expand environment variables in key 882 values. 883 */ 884 void SetExpandEnvVars(bool bDoIt = true); 885 886 /** 887 Sets whether defaults are recorded to the config file whenever an 888 attempt to read the value which is not present in it is done. 889 890 If on (default is off) all default values for the settings used by the 891 program are written back to the config file. This allows the user to 892 see what config options may be changed and is probably useful only for 893 wxFileConfig. 894 */ 895 void SetRecordDefaults(bool bDoIt = true); 896 897 //@} 898 899 900 /** 901 Create a new config object and sets it as the current one. 902 903 This function will create the most appropriate implementation of 904 wxConfig available for the current platform. By default this means that 905 the system registry will be used for storing the configuration 906 information under MSW and a file under the user home directory (see 907 wxStandardPaths::GetUserConfigDir()) elsewhere. 908 909 If you prefer to use the configuration files everywhere, you can define 910 @c wxUSE_CONFIG_NATIVE to 0 when compiling wxWidgets. Or you can simply 911 always create wxFileConfig explicitly. 912 913 Finally, if you want to create a custom wxConfig subclass you may 914 change this function behaviour by overriding wxAppTraits::CreateConfig() 915 to create it. An example when this could be useful could be an 916 application which could be installed either normally (in which case the 917 default behaviour of using wxRegConfig is appropriate) or in a 918 "portable" way in which case a wxFileConfig with a file in the program 919 directory would be used and the choice would be done in CreateConfig() 920 at run-time. 921 */ 922 static wxConfigBase* Create(); 923 924 /** 925 Calling this function will prevent @e Get() from automatically creating 926 a new config object if the current one is @NULL. It might be useful to 927 call it near the program end to prevent "accidental" creation of a new 928 config object. 929 */ 930 static void DontCreateOnDemand(); 931 932 /** 933 Get the current config object. If there is no current object and 934 @a CreateOnDemand is @true, this creates one (using Create()) unless 935 DontCreateOnDemand() was called previously. 936 */ 937 static wxConfigBase* Get(bool CreateOnDemand = true); 938 939 /** 940 Sets the config object as the current one, returns the pointer to the 941 previous current object (both the parameter and returned value may be 942 @NULL). 943 */ 944 static wxConfigBase* Set(wxConfigBase* pConfig); 945 }; 946 947 948 /** 949 @class wxConfigPathChanger 950 951 A handy little class which changes the current path in a wxConfig object and restores it in dtor. 952 Declaring a local variable of this type, it's possible to work in a specific directory 953 and ensure that the path is automatically restored when the function returns. 954 955 For example: 956 @code 957 // this function loads some settings from the given wxConfig object; 958 // the path selected inside it is left unchanged 959 bool LoadMySettings(wxConfigBase* cfg) 960 { 961 wxConfigPathChanger changer(cfg, "/Foo/Data/SomeString"); 962 wxString str; 963 if ( !config->Read("SomeString", &str) ) { 964 wxLogError("Couldn't read SomeString!"); 965 return false; 966 // NOTE: without wxConfigPathChanger it would be easy to forget to 967 // set the old path back into the wxConfig object before this return! 968 } 969 970 // do something useful with SomeString... 971 972 return true; // again: wxConfigPathChanger dtor will restore the original wxConfig path 973 } 974 @endcode 975 976 @library{wxbase} 977 @category{cfg} 978 */ 979 class wxConfigPathChanger 980 { 981 public: 982 983 /** 984 Changes the path of the given wxConfigBase object so that the key @a strEntry is accessible 985 (for read or write). 986 987 In other words, the ctor uses wxConfigBase::SetPath() with everything which precedes the 988 last slash of @a strEntry, so that: 989 @code 990 wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/SomeKeyName"); 991 @endcode 992 has the same effect of: 993 @code 994 wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/"); 995 @endcode 996 */ 997 wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry); 998 999 /** 1000 Restores the path selected, inside the wxConfig object passed to the ctor, to the path which was 1001 selected when the wxConfigPathChanger ctor was called. 1002 */ 1003 ~wxConfigPathChanger(); 1004 1005 /** 1006 Returns the name of the key which was passed to the ctor. 1007 The "name" is just anything which follows the last slash of the string given to the ctor. 1008 */ 1009 const wxString& Name() const; 1010 1011 /** 1012 This method must be called if the original path inside the wxConfig object 1013 (i.e. the current path at the moment of creation of this wxConfigPathChanger object) 1014 could have been deleted, thus preventing wxConfigPathChanger from restoring the not 1015 existing (any more) path. 1016 1017 If the original path doesn't exist any more, the path will be restored to 1018 the deepest still existing component of the old path. 1019 */ 1020 void UpdateIfDeleted(); 1021 }; 1022 1023