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   _APPCONF_H
  15 #define   _APPCONF_H
  16
  17 // ----------------------------------------------------------------------------
  18 // compile options
  19 // ----------------------------------------------------------------------------
  20
  21 // it won't compile without it anyhow
  22 #ifndef USE_WXCONFIG
  23   #error "Please define USE_WXCONFIG or remove config.cpp from your makefile"
  24 #endif // USE_WXCONFIG
  25
  26 // ----------------------------------------------------------------------------
  27 // constants
  28 // ----------------------------------------------------------------------------
  29
  30 /// shall we be case sensitive in parsing variable names?
  31 #ifndef APPCONF_CASE_SENSITIVE
  32   #define  APPCONF_CASE_SENSITIVE       false
  33 #endif
  34
  35 /// separates group and entry names
  36 #ifndef APPCONF_PATH_SEPARATOR
  37   #define   APPCONF_PATH_SEPARATOR     '/'
  38 #endif
  39
  40 /// introduces immutable entries
  41 #ifndef APPCONF_IMMUTABLE_PREFIX
  42   #define   APPCONF_IMMUTABLE_PREFIX   '!'
  43 #endif
  44
  45 /// should we use registry instead of configuration files under Win32?
  46 #ifndef   APPCONF_WIN32_NATIVE
  47   #define APPCONF_WIN32_NATIVE          true
  48 #endif
  49
  50 // ----------------------------------------------------------------------------
  51 // various helper global functions
  52 // ----------------------------------------------------------------------------
  53
  54 /*
  55   Replace environment variables ($SOMETHING) with their values. The format is
  56   $VARNAME or ${VARNAME} where VARNAME contains alphanumeric characters and
  57   '_' only. '$' must be escaped ('\$') in order to be taken literally.
  58  */
  59 extern wxString ExpandEnvVars(const wxString& str);
  60
  61 /*
  62   Split path into parts removing '..' in progress
  63  */
  64 extern void SplitPath(wxArrayString& aParts, const char *sz);
  65
  66 // ----------------------------------------------------------------------------
  67 // abstract base class wxConfig which defines the interface for derived classes
  68 //
  69 // wxConfig organizes the items in a tree-like structure (modeled after the
  70 // Unix/Dos filesystem). There are groups (directories) and keys (files).
  71 // There is always one current group given by the current path.
  72 //
  73 // Keys are pairs "key_name = value" where value may be of string or integer
  74 // (long) type (@@@ doubles and other types such as wxDate coming soon).
  75 // ----------------------------------------------------------------------------
  76 class wxConfig
  77 {
  78 public:
  79   // static functions
  80     // sets the config object, returns the previous pointer
  81   static wxConfig *Set(wxConfig *pConfig);
  82     // get the config object, creates it on demand
  83   static wxConfig *Get() { if ( !ms_pConfig ) Create(); return ms_pConfig; }
  84     // create a new config object
  85   static void Create();
  86
  87   // ctor & virtual dtor
  88   wxConfig() { }
  89   virtual ~wxConfig();
  90
  91   // path management
  92     // set current path: if the first character is '/', it's the absolute path,
  93     // otherwise it's a relative path. '..' is supported. If the strPath
  94     // doesn't exist it is created.
  95   virtual void SetPath(const wxString& strPath) = 0;
  96     // retrieve the current path (always as absolute path)
  97   virtual const wxString& GetPath() const = 0;
  98
  99   // enumeration: all functions here return false when there are no more items.
 100   // you must pass the same lIndex to GetNext and GetFirst (don't modify it)
 101     // enumerate subgroups
 102   virtual bool GetFirstGroup(wxString& str, long& lIndex) = 0;
 103   virtual bool GetNextGroup (wxString& str, long& lIndex) = 0;
 104     // enumerate entries
 105   virtual bool GetFirstEntry(wxString& str, long& lIndex) = 0;
 106   virtual bool GetNextEntry (wxString& str, long& lIndex) = 0;
 107
 108   // key access: returns TRUE if value was really read, FALSE if default used
 109   // (and if the key is not found the default value is returned.)
 110     // read a string from the key
 111   virtual bool Read(wxString *pStr, const char *szKey,
 112                     const char *szDefault = NULL) const = 0;
 113     // another version using statis buffer - it means it will be overwritten
 114     // after each call to this function!
 115   virtual const char *Read(const char *szKey,
 116                            const char *szDefault = NULL) const;
 117     // the same for longs
 118   long Read(const char *szKey, long lDefault) const
 119     { long l; Read(&l, szKey, lDefault); return l; }
 120     // and another version: returns true if default value is returned
 121   virtual bool Read(long *pl, const char *szKey, long lDefault = 0) const = 0;
 122
 123     // write the value (return true on success)
 124   virtual bool Write(const char *szKey, const char *szValue) = 0;
 125   virtual bool Write(const char *szKey, long lValue) = 0;
 126     // permanently writes all changes
 127   virtual bool Flush(bool bCurrentOnly = false) = 0;
 128
 129   // delete entries/groups
 130     // deletes the specified entry and the group it belongs to if
 131     // it was the last key in it and the second parameter is true
 132   virtual bool DeleteEntry(const char *szKey,
 133                            bool bDeleteGroupIfEmpty = true) = 0;
 134     // delete the group (with all subgroups)
 135   virtual bool DeleteGroup(const char *szKey) = 0;
 136     // delete the whole underlying object (disk file, registry key, ...)
 137     // primarly for use by desinstallation routine.
 138   virtual bool DeleteAll() = 0;
 139
 140 protected:
 141   static bool IsImmutable(const char *szKey)
 142     { return *szKey == APPCONF_IMMUTABLE_PREFIX; }
 143
 144   // a handy little class which changes current path to the path of given entry
 145   // and restores it in dtor: so if you declare a local variable of this type,
 146   // you work in the entry directory and the path is automatically restored
 147   // when function returns
 148   class PathChanger
 149   {
 150   public:
 151     // ctor/dtor do path changing/restorin
 152     PathChanger(const wxConfig *pContainer, const wxString& strEntry);
 153    ~PathChanger();
 154
 155     // get the key name
 156    const wxString& Name() const { return m_strName; }
 157
 158   private:
 159     wxConfig *m_pContainer;   // object we live in
 160     wxString  m_strName,      // name of entry (i.e. name only)
 161               m_strOldPath;   // saved path
 162     bool      m_bChanged;     // was the path changed?
 163   };
 164
 165   // are we doing automatic environment variable expansion?
 166   bool m_bExpandEnvVars;
 167
 168   // static variables
 169   static wxConfig *ms_pConfig;
 170 };
 171
 172 #endif  //_APPCONF_H
 173