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