wxPython/src/_config.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _config.i
   3 // Purpose:     SWIG interface for wxConfig, wxFileConfig, etc.
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     25-Nov-1998
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17 %newgroup
  18
  19 %{
  20 %}
  21
  22 //---------------------------------------------------------------------------
  23
  24
  25 %{
  26     static PyObject* __EnumerationHelper(bool flag, wxString& str, long index) {
  27         PyObject* ret = PyTuple_New(3);
  28         if (ret) {
  29             PyTuple_SET_ITEM(ret, 0, PyInt_FromLong(flag));
  30             PyTuple_SET_ITEM(ret, 1, wx2PyString(str));
  31             PyTuple_SET_ITEM(ret, 2, PyInt_FromLong(index));
  32         }
  33         return ret;
  34     }
  35 %}
  36
  37
  38 enum
  39 {
  40     wxCONFIG_USE_LOCAL_FILE,
  41     wxCONFIG_USE_GLOBAL_FILE,
  42     wxCONFIG_USE_RELATIVE_PATH,
  43     wxCONFIG_USE_NO_ESCAPE_CHARACTERS
  44 };
  45
  46
  47
  48 // abstract base class wxConfigBase which defines the interface for derived
  49 // classes
  50 //
  51 // wxConfig organizes the items in a tree-like structure (modeled after the
  52 // Unix/Dos filesystem). There are groups (directories) and keys (files).
  53 // There is always one current group given by the current path.
  54 //
  55 // Keys are pairs "key_name = value" where value may be of string or integer
  56 // (long) type (TODO doubles and other types such as wxDate coming soon).
  57 class wxConfigBase {
  58 public:
  59 //      wxConfigBase(const wxString& appName = wxPyEmptyString,       **** An ABC
  60 //                   const wxString& vendorName = wxPyEmptyString,
  61 //                   const wxString& localFilename = wxPyEmptyString,
  62 //                   const wxString& globalFilename = wxPyEmptyString,
  63 //                   long style = 0);
  64     ~wxConfigBase();
  65
  66     enum EntryType
  67     {
  68         Type_Unknown,
  69         Type_String,
  70         Type_Boolean,
  71         Type_Integer,    // use Read(long *)
  72         Type_Float       // use Read(double *)
  73     };
  74
  75
  76     // sets the config object, returns the previous pointer
  77     static wxConfigBase *Set(wxConfigBase *pConfig);
  78
  79     // get the config object, creates it on demand unless DontCreateOnDemand
  80     // was called
  81     static wxConfigBase *Get(bool createOnDemand = True);
  82
  83     // create a new config object: this function will create the "best"
  84     // implementation of wxConfig available for the current platform, see
  85     // comments near definition wxUSE_CONFIG_NATIVE for details. It returns
  86     // the created object and also sets it as ms_pConfig.
  87     static wxConfigBase *Create();
  88
  89     // should Get() try to create a new log object if the current one is NULL?
  90     static void DontCreateOnDemand();
  91
  92
  93
  94     // set current path: if the first character is '/', it's the absolute path,
  95     // otherwise it's a relative path. '..' is supported. If the strPath
  96     // doesn't exist it is created.
  97     virtual void SetPath(const wxString& strPath);
  98
  99     // retrieve the current path (always as absolute path)
 100     virtual const wxString& GetPath() const;
 101
 102
 103
 104
 105     // Each of these enumeration methods return a 3-tuple consisting of
 106     // the continue flag, the value string, and the index for the next call.
 107     %extend {
 108         // enumerate subgroups
 109         PyObject* GetFirstGroup() {
 110             bool     cont;
 111             long     index = 0;
 112             wxString value;
 113
 114             cont = self->GetFirstGroup(value, index);
 115             return __EnumerationHelper(cont, value, index);
 116         }
 117         PyObject* GetNextGroup(long index) {
 118             bool     cont;
 119             wxString value;
 120
 121             cont = self->GetNextGroup(value, index);
 122             return __EnumerationHelper(cont, value, index);
 123         }
 124
 125         // enumerate entries
 126         PyObject* GetFirstEntry() {
 127             bool     cont;
 128             long     index = 0;
 129             wxString value;
 130
 131             cont = self->GetFirstEntry(value, index);
 132             return __EnumerationHelper(cont, value, index);
 133         }
 134         PyObject* GetNextEntry(long index) {
 135             bool     cont;
 136             wxString value;
 137
 138             cont = self->GetNextEntry(value, index);
 139             return __EnumerationHelper(cont, value, index);
 140         }
 141     }
 142
 143
 144
 145     // get number of entries/subgroups in the current group, with or without
 146     // it's subgroups
 147     virtual size_t GetNumberOfEntries(bool bRecursive = False) const;
 148     virtual size_t GetNumberOfGroups(bool bRecursive = False) const;
 149
 150     // returns True if the group by this name exists
 151     virtual bool HasGroup(const wxString& strName) const;
 152
 153     // same as above, but for an entry
 154     virtual bool HasEntry(const wxString& strName) const;
 155
 156     // returns True if either a group or an entry with a given name exist
 157     bool Exists(const wxString& strName) const;
 158
 159     // get the entry type
 160     virtual EntryType GetEntryType(const wxString& name) const;
 161
 162
 163     // Key access.  Returns the value of key if it exists, defaultVal otherwise
 164     wxString Read(const wxString& key, const wxString& defaultVal = wxPyEmptyString);
 165
 166     %extend {
 167         long ReadInt(const wxString& key, long defaultVal = 0) {
 168             long rv;
 169             self->Read(key, &rv, defaultVal);
 170             return rv;
 171         }
 172         double ReadFloat(const wxString& key, double defaultVal = 0.0) {
 173             double rv;
 174             self->Read(key, &rv, defaultVal);
 175             return rv;
 176         }
 177         bool ReadBool(const wxString& key, bool defaultVal = False) {
 178             bool rv;
 179             self->Read(key, &rv, defaultVal);
 180             return rv;
 181         }
 182     }
 183
 184
 185     // write the value (return True on success)
 186     bool Write(const wxString& key, const wxString& value);
 187     %name(WriteInt)bool Write(const wxString& key, long value);
 188     %name(WriteFloat)bool Write(const wxString& key, double value);
 189     %name(WriteBool)bool Write(const wxString& key, bool value);
 190
 191
 192     // permanently writes all changes
 193     virtual bool Flush(bool bCurrentOnly = False);
 194
 195     // renaming, all functions return False on failure (probably because the new
 196     // name is already taken by an existing entry)
 197     // rename an entry
 198     virtual bool RenameEntry(const wxString& oldName,
 199                              const wxString& newName);
 200     // rename a group
 201     virtual bool RenameGroup(const wxString& oldName,
 202                              const wxString& newName);
 203
 204     // deletes the specified entry and the group it belongs to if
 205     // it was the last key in it and the second parameter is True
 206     virtual bool DeleteEntry(const wxString& key,
 207                              bool bDeleteGroupIfEmpty = True);
 208
 209     // delete the group (with all subgroups)
 210     virtual bool DeleteGroup(const wxString& key);
 211
 212     // delete the whole underlying object (disk file, registry key, ...)
 213     // primarly for use by desinstallation routine.
 214     virtual bool DeleteAll();
 215
 216
 217     // we can automatically expand environment variables in the config entries
 218     // (this option is on by default, you can turn it on/off at any time)
 219     bool IsExpandingEnvVars() const;
 220     void SetExpandEnvVars(bool bDoIt = True);
 221
 222     // recording of default values
 223     void SetRecordDefaults(bool bDoIt = True);
 224     bool IsRecordingDefaults() const;
 225
 226     // does expansion only if needed
 227     wxString ExpandEnvVars(const wxString& str) const;
 228
 229     // misc accessors
 230     wxString GetAppName() const;
 231     wxString GetVendorName() const;
 232
 233     // Used wxIniConfig to set members in constructor
 234     void SetAppName(const wxString& appName);
 235     void SetVendorName(const wxString& vendorName);
 236
 237     void SetStyle(long style);
 238     long GetStyle() const;
 239 };
 240
 241
 242 //---------------------------------------------------------------------------
 243
 244 // a handy little class which changes current path to the path of given entry
 245 // and restores it in dtor: so if you declare a local variable of this type,
 246 // you work in the entry directory and the path is automatically restored
 247 // when the function returns
 248 // Taken out of wxConfig since not all compilers can cope with nested classes.
 249 class wxConfigPathChanger
 250 {
 251 public:
 252   // ctor/dtor do path changing/restorin
 253   wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry);
 254  ~wxConfigPathChanger();
 255
 256   // get the key name
 257   const wxString& Name() const { return m_strName; }
 258 };
 259
 260
 261 //---------------------------------------------------------------------------
 262
 263 // This will be a wxRegConfig on Win32 and wxFileConfig otherwise.
 264 class wxConfig : public wxConfigBase {
 265 public:
 266     wxConfig(const wxString& appName = wxPyEmptyString,
 267              const wxString& vendorName = wxPyEmptyString,
 268              const wxString& localFilename = wxPyEmptyString,
 269              const wxString& globalFilename = wxPyEmptyString,
 270              long style = 0);
 271     ~wxConfig();
 272 };
 273
 274
 275 // Sometimes it's nice to explicitly have a wxFileConfig too.
 276 class wxFileConfig : public wxConfigBase {
 277 public:
 278     wxFileConfig(const wxString& appName = wxPyEmptyString,
 279                  const wxString& vendorName = wxPyEmptyString,
 280                  const wxString& localFilename = wxPyEmptyString,
 281                  const wxString& globalFilename = wxPyEmptyString,
 282                  long style = 0);
 283     ~wxFileConfig();
 284 };
 285
 286
 287 //---------------------------------------------------------------------------
 288
 289
 290 //  Replace environment variables ($SOMETHING) with their values. The format is
 291 //  $VARNAME or ${VARNAME} where VARNAME contains alphanumeric characters and
 292 //  '_' only. '$' must be escaped ('\$') in order to be taken literally.
 293 wxString wxExpandEnvVars(const wxString &sz);
 294
 295
 296 //---------------------------------------------------------------------------