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