include/wx/config.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        config.h
   3 // Purpose:     declaration of the base class of all config implementations
   4 //              (see also: fileconf.h and msw/regconf.h)
   5 // Author:      Karsten Ballüder & Vadim Zeitlin
   6 // Modified by:
   7 // Created:     07.04.98 (adapted from appconf.h)
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 1997 Karsten Ballüder   Ballueder@usa.net
  10 //                       Vadim Zeitlin      <zeitlin@dptmaths.ens-cachan.fr>
  11 // Licence:     wxWindows license
  12 ///////////////////////////////////////////////////////////////////////////////
  13
  14 #ifndef   _wxCONFIG_H
  15 #define   _wxCONFIG_H
  16
  17 #ifdef __GNUG__
  18 #pragma interface "config.h"
  19 #endif
  20
  21 // ----------------------------------------------------------------------------
  22 // compile options
  23 // ----------------------------------------------------------------------------
  24
  25 // it won't compile without it anyhow
  26 #ifndef USE_WXCONFIG
  27   #error "Please define USE_WXCONFIG or remove config.cpp from your makefile"
  28 #endif // USE_WXCONFIG
  29
  30 // ----------------------------------------------------------------------------
  31 // constants
  32 // ----------------------------------------------------------------------------
  33
  34 /// shall we be case sensitive in parsing variable names?
  35 #ifndef wxCONFIG_CASE_SENSITIVE
  36   #define  wxCONFIG_CASE_SENSITIVE       FALSE
  37 #endif
  38
  39 /// separates group and entry names (probably shouldn't be changed)
  40 #ifndef wxCONFIG_PATH_SEPARATOR
  41   #define   wxCONFIG_PATH_SEPARATOR     '/'
  42 #endif
  43
  44 /// introduces immutable entries
  45 // (i.e. the ones which can't be changed from the local config file)
  46 #ifndef wxCONFIG_IMMUTABLE_PREFIX
  47   #define   wxCONFIG_IMMUTABLE_PREFIX   '!'
  48 #endif
  49
  50 /// should we use registry instead of configuration files under Win32?
  51 // (i.e. whether wxConfig::Create() will create a wxFileConfig (if it's FALSE) or
  52 // wxRegConfig (if it's true and we're under Win32) or wxIniConfig (Win16))
  53 #ifndef   wxCONFIG_WIN32_NATIVE
  54   #define wxCONFIG_WIN32_NATIVE          TRUE
  55 #endif
  56
  57 // ----------------------------------------------------------------------------
  58 // various helper global functions
  59 // ----------------------------------------------------------------------------
  60
  61 /*
  62   Replace environment variables ($SOMETHING) with their values. The format is
  63   $VARNAME or ${VARNAME} where VARNAME contains alphanumeric characters and
  64   '_' only. '$' must be escaped ('\$') in order to be taken literally.
  65  */
  66 extern wxString wxExpandEnvVars(const wxString &sz);
  67
  68 /*
  69   Split path into parts removing '..' in progress
  70  */
  71 extern void wxSplitPath(wxArrayString& aParts, const char *sz);
  72
  73 // ----------------------------------------------------------------------------
  74 // abstract base class wxConfig which defines the interface for derived classes
  75 //
  76 // wxConfig organizes the items in a tree-like structure (modeled after the
  77 // Unix/Dos filesystem). There are groups (directories) and keys (files).
  78 // There is always one current group given by the current path.
  79 //
  80 // Keys are pairs "key_name = value" where value may be of string or integer
  81 // (long) type (@@@ doubles and other types such as wxDate coming soon).
  82 // ----------------------------------------------------------------------------
  83 class wxConfig
  84 {
  85 public:
  86   // static functions
  87     // sets the config object, returns the previous pointer
  88   static wxConfig *Set(wxConfig *pConfig);
  89     // get the config object, creates it on demand
  90   static wxConfig *Get() { if ( !ms_pConfig ) Create(); return ms_pConfig; }
  91     // create a new config object: this function will create the "best"
  92     // implementation of wxConfig available for the current platform, see
  93     // comments near definition wxCONFIG_WIN32_NATIVE for details. It returns
  94     // the created object and also sets it as ms_pConfig.
  95   static wxConfig *Create();
  96
  97   // ctor & virtual dtor
  98     // environment variable expansion is on by default
  99   wxConfig() { m_bExpandEnvVars = TRUE; }
 100     // empty but ensures that dtor of all derived classes is virtual
 101   virtual ~wxConfig() { }
 102
 103   // path management
 104     // set current path: if the first character is '/', it's the absolute path,
 105     // otherwise it's a relative path. '..' is supported. If the strPath
 106     // doesn't exist it is created.
 107   virtual void SetPath(const wxString& strPath) = 0;
 108     // retrieve the current path (always as absolute path)
 109   virtual const wxString& GetPath() const = 0;
 110
 111   // enumeration: all functions here return false when there are no more items.
 112   // you must pass the same lIndex to GetNext and GetFirst (don't modify it)
 113     // enumerate subgroups
 114   virtual bool GetFirstGroup(wxString& str, long& lIndex) = 0;
 115   virtual bool GetNextGroup (wxString& str, long& lIndex) = 0;
 116     // enumerate entries
 117   virtual bool GetFirstEntry(wxString& str, long& lIndex) = 0;
 118   virtual bool GetNextEntry (wxString& str, long& lIndex) = 0;
 119     // get number of entries/subgroups in the current group, with or without
 120     // it's subgroups
 121   virtual uint GetNumberOfEntries(bool bRecursive = FALSE) const = 0;
 122   virtual uint GetNumberOfGroups(bool bRecursive = FALSE) const = 0;
 123
 124   // tests of existence
 125     // returns TRUE if the group by this name exists
 126   virtual bool HasGroup(const wxString& strName) const = 0;
 127     // same as above, but for an entry
 128   virtual bool HasEntry(const wxString& strName) const = 0;
 129     // returns TRUE if either a group or an entry with a given name exist
 130   bool Exists(const wxString& strName) const
 131     { return HasGroup(strName) || HasEntry(strName); }
 132
 133   // key access: returns TRUE if value was really read, FALSE if default used
 134   // (and if the key is not found the default value is returned.)
 135     // read a string from the key
 136   virtual bool Read(wxString *pStr, const char *szKey,
 137                     const char *szDefault = NULL) const = 0;
 138     // another version using statis buffer - it means it will be overwritten
 139     // after each call to this function!
 140   virtual const char *Read(const char *szKey,
 141                            const char *szDefault = NULL) const;
 142     // the same for longs
 143   virtual long Read(const char *szKey, long lDefault) const
 144     { long l; Read(&l, szKey, lDefault); return l; }
 145     // and another version: returns true if default value is returned
 146   virtual bool Read(long *pl, const char *szKey, long lDefault = 0) const = 0;
 147
 148     // write the value (return true on success)
 149   virtual bool Write(const char *szKey, const char *szValue) = 0;
 150   virtual bool Write(const char *szKey, long lValue) = 0;
 151     // permanently writes all changes
 152   virtual bool Flush(bool bCurrentOnly = FALSE) = 0;
 153
 154   // delete entries/groups
 155     // deletes the specified entry and the group it belongs to if
 156     // it was the last key in it and the second parameter is true
 157   virtual bool DeleteEntry(const char *szKey,
 158                            bool bDeleteGroupIfEmpty = TRUE) = 0;
 159     // delete the group (with all subgroups)
 160   virtual bool DeleteGroup(const char *szKey) = 0;
 161     // delete the whole underlying object (disk file, registry key, ...)
 162     // primarly for use by desinstallation routine.
 163   virtual bool DeleteAll() = 0;
 164
 165   // options
 166     // we can automatically expand environment variables in the config entries
 167     // (this option is on by default, you can turn it on/off at any time)
 168   bool IsExpandingEnvVars() const { return m_bExpandEnvVars; }
 169   void SetExpandEnvVars(bool bDoIt = TRUE) { m_bExpandEnvVars = bDoIt; }
 170     // does expansion only if needed
 171   wxString ExpandEnvVars(const wxString& str) const
 172     {
 173         wxString tmp; // Required for BC++
 174         if (IsExpandingEnvVars())
 175             tmp = wxExpandEnvVars(str);
 176         else
 177             tmp = str;
 178         return tmp;
 179     }
 180
 181 protected:
 182   static bool IsImmutable(const char *szKey)
 183     { return *szKey == wxCONFIG_IMMUTABLE_PREFIX; }
 184
 185   // a handy little class which changes current path to the path of given entry
 186   // and restores it in dtor: so if you declare a local variable of this type,
 187   // you work in the entry directory and the path is automatically restored
 188   // when the function returns
 189   class PathChanger
 190   {
 191   public:
 192     // ctor/dtor do path changing/restorin
 193     PathChanger(const wxConfig *pContainer, const wxString& strEntry);
 194    ~PathChanger();
 195
 196     // get the key name
 197     const wxString& Name() const { return m_strName; }
 198
 199   private:
 200     wxConfig *m_pContainer;   // object we live in
 201     wxString  m_strName,      // name of entry (i.e. name only)
 202               m_strOldPath;   // saved path
 203     bool      m_bChanged;     // was the path changed?
 204   };
 205
 206 private:
 207   // are we doing automatic environment variable expansion?
 208   bool m_bExpandEnvVars;
 209
 210   // static variables
 211   static wxConfig *ms_pConfig;
 212 };
 213
 214 #endif  //_wxCONFIG_H
 215