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