]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/config.tex
fixed LaTeX compilation problems (part of patch 551210)
[wxWidgets.git] / docs / latex / wx / config.tex
1 \section{\class{wxConfigBase}}\label{wxconfigbase}
2
3 wxConfigBase class defines the basic interface of all config classes. It can
4 not be used by itself (it is an abstract base class) and you will always use one
5 of its derivations: wxIniConfig, wxFileConfig, wxRegConfig or any other.
6
7 However, usually you don't even need to know the precise nature of the class
8 you're working with but you would just use the wxConfigBase methods. This
9 allows you to write the same code regardless of whether you're working with
10 the registry under Win32 or text-based config files under Unix (or even
11 Windows 3.1 .INI files if you're really unlucky). To make writing the portable
12 code even easier, wxWindows provides a typedef wxConfig
13 which is mapped onto the native wxConfigBase implementation on the given
14 platform: i.e. wxRegConfig under Win32, wxIniConfig under Win16 and
15 wxFileConfig otherwise.
16
17 See \helpref{config overview}{wxconfigoverview} for the descriptions of all
18 features of this class.
19
20 It is highly recommended to use static functions {\it Get()} and/or {\it Set()},
21 so please have a \helpref{look at them.}{wxconfigstaticfunctions}
22
23 \wxheading{Derived from}
24
25 No base class
26
27 \wxheading{Include files}
28
29 <wx/config.h> (to let wxWindows choose a wxConfig class for your platform)\\
30 <wx/confbase.h> (base config class)\\
31 <wx/fileconf.h> (wxFileconfig class)\\
32 <wx/msw/regconf.h> (wxRegConfig class)\\
33 <wx/msw/iniconf.h> (wxIniConfig class)
34
35 \wxheading{Example}
36
37 Here is how you would typically use this class:
38
39 \begin{verbatim}
40 // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances
41 // portability of the code
42 wxConfig *config = new wxConfig("MyAppName");
43
44 wxString str;
45 if ( config->Read("LastPrompt", &str) ) {
46 // last prompt was found in the config file/registry and its value is now
47 // in str
48 ...
49 }
50 else {
51 // no last prompt...
52 }
53
54 // another example: using default values and the full path instead of just
55 // key name: if the key is not found , the value 17 is returned
56 long value = config->Read("/LastRun/CalculatedValues/MaxValue", 17);
57 ...
58 ...
59 ...
60 // at the end of the program we would save everything back
61 config->Write("LastPrompt", str);
62 config->Write("/LastRun/CalculatedValues/MaxValue", value);
63
64 // the changes will be written back automatically
65 delete config;
66 \end{verbatim}
67
68 This basic example, of course, doesn't show all wxConfig features, such as
69 enumerating, testing for existence and deleting the entries and groups of
70 entries in the config file, its abilities to automatically store the default
71 values or expand the environment variables on the fly. However, the main idea
72 is that using this class is easy and that it should normally do what you
73 expect it to.
74
75 NB: in the documentation of this class, the words "config file" also mean
76 "registry hive" for wxRegConfig and, generally speaking, might mean any
77 physical storage where a wxConfigBase-derived class stores its data.
78
79 \latexignore{\rtfignore{\wxheading{Function groups}}}
80
81 \membersection{Static functions}\label{wxconfigstaticfunctions}
82
83 These functions deal with the "default" config object. Although its usage is
84 not at all mandatory it may be convenient to use a global config object
85 instead of creating and deleting the local config objects each time you need
86 one (especially because creating a wxFileConfig object might be a time
87 consuming operation). In this case, you may create this global config object
88 in the very start of the program and {\it Set()} it as the default. Then, from
89 anywhere in your program, you may access it using the {\it Get()} function.
90 Note that wxWindows will delete this config object for you during the program
91 shutdown (from \helpref{wxApp::OnExit}{wxapponexit} to be precise) but you can
92 also do it yourself earlier if needed.
93
94 As it happens, you may even further simplify the procedure described above:
95 you may forget about calling {\it Set()}. When {\it Get()} is called and there
96 is no current object, it will create one using {\it Create()} function. To
97 disable this behaviour {\it DontCreateOnDemand()} is provided.
98
99 {\bf Note:} You should use either {\it Set()} or {\it Get()} because wxWindows
100 library itself would take advantage of it and could save various information
101 in it. For example \helpref{wxFontMapper}{wxfontmapper} or Unix version
102 of \helpref{wxFileDialog}{wxfiledialog} have ability to use wxConfig class.
103
104 \helpref{Set}{wxconfigbaseset}\\
105 \helpref{Get}{wxconfigbaseget}\\
106 \helpref{Create}{wxconfigbasecreate}\\
107 \helpref{DontCreateOnDemand}{wxconfigbasedontcreateondemand}
108
109 \membersection{Constructor and destructor}
110
111 \helpref{wxConfigBase}{wxconfigbasector}\\
112 \helpref{\destruct{wxConfigBase}}{wxconfigbasedtor}
113
114 \membersection{Path management}
115
116 As explained in \helpref{config overview}{wxconfigoverview}, the config classes
117 support a file system-like hierarchy of keys (files) and groups (directories).
118 As in the file system case, to specify a key in the config class you must use
119 a path to it. Config classes also support the notion of the current group,
120 which makes it possible to use the relative paths. To clarify all this, here
121 is an example (it is only for the sake of demonstration, it doesn't do anything
122 sensible!):
123
124 \begin{verbatim}
125 wxConfig *config = new wxConfig("FooBarApp");
126
127 // right now the current path is '/'
128 conf->Write("RootEntry", 1);
129
130 // go to some other place: if the group(s) don't exist, they will be created
131 conf->SetPath("/Group/Subgroup");
132
133 // create an entry in subgroup
134 conf->Write("SubgroupEntry", 3);
135
136 // '..' is understood
137 conf->Write("../GroupEntry", 2);
138 conf->SetPath("..");
139
140 wxASSERT( conf->Read("Subgroup/SubgroupEntry", 0l) == 3 );
141
142 // use absolute path: it is allowed, too
143 wxASSERT( conf->Read("/RootEntry", 0l) == 1 );
144 \end{verbatim}
145
146 {\it Warning}: it is probably a good idea to always restore the path to its
147 old value on function exit:
148
149 \begin{verbatim}
150 void foo(wxConfigBase *config)
151 {
152 wxString strOldPath = config->GetPath();
153
154 config->SetPath("/Foo/Data");
155 ...
156
157 config->SetPath(strOldPath);
158 }
159 \end{verbatim}
160
161 because otherwise the assert in the following example will surely fail
162 (we suppose here that {\it foo()} function is the same as above except that it
163 doesn't save and restore the path):
164
165 \begin{verbatim}
166 void bar(wxConfigBase *config)
167 {
168 config->Write("Test", 17);
169
170 foo(config);
171
172 // we're reading "/Foo/Data/Test" here! -1 will probably be returned...
173 wxASSERT( config->Read("Test", -1) == 17 );
174 }
175 \end{verbatim}
176
177 Finally, the path separator in wxConfigBase and derived classes is always '/',
178 regardless of the platform (i.e. it is {\bf not} '$\backslash\backslash$' under Windows).
179
180 \helpref{SetPath}{wxconfigbasesetpath}\\
181 \helpref{GetPath}{wxconfigbasegetpath}
182
183 \membersection{Enumeration}
184
185 The functions in this section allow to enumerate all entries and groups in the
186 config file. All functions here return FALSE when there are no more items.
187
188 You must pass the same index to GetNext and GetFirst (don't modify it).
189 Please note that it is {\bf not} the index of the current item (you will have
190 some great surprizes with wxRegConfig if you assume this) and you shouldn't
191 even look at it: it is just a "cookie" which stores the state of the
192 enumeration. It can't be stored inside the class because it would prevent you
193 from running several enumerations simultaneously, that's why you must pass it
194 explicitly.
195
196 Having said all this, enumerating the config entries/groups is very simple:
197
198 \begin{verbatim}
199 wxArrayString aNames;
200
201 // enumeration variables
202 wxString str;
203 long dummy;
204
205 // first enum all entries
206 bool bCont = config->GetFirstEntry(str, dummy);
207 while ( bCont ) {
208 aNames.Add(str);
209
210 bCont = GetConfig()->GetNextEntry(str, dummy);
211 }
212
213 ... we have all entry names in aNames...
214
215 // now all groups...
216 bCont = GetConfig()->GetFirstGroup(str, dummy);
217 while ( bCont ) {
218 aNames.Add(str);
219
220 bCont = GetConfig()->GetNextGroup(str, dummy);
221 }
222
223 ... we have all group (and entry) names in aNames...
224
225 \end{verbatim}
226
227 There are also functions to get the number of entries/subgroups without
228 actually enumerating them, but you will probably never need them.
229
230 \helpref{GetFirstGroup}{wxconfigbasegetfirstgroup}\\
231 \helpref{GetNextGroup}{wxconfigbasegetnextgroup}\\
232 \helpref{GetFirstEntry}{wxconfigbasegetfirstentry}\\
233 \helpref{GetNextEntry}{wxconfigbasegetnextentry}\\
234 \helpref{GetNumberOfEntries}{wxconfigbasegetnumberofentries}\\
235 \helpref{GetNumberOfGroups}{wxconfigbasegetnumberofgroups}
236
237 \membersection{Tests of existence}
238
239 \helpref{HasGroup}{wxconfigbasehasgroup}\\
240 \helpref{HasEntry}{wxconfigbasehasentry}\\
241 \helpref{Exists}{wxconfigbaseexists}\\
242 \helpref{GetEntryType}{wxconfigbasegetentrytype}
243
244 \membersection{Miscellaneous functions}
245
246 \helpref{GetAppName}{wxconfigbasegetappname}\\
247 \helpref{GetVendorName}{wxconfigbasegetvendorname}\\
248 \helpref{SetUmask}{wxfileconfigsetumask}
249
250 \membersection{Key access}
251
252 These function are the core of wxConfigBase class: they allow you to read and
253 write config file data. All {\it Read} function take a default value which
254 will be returned if the specified key is not found in the config file.
255
256 Currently, only two types of data are supported: string and long (but it might
257 change in the near future). To work with other types: for {\it int} or {\it
258 bool} you can work with function taking/returning {\it long} and just use the
259 casts. Better yet, just use {\it long} for all variables which you're going to
260 save in the config file: chances are that {\tt sizeof(bool) == sizeof(int) == sizeof(long)} anyhow on your system. For {\it float}, {\it double} and, in
261 general, any other type you'd have to translate them to/from string
262 representation and use string functions.
263
264 Try not to read long values into string variables and vice versa: although it
265 just might work with wxFileConfig, you will get a system error with
266 wxRegConfig because in the Windows registry the different types of entries are
267 indeed used.
268
269 Final remark: the {\it szKey} parameter for all these functions can contain an
270 arbitrary path (either relative or absolute), not just the key name.
271
272 \helpref{Read}{wxconfigbaseread}\\
273 \helpref{Write}{wxconfigbasewrite}\\
274 \helpref{Flush}{wxconfigbaseflush}
275
276 \membersection{Rename entries/groups}
277
278 The functions in this section allow to rename entries or subgroups of the
279 current group. They will return FALSE on error. typically because either the
280 entry/group with the original name doesn't exist, because the entry/group with
281 the new name already exists or because the function is not supported in this
282 wxConfig implementation.
283
284 \helpref{RenameEntry}{wxconfigbaserenameentry}\\
285 \helpref{RenameGroup}{wxconfigbaserenamegroup}
286
287 \membersection{Delete entries/groups}
288
289 The functions in this section delete entries and/or groups of entries from the
290 config file. {\it DeleteAll()} is especially useful if you want to erase all
291 traces of your program presence: for example, when you uninstall it.
292
293 \helpref{DeleteEntry}{wxconfigbasedeleteentry}\\
294 \helpref{DeleteGroup}{wxconfigbasedeletegroup}\\
295 \helpref{DeleteAll}{wxconfigbasedeleteall}
296
297 \membersection{Options}
298
299 Some aspects of wxConfigBase behaviour can be changed during run-time. The
300 first of them is the expansion of environment variables in the string values
301 read from the config file: for example, if you have the following in your
302 config file:
303
304 \begin{verbatim}
305 # config file for my program
306 UserData = $HOME/data
307
308 # the following syntax is valud only under Windows
309 UserData = %windir%\\data.dat
310 \end{verbatim}
311 % $ % help EMACS syntax highlighting...
312 the call to {\tt config->Read("UserData")} will return something like
313 {\tt "/home/zeitlin/data"} if you're lucky enough to run a Linux system ;-)
314
315 Although this feature is very useful, it may be annoying if you read a value
316 which containts '\$' or '\%' symbols (\% is used for environment variables
317 expansion under Windows) which are not used for environment variable
318 expansion. In this situation you may call SetExpandEnvVars(FALSE) just before
319 reading this value and SetExpandEnvVars(TRUE) just after. Another solution
320 would be to prefix the offending symbols with a backslash.
321
322 The following functions control this option:
323
324 \helpref{IsExpandingEnvVars}{wxconfigbaseisexpandingenvvars}\\
325 \helpref{SetExpandEnvVars}{wxconfigbasesetexpandenvvars}\\
326 \helpref{SetRecordDefaults}{wxconfigbasesetrecorddefaults}\\
327 \helpref{IsRecordingDefaults}{wxconfigbaseisrecordingdefaults}
328
329 %%%%% MEMBERS HERE %%%%%
330 \helponly{\insertatlevel{2}{
331
332 \wxheading{Members}
333
334 }}
335
336 \membersection{wxConfigBase::wxConfigBase}\label{wxconfigbasector}
337
338 \func{}{wxConfigBase}{\param{const wxString\& }{appName = wxEmptyString},
339 \param{const wxString\& }{vendorName = wxEmptyString},
340 \param{const wxString\& }{localFilename = wxEmptyString},
341 \param{const wxString\& }{globalFilename = wxEmptyString},
342 \param{long}{ style = 0}}
343
344 This is the default and only constructor of the wxConfigBase class, and
345 derived classes.
346
347 \wxheading{Parameters}
348
349 \docparam{appName}{The application name. If this is empty, the class will
350 normally use \helpref{wxApp::GetAppName}{wxappgetappname} to set it. The
351 application name is used in the registry key on Windows, and can be used to
352 deduce the local filename parameter if that is missing.}
353
354 \docparam{vendorName}{The vendor name. If this is empty, it is assumed that
355 no vendor name is wanted, if this is optional for the current config class.
356 The vendor name is appended to the application name for wxRegConfig.}
357
358 \docparam{localFilename}{Some config classes require a local filename. If this
359 is not present, but required, the application name will be used instead.}
360
361 \docparam{globalFilename}{Some config classes require a global filename. If
362 this is not present, but required, the application name will be used instead.}
363
364 \docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and
365 wxCONFIG\_USE\_GLOBAL\_FILE. The style interpretation depends on the config
366 class and is ignored by some. For wxFileConfig, these styles determine whether
367 a local or global config file is created or used. If the flag is present but
368 the parameter is empty, the parameter will be set to a default. If the
369 parameter is present but the style flag not, the relevant flag will be added
370 to the style. For wxFileConfig you can also add wxCONFIG\_USE\_RELATIVE\_PATH
371 by logicaly or'ing it to either of the \_FILE options to tell wxFileConfig to
372 use relative instead of absolute paths. }
373
374 \wxheading{Remarks}
375
376 By default, environment variable expansion is on and recording defaults is
377 off.
378
379 \membersection{wxConfigBase::\destruct{wxConfigBase}}\label{wxconfigbasedtor}
380
381 \func{}{\destruct{wxConfigBase}}{\void}
382
383 Empty but ensures that dtor of all derived classes is virtual.
384
385 \membersection{wxConfigBase::Create}\label{wxconfigbasecreate}
386
387 \func{static wxConfigBase *}{Create}{\void}
388
389 Create a new config object: this function will create the "best"
390 implementation of wxConfig available for the current platform, see comments
391 near the definition of wxCONFIG\_WIN32\_NATIVE for details. It returns the
392 created object and also sets it as the current one.
393
394 \membersection{wxConfigBase::DontCreateOnDemand}\label{wxconfigbasedontcreateondemand}
395
396 \func{void}{DontCreateOnDemand}{\void}
397
398 Calling this function will prevent {\it Get()} from automatically creating a
399 new config object if the current one is NULL. It might be useful to call it
400 near the program end to prevent new config object "accidental" creation.
401
402 \membersection{wxConfigBase::DeleteAll}\label{wxconfigbasedeleteall}
403
404 \func{bool}{DeleteAll}{\void}
405
406 Delete the whole underlying object (disk file, registry key, ...). Primarly
407 for use by desinstallation routine.
408
409 \membersection{wxConfigBase::DeleteEntry}\label{wxconfigbasedeleteentry}
410
411 \func{bool}{DeleteEntry}{\param{const wxString\& }{ key}, \param{bool}{ bDeleteGroupIfEmpty = TRUE}}
412
413 Deletes the specified entry and the group it belongs to if it was the last key
414 in it and the second parameter is true.
415
416 \membersection{wxConfigBase::DeleteGroup}\label{wxconfigbasedeletegroup}
417
418 \func{bool}{DeleteGroup}{\param{const wxString\& }{ key}}
419
420 Delete the group (with all subgroups)
421
422 \membersection{wxConfigBase::Exists}\label{wxconfigbaseexists}
423
424 \constfunc{bool}{Exists}{\param{wxString\& }{strName}}
425
426 returns TRUE if either a group or an entry with a given name exists
427
428 \membersection{wxConfigBase::Flush}\label{wxconfigbaseflush}
429
430 \func{bool}{Flush}{\param{bool }{bCurrentOnly = FALSE}}
431
432 permanently writes all changes (otherwise, they're only written from object's
433 destructor)
434
435 \membersection{wxConfigBase::Get}\label{wxconfigbaseget}
436
437 \func{static wxConfigBase *}{Get}{\param{bool }{CreateOnDemand = TRUE}}
438
439 Get the current config object. If there is no current object and
440 {\it CreateOnDemand} is TRUE, creates one
441 (using {\it Create}) unless DontCreateOnDemand was called previously.
442
443 \membersection{wxConfigBase::GetAppName}\label{wxconfigbasegetappname}
444
445 \constfunc{wxString}{GetAppName}{\void}
446
447 Returns the application name.
448
449 \membersection{wxConfigBase::GetEntryType}\label{wxconfigbasegetentrytype}
450
451 \constfunc{enum wxConfigBase::EntryType}{GetEntryType}{\param{const wxString\& }{name}}
452
453 Returns the type of the given entry or {\it Unknown} if the entry doesn't
454 exist. This function should be used to decide which version of Read() should
455 be used because some of wxConfig implementations will complain about type
456 mismatch otherwise: e.g., an attempt to read a string value from an integer
457 key with wxRegConfig will fail.
458
459 The result is an element of enum EntryType:
460
461 \begin{verbatim}
462 enum EntryType
463 {
464 Unknown,
465 String,
466 Boolean,
467 Integer,
468 Float
469 };
470 \end{verbatim}
471
472 \membersection{wxConfigBase::GetFirstGroup}\label{wxconfigbasegetfirstgroup}
473
474 \constfunc{bool}{GetFirstGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
475
476 Gets the first group.
477
478 \pythonnote{The wxPython version of this method returns a 3-tuple
479 consisting of the continue flag, the value string, and the index for
480 the next call.}
481
482 \perlnote{In wxPerl this method takes no arguments and returns a 3-element
483 list {\tt ( continue, str, index )}.}
484
485 \membersection{wxConfigBase::GetFirstEntry}\label{wxconfigbasegetfirstentry}
486
487 \constfunc{bool}{GetFirstEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
488
489 Gets the first entry.
490
491 \pythonnote{The wxPython version of this method returns a 3-tuple
492 consisting of the continue flag, the value string, and the index for
493 the next call.}
494
495 \perlnote{In wxPerl this method takes no arguments and returns a 3-element
496 list {\tt ( continue, str, index )}.}
497
498 \membersection{wxConfigBase::GetNextGroup}\label{wxconfigbasegetnextgroup}
499
500 \constfunc{bool}{GetNextGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
501
502 Gets the next group.
503
504 \pythonnote{The wxPython version of this method returns a 3-tuple
505 consisting of the continue flag, the value string, and the index for
506 the next call.}
507
508 \perlnote{In wxPerl this method only takes the {\tt index} parameter
509 and returns a 3-element list {\tt ( continue, str, index )}.}
510
511 \membersection{wxConfigBase::GetNextEntry}\label{wxconfigbasegetnextentry}
512
513 \constfunc{bool}{GetNextEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
514
515 Gets the next entry.
516
517 \pythonnote{The wxPython version of this method returns a 3-tuple
518 consisting of the continue flag, the value string, and the index for
519 the next call.}
520
521 \perlnote{In wxPerl this method only takes the {\tt index} parameter
522 and returns a 3-element list {\tt ( continue, str, index )}.}
523
524 \membersection{wxConfigBase::GetNumberOfEntries}\label{wxconfigbasegetnumberofentries}
525
526 \constfunc{uint }{GetNumberOfEntries}{\param{bool }{bRecursive = FALSE}}
527
528 \membersection{wxConfigBase::GetNumberOfGroups}\label{wxconfigbasegetnumberofgroups}
529
530 \constfunc{uint}{GetNumberOfGroups}{\param{bool }{bRecursive = FALSE}}
531
532 Get number of entries/subgroups in the current group, with or without its
533 subgroups.
534
535 \membersection{wxConfigBase::GetPath}\label{wxconfigbasegetpath}
536
537 \constfunc{const wxString\&}{GetPath}{\void}
538
539 Retrieve the current path (always as absolute path).
540
541 \membersection{wxConfigBase::GetVendorName}\label{wxconfigbasegetvendorname}
542
543 \constfunc{wxString}{GetVendorName}{\void}
544
545 Returns the vendor name.
546
547 \membersection{wxConfigBase::HasEntry}\label{wxconfigbasehasentry}
548
549 \constfunc{bool}{HasEntry}{\param{wxString\& }{strName}}
550
551 returns TRUE if the entry by this name exists
552
553 \membersection{wxConfigBase::HasGroup}\label{wxconfigbasehasgroup}
554
555 \constfunc{bool}{HasGroup}{\param{const wxString\& }{strName}}
556
557 returns TRUE if the group by this name exists
558
559 \membersection{wxConfigBase::IsExpandingEnvVars}\label{wxconfigbaseisexpandingenvvars}
560
561 \constfunc{bool}{IsExpandingEnvVars}{\void}
562
563 Returns TRUE if we are expanding environment variables in key values.
564
565 \membersection{wxConfigBase::IsRecordingDefaults}\label{wxconfigbaseisrecordingdefaults}
566
567 \constfunc{bool}{IsRecordingDefaults}{\void}
568
569 Returns TRUE if we are writing defaults back to the config file.
570
571 \membersection{wxConfigBase::Read}\label{wxconfigbaseread}
572
573 \constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}}
574
575 Read a string from the key, returning TRUE if the value was read. If the key
576 was not found, {\it str} is not changed.
577
578 \constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}, \param{const wxString\& }{defaultVal}}
579
580 Read a string from the key. The default value is returned if the key was not
581 found.
582
583 Returns TRUE if value was really read, FALSE if the default was used.
584
585 \constfunc{wxString}{Read}{\param{const wxString\& }{key}, \param{const
586 wxString\& }{defaultVal}}
587
588 Another version of {\it Read()}, returning the string value directly.
589
590 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l}}
591
592 Reads a long value, returning TRUE if the value was found. If the value was
593 not found, {\it l} is not changed.
594
595 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l},
596 \param{long}{ defaultVal}}
597
598 Reads a long value, returning TRUE if the value was found. If the value was
599 not found, {\it defaultVal} is used instead.
600
601 \constfunc{long }{Read}{\param{const wxString\& }{key}, \param{long}{ defaultVal}}
602
603 Reads a long value from the key and returns it. {\it defaultVal} is returned
604 if the key is not found.
605
606 NB: writing
607
608 {\small
609 \begin{verbatim}
610 conf->Read("key", 0);
611 \end{verbatim}
612 }
613
614 won't work because the call is ambiguous: compiler can not choose between two
615 {\it Read} functions. Instead, write:
616
617 {\small
618 \begin{verbatim}
619 conf->Read("key", 0l);
620 \end{verbatim}
621 }
622
623 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}}
624
625 Reads a double value, returning TRUE if the value was found. If the value was
626 not found, {\it d} is not changed.
627
628 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d},
629 \param{double}{ defaultVal}}
630
631 Reads a double value, returning TRUE if the value was found. If the value was
632 not found, {\it defaultVal} is used instead.
633
634 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ b}}
635
636 Reads a bool value, returning TRUE if the value was found. If the value was
637 not found, {\it b} is not changed.
638
639 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ d},
640 \param{bool}{ defaultVal}}
641
642 Reads a bool value, returning TRUE if the value was found. If the value was
643 not found, {\it defaultVal} is used instead.
644
645 \pythonnote{In place of a single overloaded method name, wxPython
646 implements the following methods:\par
647 \indented{2cm}{\begin{twocollist}
648 \twocolitem{{\bf Read(key, default="")}}{Returns a string.}
649 \twocolitem{{\bf ReadInt(key, default=0)}}{Returns an int.}
650 \twocolitem{{\bf ReadFloat(key, default=0.0)}}{Returns a floating point number.}
651 \end{twocollist}}
652 }
653
654 \perlnote{In place of a single overloaded method, wxPerl uses:\par
655 \indented{2cm}{\begin{twocollist}
656 \twocolitem{{\bf Read(key, default="")}}{Returns a string}
657 \twocolitem{{\bf ReadInt(key, default=0)}}{Returns an integer}
658 \twocolitem{{\bf ReadFloat(key, default=0.0)}}{Returns a floating point number}
659 \twocolitem{{\bf ReadBool(key, default=0)}}{Returns a boolean}
660 \end{twocollist}
661 }}
662
663 \membersection{wxConfigBase::RenameEntry}\label{wxconfigbaserenameentry}
664
665 \func{bool}{RenameEntry}{\param{const wxString\& }{ oldName}, \param{const wxString\& }{ newName}}
666
667 Renames an entry in the current group. The entries names (both the old and
668 the new one) shouldn't contain backslashes, i.e. only simple names and not
669 arbitrary paths are accepted by this function.
670
671 Returns FALSE if the {\it oldName} doesn't exist or if {\it newName} already
672 exists.
673
674 \membersection{wxConfigBase::RenameGroup}\label{wxconfigbaserenamegroup}
675
676 \func{bool}{RenameGroup}{\param{const wxString\& }{ oldName}, \param{const wxString\& }{ newName}}
677
678 Renames a subgroup of the current group. The subgroup names (both the old and
679 the new one) shouldn't contain backslashes, i.e. only simple names and not
680 arbitrary paths are accepted by this function.
681
682 Returns FALSE if the {\it oldName} doesn't exist or if {\it newName} already
683 exists.
684
685 \membersection{wxConfigBase::Set}\label{wxconfigbaseset}
686
687 \func{static wxConfigBase *}{Set}{\param{wxConfigBase *}{pConfig}}
688
689 Sets the config object as the current one, returns the pointer to the previous
690 current object (both the parameter and returned value may be NULL)
691
692 \membersection{wxConfigBase::SetExpandEnvVars}\label{wxconfigbasesetexpandenvvars}
693
694 \func{void}{SetExpandEnvVars }{\param{bool }{bDoIt = TRUE}}
695
696 Determine whether we wish to expand environment variables in key values.
697
698 \membersection{wxConfigBase::SetPath}\label{wxconfigbasesetpath}
699
700 \func{void}{SetPath}{\param{const wxString\& }{strPath}}
701
702 Set current path: if the first character is '/', it is the absolute path,
703 otherwise it is a relative path. '..' is supported. If the strPath doesn't
704 exist it is created.
705
706 \membersection{wxConfigBase::SetRecordDefaults}\label{wxconfigbasesetrecorddefaults}
707
708 \func{void}{SetRecordDefaults}{\param{bool }{bDoIt = TRUE}}
709
710 Sets whether defaults are recorded to the config file whenever an attempt to
711 read read the value which is not present in it is done.
712
713 If on (default is off) all default values for the settings used by the program
714 are written back to the config file. This allows the user to see what config
715 options may be changed and is probably useful only for wxFileConfig.
716
717 \membersection{wxConfigBase::SetUmask}\label{wxfileconfigsetumask}
718
719 \func{void}{SetUmask}{\param{int }{mode}}
720
721 {\bf NB:} this function is not in the base wxConfigBase class but is only
722 implemented in wxFileConfig. Moreover, this function is Unix-specific and
723 doesn't do anything on other platforms.
724
725 SetUmask() allows to set the mode to be used for the config file creation.
726 For example, to create a config file which is not readable by other users
727 (useful if it stores some sensitive information, such as passwords), you
728 should do {\tt SetUmask(0077)}.
729
730 \membersection{wxConfigBase::Write}\label{wxconfigbasewrite}
731
732 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{const wxString\& }{
733 value}}
734
735 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{long}{ value}}
736
737 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{double}{ value}}
738
739 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{bool}{ value}}
740
741 These functions write the specified value to the config file and return TRUE
742 on success.
743
744 \pythonnote{In place of a single overloaded method name, wxPython
745 implements the following methods:\par
746 \indented{2cm}{\begin{twocollist}
747 \twocolitem{{\bf Write(key, value)}}{Writes a string.}
748 \twocolitem{{\bf WriteInt(key, value)}}{Writes an int.}
749 \twocolitem{{\bf WriteFloat(key, value)}}{Writes a floating point number.}
750 \end{twocollist}}
751 }
752
753 \perlnote{In place of a single overloaded method, wxPerl uses:\par
754 \indented{2cm}{\begin{twocollist}
755 \twocolitem{{\bf Write(key, value)}}{Writes a string}
756 \twocolitem{{\bf WriteInt(key, value)}}{Writes an integer}
757 \twocolitem{{\bf WriteFloat(key, value)}}{Writes a floating point number}
758 \twocolitem{{\bf WriteBool(key, value)}}{Writes a boolean}
759 \end{twocollist}
760 }}