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