interface/wx/fileconf.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        fileconf.h
   3 // Purpose:     interface of wxFileConfig
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxFileConfig
  10
  11     wxFileConfig implements wxConfigBase interface for
  12     storing and retrieving configuration information using plain text files. The
  13     files have a simple format reminiscent of Windows INI files with lines of the
  14     form @c "key = value" defining the keys and lines of special form
  15     @c "[group]" indicating the start of each group.
  16
  17     This class is used by default for wxConfig on Unix platforms but may also be
  18     used explicitly if you want to use files and not the registry even under
  19     Windows.
  20
  21     @library{wxbase}
  22     @category{cfg}
  23
  24     @see wxFileConfig::Save
  25 */
  26 class wxFileConfig : public wxConfigBase
  27 {
  28 public:
  29     /**
  30         Constructor allowing to choose the file names to use.
  31
  32         If @a localFilename and/or @a globalFilename are explicitly specified,
  33         they are used as the names of the user and system-wide configuration
  34         files (the latter is only read by the program while the former is read
  35         from and written to). Otherwise the behaviour depends on @a style
  36         parameter. If it includes ::wxCONFIG_USE_LOCAL_FILE, then the local
  37         file name is constructed from the information in @a appName and @a
  38         vendorName arguments in a system-dependent way. If
  39         ::wxCONFIG_USE_GLOBAL_FILE is not specified at all (and @a
  40         globalFilename is empty) then the system-wide file is not used at all.
  41         Otherwise its name and path are also constructed in the way appropriate
  42         for the current platform from the application and vendor names.
  43      */
  44     wxFileConfig(const wxString& appName = wxEmptyString,
  45                const wxString& vendorName = wxEmptyString,
  46                const wxString& localFilename = wxEmptyString,
  47                const wxString& globalFilename = wxEmptyString,
  48                long style = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE,
  49                const wxMBConv& conv = wxConvAuto());
  50
  51     /**
  52         Read the config data from the specified stream instead of the associated file,
  53         as usual.
  54
  55         @see Save()
  56     */
  57     wxFileConfig(wxInputStream& is, const wxMBConv& conv = wxConvAuto());
  58
  59     /**
  60         Return the full path to the file which would be used by wxFileConfig as global,
  61         system-wide, file if it were constructed with @a basename as "global filename"
  62         parameter in the constructor.
  63
  64         Notice that this function cannot be used if @a basename is already a full path name.
  65     */
  66     static wxFileName GetGlobalFile(const wxString& basename);
  67
  68     /**
  69         Return the full path to the file which would be used by wxFileConfig as local,
  70         user-specific, file if it were constructed with @a basename as "local filename"
  71         parameter in the constructor.
  72
  73         @a style has the same meaning as in @ref wxConfigBase::wxConfigBase "wxConfig constructor"
  74         and can contain any combination of styles but only wxCONFIG_USE_SUBDIR bit is
  75         examined by this function.
  76
  77         Notice that this function cannot be used if @a basename is already a full path name.
  78     */
  79     static wxFileName GetLocalFile(const wxString& basename, int style = 0);
  80
  81     static wxString GetGlobalFileName(const wxString& szFile);
  82     static wxString GetLocalFileName(const wxString& szFile, int style = 0);
  83
  84     /**
  85         Saves all config data to the given stream, returns @true if data was saved
  86         successfully or @false on error.
  87
  88         Note the interaction of this function with the internal "dirty flag": the
  89         data is saved unconditionally, i.e. even if the object is not dirty. However
  90         after saving it successfully, the dirty flag is reset so no changes will be
  91         written back to the file this object is associated with until you change its
  92         contents again.
  93
  94         @see wxConfigBase::Flush
  95     */
  96     virtual bool Save(wxOutputStream& os, const wxMBConv& conv = wxConvAuto());
  97
  98     /**
  99         Allows to set the mode to be used for the config file creation. For example, to
 100         create a config file which is not readable by other users (useful if it stores
 101         some sensitive information, such as passwords), you could use @c SetUmask(0077).
 102
 103         This function doesn't do anything on non-Unix platforms.
 104
 105         @see wxCHANGE_UMASK()
 106     */
 107     void SetUmask(int mode);
 108
 109   // implement inherited pure virtual functions
 110   virtual void SetPath(const wxString& strPath);
 111   virtual const wxString& GetPath() const;
 112
 113   virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
 114   virtual bool GetNextGroup (wxString& str, long& lIndex) const;
 115   virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
 116   virtual bool GetNextEntry (wxString& str, long& lIndex) const;
 117
 118   virtual size_t GetNumberOfEntries(bool bRecursive = false) const;
 119   virtual size_t GetNumberOfGroups(bool bRecursive = false) const;
 120
 121   virtual bool HasGroup(const wxString& strName) const;
 122   virtual bool HasEntry(const wxString& strName) const;
 123
 124   virtual bool Flush(bool bCurrentOnly = false);
 125
 126   virtual bool RenameEntry(const wxString& oldName, const wxString& newName);
 127   virtual bool RenameGroup(const wxString& oldName, const wxString& newName);
 128
 129   virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso = true);
 130   virtual bool DeleteGroup(const wxString& szKey);
 131   virtual bool DeleteAll();
 132 };
 133