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