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