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