]> git.saurik.com Git - wxWidgets.git/blame_incremental - wxPython/src/_config.i
demo tweaks
[wxWidgets.git] / wxPython / src / _config.i
... / ...
CommitLineData
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
48DocStr(wxConfigBase,
49"wx.ConfigBase class defines the basic interface of all config
50classes. It can not be used by itself (it is an abstract base
51class) and you will always use one of its derivations: wx.Config
52or wx.FileConfig.
53
54wx.ConfigBase organizes the items in a tree-like structure,
55modeled after the Unix/Dos filesystem. There are groups that act
56like directories and entries, key/value pairs that act like
57files. There is always one current group given by the current
58path. As in the file system case, to specify a key in the config
59class you must use a path to it. Config classes also support the
60notion of the current group, which makes it possible to use
61relative paths.
62
63Keys are pairs \"key_name = value\" where value may be of string,
64integer floating point or boolean, you can not store binary data
65without first encoding it as a string. For performance reasons
66items should be kept small, no more than a couple kilobytes.
67");
68
69
70class wxConfigBase {
71public:
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
375DocStr(wxConfig,
376"This ConfigBase-derived class will use the registry on Windows,
377and will be a wx.FileConfig on other platforms.");
378
379class wxConfig : public wxConfigBase {
380public:
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 = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
387 "");
388
389 ~wxConfig();
390};
391
392
393
394
395DocStr(wxFileConfig,
396 "This config class will use a file for storage on all platforms.");
397
398class wxFileConfig : public wxConfigBase {
399public:
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 = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
406 "");
407
408 ~wxFileConfig();
409};
410
411
412//---------------------------------------------------------------------------
413
414DocStr(wxConfigPathChanger,
415"A handy little class which changes current path to the path of
416given entry and restores it in the destructoir: so if you declare
417a local variable of this type, you work in the entry directory
418and the path is automatically restored when the function returns.");
419
420class wxConfigPathChanger
421{
422public:
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
439DocDeclStr(
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//---------------------------------------------------------------------------