interface/config.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        config.h
   3 // Purpose:     documentation for wxConfigBase class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxConfigBase
  11     @wxheader{config.h}
  12
  13     wxConfigBase class defines the basic interface of all config classes. It can
  14     not be used by itself (it is an abstract base class) and you will always use one
  15     of its derivations: wxFileConfig,
  16     wxRegConfig or any other.
  17
  18     However, usually you don't even need to know the precise nature of the class
  19     you're working with but you would just use the wxConfigBase methods. This
  20     allows you to write the same code regardless of whether you're working with
  21     the registry under Win32 or text-based config files under Unix (or even
  22     Windows 3.1 .INI files if you're really unlucky). To make writing the portable
  23     code even easier, wxWidgets provides a typedef wxConfig
  24     which is mapped onto the native wxConfigBase implementation on the given
  25     platform: i.e. wxRegConfig under Win32 and
  26     wxFileConfig otherwise.
  27
  28     See @ref overview_wxconfigoverview "config overview" for the descriptions of all
  29     features of this class.
  30
  31     It is highly recommended to use static functions @e Get() and/or @e Set(),
  32     so please have a @ref overview_wxconfigstaticfunctions "look at them."
  33
  34     @library{wxbase}
  35     @category{misc}
  36 */
  37 class wxConfigBase : public wxObject
  38 {
  39 public:
  40     /**
  41         )
  42
  43         This is the default and only constructor of the wxConfigBase class, and
  44         derived classes.
  45
  46         @param appName
  47         The application name. If this is empty, the class will
  48         normally use wxApp::GetAppName to set it. The
  49         application name is used in the registry key on Windows, and can be used to
  50         deduce the local filename parameter if that is missing.
  51
  52         @param vendorName
  53         The vendor name. If this is empty, it is assumed that
  54         no vendor name is wanted, if this is optional for the current config class.
  55         The vendor name is appended to the application name for wxRegConfig.
  56
  57         @param localFilename
  58         Some config classes require a local filename. If this
  59         is not present, but required, the application name will be used instead.
  60
  61         @param globalFilename
  62         Some config classes require a global filename. If
  63         this is not present, but required, the application name will be used instead.
  64
  65         @param style
  66         Can be one of wxCONFIG_USE_LOCAL_FILE and
  67         wxCONFIG_USE_GLOBAL_FILE. The style interpretation depends on the config
  68         class and is ignored by some implementations. For wxFileConfig, these styles
  69         determine whether a local or global config file is created or used: if
  70         wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the global
  71         config file and if wxCONFIG_USE_LOCAL_FILE is used, settings are read from
  72         and written to local config file (if they are both set, global file is read
  73         first, then local file, overwriting global settings). If the
  74         flag is present but the parameter is empty, the parameter will be set to a
  75         default. If the parameter is present but the style flag not, the relevant flag
  76         will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM
  77         key while LOCAL one is for the usual HKCU one.
  78
  79         For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by logically
  80         or'ing it to either of the _FILE options to tell wxFileConfig to use relative
  81         instead of absolute paths.
  82
  83         On non-VMS Unix systems, the default local configuration file is ~/.appname.
  84         However, this path may be also used as user data directory
  85         (see wxStandardPaths::GetUserDataDir) if
  86         the application has several data files. In this case wxCONFIG_USE_SUBDIR
  87         flag, which changes the default local configuration file to ~/.appname/appname
  88         should be used. Notice that this flag is ignored if localFilename is
  89         provided. This function is new since wxWidgets version 2.8.2
  90
  91         For wxFileConfig, you can also add wxCONFIG_USE_NO_ESCAPE_CHARACTERS which
  92         will turn off character escaping for the values of entries stored in the config
  93         file: for example a foo key with some backslash characters will be stored
  94         as foo=C:\mydir instead of the usual storage of
  95         foo=C:\\mydir.
  96
  97         The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your config
  98         file must be read or written to by a non-wxWidgets program (which might not
  99         understand the escape characters). Note, however, that if
 100         wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is now
 101         your application's responsibility to ensure that there is no newline or
 102         other illegal characters in a value, before writing that value to the file.
 103
 104         @param conv
 105         This parameter is only used by wxFileConfig when compiled
 106         in Unicode mode. It specifies the encoding in which the configuration file
 107         is written.
 108
 109         @remarks By default, environment variable expansion is on and recording
 110                    defaults is off.
 111     */
 112     wxConfigBase(const wxString& appName = wxEmptyString,
 113                  const wxString& vendorName = wxEmptyString,
 114                  const wxString& localFilename = wxEmptyString,
 115                  const wxString& globalFilename = wxEmptyString,
 116                  long style = 0);
 117
 118     /**
 119         Empty but ensures that dtor of all derived classes is virtual.
 120     */
 121     ~wxConfigBase();
 122
 123     /**
 124         @ref ctor() wxConfigBase
 125
 126         @ref dtor() ~wxConfigBase
 127     */
 128
 129
 130     /**
 131         Create a new config object: this function will create the "best"
 132         implementation of wxConfig available for the current platform, see comments
 133         near the definition of wxCONFIG_WIN32_NATIVE for details. It returns the
 134         created object and also sets it as the current one.
 135     */
 136     static wxConfigBase * Create();
 137
 138     /**
 139         The functions in this section delete entries and/or groups of entries from the
 140         config file. @e DeleteAll() is especially useful if you want to erase all
 141         traces of your program presence: for example, when you uninstall it.
 142
 143         DeleteEntry()
 144
 145         DeleteGroup()
 146
 147         DeleteAll()
 148     */
 149
 150
 151     /**
 152         Delete the whole underlying object (disk file, registry key, ...). Primarly
 153         for use by uninstallation routine.
 154     */
 155     bool DeleteAll();
 156
 157     /**
 158         Deletes the specified entry and the group it belongs to if it was the last key
 159         in it and the second parameter is @true.
 160     */
 161     bool DeleteEntry(const wxString& key,
 162                      bool bDeleteGroupIfEmpty = @true);
 163
 164     /**
 165         Delete the group (with all subgroups). If the current path is under the group
 166         being deleted it is changed to its deepest still existing component. E.g. if
 167         the current path is @c /A/B/C/D and the group @c C is deleted the
 168         path becomes @c /A/B.
 169     */
 170     bool DeleteGroup(const wxString& key);
 171
 172     /**
 173         Calling this function will prevent @e Get() from automatically creating a
 174         new config object if the current one is @NULL. It might be useful to call it
 175         near the program end to prevent "accidental" creation of a new config object.
 176     */
 177     void DontCreateOnDemand();
 178
 179     /**
 180         The functions in this section allow to enumerate all entries and groups in the
 181         config file. All functions here return @false when there are no more items.
 182
 183         You must pass the same index to GetNext and GetFirst (don't modify it).
 184         Please note that it is @b not the index of the current item (you will have
 185         some great surprises with wxRegConfig if you assume this) and you shouldn't
 186         even look at it: it is just a "cookie" which stores the state of the
 187         enumeration. It can't be stored inside the class because it would prevent you
 188         from running several enumerations simultaneously, that's why you must pass it
 189         explicitly.
 190
 191         Having said all this, enumerating the config entries/groups is very simple:
 192         There are also functions to get the number of entries/subgroups without
 193         actually enumerating them, but you will probably never need them.
 194
 195         GetFirstGroup()
 196
 197         GetNextGroup()
 198
 199         GetFirstEntry()
 200
 201         GetNextEntry()
 202
 203         GetNumberOfEntries()
 204
 205         GetNumberOfGroups()
 206     */
 207
 208
 209     /**
 210         returns @true if either a group or an entry with a given name exists
 211     */
 212     bool Exists(wxString& strName);
 213
 214     /**
 215         permanently writes all changes (otherwise, they're only written from object's
 216         destructor)
 217     */
 218     bool Flush(bool bCurrentOnly = @false);
 219
 220     /**
 221         Get the current config object. If there is no current object and
 222         @e CreateOnDemand is @true, creates one
 223         (using @e Create) unless DontCreateOnDemand was called previously.
 224     */
 225 #define static wxConfigBase * Get(bool CreateOnDemand = @true)     /* implementation is private */
 226
 227     /**
 228         Returns the application name.
 229     */
 230     wxString GetAppName();
 231
 232     /**
 233         Returns the type of the given entry or @e Unknown if the entry doesn't
 234         exist. This function should be used to decide which version of Read() should
 235         be used because some of wxConfig implementations will complain about type
 236         mismatch otherwise: e.g., an attempt to read a string value from an integer
 237         key with wxRegConfig will fail.
 238
 239         The result is an element of enum EntryType:
 240     */
 241     enum wxConfigBase::EntryType GetEntryType(const wxString& name);
 242
 243     /**
 244         Gets the first entry.
 245     */
 246     bool GetFirstEntry(wxString& str, long& index);
 247
 248     /**
 249         Gets the first group.
 250     */
 251     bool GetFirstGroup(wxString& str, long& index);
 252
 253     /**
 254         Gets the next entry.
 255     */
 256     bool GetNextEntry(wxString& str, long& index);
 257
 258     /**
 259         Gets the next group.
 260     */
 261     bool GetNextGroup(wxString& str, long& index);
 262
 263     /**
 264
 265     */
 266     uint GetNumberOfEntries(bool bRecursive = @false);
 267
 268     /**
 269         Get number of entries/subgroups in the current group, with or without its
 270         subgroups.
 271     */
 272     uint GetNumberOfGroups(bool bRecursive = @false);
 273
 274     /**
 275         Retrieve the current path (always as absolute path).
 276     */
 277     const wxString GetPath();
 278
 279     /**
 280         Returns the vendor name.
 281     */
 282     wxString GetVendorName();
 283
 284     /**
 285         returns @true if the entry by this name exists
 286     */
 287     bool HasEntry(wxString& strName);
 288
 289     /**
 290         returns @true if the group by this name exists
 291     */
 292     bool HasGroup(const wxString& strName);
 293
 294     /**
 295         Returns @true if we are expanding environment variables in key values.
 296     */
 297     bool IsExpandingEnvVars();
 298
 299     /**
 300         Returns @true if we are writing defaults back to the config file.
 301     */
 302     bool IsRecordingDefaults();
 303
 304     /**
 305         These function are the core of wxConfigBase class: they allow you to read and
 306         write config file data. All @e Read function take a default value which
 307         will be returned if the specified key is not found in the config file.
 308
 309         Currently, supported types of data are:
 310         wxString, @e long, @e double, @e bool,
 311         wxColour and any other types,
 312         for which functions wxToString
 313         and wxFromString are defined.
 314
 315         Try not to read long values into string variables and vice versa: although it
 316         just might work with wxFileConfig, you will get a system error with
 317         wxRegConfig because in the Windows registry the different types of entries are
 318         indeed used.
 319
 320         Final remark: the @e szKey parameter for all these functions can contain an
 321         arbitrary path (either relative or absolute), not just the key name.
 322
 323         Read()
 324
 325         Write()
 326
 327         Flush()
 328     */
 329
 330
 331     /**
 332         GetAppName()
 333
 334         GetVendorName()
 335
 336         wxFileConfig::SetUmask
 337     */
 338
 339
 340     /**
 341         Some aspects of wxConfigBase behaviour can be changed during run-time. The
 342         first of them is the expansion of environment variables in the string values
 343         read from the config file: for example, if you have the following in your
 344         config file:
 345         the call to @c config-Read("UserData") will return something like
 346         @c "/home/zeitlin/data" if you're lucky enough to run a Linux system ;-)
 347
 348         Although this feature is very useful, it may be annoying if you read a value
 349         which containts '$' or '%' symbols (% is used for environment variables
 350         expansion under Windows) which are not used for environment variable
 351         expansion. In this situation you may call SetExpandEnvVars(@false) just before
 352         reading this value and SetExpandEnvVars(@true) just after. Another solution
 353         would be to prefix the offending symbols with a backslash.
 354
 355         The following functions control this option:
 356
 357         IsExpandingEnvVars()
 358
 359         SetExpandEnvVars()
 360
 361         SetRecordDefaults()
 362
 363         IsRecordingDefaults()
 364     */
 365
 366
 367     /**
 368         As explained in @ref overview_wxconfigoverview "config overview", the config
 369         classes
 370         support a file system-like hierarchy of keys (files) and groups (directories).
 371         As in the file system case, to specify a key in the config class you must use
 372         a path to it. Config classes also support the notion of the current group,
 373         which makes it possible to use the relative paths. To clarify all this, here
 374         is an example (it is only for the sake of demonstration, it doesn't do anything
 375         sensible!):
 376         @e Warning: it is probably a good idea to always restore the path to its
 377         old value on function exit:
 378         because otherwise the assert in the following example will surely fail
 379         (we suppose here that @e foo() function is the same as above except that it
 380         doesn't save and restore the path):
 381         Finally, the path separator in wxConfigBase and derived classes is always '/',
 382         regardless of the platform (i.e. it is @b not '\\' under Windows).
 383
 384         SetPath()
 385
 386         GetPath()
 387     */
 388
 389
 390     //@{
 391     /**
 392         Reads a value of type T, for which function
 393         wxFromString is defined,
 394         returning @true if the value was found.
 395         If the value was not found, @e defaultVal is used instead.
 396
 397         bool Read(const wxStringkey, T* value) const;
 398
 399
 400
 401         @b Read(key, default="")
 402
 403
 404         Returns a string
 405
 406         @b ReadInt(key, default=0)
 407
 408
 409         Returns an integer
 410
 411         @b ReadFloat(key, default=0.0)
 412
 413
 414         Returns a floating point number
 415
 416         @b ReadBool(key, default=0)
 417
 418
 419         Returns a boolean
 420     */
 421     bool Read(const wxString& key, wxString* str);
 422         bool Read(const wxString& key, wxString* str,
 423                   const wxString& defaultVal);
 424         wxString Read(const wxString& key,
 425                       const
 426 wxString& defaultVal);
 427         bool Read(const wxString& key, long* l);
 428         bool Read(const wxString& key, long* l, long defaultVal);
 429         bool Read(const wxString& key, double* d);
 430         bool Read(const wxString& key, double* d, double defaultVal);
 431         bool Read(const wxString& key, bool* b);
 432         bool Read(const wxString& key, bool* d, bool defaultVal);
 433         bool Read(const wxString& key, wxMemoryBuffer* buf);
 434         bool Read(const wxString& key, T* value);
 435         bool Read(const wxString& key, T* value,
 436                   T const& defaultVal);
 437     //@}
 438
 439     /**
 440         Reads a bool value from the key and returns it. @e defaultVal is returned
 441         if the key is not found.
 442     */
 443     long ReadBool(const wxString& key, bool defaultVal);
 444
 445     /**
 446         Reads a double value from the key and returns it. @e defaultVal is returned
 447         if the key is not found.
 448     */
 449     long ReadDouble(const wxString& key, double defaultVal);
 450
 451     /**
 452         Reads a long value from the key and returns it. @e defaultVal is returned
 453         if the key is not found.
 454     */
 455     long ReadLong(const wxString& key, long defaultVal);
 456
 457     /**
 458         Reads a value of type T, for which function
 459         wxFromString is defined, from the key and returns it.
 460         @e defaultVal is returned if the key is not found.
 461     */
 462     T ReadObject(const wxString& key, T const& defaultVal);
 463
 464     /**
 465         The functions in this section allow to rename entries or subgroups of the
 466         current group. They will return @false on error. typically because either the
 467         entry/group with the original name doesn't exist, because the entry/group with
 468         the new name already exists or because the function is not supported in this
 469         wxConfig implementation.
 470
 471         RenameEntry()
 472
 473         RenameGroup()
 474     */
 475
 476
 477     /**
 478         Renames an entry in the current group. The entries names (both the old and
 479         the new one) shouldn't contain backslashes, i.e. only simple names and not
 480         arbitrary paths are accepted by this function.
 481
 482         Returns @false if @e oldName doesn't exist or if @e newName already
 483         exists.
 484     */
 485     bool RenameEntry(const wxString& oldName,
 486                      const wxString& newName);
 487
 488     /**
 489         Renames a subgroup of the current group. The subgroup names (both the old and
 490         the new one) shouldn't contain backslashes, i.e. only simple names and not
 491         arbitrary paths are accepted by this function.
 492
 493         Returns @false if @e oldName doesn't exist or if @e newName already
 494         exists.
 495     */
 496     bool RenameGroup(const wxString& oldName,
 497                      const wxString& newName);
 498
 499     /**
 500         Sets the config object as the current one, returns the pointer to the previous
 501         current object (both the parameter and returned value may be @NULL)
 502     */
 503 #define static wxConfigBase * Set(wxConfigBase * pConfig)     /* implementation is private */
 504
 505     /**
 506         Determine whether we wish to expand environment variables in key values.
 507     */
 508     void SetExpandEnvVars(bool bDoIt = @true);
 509
 510     /**
 511         Set current path: if the first character is '/', it is the absolute path,
 512         otherwise it is a relative path. '..' is supported. If strPath doesn't
 513         exist it is created.
 514     */
 515     void SetPath(const wxString& strPath);
 516
 517     /**
 518         Sets whether defaults are recorded to the config file whenever an attempt to
 519         read the value which is not present in it is done.
 520
 521         If on (default is off) all default values for the settings used by the program
 522         are written back to the config file. This allows the user to see what config
 523         options may be changed and is probably useful only for wxFileConfig.
 524     */
 525     void SetRecordDefaults(bool bDoIt = @true);
 526
 527     /**
 528         These functions deal with the "default" config object. Although its usage is
 529         not at all mandatory it may be convenient to use a global config object
 530         instead of creating and deleting the local config objects each time you need
 531         one (especially because creating a wxFileConfig object might be a time
 532         consuming operation). In this case, you may create this global config object
 533         in the very start of the program and @e Set() it as the default. Then, from
 534         anywhere in your program, you may access it using the @e Get() function.
 535         This global wxConfig object will be deleted by wxWidgets automatically if it
 536         exists. Note that this implies that if you do delete this object yourself
 537         (usually in wxApp::OnExit) you must use @e Set(@NULL)
 538         to prevent wxWidgets from deleting it the second time.
 539
 540         As it happens, you may even further simplify the procedure described above:
 541         you may forget about calling @e Set(). When @e Get() is called and there
 542         is no current object, it will create one using @e Create() function. To
 543         disable this behaviour @e DontCreateOnDemand() is provided.
 544
 545         @b Note: You should use either @e Set() or @e Get() because wxWidgets
 546         library itself would take advantage of it and could save various information
 547         in it. For example wxFontMapper or Unix version
 548         of wxFileDialog have the ability to use wxConfig class.
 549
 550         Set()
 551
 552         Get()
 553
 554         Create()
 555
 556         DontCreateOnDemand()
 557     */
 558
 559
 560     /**
 561         HasGroup()
 562
 563         HasEntry()
 564
 565         Exists()
 566
 567         GetEntryType()
 568     */
 569
 570
 571     //@{
 572     /**
 573         These functions write the specified value to the config file and return @true
 574         on success. In the last one, function wxToString must be
 575         defined for type @e T.
 576
 577
 578
 579         @b Write(key, value)
 580
 581
 582         Writes a string
 583
 584         @b WriteInt(key, value)
 585
 586
 587         Writes an integer
 588
 589         @b WriteFloat(key, value)
 590
 591
 592         Writes a floating point number
 593
 594         @b WriteBool(key, value)
 595
 596
 597         Writes a boolean
 598     */
 599     bool Write(const wxString& key, const wxString& value);
 600         bool Write(const wxString& key, long value);
 601         bool Write(const wxString& key, double value);
 602         bool Write(const wxString& key, bool value);
 603         bool Write(const wxString& key, const wxMemoryBuffer& buf);
 604         bool Write(const wxString& key, const T& buf);
 605     //@}
 606 };