]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/config.tex
Made wxStubs compile on Unix.
[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's an abstract base class) and you'll always use one
5 of its derivations: wxIniConfig, wxFileConfig, wxRegConfig or
6 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, wxWindows provides a typedef wxConfig
14 which is mapped onto the native wxConfigBase implementation on the given
15 platform: i.e. wxRegConfig under Win32, wxIniConfig under Win16 and
16 wxFileConfig otherwise.
17
18 %See \helpref{config overview}{configoverview} for the descriptions of all
19 %features of this class.
20
21 \wxheading{Derived from}
22
23 No base class
24
25 \wxheading{Example}
26
27 Here is how you would typically use this class:
28
29 \begin{verbatim}
30 // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances
31 // portability of the code
32 wxConfig *config = new wxConfig("MyAppName");
33
34 wxString str;
35 if ( config->Read("LastPrompt", &str) ) {
36 // last prompt was found in the config file/registry and its value is now
37 // in str
38 ...
39 }
40 else {
41 // no last prompt...
42 }
43
44 // another example: using default values and the full path instead of just
45 // key name: if the key is not found , the value 17 is returned
46 long value = config->Read("/LastRun/CalculatedValues/MaxValue", -1);
47 ...
48 ...
49 ...
50 // at the end of the program we would save everything back
51 config->Write("LastPrompt", str);
52 config->Write("/LastRun/CalculatedValues/MaxValue", value);
53
54 // the changes will be written back automatically
55 delete config;
56 \end{verbatim}
57
58 This basic example, of course, doesn't show all wxConfig features, such as
59 enumerating, testing for existence and deleting the entries and groups of
60 entries in the config file, its abilities to automatically store the default
61 values or expand the environment variables on the fly. However, the main idea
62 is that using this class is easy and that it should normally do what you
63 expect it to.
64
65 NB: in the documentation of this class, the words "config file" also mean
66 "registry hive" for wxRegConfig and, generally speaking, might mean any
67 physical storage where a wxConfigBase-derived class stores its data.
68
69 \latexignore{\rtfignore{\wxheading{Function groups}}}
70
71 \membersection{Static functions}
72
73 These functions deal with the "default" config object. Although its usage is
74 not at all mandatory it may be convenient to use a global config object
75 instead of creating and deleting the local config objects each time you need
76 one (especially because creating a wxFileConfig object might be a time
77 consuming operation). In this case, you may create this global config object
78 in the very start of the program and {\it Set()} it as the default. Then, from
79 anywhere in your program, you may access it using the {\it Get()} function. Of
80 course, you should delete it on the program termination (otherwise, not only a
81 memory leak will result, but even more importantly the changes won't be
82 written back!).
83
84 As it happens, you may even further simplify the procedure described above:
85 you may forget about calling {\it Set()}. When {\it Get()} is called and there
86 is no current object, it will create one using {\it Create()} function. To
87 disable this behaviour {\it DontCreateOnDemand()} is provided.
88
89 \helpref{Set}{wxconfigbaseset}\\
90 \helpref{Get}{wxconfigbaseget}\\
91 \helpref{Create}{wxconfigbasecreate}\\
92 \helpref{DontCreateOnDemand}{wxconfigbasedontcreateondemand}
93
94 \membersection{Constructor and destructor}
95
96 \helpref{wxConfigBase}{wxconfigbasector}\\
97 \helpref{\destruct{wxConfigBase}}{wxconfigbasedtor}
98
99 \membersection{Path management}
100
101 %As explained in \helpref{config overview}{configoverview},
102 The config classes support a file system-like hierarchy of keys (files) and groups (directories).
103 As in the file system case, to specify a key in the config class you must use
104 a path to it. Config classes also support the notion of the current group,
105 which makes it possible to use the relative paths. To clarify all this, here
106 is an example (it's only for the sake of demonstration, it doesn't do anything
107 sensible!):
108
109 \begin{verbatim}
110 wxConfig *config = new wxConfig("FooBarApp");
111
112 // right now the current path is '/'
113 conf->Write("RootEntry", 1);
114
115 // go to some other place: if the group(s) don't exist, they will be created
116 conf->SetPath("/Group/Subgroup");
117
118 // create an entry in subgroup
119 conf->Write("SubgroupEntry", 3);
120
121 // '..' is understood
122 conf->Write("../GroupEntry", 2);
123 conf->SetPath("..");
124
125 wxASSERT( conf->Read("Subgroup/SubgroupEntry", 0l) == 3 );
126
127 // use absolute path: it's allowed, too
128 wxASSERT( conf->Read("/RootEntry", 0l) == 1 );
129 \end{verbatim}
130
131 {\it Warning}: it's probably a good idea to always restore the path to its
132 old value on function exit:
133
134 \begin{verbatim}
135 void foo(wxConfigBase *config)
136 {
137 wxString strOldPath = config->GetPath();
138
139 config->SetPath("/Foo/Data");
140 ...
141
142 config->SetPath(strOldPath);
143 }
144 \end{verbatim}
145
146 because otherwise the assert in the following example will surely fail
147 (we suppose here that {\it foo()} function is the same as above except that it
148 doesn't save and restore the path):
149
150 \begin{verbatim}
151 void bar(wxConfigBase *config)
152 {
153 config->Write("Test", 17);
154
155 foo(config);
156
157 // we're reading "/Foo/Data/Test" here! -1 will probably be returned...
158 wxASSERT( config->Read("Test", -1) == 17 );
159 }
160 \end{verbatim}
161
162 Finally, the path separator in wxConfigBase and derived classes is always '/',
163 regardless of the platform (i.e. it's {\bf not} '$\backslash\backslash$' under Windows).
164
165 \helpref{SetPath}{wxconfigbasesetpath}\\
166 \helpref{GetPath}{wxconfigbasegetpath}
167
168 \membersection{Enumeration}
169
170 The functions in this section allow to enumerate all entries and groups in the
171 config file. All functions here return FALSE when there are no more items.
172
173 You must pass the same index to GetNext and GetFirst (don't modify it).
174 Please note that it's {\bf not} the index of the current item (you will have
175 some great surprizes with wxRegConfig if you assume this) and you shouldn't
176 even look at it: it's just a "cookie" which stores the state of the
177 enumeration. It can't be stored inside the class because it would prevent you
178 from running several enumerations simultaneously, that's why you must pass it
179 explicitly.
180
181 Having said all this, enumerating the config entries/groups is very simple:
182
183 \begin{verbatim}
184 wxArrayString aNames;
185
186 // enumeration variables
187 wxString str;
188 long dummy;
189
190 // first enum all entries
191 bool bCont = config->GetFirstEntry(str, dummy);
192 while ( bCont ) {
193 aNames.Add(str);
194
195 bCont = GetConfig()->GetNextEntry(str, dummy);
196 }
197
198 ... we have all entry names in aNames...
199
200 // now all groups...
201 bCont = GetConfig()->GetFirstGroup(str, dummy);
202 while ( bCont ) {
203 aNames.Add(str);
204
205 bCont = GetConfig()->GetNextGroup(str, dummy);
206 }
207
208 ... we have all group (and entry) names in aNames...
209
210 \end{verbatim}
211
212 There are also functions to get the number of entries/subgroups without
213 actually enumerating them, but you will probably never need them.
214
215 \helpref{GetFirstGroup}{wxconfigbasegetfirstgroup}\\
216 \helpref{GetNextGroup}{wxconfigbasegetnextgroup}\\
217 \helpref{GetFirstEntry}{wxconfigbasegetfirstentry}\\
218 \helpref{GetNextEntry}{wxconfigbasegetnextentry}\\
219 \helpref{GetNumberOfEntries}{wxconfigbasegetnumberofentries}\\
220 \helpref{GetNumberOfGroups}{wxconfigbasegetnumberofgroups}
221
222 \membersection{Tests of existence}
223
224 \helpref{HasGroup}{wxconfigbasehasgroup}\\
225 \helpref{HasEntry}{wxconfigbasehasentry}\\
226 \helpref{Exists}{wxconfigbaseexists}
227
228 \membersection{Miscellaneous accessors}
229
230 \helpref{SetAppName}{wxconfigbasesetappname}\\
231 \helpref{GetAppName}{wxconfigbasegetappname}\\
232 \helpref{SetVendorName}{wxconfigbasesetvendorname}\\
233 \helpref{GetVendorName}{wxconfigbasegetvendorname}
234
235 \membersection{Key access}
236
237 These function are the core of wxConfigBase class: they allow you to read and
238 write config file data. All {\it Read} function take a default value which
239 will be returned if the specified key is not found in the config file.
240
241 Currently, only two types of data are supported: string and long (but it might
242 change in the near future). To work with other types: for {\it int} or {\it
243 bool} you can work with function taking/returning {\it long} and just use the
244 casts. Better yet, just use {\it long} for all variables which you're going to
245 save in the config file: chances are that \verb$sizeof(bool) == sizeof(int) == sizeof(long)$ anyhow on your system. For {\it float}, {\it double} and, in
246 general, any other type you'd have to translate them to/from string
247 representation and use string functions.
248
249 Try not to read long values into string variables and vice versa: although it
250 just might work with wxFileConfig, you will get a system error with
251 wxRegConfig because in the Windows registry the different types of entries are
252 indeed used.
253
254 Final remark: the {\it szKey} parameter for all these functions can contain an
255 arbitrary path (either relative or absolute), not just the key name.
256
257 \helpref{Read}{wxconfigbaseread}\\
258 \helpref{Write}{wxconfigbasewrite}\\
259 \helpref{Flush}{wxconfigbaseflush}
260
261 \membersection{Delete entries/groups}
262
263 The functions in this section delete entries and/or groups of entries from the
264 config file. {\it DeleteAll()} is especially useful if you want to erase all
265 traces of your program presence: for example, when you uninstall it.
266
267 \helpref{DeleteEntry}{wxconfigbasedeleteentry}\\
268 \helpref{DeleteGroup}{wxconfigbasedeletegroup}\\
269 \helpref{DeleteAll}{wxconfigbasedeleteall}
270
271 \membersection{Options}
272
273 Some aspects of wxConfigBase behaviour can be changed during run-time. The
274 first of them is the expansion of environment variables in the string values
275 read from the config file: for example, if you have the following in your
276 config file:
277
278 \begin{verbatim}
279 # config file for my program
280 UserData = $HOME/data
281
282 # the following syntax is valud only under Windows
283 UserData = %windir%\\data.dat
284 \end{verbatim}
285
286 the call to \verb$config->Read("UserData")$ will return something like
287 \verb$"/home/zeitlin/data"$ if you're lucky enough to run a Linux system ;-)
288
289 Although this feature is very useful, it may be annoying if you read a value
290 which containts '\$' or '\%' symbols (\% is used for environment variables
291 expansion under Windows) which are not used for environment variable
292 expansion. In this situation you may call SetExpandEnvVars(FALSE) just before
293 reading this value and SetExpandEnvVars(TRUE) just after. Another solution
294 would be to prefix the offending symbols with a backslash.
295
296 The following functions control this option:
297
298 \helpref{IsExpandingEnvVars}{wxconfigbaseisexpandingenvvars}\\
299 \helpref{SetExpandingEnvVars}{wxconfigbasesetexpandingenvvars}\\
300 \helpref{SetRecordDefaults}{wxconfigbasesetrecorddefaults}\\
301 \helpref{IsRecordingDefaults}{wxconfigbaseisrecordingdefaults}
302
303 %%%%% MEMBERS HERE %%%%%
304 \helponly{\insertatlevel{2}{
305
306 \wxheading{Members}
307
308 }}
309
310 \membersection{wxConfigBase::wxConfigBase}\label{wxconfigbasector}
311
312 \func{}{wxConfigBase}{\param{const wxString\& }{appName = wxEmptyString},
313 \param{const wxString\& }{vendorName = wxEmptyString},
314 \param{const wxString\& }{localFilename = wxEmptyString},
315 \param{const wxString\& }{globalFilename = wxEmptyString},
316 \param{long}{ style = 0}}
317
318 This is the default and only constructor of the wxConfigBase class, and derived classes.
319
320 \wxheading{Parameters}
321
322 \docparam{appName}{The application name. If this is empty, the class will normally
323 use \helpref{wxApp::GetAppName}{wxappgetappname} to set it. The application name
324 is used in the registry key on Windows, and can be used to deduce the local filename
325 parameter if that is missing.}
326
327 \docparam{vendorName}{The vendor name. If this is empty, it is assumed that
328 no vendor name is wanted, if this is optional for the current config class.
329 The vendor name is appended to the application name for wxRegConfig.}
330
331 \docparam{localFilename}{Some config classes require a local filename. If this is not
332 present, but required, the application name will be used instead.}
333
334 \docparam{globalFilename}{Some config classes require a global filename. If this is not
335 present, but required, the application name will be used instead.}
336
337 \docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and wxCONFIG\_USE\_GLOBAL\_FILE.
338 The style interpretation depends on the config class and is ignored by some.
339 For wxFileConfig, these styles determine whether a local or global config file is created or used.
340 If the flag is present but the parameter is empty, the parameter will be set to a default.
341 If the parameter is present but the style flag not, the relevant flag will be added to the style.}
342
343 \wxheading{Remarks}
344
345 By default, environment variable expansion is on and recording
346 defaults is off.
347
348 \membersection{wxConfigBase::\destruct{wxConfigBase}}\label{wxconfigbasedtor}
349
350 \func{}{\destruct{wxConfigBase}}{\void}
351
352 Empty but ensures that dtor of all derived classes is virtual.
353
354 \membersection{wxConfigBase::Create}\label{wxconfigbasecreate}
355
356 \func{static wxConfigBase *}{Create}{\void}
357
358 Create a new config object: this function will create the "best"
359 implementation of wxConfig available for the current platform, see
360 comments near the definition of wxCONFIG\_WIN32\_NATIVE for details. It returns
361 the created object and also sets it as the current one.
362
363 \membersection{wxConfigBase::DontCreateOnDemand}\label{wxconfigbasedontcreateondemand}
364
365 \func{void}{DontCreateOnDemand}{\void}
366
367 Calling this function will prevent {\it Get()} from automatically creating a
368 new config object if the current one is NULL. It might be useful to call it
369 near the program end to prevent new config object "accidental" creation.
370
371 \membersection{wxConfigBase::DeleteAll}\label{wxconfigbasedeleteall}
372
373 \func{bool}{DeleteAll}{\void}
374
375 Delete the whole underlying object (disk file, registry key, ...). Primarly
376 for use by desinstallation routine.
377
378 \membersection{wxConfigBase::DeleteEntry}\label{wxconfigbasedeleteentry}
379
380 \func{bool}{DeleteEntry}{\param{const wxString\& }{ key}, \param{bool}{ bDeleteGroupIfEmpty = TRUE}}
381
382 Deletes the specified entry and the group it belongs to if
383 it was the last key in it and the second parameter is true.
384
385 \membersection{wxConfigBase::DeleteGroup}\label{wxconfigbasedeletegroup}
386
387 \func{bool}{DeleteGroup}{\param{const wxString\& }{ key}}
388
389 Delete the group (with all subgroups)
390
391 \membersection{wxConfigBase::Exists}\label{wxconfigbaseexists}
392
393 \constfunc{bool}{Exists}{\param{wxString\& }{strName}}
394
395 returns TRUE if either a group or an entry with a given name exists
396
397 \membersection{wxConfigBase::Flush}\label{wxconfigbaseflush}
398
399 \func{bool}{Flush}{\param{bool }{bCurrentOnly = FALSE}}
400
401 permanently writes all changes (otherwise, they're only written from object's
402 destructor)
403
404 \membersection{wxConfigBase::Get}\label{wxconfigbaseget}
405
406 \func{wxConfigBase *}{Get}{\void}
407
408 Get the current config object. If there is no current object, creates one
409 (using {\it Create}) unless DontCreateOnDemand was called previously.
410
411 \membersection{wxConfigBase::GetAppName}\label{wxconfigbasegetappname}
412
413 \constfunc{wxString}{GetAppName}{\void}
414
415 Returns the application name.
416
417 \membersection{wxConfigBase::GetFirstGroup}\label{wxconfigbasegetfirstgroup}
418
419 \constfunc{bool}{GetFirstGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
420
421 Gets the first group.
422
423 \membersection{wxConfigBase::GetFirstEntry}\label{wxconfigbasegetfirstentry}
424
425 \constfunc{bool}{GetFirstEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
426
427 Gets the first entry.
428
429 \membersection{wxConfigBase::GetNextGroup}\label{wxconfigbasegetnextgroup}
430
431 \constfunc{bool}{GetNextGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
432
433 Gets the next group.
434
435 \membersection{wxConfigBase::GetNextEntry}\label{wxconfigbasegetnextentry}
436
437 \constfunc{bool}{GetNextEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
438
439 Gets the next entry.
440
441 \membersection{wxConfigBase::GetNumberOfEntries}\label{wxconfigbasegetnumberofentries}
442
443 \constfunc{uint }{GetNumberOfEntries}{\param{bool }{bRecursive = FALSE}}
444
445 \membersection{wxConfigBase::GetNumberOfGroups}\label{wxconfigbasegetnumberofgroups}
446
447 \constfunc{uint}{GetNumberOfGroups}{\param{bool }{bRecursive = FALSE}}
448
449 Get number of entries/subgroups in the current group, with or without
450 its subgroups.
451
452 \membersection{wxConfigBase::GetPath}\label{wxconfigbasegetpath}
453
454 \constfunc{const wxString\&}{GetPath}{\void}
455
456 Retrieve the current path (always as absolute path).
457
458 \membersection{wxConfigBase::GetVendorName}\label{wxconfigbasegetvendorname}
459
460 \constfunc{wxString}{GetVendorName}{\void}
461
462 Returns the vendor name.
463
464 \membersection{wxConfigBase::HasEntry}\label{wxconfigbasehasentry}
465
466 \constfunc{bool}{HasEntry}{\param{wxString\& }{strName}}
467
468 returns TRUE if the entry by this name exists
469
470 \membersection{wxConfigBase::HasGroup}\label{wxconfigbasehasgroup}
471
472 \constfunc{bool}{HasGroup}{\param{const wxString\& }{strName}}
473
474 returns TRUE if the group by this name exists
475
476 \membersection{wxConfigBase::IsExpandingEnvVars}\label{wxconfigbaseisexpandingenvvars}
477
478 \constfunc{bool}{IsExpandingEnvVars}{\void}
479
480 Returns TRUE if we are expanding environment variables in key values.
481
482 \membersection{wxConfigBase::IsRecordingDefaults}\label{wxconfigbaseisrecordingdefaults}
483
484 \func{bool}{IsRecordingDefaults}{\void} const
485
486 Returns TRUE if we are writing defaults back to the config file.
487
488 \membersection{wxConfigBase::Read}\label{wxconfigbaseread}
489
490 \constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}}
491
492 Read a string from the key, returning TRUE if the value was read. If the key was not
493 found, {\it str} is not changed.
494
495 \constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}, \param{const wxString\& }{defaultVal}}
496
497 Read a string from the key. The default value is returned if the key was not found.
498
499 Returns TRUE if value was really read, FALSE if the default was used.
500
501 \constfunc{wxString}{Read}{\param{const wxString\& }{key}, \param{const wxString\& }{defaultVal}}
502
503 Another version of {\it Read()}, returning the string value directly.
504
505 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l}}
506
507 Reads a long value, returning TRUE if the value was
508 found. If the value was not found, {\it l} is not changed.
509
510 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l}, \param{long}{ defaultVal}}
511
512 Reads a long value, returning TRUE if the value was
513 found. If the value was not found, {\it defaultVal} is used instead.
514
515 \constfunc{long }{Read}{\param{const wxString\& }{key}, \param{long}{ defaultVal}}
516
517 Reads a long value from the key and returns it. {\it defaultVal} is returned if the key is not
518 found.
519
520 NB: writing
521
522 {\small
523 \begin{verbatim}
524 conf->Read("key", 0);
525 \end{verbatim}
526 }
527
528 won't work because the call is ambiguous: compiler can not choose between two {\it Read} functions. Instead, write:
529
530 {\small
531 \begin{verbatim}
532 conf->Read("key", 0l);
533 \end{verbatim}
534 }
535
536 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}}
537
538 Reads a double value, returning TRUE if the value was
539 found. If the value was not found, {\it d} is not changed.
540
541 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}, \param{double}{ defaultVal}}
542
543 Reads a double value, returning TRUE if the value was
544 found. If the value was not found, {\it defaultVal} is used instead.
545
546 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ b}}
547
548 Reads a bool value, returning TRUE if the value was
549 found. If the value was not found, {\it b} is not changed.
550
551 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ d}, \param{bool}{ defaultVal}}
552
553 Reads a bool value, returning TRUE if the value was
554 found. If the value was not found, {\it defaultVal} is used instead.
555
556 \membersection{wxConfigBase::Set}\label{wxconfigbaseset}
557
558 \func{wxConfigBase *}{Set}{\param{wxConfigBase *}{pConfig}}
559
560 Sets the config object as the current one, returns the pointer to the previous
561 current object (both the parameter and returned value may be NULL)
562
563 \membersection{wxConfigBase::SetAppName}\label{wxconfigbasesetappname}
564
565 \func{void }{SetAppName}{\param{const wxString\&}{ appName}}
566
567 Sets the application name.
568
569 \membersection{wxConfigBase::SetExpandingEnvVars}\label{wxconfigbasesetexpandingenvvars}
570
571 \func{void}{SetExpandEnvVars }{\param{bool }{bDoIt = TRUE}}
572
573 Determine whether we wish to expand environment variables in key values.
574
575 \membersection{wxConfigBase::SetPath}\label{wxconfigbasesetpath}
576
577 \func{void}{SetPath}{\param{const wxString\& }{strPath}}
578
579 Set current path: if the first character is '/', it's the absolute path,
580 otherwise it's a relative path. '..' is supported. If the strPath
581 doesn't exist it is created.
582
583 \membersection{wxConfigBase::SetRecordDefaults}\label{wxconfigbasesetrecorddefaults}
584
585 \func{void}{SetRecordDefaults}{\param{bool }{bDoIt = TRUE}}
586
587 Sets whether defaults are written back to the config file.
588
589 If on (default is off) all default values are written back to the config file. This allows
590 the user to see what config options may be changed and is probably useful only
591 for wxFileConfig.
592
593 \membersection{wxConfigBase::SetVendorName}\label{wxconfigbasesetvendorname}
594
595 \func{void}{SetVendorName}{\param{const wxString\&}{ vendorName}}
596
597 Sets the vendor name.
598
599 \membersection{wxConfigBase::Write}\label{wxconfigbasewrite}
600
601 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{const wxString\& }{ value}}
602
603 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{long}{ value}}
604
605 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{double}{ value}}
606
607 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{bool}{ value}}
608
609 These functions write the specified value to the config file and
610 return TRUE on success.
611
612