home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / include / wx / fileconf.h < prev    next >
C/C++ Source or Header  |  2002-08-31  |  9KB  |  221 lines
  1. ///////////////////////////////////////////////////////////////////////////////
  2. // Name:        wx/fileconf.h
  3. // Purpose:     wxFileConfig derivation of wxConfigBase
  4. // Author:      Vadim Zeitlin
  5. // Modified by:
  6. // Created:     07.04.98 (adapted from appconf.cpp)
  7. // RCS-ID:      $Id: fileconf.h,v 1.38 2002/08/31 11:29:10 GD Exp $
  8. // Copyright:   (c) 1997 Karsten Ballⁿder   &  Vadim Zeitlin
  9. //                       Ballueder@usa.net     <zeitlin@dptmaths.ens-cachan.fr>
  10. // Licence:     wxWindows license
  11. ///////////////////////////////////////////////////////////////////////////////
  12.  
  13. #ifndef   _FILECONF_H
  14. #define   _FILECONF_H
  15.  
  16. #if defined(__GNUG__) && !defined(__APPLE__)
  17. #pragma interface "fileconf.h"
  18. #endif
  19.  
  20. #include "wx/defs.h"
  21.  
  22. #if wxUSE_CONFIG
  23.  
  24. #include "wx/textfile.h"
  25. #include "wx/string.h"
  26.  
  27. // ----------------------------------------------------------------------------
  28. // wxFileConfig
  29. // ----------------------------------------------------------------------------
  30.  
  31. /*
  32.   wxFileConfig derives from base Config and implements file based config class,
  33.   i.e. it uses ASCII disk files to store the information. These files are
  34.   alternatively called INI, .conf or .rc in the documentation. They are
  35.   organized in groups or sections, which can nest (i.e. a group contains
  36.   subgroups, which contain their own subgroups &c). Each group has some
  37.   number of entries, which are "key = value" pairs. More precisely, the format
  38.   is:
  39.  
  40.   # comments are allowed after either ';' or '#' (Win/UNIX standard)
  41.  
  42.   # blank lines (as above) are ignored
  43.  
  44.   # global entries are members of special (no name) top group
  45.   written_for = Windows
  46.   platform    = Linux
  47.  
  48.   # the start of the group 'Foo'
  49.   [Foo]                           # may put comments like this also
  50.   # following 3 lines are entries
  51.   key = value
  52.   another_key = "  strings with spaces in the beginning should be quoted, \
  53.                    otherwise the spaces are lost"
  54.   last_key = but you don't have to put " normally (nor quote them, like here)
  55.  
  56.   # subgroup of the group 'Foo'
  57.   # (order is not important, only the name is: separator is '/', as in paths)
  58.   [Foo/Bar]
  59.   # entries prefixed with "!" are immutable, i.e. can't be changed if they are
  60.   # set in the system-wide config file
  61.   !special_key = value
  62.   bar_entry = whatever
  63.  
  64.   [Foo/Bar/Fubar]   # depth is (theoretically :-) unlimited
  65.   # may have the same name as key in another section
  66.   bar_entry = whatever not
  67.  
  68.   You have {read/write/delete}Entry functions (guess what they do) and also
  69.   setCurrentPath to select current group. enum{Subgroups/Entries} allow you
  70.   to get all entries in the config file (in the current group). Finally,
  71.   flush() writes immediately all changed entries to disk (otherwise it would
  72.   be done automatically in dtor)
  73.  
  74.   wxFileConfig manages not less than 2 config files for each program: global
  75.   and local (or system and user if you prefer). Entries are read from both of
  76.   them and the local entries override the global ones unless the latter is
  77.   immutable (prefixed with '!') in which case a warning message is generated
  78.   and local value is ignored. Of course, the changes are always written to local
  79.   file only.
  80.  
  81.   The names of these files can be specified in a number of ways. First of all,
  82.   you can use the standard convention: using the ctor which takes 'strAppName'
  83.   parameter will probably be sufficient for 90% of cases. If, for whatever
  84.   reason you wish to use the files with some other names, you can always use the
  85.   second ctor.
  86.  
  87.   wxFileConfig also may automatically expand the values of environment variables
  88.   in the entries it reads: for example, if you have an entry
  89.     score_file = $HOME/.score
  90.   a call to Read(&str, "score_file") will return a complete path to .score file
  91.   unless the expansion was previousle disabled with SetExpandEnvVars(FALSE) call
  92.   (it's on by default, the current status can be retrieved with
  93.    IsExpandingEnvVars function).
  94. */
  95. class WXDLLEXPORT wxFileConfigGroup;
  96. class WXDLLEXPORT wxFileConfigEntry;
  97. class WXDLLEXPORT wxFileConfigLineList;
  98. class WXDLLEXPORT wxInputStream;
  99.  
  100. class WXDLLEXPORT wxFileConfig : public wxConfigBase
  101. {
  102. public:
  103.   // construct the "standard" full name for global (system-wide) and
  104.   // local (user-specific) config files from the base file name.
  105.   //
  106.   // the following are the filenames returned by this functions:
  107.   //            global                local
  108.   // Unix   /etc/file.ext           ~/.file
  109.   // Win    %windir%\file.ext   %USERPROFILE%\file.ext
  110.   //
  111.   // where file is the basename of szFile, ext is it's extension
  112.   // or .conf (Unix) or .ini (Win) if it has none
  113.   static wxString GetGlobalFileName(const wxChar *szFile);
  114.   static wxString GetLocalFileName(const wxChar *szFile);
  115.  
  116.   // ctor & dtor
  117.     // New constructor: one size fits all. Specify wxCONFIG_USE_LOCAL_FILE or
  118.     // wxCONFIG_USE_GLOBAL_FILE to say which files should be used.
  119.   wxFileConfig(const wxString& appName,
  120.                const wxString& vendorName = wxT(""),
  121.                const wxString& localFilename = wxT(""),
  122.                const wxString& globalFilename = wxT(""),
  123.                long style = wxCONFIG_USE_LOCAL_FILE);
  124.  
  125. #if wxUSE_STREAMS
  126.     // ctor that takes an input stream.
  127.   wxFileConfig(wxInputStream &inStream);
  128. #endif // wxUSE_STREAMS
  129.  
  130.     // dtor will save unsaved data
  131.   virtual ~wxFileConfig();
  132.  
  133.   // under Unix, set the umask to be used for the file creation, do nothing
  134.   // under other systems
  135. #ifdef __UNIX__
  136.   void SetUmask(int mode) { m_umask = mode; }
  137. #else // !__UNIX__
  138.   void SetUmask(int WXUNUSED(mode)) { }
  139. #endif // __UNIX__/!__UNIX__
  140.  
  141.   // implement inherited pure virtual functions
  142.   virtual void SetPath(const wxString& strPath);
  143.   virtual const wxString& GetPath() const { return m_strPath; }
  144.  
  145.   virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
  146.   virtual bool GetNextGroup (wxString& str, long& lIndex) const;
  147.   virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
  148.   virtual bool GetNextEntry (wxString& str, long& lIndex) const;
  149.  
  150.   virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const;
  151.   virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const;
  152.  
  153.   virtual bool HasGroup(const wxString& strName) const;
  154.   virtual bool HasEntry(const wxString& strName) const;
  155.  
  156.   virtual bool Flush(bool bCurrentOnly = FALSE);
  157.  
  158.   virtual bool RenameEntry(const wxString& oldName, const wxString& newName);
  159.   virtual bool RenameGroup(const wxString& oldName, const wxString& newName);
  160.  
  161.   virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso = TRUE);
  162.   virtual bool DeleteGroup(const wxString& szKey);
  163.   virtual bool DeleteAll();
  164.  
  165. public:
  166.   // functions to work with this list
  167.   wxFileConfigLineList *LineListAppend(const wxString& str);
  168.   wxFileConfigLineList *LineListInsert(const wxString& str,
  169.                            wxFileConfigLineList *pLine);    // NULL => Prepend()
  170.   void      LineListRemove(wxFileConfigLineList *pLine);
  171.   bool      LineListIsEmpty();
  172.  
  173. protected:
  174.   virtual bool DoReadString(const wxString& key, wxString *pStr) const;
  175.   virtual bool DoReadLong(const wxString& key, long *pl) const;
  176.  
  177.   virtual bool DoWriteString(const wxString& key, const wxString& szValue);
  178.   virtual bool DoWriteLong(const wxString& key, long lValue);
  179.  
  180. private:
  181.   // GetXXXFileName helpers: return ('/' terminated) directory names
  182.   static wxString GetGlobalDir();
  183.   static wxString GetLocalDir();
  184.  
  185.   // common part of all ctors (assumes that m_str{Local|Global}File are already
  186.   // initialized
  187.   void Init();
  188.  
  189.   // common part of from dtor and DeleteAll
  190.   void CleanUp();
  191.  
  192.   // parse the whole file
  193.   void Parse(wxTextBuffer& buffer, bool bLocal);
  194.  
  195.   // the same as SetPath("/")
  196.   void SetRootPath();
  197.  
  198.   // member variables
  199.   // ----------------
  200.   wxFileConfigLineList *m_linesHead,        // head of the linked list
  201.                        *m_linesTail;        // tail
  202.  
  203.   wxString    m_strLocalFile,     // local  file name passed to ctor
  204.               m_strGlobalFile;    // global
  205.   wxString    m_strPath;          // current path (not '/' terminated)
  206.  
  207.   wxFileConfigGroup *m_pRootGroup,      // the top (unnamed) group
  208.                     *m_pCurrentGroup;   // the current group
  209.  
  210. #ifdef __UNIX__
  211.   int m_umask;                    // the umask to use for file creation
  212. #endif // __UNIX__
  213. };
  214.  
  215. #endif
  216.   // wxUSE_CONFIG
  217.  
  218. #endif  
  219.   //_FILECONF_H
  220.  
  221.