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     DocDeclStr(
  89         static wxConfigBase *, Set(wxConfigBase *config),
  90         "Sets the global config object (the one returned by Get) and returns a
  91 reference to the previous global config object.", "");
  92
  93
  94     DocDeclStr(
  95         static wxConfigBase *, Get(bool createOnDemand = True),
  96         "Returns the current global config object, creating one if neccessary.", "");
  97
  98
  99     DocDeclStr(
 100         static wxConfigBase *, Create(),
 101         "Create and return a new global config object.  This function will
 102 create the \"best\" implementation of wx.Config available for the
 103 current platform.", "");
 104
 105
 106
 107     DocDeclStr(
 108         static void , DontCreateOnDemand(),
 109         "Should Get() try to create a new log object if there isn't a current
 110 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
 118 path, otherwise it's a relative path. '..' is supported. If the
 119 strPath 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 a tuple
 132 containing a flag indicating there are more items, the name of the
 133 current item, and an index to pass to GetNextGroup to fetch the next
 134 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 a tuple
 149 containing a flag indicating there are more items, the name of the
 150 current item, and an index to pass to GetNextGroup to fetch the next
 151 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
 164 object.  Returns a tuple containing a flag indicating there are more
 165 items, the name of the current item, and an index to pass to
 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
 180 object.  Returns a tuple containing a flag indicating there are more
 181 items, the name of the current item, and an index to pass to
 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 without its
 197 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 without its
 202 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
 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 a group.  Returns False on failure (probably because the new
 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 it was the
 305 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, ...)
 316 primarly intended for use by deinstallation routine.", "");
 317
 318
 319
 320     DocDeclStr(
 321         void , SetExpandEnvVars(bool doIt = True),
 322         "We can automatically expand environment variables in the config
 323 entries this option is on by default, you can turn it on/off at any
 324 time)", "");
 325
 326     DocDeclStr(
 327         bool , IsExpandingEnvVars() const,
 328         "Are we currently expanding environment variables?", "");
 329
 330
 331     DocDeclStr(
 332         void , SetRecordDefaults(bool doIt = True),
 333         "Set whether the config objec should record default values.", "");
 334
 335     DocDeclStr(
 336         bool , IsRecordingDefaults() const,
 337         "Are we currently recording default values?", "");
 338
 339
 340     DocDeclStr(
 341         wxString , ExpandEnvVars(const wxString& str) const,
 342         "Expand any environment variables in str and return the result", "");
 343
 344
 345     DocDeclStr(
 346         wxString , GetAppName() const,
 347         "", "");
 348
 349     DocDeclStr(
 350         wxString , GetVendorName() const,
 351         "", "");
 352
 353
 354     DocDeclStr(
 355         void , SetAppName(const wxString& appName),
 356         "", "");
 357
 358     DocDeclStr(
 359         void , SetVendorName(const wxString& vendorName),
 360         "", "");
 361
 362
 363     DocDeclStr(
 364         void , SetStyle(long style),
 365         "", "");
 366
 367     DocDeclStr(
 368         long , GetStyle() const,
 369         "", "");
 370
 371 };
 372
 373
 374 //---------------------------------------------------------------------------
 375
 376 DocStr(wxConfig,
 377 "This ConfigBase-derived class will use the registry on Windows,
 378 and will be a wx.FileConfig on other platforms.", "");
 379
 380 class wxConfig : public wxConfigBase {
 381 public:
 382     DocCtorStr(
 383         wxConfig(const wxString& appName = wxPyEmptyString,
 384                  const wxString& vendorName = wxPyEmptyString,
 385                  const wxString& localFilename = wxPyEmptyString,
 386                  const wxString& globalFilename = wxPyEmptyString,
 387                  long style = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
 388         "", "");
 389
 390     ~wxConfig();
 391 };
 392
 393
 394
 395
 396 DocStr(wxFileConfig,
 397        "This config class will use a file for storage on all platforms.", "");
 398
 399 class wxFileConfig : public wxConfigBase {
 400 public:
 401     DocCtorStr(
 402         wxFileConfig(const wxString& appName = wxPyEmptyString,
 403                      const wxString& vendorName = wxPyEmptyString,
 404                      const wxString& localFilename = wxPyEmptyString,
 405                      const wxString& globalFilename = wxPyEmptyString,
 406                      long style = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
 407         "", "");
 408
 409     ~wxFileConfig();
 410 };
 411
 412
 413 //---------------------------------------------------------------------------
 414
 415 DocStr(wxConfigPathChanger,
 416 "A handy little class which changes current path to the path of given
 417 entry and restores it in the destructoir: so if you declare a local
 418 variable of this type, you work in the entry directory and the path is
 419 automatically restored when the function returns.", "");
 420
 421 class wxConfigPathChanger
 422 {
 423 public:
 424     DocCtorStr(
 425         wxConfigPathChanger(const wxConfigBase *config, const wxString& entry),
 426         "", "");
 427
 428     ~wxConfigPathChanger();
 429
 430     DocDeclStr(
 431         const wxString& , Name() const,
 432         "Get the key name", "");
 433 };
 434
 435
 436 //---------------------------------------------------------------------------
 437
 438
 439
 440 DocDeclStr(
 441     wxString , wxExpandEnvVars(const wxString &sz),
 442     "Replace environment variables ($SOMETHING) with their values. The
 443 format is $VARNAME or ${VARNAME} where VARNAME contains alphanumeric
 444 characters and '_' only. '$' must be escaped ('\$') in order to be
 445 taken literally.", "");
 446
 447
 448
 449 //---------------------------------------------------------------------------