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