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