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 DocStr(wxConfigBase,
  49 "wx.ConfigBase class defines the basic interface of all config
  50 classes. It can not be used by itself (it is an abstract base class)
  51 and you will always use one of its derivations: wx.Config or
  52 wx.FileConfig.
  53
  54 wx.ConfigBase organizes the items in a tree-like structure, modeled
  55 after the Unix/Dos filesystem. There are groups that act like
  56 directories and entries, key/value pairs that act like files.  There
  57 is always one current group given by the current path.  As in the file
  58 system case, to specify a key in the config class you must use a path
  59 to it.  Config classes also support the notion of the current group,
  60 which makes it possible to use relative paths.
  61
  62 Keys are pairs \"key_name = value\" where value may be of string,
  63 integer floating point or boolean, you can not store binary data
  64 without first encoding it as a string.  For performance reasons items
  65 should be kept small, no more than a couple kilobytes.
  66 ", "");
  67
  68
  69 class wxConfigBase {
  70 public:
  71 //      wxConfigBase(const wxString& appName = wxPyEmptyString,       **** An ABC
  72 //                   const wxString& vendorName = wxPyEmptyString,
  73 //                   const wxString& localFilename = wxPyEmptyString,
  74 //                   const wxString& globalFilename = wxPyEmptyString,
  75 //                   long style = 0);
  76     ~wxConfigBase();
  77
  78     enum EntryType
  79     {
  80         Type_Unknown,
  81         Type_String,
  82         Type_Boolean,
  83         Type_Integer,    // use Read(long *)
  84         Type_Float       // use Read(double *)
  85     };
  86
  87
  88     %apply SWIGTYPE *DISOWN { wxConfigBase *config };
  89     DocDeclStr(
  90         static wxConfigBase *, Set(wxConfigBase *config),
  91         "Sets the global config object (the one returned by Get) and returns a
  92 reference to the previous global config object.", "");
  93     %clear wxConfigBase *config;
  94
  95     DocDeclStr(
  96         static wxConfigBase *, Get(bool createOnDemand = true),
  97         "Returns the current global config object, creating one if neccessary.", "");
  98
  99
 100     DocDeclStr(
 101         static wxConfigBase *, Create(),
 102         "Create and return a new global config object.  This function will
 103 create the \"best\" implementation of wx.Config available for the
 104 current platform.", "");
 105
 106
 107
 108     DocDeclStr(
 109         static void , DontCreateOnDemand(),
 110         "Should Get() try to create a new log object if there isn't a current
 111 one?", "");
 112
 113
 114
 115
 116     DocDeclStr(
 117         virtual void , SetPath(const wxString& path),
 118         "Set current path: if the first character is '/', it's the absolute
 119 path, otherwise it's a relative path. '..' is supported. If the
 120 strPath doesn't exist it is created.", "");
 121
 122
 123     DocDeclStr(
 124         virtual const wxString& , GetPath() const,
 125         "Retrieve the current path (always as absolute path)", "");
 126
 127
 128
 129     %extend {
 130         DocAStr(GetFirstGroup,
 131                 "GetFirstGroup() -> (more, value, index)",
 132                 "Allows enumerating the subgroups in a config object.  Returns a tuple
 133 containing a flag indicating there are more items, the name of the
 134 current item, and an index to pass to GetNextGroup to fetch the next
 135 item.", "");
 136         PyObject* GetFirstGroup() {
 137             bool     cont;
 138             long     index = 0;
 139             wxString value;
 140
 141             cont = self->GetFirstGroup(value, index);
 142             return __EnumerationHelper(cont, value, index);
 143         }
 144
 145
 146
 147         DocAStr(GetNextGroup,
 148                 "GetNextGroup(long index) -> (more, value, index)",
 149                 "Allows enumerating the subgroups in a config object.  Returns a tuple
 150 containing a flag indicating there are more items, the name of the
 151 current item, and an index to pass to GetNextGroup to fetch the next
 152 item.", "");
 153         PyObject* GetNextGroup(long index) {
 154             bool     cont;
 155             wxString value;
 156
 157             cont = self->GetNextGroup(value, index);
 158             return __EnumerationHelper(cont, value, index);
 159         }
 160
 161
 162         DocAStr(GetFirstEntry,
 163                 "GetFirstEntry() -> (more, value, index)",
 164                 "Allows enumerating the entries in the current group in a config
 165 object.  Returns a tuple containing a flag indicating there are more
 166 items, the name of the current item, and an index to pass to
 167 GetNextGroup to fetch the next item.", "");
 168         PyObject* GetFirstEntry() {
 169             bool     cont;
 170             long     index = 0;
 171             wxString value;
 172
 173             cont = self->GetFirstEntry(value, index);
 174             return __EnumerationHelper(cont, value, index);
 175         }
 176
 177
 178         DocAStr(GetNextEntry,
 179                 "GetNextEntry(long index) -> (more, value, index)",
 180                 "Allows enumerating the entries in the current group in a config
 181 object.  Returns a tuple containing a flag indicating there are more
 182 items, the name of the current item, and an index to pass to
 183 GetNextGroup to fetch the next item.", "");
 184         PyObject* GetNextEntry(long index) {
 185             bool     cont;
 186             wxString value;
 187
 188             cont = self->GetNextEntry(value, index);
 189             return __EnumerationHelper(cont, value, index);
 190         }
 191     }
 192
 193
 194
 195     DocDeclStr(
 196         virtual size_t , GetNumberOfEntries(bool recursive = false) const,
 197         "Get the number of entries in the current group, with or without its
 198 subgroups.", "");
 199
 200     DocDeclStr(
 201         virtual size_t , GetNumberOfGroups(bool recursive = false) const,
 202         "Get the number of subgroups in the current group, with or without its
 203 subgroups.", "");
 204
 205
 206
 207     DocDeclStr(
 208         virtual bool , HasGroup(const wxString& name) const,
 209         "Returns True if the group by this name exists", "");
 210
 211
 212     DocDeclStr(
 213         virtual bool , HasEntry(const wxString& name) const,
 214         "Returns True if the entry by this name exists", "");
 215
 216
 217     DocDeclStr(
 218         bool , Exists(const wxString& name) const,
 219         "Returns True if either a group or an entry with a given name exists", "");
 220
 221
 222     // get the entry type
 223     DocDeclStr(
 224         virtual EntryType , GetEntryType(const wxString& name) const,
 225         "Get the type of the entry.  Returns one of the wx.Config.Type_XXX values.", "");
 226
 227
 228
 229     DocDeclStr(
 230         wxString , Read(const wxString& key, const wxString& defaultVal = wxPyEmptyString),
 231         "Returns the value of key if it exists, defaultVal otherwise.", "");
 232
 233
 234     %extend {
 235         DocStr(ReadInt,
 236                "Returns the value of key if it exists, defaultVal otherwise.", "");
 237         long ReadInt(const wxString& key, long defaultVal = 0) {
 238             long rv;
 239             self->Read(key, &rv, defaultVal);
 240             return rv;
 241         }
 242
 243         DocStr(ReadFloat,
 244                "Returns the value of key if it exists, defaultVal otherwise.", "");
 245         double ReadFloat(const wxString& key, double defaultVal = 0.0) {
 246             double rv;
 247             self->Read(key, &rv, defaultVal);
 248             return rv;
 249         }
 250
 251         DocStr(ReadBool,
 252                "Returns the value of key if it exists, defaultVal otherwise.", "");
 253         bool ReadBool(const wxString& key, bool defaultVal = false) {
 254             bool rv;
 255             self->Read(key, &rv, defaultVal);
 256             return rv;
 257         }
 258     }
 259
 260
 261     // write the value (return True on success)
 262     DocDeclStr(
 263         bool , Write(const wxString& key, const wxString& value),
 264         "write the value (return True on success)", "");
 265
 266     DocDeclStrName(
 267         bool, Write(const wxString& key, long value),
 268         "write the value (return True on success)", "",
 269         WriteInt);
 270
 271     DocDeclStrName(
 272         bool, Write(const wxString& key, double value),
 273         "write the value (return True on success)", "",
 274         WriteFloat);
 275
 276     DocDeclStrName(
 277         bool, Write(const wxString& key, bool value),
 278         "write the value (return True on success)", "",
 279         WriteBool);
 280
 281
 282     DocDeclStr(
 283         virtual bool , Flush(bool currentOnly = false),
 284         "permanently writes all changes", "");
 285
 286
 287     DocDeclStr(
 288         virtual bool , RenameEntry(const wxString& oldName,
 289                                    const wxString& newName),
 290         "Rename an entry.  Returns False on failure (probably because the new
 291 name is already taken by an existing entry)", "");
 292
 293     DocDeclStr(
 294         virtual bool , RenameGroup(const wxString& oldName,
 295                                    const wxString& newName),
 296         "Rename a group.  Returns False on failure (probably because the new
 297 name is already taken by an existing entry)", "");
 298
 299
 300     // deletes the specified entry and the group it belongs to if
 301     // it was the last key in it and the second parameter is True
 302     DocDeclStr(
 303         virtual bool , DeleteEntry(const wxString& key,
 304                                    bool deleteGroupIfEmpty = true),
 305         "Deletes the specified entry and the group it belongs to if it was the
 306 last key in it and the second parameter is True", "");
 307
 308
 309     DocDeclStr(
 310         virtual bool , DeleteGroup(const wxString& key),
 311         "Delete the group (with all subgroups)", "");
 312
 313
 314     DocDeclStr(
 315         virtual bool , DeleteAll(),
 316         "Delete the whole underlying object (disk file, registry key, ...)
 317 primarly intended for use by deinstallation routine.", "");
 318
 319
 320
 321     DocDeclStr(
 322         void , SetExpandEnvVars(bool doIt = true),
 323         "We can automatically expand environment variables in the config
 324 entries this option is on by default, you can turn it on/off at any
 325 time)", "");
 326
 327     DocDeclStr(
 328         bool , IsExpandingEnvVars() const,
 329         "Are we currently expanding environment variables?", "");
 330
 331
 332     DocDeclStr(
 333         void , SetRecordDefaults(bool doIt = true),
 334         "Set whether the config objec should record default values.", "");
 335
 336     DocDeclStr(
 337         bool , IsRecordingDefaults() const,
 338         "Are we currently recording default values?", "");
 339
 340
 341     DocDeclStr(
 342         wxString , ExpandEnvVars(const wxString& str) const,
 343         "Expand any environment variables in str and return the result", "");
 344
 345
 346     DocDeclStr(
 347         wxString , GetAppName() const,
 348         "", "");
 349
 350     DocDeclStr(
 351         wxString , GetVendorName() const,
 352         "", "");
 353
 354
 355     DocDeclStr(
 356         void , SetAppName(const wxString& appName),
 357         "", "");
 358
 359     DocDeclStr(
 360         void , SetVendorName(const wxString& vendorName),
 361         "", "");
 362
 363
 364     DocDeclStr(
 365         void , SetStyle(long style),
 366         "", "");
 367
 368     DocDeclStr(
 369         long , GetStyle() const,
 370         "", "");
 371
 372 };
 373
 374
 375 //---------------------------------------------------------------------------
 376
 377 DocStr(wxConfig,
 378 "This ConfigBase-derived class will use the registry on Windows,
 379 and will be a wx.FileConfig on other platforms.", "");
 380
 381 class wxConfig : public wxConfigBase {
 382 public:
 383     DocCtorStr(
 384         wxConfig(const wxString& appName = wxPyEmptyString,
 385                  const wxString& vendorName = wxPyEmptyString,
 386                  const wxString& localFilename = wxPyEmptyString,
 387                  const wxString& globalFilename = wxPyEmptyString,
 388                  long style = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
 389         "", "");
 390
 391     ~wxConfig();
 392 };
 393
 394
 395
 396
 397 DocStr(wxFileConfig,
 398        "This config class will use a file for storage on all platforms.", "");
 399
 400 class wxFileConfig : public wxConfigBase {
 401 public:
 402     DocCtorStr(
 403         wxFileConfig(const wxString& appName = wxPyEmptyString,
 404                      const wxString& vendorName = wxPyEmptyString,
 405                      const wxString& localFilename = wxPyEmptyString,
 406                      const wxString& globalFilename = wxPyEmptyString,
 407                      long style = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
 408         "", "");
 409
 410     ~wxFileConfig();
 411 };
 412
 413
 414 //---------------------------------------------------------------------------
 415
 416 DocStr(wxConfigPathChanger,
 417 "A handy little class which changes current path to the path of given
 418 entry and restores it in the destructoir: so if you declare a local
 419 variable of this type, you work in the entry directory and the path is
 420 automatically restored when the function returns.", "");
 421
 422 class wxConfigPathChanger
 423 {
 424 public:
 425     DocCtorStr(
 426         wxConfigPathChanger(const wxConfigBase *config, const wxString& entry),
 427         "", "");
 428
 429     ~wxConfigPathChanger();
 430
 431     DocDeclStr(
 432         const wxString& , Name() const,
 433         "Get the key name", "");
 434 };
 435
 436
 437 //---------------------------------------------------------------------------
 438
 439
 440
 441 DocDeclStr(
 442     wxString , wxExpandEnvVars(const wxString &sz),
 443     "Replace environment variables ($SOMETHING) with their values. The
 444 format is $VARNAME or ${VARNAME} where VARNAME contains alphanumeric
 445 characters and '_' only. '$' must be escaped ('\$') in order to be
 446 taken literally.", "");
 447
 448
 449
 450 //---------------------------------------------------------------------------