include/wx/config.h

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