interface/config.h

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