interface/fileconf.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        fileconf.h
   3 // Purpose:     interface of wxFileConfig
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFileConfig
  11     @wxheader{fileconf.h}
  12
  13     wxFileConfig implements wxConfigBase interface for
  14     storing and retrieving configuration information using plain text files. The
  15     files have a simple format reminiscent of Windows INI files with lines of the
  16     form @c key = value defining the keys and lines of special form
  17     @c [group] indicating the start of each group.
  18
  19     This class is used by default for wxConfig on Unix platforms but may also be
  20     used explicitly if you want to use files and not the registry even under
  21     Windows.
  22
  23     @library{wxbase}
  24     @category{misc}
  25
  26     @see wxFileConfig::Save
  27 */
  28 class wxFileConfig : public wxConfigBase
  29 {
  30 public:
  31     /**
  32         Read the config data from the specified stream instead of the associated file,
  33         as usual.
  34
  35         @see Save()
  36     */
  37     wxFileConfig(wxInputStream& is, const wxMBConv& conv = wxConvAuto());
  38
  39     /**
  40         Return the full path to the file which would be used by wxFileConfig as global,
  41         system-wide, file if it were constructed with @a basename as "global filename"
  42         parameter in the constructor.
  43
  44         Notice that this function cannot be used if @a basename is already a full path name.
  45     */
  46     static wxFileName GetGlobalFile(const wxString& basename);
  47
  48     /**
  49         Return the full path to the file which would be used by wxFileConfig as local,
  50         user-specific, file if it were constructed with @a basename as "local filename"
  51         parameter in the constructor.
  52
  53         @a style has the same meaning as in @ref wxConfigBase::ctor constructor
  54         and can contain any combination of styles but only wxCONFIG_USE_SUBDIR bit is
  55         examined by this function.
  56
  57         Notice that this function cannot be used if @a basename is already a full path name.
  58     */
  59     static wxFileName GetLocalFile(const wxString& basename,
  60                                    int style = 0);
  61
  62     /**
  63         Saves all config data to the given stream, returns @true if data was saved
  64         successfully or @false on error.
  65
  66         Note the interaction of this function with the internal "dirty flag": the
  67         data is saved unconditionally, i.e. even if the object is not dirty. However
  68         after saving it successfully, the dirty flag is reset so no changes will be
  69         written back to the file this object is associated with until you change its
  70         contents again.
  71
  72         @see wxConfigBase::Flush
  73     */
  74     bool Save(wxOutputStream& os, const wxMBConv& conv = wxConvAuto());
  75
  76     /**
  77         Allows to set the mode to be used for the config file creation. For example, to
  78         create a config file which is not readable by other users (useful if it stores
  79         some sensitive information, such as passwords), you could use @c SetUmask(0077).
  80
  81         This function doesn't do anything on non-Unix platforms.
  82
  83         @see wxCHANGE_UMASK()
  84     */
  85     void SetUmask(int mode);
  86 };
  87