home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / include / wx / confbase.h < prev    next >
C/C++ Source or Header  |  2002-08-31  |  14KB  |  350 lines
  1. ///////////////////////////////////////////////////////////////////////////////
  2. // Name:        confbase.h
  3. // Purpose:     declaration of the base class of all config implementations
  4. //              (see also: fileconf.h and msw/regconf.h and iniconf.h)
  5. // Author:      Karsten Ballⁿder & Vadim Zeitlin
  6. // Modified by:
  7. // Created:     07.04.98 (adapted from appconf.h)
  8. // RCS-ID:      $Id: confbase.h,v 1.39 2002/08/31 11:29:09 GD Exp $
  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   _WX_CONFBASE_H_
  15. #define   _WX_CONFBASE_H_
  16.  
  17. #if defined(__GNUG__) && !defined(__APPLE__)
  18. #pragma interface "confbase.h"
  19. #endif
  20.  
  21. #include "wx/defs.h"
  22. #include "wx/string.h"
  23.  
  24. // ----------------------------------------------------------------------------
  25. // constants
  26. // ----------------------------------------------------------------------------
  27.  
  28. /// shall we be case sensitive in parsing variable names?
  29. #ifndef wxCONFIG_CASE_SENSITIVE
  30.   #define  wxCONFIG_CASE_SENSITIVE       0
  31. #endif
  32.  
  33. /// separates group and entry names (probably shouldn't be changed)
  34. #ifndef wxCONFIG_PATH_SEPARATOR
  35.   #define   wxCONFIG_PATH_SEPARATOR     _T('/')
  36. #endif
  37.  
  38. /// introduces immutable entries
  39. // (i.e. the ones which can't be changed from the local config file)
  40. #ifndef wxCONFIG_IMMUTABLE_PREFIX
  41.   #define   wxCONFIG_IMMUTABLE_PREFIX   _T('!')
  42. #endif
  43.  
  44. #if wxUSE_CONFIG
  45.  
  46. #include "wx/string.h"
  47.  
  48. /// should we use registry instead of configuration files under Windows?
  49. // (i.e. whether wxConfigBase::Create() will create a wxFileConfig (if it's
  50. //  FALSE) or wxRegConfig (if it's true and we're under Win32) or wxIniConfig
  51. //  (under Win16))
  52. #ifndef   wxUSE_CONFIG_NATIVE
  53.   #define wxUSE_CONFIG_NATIVE 1
  54. #endif
  55.  
  56. // Style flags for constructor style parameter
  57. enum
  58. {
  59.     wxCONFIG_USE_LOCAL_FILE = 1,
  60.     wxCONFIG_USE_GLOBAL_FILE = 2,
  61.     wxCONFIG_USE_RELATIVE_PATH = 4,
  62.     wxCONFIG_USE_NO_ESCAPE_CHARACTERS = 8
  63. };
  64.  
  65. // ----------------------------------------------------------------------------
  66. // abstract base class wxConfigBase which defines the interface for derived
  67. // 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 (TODO doubles and other types such as wxDate coming soon).
  75. // ----------------------------------------------------------------------------
  76. class WXDLLEXPORT wxConfigBase
  77. {
  78. public:
  79.   // constants
  80.     // the type of an entry
  81.   enum EntryType
  82.   {
  83.     Type_Unknown,
  84.     Type_String,
  85.     Type_Boolean,
  86.     Type_Integer,    // use Read(long *)
  87.     Type_Float       // use Read(double *)
  88.   };
  89.  
  90.   // static functions
  91.     // sets the config object, returns the previous pointer
  92.   static wxConfigBase *Set(wxConfigBase *pConfig);
  93.     // get the config object, creates it on demand unless DontCreateOnDemand
  94.     // was called
  95.   static wxConfigBase *Get(bool createOnDemand = TRUE) 
  96.        { if ( createOnDemand && (!ms_pConfig) ) Create(); return ms_pConfig; }
  97.     // create a new config object: this function will create the "best"
  98.     // implementation of wxConfig available for the current platform, see
  99.     // comments near definition wxUSE_CONFIG_NATIVE for details. It returns
  100.     // the created object and also sets it as ms_pConfig.
  101.   static wxConfigBase *Create();
  102.     // should Get() try to create a new log object if the current one is NULL?
  103.   static void DontCreateOnDemand() { ms_bAutoCreate = FALSE; }
  104.  
  105.   // ctor & virtual dtor
  106.       // ctor (can be used as default ctor too)
  107.       //
  108.       // Not all args will always be used by derived classes, but including
  109.       // them all in each class ensures compatibility. If appName is empty,
  110.       // uses wxApp name
  111.   wxConfigBase(const wxString& appName = wxEmptyString,
  112.                const wxString& vendorName = wxEmptyString,
  113.                const wxString& localFilename = wxEmptyString,
  114.                const wxString& globalFilename = wxEmptyString,
  115.                long style = 0);
  116.  
  117.     // empty but ensures that dtor of all derived classes is virtual
  118.   virtual ~wxConfigBase();
  119.  
  120.   // path management
  121.     // set current path: if the first character is '/', it's the absolute path,
  122.     // otherwise it's a relative path. '..' is supported. If the strPath
  123.     // doesn't exist it is created.
  124.   virtual void SetPath(const wxString& strPath) = 0;
  125.     // retrieve the current path (always as absolute path)
  126.   virtual const wxString& GetPath() const = 0;
  127.  
  128.   // enumeration: all functions here return false when there are no more items.
  129.   // you must pass the same lIndex to GetNext and GetFirst (don't modify it)
  130.     // enumerate subgroups
  131.   virtual bool GetFirstGroup(wxString& str, long& lIndex) const = 0;
  132.   virtual bool GetNextGroup (wxString& str, long& lIndex) const = 0;
  133.     // enumerate entries
  134.   virtual bool GetFirstEntry(wxString& str, long& lIndex) const = 0;
  135.   virtual bool GetNextEntry (wxString& str, long& lIndex) const = 0;
  136.     // get number of entries/subgroups in the current group, with or without
  137.     // it's subgroups
  138.   virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const = 0;
  139.   virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const = 0;
  140.  
  141.   // tests of existence
  142.     // returns TRUE if the group by this name exists
  143.   virtual bool HasGroup(const wxString& strName) const = 0;
  144.     // same as above, but for an entry
  145.   virtual bool HasEntry(const wxString& strName) const = 0;
  146.     // returns TRUE if either a group or an entry with a given name exist
  147.   bool Exists(const wxString& strName) const
  148.     { return HasGroup(strName) || HasEntry(strName); }
  149.  
  150.     // get the entry type
  151.   virtual EntryType GetEntryType(const wxString& name) const
  152.   {
  153.     // by default all entries are strings
  154.     return HasEntry(name) ? Type_String : Type_Unknown;
  155.   }
  156.  
  157.   // key access: returns TRUE if value was really read, FALSE if default used
  158.   // (and if the key is not found the default value is returned.)
  159.  
  160.     // read a string from the key
  161.   bool Read(const wxString& key, wxString *pStr) const;
  162.   bool Read(const wxString& key, wxString *pStr, const wxString& defVal) const;
  163.  
  164.     // read a number (long)
  165.   bool Read(const wxString& key, long *pl) const;
  166.   bool Read(const wxString& key, long *pl, long defVal) const;
  167.  
  168.     // read an int
  169.   bool Read(const wxString& key, int *pi) const;
  170.   bool Read(const wxString& key, int *pi, int defVal) const;
  171.  
  172.     // read a double
  173.   bool Read(const wxString& key, double* val) const;
  174.   bool Read(const wxString& key, double* val, double defVal) const;
  175.  
  176.     // read a bool
  177.   bool Read(const wxString& key, bool* val) const;
  178.   bool Read(const wxString& key, bool* val, bool defVal) const;
  179.  
  180.   // convenience functions returning directly the value (we don't have them for
  181.   // int/double/bool as there would be ambiguities with the long one then)
  182.   wxString Read(const wxString& key,
  183.                 const wxString& defVal = wxEmptyString) const
  184.     { wxString s; (void)Read(key, &s, defVal); return s; }
  185.  
  186.   long Read(const wxString& key, long defVal) const
  187.     { long l; (void)Read(key, &l, defVal); return l; }
  188.  
  189.     // write the value (return true on success)
  190.   bool Write(const wxString& key, const wxString& value)
  191.     { return DoWriteString(key, value); }
  192.  
  193.   bool Write(const wxString& key, long value)
  194.     { return DoWriteLong(key, value); }
  195.  
  196.   bool Write(const wxString& key, int value)
  197.     { return DoWriteInt(key, value); }
  198.  
  199.   bool Write(const wxString& key, double value)
  200.     { return DoWriteDouble(key, value); }
  201.  
  202.   bool Write(const wxString& key, bool value)
  203.     { return DoWriteBool(key, value); }
  204.  
  205.   // we have to provide a separate version for C strings as otherwise they
  206.   // would be converted to bool and not to wxString as expected!
  207.   bool Write(const wxString& key, const wxChar *value)
  208.     { return Write(key, wxString(value)); }
  209.  
  210.   // permanently writes all changes
  211.   virtual bool Flush(bool bCurrentOnly = FALSE) = 0;
  212.  
  213.   // renaming, all functions return FALSE on failure (probably because the new
  214.   // name is already taken by an existing entry)
  215.     // rename an entry
  216.   virtual bool RenameEntry(const wxString& oldName,
  217.                            const wxString& newName) = 0;
  218.     // rename a group
  219.   virtual bool RenameGroup(const wxString& oldName,
  220.                            const wxString& newName) = 0;
  221.  
  222.   // delete entries/groups
  223.     // deletes the specified entry and the group it belongs to if
  224.     // it was the last key in it and the second parameter is true
  225.   virtual bool DeleteEntry(const wxString& key,
  226.                            bool bDeleteGroupIfEmpty = TRUE) = 0;
  227.     // delete the group (with all subgroups)
  228.   virtual bool DeleteGroup(const wxString& key) = 0;
  229.     // delete the whole underlying object (disk file, registry key, ...)
  230.     // primarly for use by desinstallation routine.
  231.   virtual bool DeleteAll() = 0;
  232.  
  233.   // options
  234.     // we can automatically expand environment variables in the config entries
  235.     // (this option is on by default, you can turn it on/off at any time)
  236.   bool IsExpandingEnvVars() const { return m_bExpandEnvVars; }
  237.   void SetExpandEnvVars(bool bDoIt = TRUE) { m_bExpandEnvVars = bDoIt; }
  238.     // recording of default values
  239.   void SetRecordDefaults(bool bDoIt = TRUE) { m_bRecordDefaults = bDoIt; }
  240.   bool IsRecordingDefaults() const { return m_bRecordDefaults; }
  241.   // does expansion only if needed
  242.   wxString ExpandEnvVars(const wxString& str) const;
  243.  
  244.     // misc accessors
  245.   wxString GetAppName() const { return m_appName; }
  246.   wxString GetVendorName() const { return m_vendorName; }
  247.  
  248.   // Used wxIniConfig to set members in constructor
  249.   void SetAppName(const wxString& appName) { m_appName = appName; }
  250.   void SetVendorName(const wxString& vendorName) { m_vendorName = vendorName; }
  251.  
  252.   void SetStyle(long style) { m_style = style; }
  253.   long GetStyle() const { return m_style; }
  254.  
  255. protected:
  256.   static bool IsImmutable(const wxString& key)
  257.     { return !key.IsEmpty() && key[0] == wxCONFIG_IMMUTABLE_PREFIX; }
  258.  
  259.   // do read/write the values of different types
  260.   virtual bool DoReadString(const wxString& key, wxString *pStr) const = 0;
  261.   virtual bool DoReadLong(const wxString& key, long *pl) const = 0;
  262.   virtual bool DoReadInt(const wxString& key, int *pi) const;
  263.   virtual bool DoReadDouble(const wxString& key, double* val) const;
  264.   virtual bool DoReadBool(const wxString& key, bool* val) const;
  265.  
  266.   virtual bool DoWriteString(const wxString& key, const wxString& value) = 0;
  267.   virtual bool DoWriteLong(const wxString& key, long value) = 0;
  268.   virtual bool DoWriteInt(const wxString& key, int value);
  269.   virtual bool DoWriteDouble(const wxString& key, double value);
  270.   virtual bool DoWriteBool(const wxString& key, bool value);
  271.  
  272. private:
  273.   // are we doing automatic environment variable expansion?
  274.   bool m_bExpandEnvVars;
  275.   // do we record default values?
  276.   bool m_bRecordDefaults;
  277.  
  278.   // static variables
  279.   static wxConfigBase *ms_pConfig;
  280.   static bool          ms_bAutoCreate;
  281.  
  282.   // Application name and organisation name
  283.   wxString          m_appName;
  284.   wxString          m_vendorName;
  285.  
  286.   // Style flag
  287.   long              m_style;
  288. };
  289.  
  290. // a handy little class which changes current path to the path of given entry
  291. // and restores it in dtor: so if you declare a local variable of this type,
  292. // you work in the entry directory and the path is automatically restored
  293. // when the function returns
  294. // Taken out of wxConfig since not all compilers can cope with nested classes.
  295. class wxConfigPathChanger
  296. {
  297. public:
  298.   // ctor/dtor do path changing/restorin
  299.   wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry);
  300.  ~wxConfigPathChanger();
  301.  
  302.   // get the key name
  303.   const wxString& Name() const { return m_strName; }
  304.  
  305. private:
  306.   wxConfigBase *m_pContainer;   // object we live in
  307.   wxString      m_strName,      // name of entry (i.e. name only)
  308.                 m_strOldPath;   // saved path
  309.   bool          m_bChanged;     // was the path changed?
  310. };
  311.  
  312.  
  313. // ----------------------------------------------------------------------------
  314. // the native wxConfigBase implementation
  315. // ----------------------------------------------------------------------------
  316.  
  317. // under Windows we prefer to use the native implementation
  318. #if defined(__WXMSW__) && wxUSE_CONFIG_NATIVE
  319.   #ifdef __WIN32__
  320.     #define wxConfig  wxRegConfig
  321.     #define sm_classwxConfig sm_classwxRegConfig
  322.   #else  //WIN16
  323.     #define wxConfig  wxIniConfig
  324.     #define sm_classwxConfig sm_classwxIniConfig
  325.   #endif
  326. #else // either we're under Unix or wish to use files even under Windows
  327.   #define wxConfig  wxFileConfig
  328.   #define sm_classwxConfig sm_classwxFileConfig
  329. #endif
  330.  
  331. #endif // wxUSE_CONFIG
  332.  
  333. /*
  334.   Replace environment variables ($SOMETHING) with their values. The format is
  335.   $VARNAME or ${VARNAME} where VARNAME contains alphanumeric characters and
  336.   '_' only. '$' must be escaped ('\$') in order to be taken literally.
  337. */
  338.  
  339. WXDLLEXPORT wxString wxExpandEnvVars(const wxString &sz);
  340.  
  341. /*
  342.   Split path into parts removing '..' in progress
  343.  */
  344. WXDLLEXPORT void wxSplitPath(wxArrayString& aParts, const wxChar *sz);
  345.  
  346.  
  347. #endif
  348.   // _WX_CONFIG_H_
  349.  
  350.