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