interface/wx/config.h

   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 containts '$' 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