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