]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/function.tex
Minor tweek for WXPM
[wxWidgets.git] / docs / latex / wx / function.tex
CommitLineData
a660d684
KB
1\chapter{Functions}\label{functions}
2\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
3\setfooter{\thepage}{}{}{}{}{\thepage}
4
5The functions defined in wxWindows are described here.
6
7\section{File functions}\label{filefunctions}
8
954b8ae6
JS
9\wxheading{Include files}
10
11<wx/utils.h>
12
13\wxheading{See also}
14
15\helpref{wxPathList}{wxpathlist}
a660d684
KB
16
17\membersection{::wxDirExists}
18
19\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
20
21Returns TRUE if the directory exists.
22
23\membersection{::wxDos2UnixFilename}
24
25\func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}}
26
e2a6f233 27Converts a DOS to a Unix filename by replacing backslashes with forward
a660d684
KB
28slashes.
29
30\membersection{::wxFileExists}
31
32\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
33
e8b04eb3
RR
34Returns TRUE if the file exists. It also returns TRUE if the file is
35a directory.
a660d684
KB
36
37\membersection{::wxFileNameFromPath}
38
39\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
40
532372a3
JS
41\func{char*}{wxFileNameFromPath}{\param{char* }{path}}
42
43Returns the filename for a full path. The second form returns a pointer to
44temporary storage that should not be deallocated.
a660d684
KB
45
46\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
47
532372a3 48\func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}}
a660d684
KB
49
50This function does directory searching; returns the first file
532372a3 51that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
9c884972
RR
52get the next matching file. Neither will report the current directory "." or the
53parent directory "..".
a660d684
KB
54
55{\it spec} may contain wildcards.
56
9c884972 57{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
a660d684 58
a660d684
KB
59For example:
60
61\begin{verbatim}
62 wxString f = wxFindFirstFile("/home/project/*.*");
58503787 63 while ( !f.IsEmpty() )
a660d684
KB
64 {
65 ...
66 f = wxFindNextFile();
67 }
68\end{verbatim}
69
70\membersection{::wxFindNextFile}\label{wxfindnextfile}
71
5ab656cd 72\func{wxString}{wxFindNextFile}{\void}
a660d684
KB
73
74Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
75
5ab656cd
VZ
76See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
77
631f1bfe
JS
78\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
79
80\func{wxString}{wxGetOSDirectory}{\void}
81
82Returns the Windows directory under Windows; on other platforms returns the empty string.
83
b5a4a47d
SB
84\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
85
86\func{void}{wxInitAllImageHandlers}{\void}
87
88Adds some common image format handlers, which, depending on wxWindows
89configuration, can be handlers for BMP (loading) (always installed), GIF
fc9c7c09 90(loading), PCX (loading), PNM (loading and saving as raw
b5a4a47d
SB
91rgb), PNG (loading and saving), JPEG (loading and saving), file formats.
92
93See also: \helpref{wxImage}{wximage} \helpref{wxImageHandler}{wximagehandler}
94
a660d684
KB
95\membersection{::wxIsAbsolutePath}
96
97\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
98
99Returns TRUE if the argument is an absolute filename, i.e. with a slash
100or drive name at the beginning.
101
102\membersection{::wxPathOnly}
103
104\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
105
532372a3 106Returns the directory part of the filename.
a660d684
KB
107
108\membersection{::wxUnix2DosFilename}
109
110\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
111
e2a6f233 112Converts a Unix to a DOS filename by replacing forward
a660d684
KB
113slashes with backslashes.
114
115\membersection{::wxConcatFiles}
116
117\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
118\param{const wxString\& }{file3}}
119
120Concatenates {\it file1} and {\it file2} to {\it file3}, returning
121TRUE if successful.
122
123\membersection{::wxCopyFile}
124
125\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
126
127Copies {\it file1} to {\it file2}, returning TRUE if successful.
128
7af89395
VZ
129\membersection{::wxGetCwd}\label{wxgetcwd}
130
131\func{wxString}{wxGetCwd}{\void}
132
133Returns a string containing the current (or working) directory.
134
a660d684
KB
135\membersection{::wxGetWorkingDirectory}
136
532372a3 137\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
a660d684 138
7af89395
VZ
139This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
140
a660d684
KB
141Copies the current working directory into the buffer if supplied, or
142copies the working directory into new storage (which you must delete yourself)
143if the buffer is NULL.
144
145{\it sz} is the size of the buffer if supplied.
146
147\membersection{::wxGetTempFileName}
148
532372a3 149\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}}
a660d684 150
c0ab6adf
JS
151\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
152
a660d684
KB
153Makes a temporary filename based on {\it prefix}, opens and closes the file,
154and places the name in {\it buf}. If {\it buf} is NULL, new store
155is allocated for the temporary filename using {\it new}.
156
157Under Windows, the filename will include the drive and name of the
158directory allocated for temporary files (usually the contents of the
e2a6f233 159TEMP variable). Under Unix, the {\tt /tmp} directory is used.
a660d684
KB
160
161It is the application's responsibility to create and delete the file.
162
163\membersection{::wxIsWild}\label{wxiswild}
164
165\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
166
167Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
168
169\membersection{::wxMatchWild}\label{wxmatchwild}
170
171\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
172
173Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it
174dot\_special}\/ is TRUE, filenames beginning with a dot are not matched
175with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
176
177\membersection{::wxMkdir}
178
1a33c3ba 179\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
a660d684
KB
180
181Makes the directory {\it dir}, returning TRUE if successful.
182
1a33c3ba
VZ
183{\it perm} is the access mask for the directory for the systems on which it is
184supported (Unix) and doesn't have effect for the other ones.
185
a660d684
KB
186\membersection{::wxRemoveFile}
187
188\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
189
190Removes {\it file}, returning TRUE if successful.
191
192\membersection{::wxRenameFile}
193
194\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
195
196Renames {\it file1} to {\it file2}, returning TRUE if successful.
197
198\membersection{::wxRmdir}
199
200\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
201
202Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS.
203
204The {\it flags} parameter is reserved for future use.
205
206\membersection{::wxSetWorkingDirectory}
207
208\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
209
210Sets the current working directory, returning TRUE if the operation succeeded.
211Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
212
d37fd2fa
VZ
213\membersection{::wxSplitPath}\label{wxsplitfunction}
214
215\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{const wxString *}{ path}, \param{const wxString *}{ name}, \param{const wxString *}{ ext}}
216
217This function splits a full file name into components: the path (including possible disk/drive
218specification under Windows), the base name and the extension. Any of the output parameters
219({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
220a particular component.
221
222wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
223Windows, however it will not consider backslashes as path separators under Unix (where backslash
224is a valid character in a filename).
225
226On entry, {\it fullname} should be non NULL (it may be empty though).
227
228On return, {\it path} contains the file path (without the trailing separator), {\it name}
229contains the file name and {\it ext} contains the file extension without leading dot. All
230three of them may be empty if the corresponding component is. The old contents of the
231strings pointed to by these parameters will be overwritten in any case (if the pointers
232are not NULL).
233
ed93168b
VZ
234\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
235
236\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
237
238Copies the given file to {\it stream}. Useful when converting an old application to
239use streams (within the document/view framework, for example).
240
241Use of this function requires the file wx\_doc.h to be included.
242
243\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
244
245\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
246
247Copies the given stream to the file {\it filename}. Useful when converting an old application to
248use streams (within the document/view framework, for example).
249
250Use of this function requires the file wx\_doc.h to be included.
251
d524e22d
VZ
252\section{Network functions}\label{networkfunctions}
253
254\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
255
256\func{wxString}{wxGetFullHostName}{\void}
257
258Returns the FQDN (fully qualified domain host name) or an empty string on
259error.
260
261See also: \helpref{wxGetHostName}{wxgethostname}
262
263\wxheading{Include files}
264
265<wx/utils.h>
266
267\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
268
269\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
270
271Copies the user's email address into the supplied buffer, by
272concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
273and \helpref{wxGetUserId}{wxgetuserid}.
274
275Returns TRUE if successful, FALSE otherwise.
276
277\wxheading{Include files}
278
279<wx/utils.h>
280
281\membersection{::wxGetHostName}\label{wxgethostname}
282
283\func{wxString}{wxGetHostName}{\void}
284\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
285
286Copies the current host machine's name into the supplied buffer. Please note
287that the returned name is {\it not} fully qualified, i.e. it does not include
288the domain name.
289
290Under Windows or NT, this function first looks in the environment
291variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
292in the {\bf wxWindows} section of the WIN.INI file is tried.
293
294The first variant of this function returns the hostname if successful or an
295empty string otherwise. The second (deprecated) function returns TRUE
296if successful, FALSE otherwise.
297
298See also: \helpref{wxGetFullHostName}{wxgetfullhostname}
299
300\wxheading{Include files}
301
302<wx/utils.h>
303
304\section{User identification}\label{useridfunctions}
305
306\membersection{::wxGetUserId}\label{wxgetuserid}
307
308\func{wxString}{wxGetUserId}{\void}
309\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
310
311This function returns the "user id" also known as "login name" under Unix i.e.
312something like "jsmith". It uniquely identifies the current user (on this system).
313
314Under Windows or NT, this function first looks in the environment
315variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
316in the {\bf wxWindows} section of the WIN.INI file is tried.
317
318The first variant of this function returns the login name if successful or an
319empty string otherwise. The second (deprecated) function returns TRUE
320if successful, FALSE otherwise.
321
322See also: \helpref{wxGetUserName}{wxgetusername}
323
324\wxheading{Include files}
325
326<wx/utils.h>
327
328\membersection{::wxGetUserName}\label{wxgetusername}
329
330\func{wxString}{wxGetUserName}{\void}
331\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
332
333This function returns the full user name (something like "Mr. John Smith").
334
335Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
336in the {\bf wxWindows} section of the WIN.INI file. If PenWindows
337is running, the entry {\bf Current} in the section {\bf User} of
338the PENWIN.INI file is used.
339
340The first variant of this function returns the user name if successful or an
341empty string otherwise. The second (deprecated) function returns TRUE
342if successful, FALSE otherwise.
343
344See also: \helpref{wxGetUserId}{wxgetuserid}
345
346\wxheading{Include files}
347
348<wx/utils.h>
349
a660d684
KB
350\section{String functions}
351
352\membersection{::copystring}
353
354\func{char*}{copystring}{\param{const char* }{s}}
355
356Makes a copy of the string {\it s} using the C++ new operator, so it can be
357deleted with the {\it delete} operator.
358
359\membersection{::wxStringMatch}
360
361\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
362 \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
363
364Returns TRUE if the substring {\it s1} is found within {\it s2},
365ignoring case if {\it exact} is FALSE. If {\it subString} is FALSE,
366no substring matching is done.
367
368\membersection{::wxStringEq}\label{wxstringeq}
369
370\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
371
372A macro defined as:
373
374\begin{verbatim}
375#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
376\end{verbatim}
377
ed93168b 378\membersection{::IsEmpty}\label{isempty}
a660d684 379
ed93168b 380\func{bool}{IsEmpty}{\param{const char *}{ p}}
a660d684 381
ed93168b
VZ
382Returns TRUE if the string is empty, FALSE otherwise. It is safe to pass NULL
383pointer to this function and it will return TRUE for it.
a660d684 384
ed93168b 385\membersection{::Stricmp}\label{stricmp}
a660d684 386
ed93168b 387\func{int}{Stricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
a660d684 388
ed93168b
VZ
389Returns a negative value, 0, or positive value if {\it p1} is less than, equal
390to or greater than {\it p2}. The comparison is case-insensitive.
a660d684 391
ed93168b
VZ
392This function complements the standard C function {\it strcmp()} which performs
393case-sensitive comparison.
a660d684 394
ed93168b
VZ
395\membersection{::Strlen}\label{strlen}
396
397\func{size\_t}{Strlen}{\param{const char *}{ p}}
398
399This is a safe version of standard function {\it strlen()}: it does exactly the
400same thing (i.e. returns the length of the string) except that it returns 0 if
401{\it p} is the NULL pointer.
402
403\membersection{::wxGetTranslation}\label{wxgettranslation}
404
405\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
406
407This function returns the translation of string {\it str} in the current
408\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
409message catalogs (see \helpref{i18n overview}{internationalization}), the
410original string is returned. In debug build, an error message is logged - this
411should help to find the strings which were not yet translated. As this function
412is used very often, an alternative syntax is provided: the \_() macro is
413defined as wxGetTranslation().
a660d684
KB
414
415\section{Dialog functions}\label{dialogfunctions}
416
417Below are a number of convenience functions for getting input from the
418user or displaying messages. Note that in these functions the last three
419parameters are optional. However, it is recommended to pass a parent frame
420parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
421the front when the dialog box is popped up.
422
c50f1fb9
VZ
423\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
424
0e528b99
JS
425\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
426 \param{size\_t }{currentTip}}
c50f1fb9
VZ
427
428This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
429used with \helpref{wxShowTip}{wxshowtip}.
430
431\docparam{filename}{The name of the file containing the tips, one per line}
432\docparam{currentTip}{The index of the first tip to show - normally this index
0e528b99 433is remembered between the 2 program runs.}
c50f1fb9
VZ
434
435\wxheading{See also:}
436
437\helpref{Tips overview}{tipsoverview}
438
439\wxheading{Include files}
440
441<wx/tipdlg.h>
442
a660d684
KB
443\membersection{::wxFileSelector}\label{wxfileselector}
444
f5ee2e5f 445\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
0e528b99
JS
446 \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\
447 \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = ""},\\
448 \param{int}{ x = -1}, \param{int}{ y = -1}}
a660d684
KB
449
450Pops up a file selector box. In Windows, this is the common file selector
451dialog. In X, this is a file selector box with somewhat less functionality.
452The path and filename are distinct elements of a full file pathname.
706bb5f9 453If path is empty, the current directory will be used. If filename is empty,
a660d684
KB
454no default filename will be supplied. The wildcard determines what files
455are displayed in the file selector, and file extension supplies a type
456extension for the required filename. Flags may be a combination of wxOPEN,
e6daf794 457wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, or 0.
a660d684 458
e6daf794 459Both the Unix and Windows versions implement a wildcard filter. Typing a
a660d684
KB
460filename containing wildcards (*, ?) in the filename text item, and
461clicking on Ok, will result in only those files matching the pattern being
e6daf794 462displayed.
a660d684 463
e6daf794
RR
464The wildcard may be a specification for multiple types of file
465with a description for each, such as:
a660d684
KB
466
467\begin{verbatim}
58abfef6 468 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
a660d684
KB
469\end{verbatim}
470
706bb5f9 471The application must check for an empty return value (the user pressed
a660d684
KB
472Cancel). For example:
473
474\begin{verbatim}
f5ee2e5f 475const wxString& s = wxFileSelector("Choose a file to open");
a660d684
KB
476if (s)
477{
478 ...
479}
480\end{verbatim}
481
954b8ae6
JS
482\wxheading{Include files}
483
484<wx/filedlg.h>
485
c49245f8
VZ
486\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
487
488\func{long}{wxGetNumberFromUser}{
0e528b99
JS
489 \param{const wxString\& }{message},
490 \param{const wxString\& }{prompt},
491 \param{const wxString\& }{caption},
492 \param{long }{value},
493 \param{long }{min = 0},
494 \param{long }{max = 100},
495 \param{wxWindow *}{parent = NULL},
496 \param{const wxPoint\& }{pos = wxDefaultPosition}}
c49245f8
VZ
497
498Shows a dialog asking the user for numeric input. The dialogs title is set to
499{\it caption}, it contains a (possibly) multiline {\it message} above the
500single line {\it prompt} and the zone for entering the number.
501
502The number entered must be in the range {\it min}..{\it max} (both of which
503should be positive) and {\it value} is the initial value of it. If the user
504enters an invalid value or cancels the dialog, the function will return -1.
505
506Dialog is centered on its {\it parent} unless an explicit position is given in
507{\it pos}.
508
509\wxheading{Include files}
510
511<wx/textdlg.h>
512
a660d684
KB
513\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
514
515\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
0e528b99
JS
516 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
517 \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = TRUE}}
a660d684
KB
518
519Pop up a dialog box with title set to {\it caption}, message {\it message}, and a
520\rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
532372a3 521or press Cancel to return the empty string.
a660d684
KB
522
523If {\it centre} is TRUE, the message text (which may include new line characters)
524is centred; if FALSE, the message is left-justified.
525
954b8ae6
JS
526\wxheading{Include files}
527
528<wx/textdlg.h>
529
a660d684
KB
530\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
531
532\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
0e528b99
JS
533 \param{int }{nsel}, \param{int *}{selection},
534 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
535 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684
KB
536
537Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
538listbox. The user may choose one or more item(s) and press OK or Cancel.
539
540The number of initially selected choices, and array of the selected indices,
541are passed in; this array will contain the user selections on exit, with
542the function returning the number of selections. {\it selection} must be
543as big as the number of choices, in case all are selected.
544
545If Cancel is pressed, -1 is returned.
546
547{\it choices} is an array of {\it n} strings for the listbox.
548
549If {\it centre} is TRUE, the message text (which may include new line characters)
550is centred; if FALSE, the message is left-justified.
551
954b8ae6
JS
552\wxheading{Include files}
553
554<wx/choicdlg.h>
555
a660d684
KB
556\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
557
558\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
0e528b99
JS
559 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
560 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684
KB
561
562Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection
563listbox. The user may choose an item and press OK to return a string or
532372a3 564Cancel to return the empty string.
a660d684
KB
565
566{\it choices} is an array of {\it n} strings for the listbox.
567
568If {\it centre} is TRUE, the message text (which may include new line characters)
569is centred; if FALSE, the message is left-justified.
570
954b8ae6
JS
571\wxheading{Include files}
572
573<wx/choicdlg.h>
574
a660d684
KB
575\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
576
577\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
0e528b99
JS
578 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
579 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684
KB
580
581As {\bf wxGetSingleChoice} but returns the index representing the selected string.
582If the user pressed cancel, -1 is returned.
583
954b8ae6
JS
584\wxheading{Include files}
585
586<wx/choicdlg.h>
587
a660d684
KB
588\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
589
590\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
0e528b99
JS
591 \param{const wxString\& }{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\
592 \param{int}{ y = -1}, \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684
KB
593
594As {\bf wxGetSingleChoice} but takes an array of client data pointers
595corresponding to the strings, and returns one of these pointers.
596
954b8ae6
JS
597\wxheading{Include files}
598
599<wx/choicdlg.h>
600
a660d684
KB
601\membersection{::wxMessageBox}\label{wxmessagebox}
602
603\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
0e528b99 604 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
a660d684
KB
605
606General purpose message dialog. {\it style} may be a bit list of the
607following identifiers:
608
609\begin{twocollist}\itemsep=0pt
610\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
611wxCANCEL.}
612\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
613wxYES\_NO or wxOK.}
614\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
615\twocolitem{wxCENTRE}{Centres the text.}
616\twocolitem{wxICON\_EXCLAMATION}{Under Windows, displays an exclamation mark symbol.}
617\twocolitem{wxICON\_HAND}{Under Windows, displays a hand symbol.}
618\twocolitem{wxICON\_QUESTION}{Under Windows, displays a question mark symbol.}
619\twocolitem{wxICON\_INFORMATION}{Under Windows, displays an information symbol.}
620\end{twocollist}
621
622The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
623
624For example:
625
626\begin{verbatim}
627 ...
628 int answer = wxMessageBox("Quit program?", "Confirm",
629 wxYES_NO | wxCANCEL, main_frame);
630 if (answer == wxYES)
631 delete main_frame;
632 ...
633\end{verbatim}
634
635{\it message} may contain newline characters, in which case the
636message will be split into separate lines, to cater for large messages.
637
638Under Windows, the native MessageBox function is used unless wxCENTRE
639is specified in the style, in which case a generic function is used.
640This is because the native MessageBox function cannot centre text.
641The symbols are not shown when the generic function is used.
642
954b8ae6
JS
643\wxheading{Include files}
644
645<wx/msgdlg.h>
646
c50f1fb9
VZ
647\membersection{::wxShowTip}\label{wxshowtip}
648
0e528b99
JS
649\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
650 \param{wxTipProvider *}{tipProvider},
651 \param{bool }{showAtStartup = TRUE}}
c50f1fb9
VZ
652
653This function shows a "startup tip" to the user.
654
655\docparam{parent}{The parent window for the modal dialog}
656
657\docparam{tipProvider}{An object which is used to get the text of the tips.
0e528b99 658It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
c50f1fb9
VZ
659
660\docparam{showAtStartup}{Should be TRUE if startup tips are shown, FALSE
0e528b99
JS
661otherwise. This is used as the initial value for "Show tips at startup"
662checkbox which is shown in the tips dialog.}
c50f1fb9
VZ
663
664\wxheading{See also:}
665
666\helpref{Tips overview}{tipsoverview}
667
668\wxheading{Include files}
669
670<wx/tipdlg.h>
671
a660d684
KB
672\section{GDI functions}\label{gdifunctions}
673
674The following are relevant to the GDI (Graphics Device Interface).
675
954b8ae6
JS
676\wxheading{Include files}
677
678<wx/gdicmn.h>
679
a660d684
KB
680\membersection{::wxColourDisplay}
681
682\func{bool}{wxColourDisplay}{\void}
683
684Returns TRUE if the display is colour, FALSE otherwise.
685
686\membersection{::wxDisplayDepth}
687
688\func{int}{wxDisplayDepth}{\void}
689
690Returns the depth of the display (a value of 1 denotes a monochrome display).
691
e2a6f233 692\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
a660d684 693
e2a6f233 694\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
a660d684
KB
695 \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
696
e2a6f233 697Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
a660d684
KB
698makes it into a placeable metafile by prepending a header containing the given
699bounding box. The bounding box may be obtained from a device context after drawing
700into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
701
702In addition to adding the placeable metafile header, this function adds
703the equivalent of the following code to the start of the metafile data:
704
705\begin{verbatim}
706 SetMapMode(dc, MM_ANISOTROPIC);
707 SetWindowOrg(dc, minX, minY);
708 SetWindowExt(dc, maxX - minX, maxY - minY);
709\end{verbatim}
710
e3065973 711This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
a660d684
KB
712
713Placeable metafiles may be imported by many Windows applications, and can be
714used in RTF (Rich Text Format) files.
715
716{\it scale} allows the specification of scale for the metafile.
717
718This function is only available under Windows.
719
720\membersection{::wxSetCursor}\label{wxsetcursor}
721
722\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
723
f53561f1 724Globally sets the cursor; only has an effect in Windows and GTK.
a660d684
KB
725See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
726
a660d684
KB
727\section{Printer settings}\label{printersettings}
728
f53561f1
RR
729These routines are obsolete and should no longer be used!
730
a660d684
KB
731The following functions are used to control PostScript printing. Under
732Windows, PostScript output can only be sent to a file.
733
954b8ae6
JS
734\wxheading{Include files}
735
736<wx/dcps.h>
737
a660d684
KB
738\membersection{::wxGetPrinterCommand}
739
740\func{wxString}{wxGetPrinterCommand}{\void}
741
742Gets the printer command used to print a file. The default is {\tt lpr}.
743
744\membersection{::wxGetPrinterFile}
745
746\func{wxString}{wxGetPrinterFile}{\void}
747
748Gets the PostScript output filename.
749
750\membersection{::wxGetPrinterMode}
751
752\func{int}{wxGetPrinterMode}{\void}
753
754Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
755The default is PS\_PREVIEW.
756
757\membersection{::wxGetPrinterOptions}
758
759\func{wxString}{wxGetPrinterOptions}{\void}
760
761Gets the additional options for the print command (e.g. specific printer). The default is nothing.
762
763\membersection{::wxGetPrinterOrientation}
764
765\func{int}{wxGetPrinterOrientation}{\void}
766
767Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
768
769\membersection{::wxGetPrinterPreviewCommand}
770
771\func{wxString}{wxGetPrinterPreviewCommand}{\void}
772
773Gets the command used to view a PostScript file. The default depends on the platform.
774
775\membersection{::wxGetPrinterScaling}
776
777\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
778
779Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
780
781\membersection{::wxGetPrinterTranslation}
782
783\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
784
785Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
786
787\membersection{::wxSetPrinterCommand}
788
789\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
790
791Sets the printer command used to print a file. The default is {\tt lpr}.
792
793\membersection{::wxSetPrinterFile}
794
795\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
796
797Sets the PostScript output filename.
798
799\membersection{::wxSetPrinterMode}
800
801\func{void}{wxSetPrinterMode}{\param{int }{mode}}
802
803Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
804The default is PS\_PREVIEW.
805
806\membersection{::wxSetPrinterOptions}
807
808\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
809
810Sets the additional options for the print command (e.g. specific printer). The default is nothing.
811
812\membersection{::wxSetPrinterOrientation}
813
814\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
815
816Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
817
818\membersection{::wxSetPrinterPreviewCommand}
819
820\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
821
822Sets the command used to view a PostScript file. The default depends on the platform.
823
824\membersection{::wxSetPrinterScaling}
825
826\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
827
828Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
829
830\membersection{::wxSetPrinterTranslation}
831
832\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
833
834Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
835
836\section{Clipboard functions}\label{clipsboard}
837
838These clipboard functions are implemented for Windows only.
839
954b8ae6
JS
840\wxheading{Include files}
841
842<wx/clipbrd.h>
843
a660d684
KB
844\membersection{::wxClipboardOpen}
845
846\func{bool}{wxClipboardOpen}{\void}
847
848Returns TRUE if this application has already opened the clipboard.
849
850\membersection{::wxCloseClipboard}
851
852\func{bool}{wxCloseClipboard}{\void}
853
854Closes the clipboard to allow other applications to use it.
855
856\membersection{::wxEmptyClipboard}
857
858\func{bool}{wxEmptyClipboard}{\void}
859
860Empties the clipboard.
861
862\membersection{::wxEnumClipboardFormats}
863
864\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
865
866Enumerates the formats found in a list of available formats that belong
867to the clipboard. Each call to this function specifies a known
868available format; the function returns the format that appears next in
869the list.
870
871{\it dataFormat} specifies a known format. If this parameter is zero,
872the function returns the first format in the list.
873
874The return value specifies the next known clipboard data format if the
875function is successful. It is zero if the {\it dataFormat} parameter specifies
876the last format in the list of available formats, or if the clipboard
877is not open.
878
879Before it enumerates the formats function, an application must open the clipboard by using the
880wxOpenClipboard function.
881
882\membersection{::wxGetClipboardData}
883
884\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
885
886Gets data from the clipboard.
887
888{\it dataFormat} may be one of:
889
890\begin{itemize}\itemsep=0pt
891\item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
892\item wxCF\_BITMAP: returns a new wxBitmap.
893\end{itemize}
894
895The clipboard must have previously been opened for this call to succeed.
896
897\membersection{::wxGetClipboardFormatName}
898
899\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
900
901Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
902length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
903
904\membersection{::wxIsClipboardFormatAvailable}
905
906\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
907
908Returns TRUE if the given data format is available on the clipboard.
909
910\membersection{::wxOpenClipboard}
911
912\func{bool}{wxOpenClipboard}{\void}
913
914Opens the clipboard for passing data to it or getting data from it.
915
916\membersection{::wxRegisterClipboardFormat}
917
918\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
919
920Registers the clipboard data format name and returns an identifier.
921
922\membersection{::wxSetClipboardData}
923
924\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
925
926Passes data to the clipboard.
927
928{\it dataFormat} may be one of:
929
930\begin{itemize}\itemsep=0pt
931\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
932\item wxCF\_BITMAP: {\it data} is a wxBitmap.
933\item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
e2a6f233 934\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
a660d684
KB
935\end{itemize}
936
937The clipboard must have previously been opened for this call to succeed.
938
939\section{Miscellaneous functions}\label{miscellany}
940
954b8ae6 941\membersection{::wxNewId}
a660d684 942
954b8ae6 943\func{long}{wxNewId}{\void}
a660d684
KB
944
945Generates an integer identifier unique to this run of the program.
946
954b8ae6
JS
947\wxheading{Include files}
948
949<wx/utils.h>
a660d684 950
954b8ae6
JS
951\membersection{::wxRegisterId}
952
953\func{void}{wxRegisterId}{\param{long}{ id}}
a660d684
KB
954
955Ensures that ids subsequently generated by {\bf NewId} do not clash with
956the given {\bf id}.
957
954b8ae6
JS
958\wxheading{Include files}
959
960<wx/utils.h>
961
a660d684
KB
962\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
963
964\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
965
966Changes the cursor to the given cursor for all windows in the application.
967Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
968to its previous state. These two calls can be nested, and a counter
969ensures that only the outer calls take effect.
970
e2a6f233 971See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
a660d684 972
954b8ae6
JS
973\wxheading{Include files}
974
975<wx/utils.h>
976
a660d684
KB
977\membersection{::wxBell}
978
979\func{void}{wxBell}{\void}
980
981Ring the system bell.
982
954b8ae6 983\wxheading{Include files}
a660d684 984
954b8ae6 985<wx/utils.h>
a660d684
KB
986
987\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
988
989\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
990
991Creates and returns an object of the given class, if the class has been
992registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
993
e2a6f233
JS
994\membersection{::wxDDECleanUp}\label{wxddecleanup}
995
996\func{void}{wxDDECleanUp}{\void}
997
998Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
999called by the application.
1000
1001See also helpref{wxDDEInitialize}{wxddeinitialize}.
1002
954b8ae6
JS
1003\wxheading{Include files}
1004
1005<wx/dde.h>
1006
e2a6f233
JS
1007\membersection{::wxDDEInitialize}\label{wxddeinitialize}
1008
1009\func{void}{wxDDEInitialize}{\void}
1010
1011Initializes the DDE system. May be called multiple times without harm.
1012
1013This no longer needs to be called by the application: it will be called
1014by wxWindows if necessary.
1015
1016See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
1017\helpref{wxDDECleanUp}{wxddecleanup}.
1018
954b8ae6
JS
1019\wxheading{Include files}
1020
1021<wx/dde.h>
1022
e2a6f233 1023\membersection{::wxDebugMsg}\label{wxdebugmsg}
a660d684
KB
1024
1025\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
1026
de6019fb
VZ
1027{\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogoverview} instead!}
1028
a660d684 1029Display a debugging message; under Windows, this will appear on the
e2a6f233 1030debugger command window, and under Unix, it will be written to standard
a660d684
KB
1031error.
1032
1033The syntax is identical to {\bf printf}: pass a format string and a
1034variable list of arguments.
1035
a660d684
KB
1036{\bf Tip:} under Windows, if your application crashes before the
1037message appears in the debugging window, put a wxYield call after
1038each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
1039(at least for Watcom C++): preformat your messages and use OutputDebugString
1040instead.
1041
6fb26ea3
JS
1042This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1043
954b8ae6
JS
1044\wxheading{Include files}
1045
1046<wx/utils.h>
1047
a660d684
KB
1048\membersection{::wxDisplaySize}
1049
1050\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
1051
1052Gets the physical size of the display in pixels.
1053
954b8ae6
JS
1054\wxheading{Include files}
1055
1056<wx/gdicmn.h>
1057
8e193f38
VZ
1058\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
1059
1060\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
1061
1062This function enables or disables all top level windows. It is used by
1063\helpref{::wxSafeYield}{wxsafeyield}.
1064
1065\wxheading{Include files}
1066
1067<wx/utils.h>
1068
a660d684
KB
1069\membersection{::wxEntry}\label{wxentry}
1070
1071This initializes wxWindows in a platform-dependent way. Use this if you
1072are not using the default wxWindows entry code (e.g. main or WinMain). For example,
1073you can initialize wxWindows from an Microsoft Foundation Classes application using
954b8ae6 1074this function.
a660d684
KB
1075
1076\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
1077 \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
1078
1079wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
1080function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
1081message loop will be entered.
1082
1083\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
1084 \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
1085
1086wxWindows initialization under Windows (for applications constructed as a DLL).
1087
1088\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
1089
e2a6f233 1090wxWindows initialization under Unix.
a660d684 1091
954b8ae6
JS
1092\wxheading{Remarks}
1093
1094To clean up wxWindows, call wxApp::OnExit followed by the static function
1095wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:
1096
1097\begin{verbatim}
1098int CTheApp::ExitInstance()
1099{
1100 // OnExit isn't called by CleanUp so must be called explicitly.
1101 wxTheApp->OnExit();
1102 wxApp::CleanUp();
1103
1104 return CWinApp::ExitInstance();
1105}
1106\end{verbatim}
1107
1108\wxheading{Include files}
1109
1110<wx/app.h>
1111
8e193f38 1112\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
a660d684 1113
8e193f38 1114\func{void}{wxEndBusyCursor}{\void}
a660d684 1115
8e193f38
VZ
1116Changes the cursor back to the original cursor, for all windows in the application.
1117Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
1118
1119See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
a660d684 1120
954b8ae6
JS
1121\wxheading{Include files}
1122
1123<wx/utils.h>
1124
8e193f38 1125\membersection{::wxError}\label{wxerror}
a660d684 1126
8e193f38 1127\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
a660d684 1128
8e193f38
VZ
1129Displays {\it msg} and continues. This writes to standard error under
1130Unix, and pops up a message box under Windows. Used for internal
1131wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
a660d684 1132
954b8ae6
JS
1133\wxheading{Include files}
1134
1135<wx/utils.h>
1136
a660d684
KB
1137\membersection{::wxExecute}\label{wxexecute}
1138
eafc087e 1139\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
a660d684 1140
e2a6f233 1141\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
a660d684 1142
e2a6f233 1143Executes another program in Unix or Windows.
a660d684
KB
1144
1145The first form takes a command string, such as {\tt "emacs file.txt"}.
1146
1147The second form takes an array of values: a command, any number of
1148arguments, terminated by NULL.
1149
1150If {\it sync} is FALSE (the default), flow of control immediately returns.
1151If TRUE, the current application waits until the other program has terminated.
1152
43bb3699 1153In the case of synchronous execution, the return value is the exit code of
e6045e08
VZ
1154the process (which terminates by the moment the function returns) and will be
1155$-1$ if the process couldn't be started and typically 0 if the process
34adc693
KB
1156terminated successfully. Also, while waiting for the process to
1157terminate, wxExecute will call \helpref{wxYield}{wxyield}. The caller
1158should ensure that this can cause no recursion, in the simples case by
1159calling \helpref{wxEnableTopLevelWindows(FALSE)}{wxenabletoplevelwindows}.
e6045e08
VZ
1160
1161For asynchronous execution, however, the return value is the process id and
1162zero value indicates that the command could not be executed.
a660d684 1163
7e84f02d
VZ
1164If callback isn't NULL and if execution is asynchronous (note that callback
1165parameter can not be non NULL for synchronous execution),
eafc087e
GL
1166\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
1167the process finishes.
1168
1169See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}.
a660d684 1170
954b8ae6
JS
1171\wxheading{Include files}
1172
1173<wx/utils.h>
1174
a660d684
KB
1175\membersection{::wxExit}\label{wxexit}
1176
1177\func{void}{wxExit}{\void}
1178
1179Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
1180Should only be used in an emergency: normally the top-level frame
1181should be deleted (after deleting all other frames) to terminate the
1182application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
1183
954b8ae6
JS
1184\wxheading{Include files}
1185
1186<wx/app.h>
1187
a660d684
KB
1188\membersection{::wxFatalError}\label{wxfatalerror}
1189
1190\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
1191
e2a6f233 1192Displays {\it msg} and exits. This writes to standard error under Unix,
a660d684
KB
1193and pops up a message box under Windows. Used for fatal internal
1194wxWindows errors. See also \helpref{wxError}{wxerror}.
1195
954b8ae6
JS
1196\wxheading{Include files}
1197
1198<wx/utils.h>
1199
a660d684
KB
1200\membersection{::wxFindMenuItemId}
1201
1202\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
1203
1204Find a menu item identifier associated with the given frame's menu bar.
1205
954b8ae6
JS
1206\wxheading{Include files}
1207
1208<wx/utils.h>
1209
a660d684
KB
1210\membersection{::wxFindWindowByLabel}
1211
1212\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
1213
1214Find a window by its label. Depending on the type of window, the label may be a window title
1215or panel item label. If {\it parent} is NULL, the search will start from all top-level
1216frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1217The search is recursive in both cases.
1218
954b8ae6
JS
1219\wxheading{Include files}
1220
1221<wx/utils.h>
1222
a660d684
KB
1223\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
1224
1225\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
1226
1227Find a window by its name (as given in a window constructor or {\bf Create} function call).
1228If {\it parent} is NULL, the search will start from all top-level
1229frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1230The search is recursive in both cases.
1231
1232If no such named window is found, {\bf wxFindWindowByLabel} is called.
1233
954b8ae6
JS
1234\wxheading{Include files}
1235
1236<wx/utils.h>
1237
a660d684
KB
1238\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
1239
1240\func{wxWindow *}{wxGetActiveWindow}{\void}
1241
1242Gets the currently active window (Windows only).
1243
954b8ae6
JS
1244\wxheading{Include files}
1245
1246<wx/windows.h>
1247
a660d684
KB
1248\membersection{::wxGetDisplayName}\label{wxgetdisplayname}
1249
1250\func{wxString}{wxGetDisplayName}{\void}
1251
1252Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
1253
954b8ae6
JS
1254\wxheading{Include files}
1255
1256<wx/utils.h>
1257
a660d684
KB
1258\membersection{::wxGetHomeDir}
1259
1260\func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}}
1261
e2a6f233 1262Fills the buffer with a string representing the user's home directory (Unix only).
a660d684 1263
954b8ae6
JS
1264\wxheading{Include files}
1265
1266<wx/utils.h>
1267
a660d684
KB
1268\membersection{::wxGetHostName}
1269
1270\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1271
1272Copies the host name of the machine the program is running on into the
1273buffer {\it buf}, of maximum size {\it bufSize}, returning TRUE if
e2a6f233 1274successful. Under Unix, this will return a machine name. Under Windows,
a660d684
KB
1275this returns ``windows''.
1276
954b8ae6
JS
1277\wxheading{Include files}
1278
1279<wx/utils.h>
1280
a660d684
KB
1281\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
1282
1283\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}}
1284
1285Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
1286
1287If {\it resetTimer} is TRUE (the default), the timer is reset to zero
1288by this call.
1289
1290See also \helpref{wxTimer}{wxtimer}.
1291
954b8ae6
JS
1292\wxheading{Include files}
1293
1294<wx/timer.h>
1295
e2a6f233 1296\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
a660d684
KB
1297
1298\func{long}{wxGetFreeMemory}{\void}
1299
1300Returns the amount of free memory in Kbytes under environments which
1301support it, and -1 if not supported. Currently, returns a positive value
e2a6f233 1302under Windows, and -1 under Unix.
a660d684 1303
954b8ae6
JS
1304\wxheading{Include files}
1305
1306<wx/utils.h>
1307
a660d684
KB
1308\membersection{::wxGetMousePosition}
1309
1310\func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}}
1311
1312Returns the mouse position in screen coordinates.
1313
954b8ae6
JS
1314\wxheading{Include files}
1315
1316<wx/utils.h>
1317
a660d684
KB
1318\membersection{::wxGetOsVersion}
1319
1320\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
1321
1322Gets operating system version information.
1323
1324\begin{twocollist}\itemsep=0pt
1325\twocolitemruled{Platform}{Return tyes}
1326\twocolitem{Macintosh}{Return value is wxMACINTOSH.}
12a44087 1327\twocolitem{GTK}{Return value is wxGTK, {\it major} is 1, {\it minor} is 0. (for GTK 1.0.X) }
a660d684
KB
1328\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
1329\twocolitem{OS/2}{Return value is wxOS2\_PM.}
1330\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
1331\twocolitem{Windows NT}{Return value is wxWINDOWS\_NT, {\it major} is 3, {\it minor} is 1.}
1332\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 3, {\it minor} is 1.}
1333\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
1334\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
1335\end{twocollist}
1336
954b8ae6
JS
1337\wxheading{Include files}
1338
1339<wx/utils.h>
1340
a660d684
KB
1341\membersection{::wxGetResource}\label{wxgetresource}
1342
1343\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1344 \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
1345
1346\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1347 \param{float *}{value}, \param{const wxString\& }{file = NULL}}
1348
1349\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1350 \param{long *}{value}, \param{const wxString\& }{file = NULL}}
1351
1352\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1353 \param{int *}{value}, \param{const wxString\& }{file = NULL}}
1354
1355Gets a resource value from the resource database (for example, WIN.INI, or
1356.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1357otherwise the specified file is used.
1358
e2a6f233 1359Under X, if an application class (wxApp::GetClassName) has been defined,
a660d684
KB
1360it is appended to the string /usr/lib/X11/app-defaults/ to try to find
1361an applications default file when merging all resource databases.
1362
1363The reason for passing the result in an argument is that it
1364can be convenient to define a default value, which gets overridden
1365if the value exists in the resource file. It saves a separate
1366test for that resource's existence, and it also allows
1367the overloading of the function for different types.
1368
e2a6f233 1369See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
a660d684 1370
954b8ae6
JS
1371\wxheading{Include files}
1372
1373<wx/utils.h>
1374
a660d684
KB
1375\membersection{::wxGetUserId}
1376
1377\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1378
1379Copies the user's login identity (such as ``jacs'') into the buffer {\it
1380buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1381Under Windows, this returns ``user''.
1382
954b8ae6
JS
1383\wxheading{Include files}
1384
1385<wx/utils.h>
1386
a660d684
KB
1387\membersection{::wxGetUserName}
1388
1389\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1390
1391Copies the user's name (such as ``Julian Smart'') into the buffer {\it
1392buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1393Under Windows, this returns ``unknown''.
1394
954b8ae6
JS
1395\wxheading{Include files}
1396
1397<wx/utils.h>
1398
a660d684
KB
1399\membersection{::wxKill}\label{wxkill}
1400
1401\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
1402
e2a6f233 1403Under Unix (the only supported platform), equivalent to the Unix kill function.
a660d684
KB
1404Returns 0 on success, -1 on failure.
1405
1406Tip: sending a signal of 0 to a process returns -1 if the process does not exist.
1407It does not raise a signal in the receiving process.
1408
954b8ae6 1409\wxheading{Include files}
a660d684 1410
954b8ae6 1411<wx/utils.h>
a660d684 1412
a660d684
KB
1413\membersection{::wxIsBusy}\label{wxisbusy}
1414
1415\func{bool}{wxIsBusy}{\void}
1416
1417Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
1418\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
1419
e2a6f233
JS
1420See also \helpref{wxBusyCursor}{wxbusycursor}.
1421
954b8ae6
JS
1422\wxheading{Include files}
1423
1424<wx/utils.h>
1425
a660d684
KB
1426\membersection{::wxLoadUserResource}\label{wxloaduserresource}
1427
1428\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
1429
1430Loads a user-defined Windows resource as a string. If the resource is found, the function creates
1431a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
1432
1433The resource must be defined in the {\tt .rc} file using the following syntax:
1434
1435\begin{verbatim}
1436myResource TEXT file.ext
1437\end{verbatim}
1438
1439where {\tt file.ext} is a file that the resource compiler can find.
1440
1441One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers
1442cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed
1443using \helpref{wxResourceParseString}{wxresourceparsestring}.
1444
1445This function is available under Windows only.
1446
954b8ae6
JS
1447\wxheading{Include files}
1448
1449<wx/utils.h>
1450
a660d684
KB
1451\membersection{::wxNow}\label{wxnow}
1452
1453\func{wxString}{wxNow}{\void}
1454
1455Returns a string representing the current date and time.
1456
954b8ae6
JS
1457\wxheading{Include files}
1458
1459<wx/utils.h>
1460
a660d684
KB
1461\membersection{::wxPostDelete}\label{wxpostdelete}
1462
1463\func{void}{wxPostDelete}{\param{wxObject *}{object}}
1464
954b8ae6 1465Tells the system to delete the specified object when
a660d684
KB
1466all other events have been processed. In some environments, it is
1467necessary to use this instead of deleting a frame directly with the
954b8ae6 1468delete operator, because some GUIs will still send events to a deleted window.
a660d684
KB
1469
1470Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
1471
954b8ae6
JS
1472\wxheading{Include files}
1473
1474<wx/utils.h>
1475
8e193f38
VZ
1476\membersection{::wxPostEvent}\label{wxpostevent}
1477
1478\func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
1479
1480This function posts the event to the specified {\it dest} object. The
1481difference between sending an event and posting it is that in the first case
1482the event is processed before the function returns (in wxWindows, event sending
1483is done with \helpref{ProcessEvent}{wxevthandlerprocessevent} function), but in
1484the second, the function returns immediately and the event will be processed
1485sometime later - usually during the next even loop iteration.
1486
1487Note that a copy of the {\it event} is made by the function, so the original
1488copy can be deleted as soon as function returns. This function can also be used
1489to send events between different threads safely.
1490
1491\wxheading{Include files}
1492
1493<wx/app.h>
1494
6776a0b2 1495\membersection{::wxSafeYield}\label{wxsafeyield}
43bb3699
VZ
1496
1497\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
1498
1499This function is similar to wxYield, except that it disables the user input to
a818ccea
KB
1500all program windows before calling wxYield and re-enables it again
1501afterwards. If {\it win} is not NULL, this window will remain enabled,
1502allowing the implementation of some limited user interaction.
43bb3699
VZ
1503
1504Returns the result of the call to \helpref{::wxYield}{wxyield}.
1505
1506\wxheading{Include files}
1507
1508<wx/utils.h>
1509
a660d684
KB
1510\membersection{::wxSetDisplayName}\label{wxsetdisplayname}
1511
1512\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
1513
1514Under X only, sets the current display name. This is the X host and display name such
1515as ``colonsay:0.0", and the function indicates which display should be used for creating
1516windows from this point on. Setting the display within an application allows multiple
1517displays to be used.
1518
1519See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
1520
954b8ae6
JS
1521\wxheading{Include files}
1522
1523<wx/utils.h>
1524
a660d684
KB
1525\membersection{::wxShell}\label{wxshell}
1526
1527\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
1528
1529Executes a command in an interactive shell window. If no command is
1530specified, then just the shell is spawned.
1531
1532See also \helpref{wxExecute}{wxexecute}.
1533
954b8ae6
JS
1534\wxheading{Include files}
1535
1536<wx/utils.h>
1537
e2a6f233 1538\membersection{::wxSleep}\label{wxsleep}
a660d684
KB
1539
1540\func{void}{wxSleep}{\param{int}{ secs}}
1541
e2a6f233 1542Sleeps for the specified number of seconds.
a660d684 1543
954b8ae6
JS
1544\wxheading{Include files}
1545
1546<wx/utils.h>
1547
a660d684
KB
1548\membersection{::wxStripMenuCodes}
1549
8a2c6ef8
JS
1550\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
1551
1552\func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}}
a660d684
KB
1553
1554Strips any menu codes from {\it in} and places the result
8a2c6ef8
JS
1555in {\it out} (or returns the new string, in the first form).
1556
1557Menu codes include \& (mark the next character with an underline
a660d684
KB
1558as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
1559
954b8ae6
JS
1560\wxheading{Include files}
1561
1562<wx/utils.h>
1563
a660d684
KB
1564\membersection{::wxStartTimer}\label{wxstarttimer}
1565
1566\func{void}{wxStartTimer}{\void}
1567
1568Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
1569
1570See also \helpref{wxTimer}{wxtimer}.
1571
954b8ae6
JS
1572\wxheading{Include files}
1573
1574<wx/timer.h>
1575
a660d684
KB
1576\membersection{::wxToLower}\label{wxtolower}
1577
1578\func{char}{wxToLower}{\param{char }{ch}}
1579
1580Converts the character to lower case. This is implemented as a macro for efficiency.
1581
954b8ae6
JS
1582\wxheading{Include files}
1583
1584<wx/utils.h>
1585
a660d684
KB
1586\membersection{::wxToUpper}\label{wxtoupper}
1587
1588\func{char}{wxToUpper}{\param{char }{ch}}
1589
1590Converts the character to upper case. This is implemented as a macro for efficiency.
1591
954b8ae6
JS
1592\wxheading{Include files}
1593
1594<wx/utils.h>
1595
a660d684
KB
1596\membersection{::wxTrace}\label{wxtrace}
1597
1598\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
1599
1600Takes printf-style variable argument syntax. Output
1601is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1602
6fb26ea3
JS
1603This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1604
954b8ae6
JS
1605\wxheading{Include files}
1606
1607<wx/memory.h>
1608
a660d684
KB
1609\membersection{::wxTraceLevel}\label{wxtracelevel}
1610
1611\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
1612
1613Takes printf-style variable argument syntax. Output
1614is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1615The first argument should be the level at which this information is appropriate.
1616It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
1617this value.
1618
6fb26ea3
JS
1619This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1620
954b8ae6
JS
1621\wxheading{Include files}
1622
1623<wx/memory.h>
1624
afb74891
VZ
1625\membersection{::wxUsleep}\label{wxusleep}
1626
1627\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
1628
1629Sleeps for the specified number of milliseconds. Notice that usage of this
1630function is encouraged instead of calling usleep(3) directly because the
1631standard usleep() function is not MT safe.
1632
1633\wxheading{Include files}
1634
1635<wx/utils.h>
1636
a660d684
KB
1637\membersection{::wxWriteResource}\label{wxwriteresource}
1638
1639\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1640 \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
1641
1642\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1643 \param{float }{value}, \param{const wxString\& }{file = NULL}}
1644
1645\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1646 \param{long }{value}, \param{const wxString\& }{file = NULL}}
1647
1648\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1649 \param{int }{value}, \param{const wxString\& }{file = NULL}}
1650
1651Writes a resource value into the resource database (for example, WIN.INI, or
1652.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1653otherwise the specified file is used.
1654
1655Under X, the resource databases are cached until the internal function
1656\rtfsp{\bf wxFlushResources} is called automatically on exit, when
1657all updated resource databases are written to their files.
1658
1659Note that it is considered bad manners to write to the .Xdefaults
e2a6f233 1660file under Unix, although the WIN.INI file is fair game under Windows.
a660d684 1661
e2a6f233 1662See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
a660d684 1663
954b8ae6
JS
1664\wxheading{Include files}
1665
1666<wx/utils.h>
1667
fd34e3a5 1668\membersection{::wxYield}\label{wxyield}
a660d684
KB
1669
1670\func{bool}{wxYield}{\void}
1671
1672Yields control to pending messages in the windowing system. This can be useful, for example, when a
1673time-consuming process writes to a text window. Without an occasional
1674yield, the text window will not be updated properly, and (since Windows
1675multitasking is cooperative) other processes will not respond.
1676
1677Caution should be exercised, however, since yielding may allow the
1678user to perform actions which are not compatible with the current task.
1679Disabling menu items or whole menus during processing can avoid unwanted
43bb3699
VZ
1680reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better
1681function.
a660d684 1682
954b8ae6
JS
1683\wxheading{Include files}
1684
8e193f38 1685<wx/app.h> or <wx/utils.h>
954b8ae6 1686
a660d684
KB
1687\section{Macros}\label{macros}
1688
1689These macros are defined in wxWindows.
1690
0180dad6
RR
1691\membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways}
1692
1693\func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}}
1694
1695\func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}}
1696
1697\func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}}
1698
1699\func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
1700
1701This macro will swap the bytes of the {\it value} variable from little
1702endian to big endian or vice versa.
1703
1704\membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe}
1705
1706\func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}}
1707
1708\func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}}
1709
1710\func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}}
1711
1712\func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}}
1713
1714This macro will swap the bytes of the {\it value} variable from little
1715endian to big endian or vice versa if the program is compiled on a
1716big-endian architecture (such as Sun work stations). If the program has
1717been compiled on a little-endian architecture, the value will be unchanged.
1718
1719Use these macros to read data from and write data to a file that stores
1720data in little endian (Intel i386) format.
1721
1722\membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
1723
1724\func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}}
1725
1726\func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}}
1727
1728\func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}}
1729
1730\func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}}
1731
1732This macro will swap the bytes of the {\it value} variable from little
1733endian to big endian or vice versa if the program is compiled on a
1734little-endian architecture (such as Intel PCs). If the program has
1735been compiled on a big-endian architecture, the value will be unchanged.
1736
1737Use these macros to read data from and write data to a file that stores
1738data in big endian format.
1739
a660d684
KB
1740\membersection{CLASSINFO}\label{classinfo}
1741
1742\func{wxClassInfo *}{CLASSINFO}{className}
1743
1744Returns a pointer to the wxClassInfo object associated with this class.
1745
954b8ae6
JS
1746\wxheading{Include files}
1747
1748<wx/object.h>
1749
a660d684
KB
1750\membersection{DECLARE\_ABSTRACT\_CLASS}
1751
1752\func{}{DECLARE\_ABSTRACT\_CLASS}{className}
1753
1754Used inside a class declaration to declare that the class should be
1755made known to the class hierarchy, but objects of this class cannot be created
1756dynamically. The same as DECLARE\_CLASS.
1757
1758Example:
1759
1760\begin{verbatim}
1761class wxCommand: public wxObject
1762{
1763 DECLARE_ABSTRACT_CLASS(wxCommand)
1764
1765 private:
1766 ...
1767 public:
1768 ...
1769};
1770\end{verbatim}
1771
954b8ae6
JS
1772\wxheading{Include files}
1773
1774<wx/object.h>
1775
a660d684
KB
1776\membersection{DECLARE\_APP}\label{declareapp}
1777
1778\func{}{DECLARE\_APP}{className}
1779
1780This is used in headers to create a forward declaration of the wxGetApp function implemented
1781by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}.
1782
1783Example:
1784
1785\begin{verbatim}
1786 DECLARE_APP(MyApp)
1787\end{verbatim}
1788
954b8ae6
JS
1789\wxheading{Include files}
1790
1791<wx/app.h>
1792
a660d684
KB
1793\membersection{DECLARE\_CLASS}
1794
1795\func{}{DECLARE\_CLASS}{className}
1796
1797Used inside a class declaration to declare that the class should be
1798made known to the class hierarchy, but objects of this class cannot be created
1799dynamically. The same as DECLARE\_ABSTRACT\_CLASS.
1800
954b8ae6
JS
1801\wxheading{Include files}
1802
1803<wx/object.h>
1804
a660d684
KB
1805\membersection{DECLARE\_DYNAMIC\_CLASS}
1806
1807\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
1808
1809Used inside a class declaration to declare that the objects of this class should be dynamically
1810createable from run-time type information.
1811
1812Example:
1813
1814\begin{verbatim}
1815class wxFrame: public wxWindow
1816{
1817 DECLARE_DYNAMIC_CLASS(wxFrame)
1818
1819 private:
1820 const wxString\& frameTitle;
1821 public:
1822 ...
1823};
1824\end{verbatim}
1825
954b8ae6
JS
1826\wxheading{Include files}
1827
1828<wx/object.h>
1829
a660d684
KB
1830\membersection{IMPLEMENT\_ABSTRACT\_CLASS}
1831
1832\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
1833
1834Used in a C++ implementation file to complete the declaration of
1835a class that has run-time type information. The same as IMPLEMENT\_CLASS.
1836
1837Example:
1838
1839\begin{verbatim}
1840IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
1841
1842wxCommand::wxCommand(void)
1843{
1844...
1845}
1846\end{verbatim}
1847
954b8ae6
JS
1848\wxheading{Include files}
1849
1850<wx/object.h>
1851
a660d684
KB
1852\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}
1853
1854\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
1855
1856Used in a C++ implementation file to complete the declaration of
1857a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
1858
954b8ae6
JS
1859\wxheading{Include files}
1860
1861<wx/object.h>
1862
a660d684
KB
1863\membersection{IMPLEMENT\_APP}\label{implementapp}
1864
1865\func{}{IMPLEMENT\_APP}{className}
1866
1867This is used in the application class implementation file to make the application class known to
1868wxWindows for dynamic construction. You use this instead of
1869
1870Old form:
1871
1872\begin{verbatim}
1873 MyApp myApp;
1874\end{verbatim}
1875
1876New form:
1877
1878\begin{verbatim}
1879 IMPLEMENT_APP(MyApp)
1880\end{verbatim}
1881
1882See also \helpref{DECLARE\_APP}{declareapp}.
1883
954b8ae6
JS
1884\wxheading{Include files}
1885
1886<wx/app.h>
1887
a660d684
KB
1888\membersection{IMPLEMENT\_CLASS}
1889
1890\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
1891
1892Used in a C++ implementation file to complete the declaration of
1893a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
1894
954b8ae6
JS
1895\wxheading{Include files}
1896
1897<wx/object.h>
1898
a660d684
KB
1899\membersection{IMPLEMENT\_CLASS2}
1900
1901\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
1902
1903Used in a C++ implementation file to complete the declaration of a
1904class that has run-time type information and two base classes. The
1905same as IMPLEMENT\_ABSTRACT\_CLASS2.
1906
954b8ae6
JS
1907\wxheading{Include files}
1908
1909<wx/object.h>
1910
a660d684
KB
1911\membersection{IMPLEMENT\_DYNAMIC\_CLASS}
1912
1913\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
1914
1915Used in a C++ implementation file to complete the declaration of
1916a class that has run-time type information, and whose instances
1917can be created dynamically.
1918
1919Example:
1920
1921\begin{verbatim}
1922IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
1923
1924wxFrame::wxFrame(void)
1925{
1926...
1927}
1928\end{verbatim}
1929
954b8ae6
JS
1930\wxheading{Include files}
1931
1932<wx/object.h>
1933
a660d684
KB
1934\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}
1935
1936\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
1937
1938Used in a C++ implementation file to complete the declaration of
1939a class that has run-time type information, and whose instances
1940can be created dynamically. Use this for classes derived from two
1941base classes.
1942
954b8ae6
JS
1943\wxheading{Include files}
1944
1945<wx/object.h>
1946
88b1927c 1947\membersection{wxBITMAP}\label{wxbitmapmacro}
0c5d3e1c
VZ
1948
1949\func{}{wxBITMAP}{bitmapName}
1950
1951This macro loads a bitmap from either application resources (on the platforms
1952for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
1953avoid using {\tt #ifdef}s when creating bitmaps.
1954
1955\wxheading{See also}
1956
88b1927c
JS
1957\helpref{Bitmaps and icons overview}{wxbitmapoverview},
1958\helpref{wxICON}{wxiconmacro}
0c5d3e1c
VZ
1959
1960\wxheading{Include files}
1961
1962<wx/gdicmn.h>
1963
34636400
VZ
1964\membersection{WXDEBUG\_NEW}\label{debugnew}
1965
1966\func{}{WXDEBUG\_NEW}{arg}
1967
1968This is defined in debug mode to be call the redefined new operator
1969with filename and line number arguments. The definition is:
1970
1971\begin{verbatim}
1972#define WXDEBUG_NEW new(__FILE__,__LINE__)
1973\end{verbatim}
1974
1975In non-debug mode, this is defined as the normal new operator.
1976
1977\wxheading{Include files}
1978
1979<wx/object.h>
1980
1981\membersection{wxDynamicCast}\label{wxdynamiccast}
1982
1983\func{}{wxDynamicCast}{ptr, classname}
1984
1985This macro returns the pointer {\it ptr} cast to the type {\it classname *} if
1986the pointer is of this type (the check is done during the run-time) or NULL
1987otherwise. Usage of this macro is prefered over obsoleted wxObject::IsKindOf()
1988function.
1989
1990The {\it ptr} argument may be NULL, in which case NULL will be returned.
1991
1992Example:
1993
1994\begin{verbatim}
1995 wxWindow *win = wxWindow::FindFocus();
1996 wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
1997 if ( text )
1998 {
1999 // a text control has the focus...
2000 }
2001 else
2002 {
2003 // no window has the focus or it's not a text control
2004 }
2005\end{verbatim}
2006
2007\wxheading{See also}
2008
2009\helpref{RTTI overview}{runtimeclassoverview}
2010
88b1927c 2011\membersection{wxICON}\label{wxiconmacro}
0c5d3e1c
VZ
2012
2013\func{}{wxICON}{iconName}
2014
2015This macro loads an icon from either application resources (on the platforms
2016for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
2017avoid using {\tt #ifdef}s when creating icons.
2018
2019\wxheading{See also}
2020
88b1927c
JS
2021\helpref{Bitmaps and icons overview}{wxbitmapoverview},
2022\helpref{wxBITMAP}{wxbitmapmacro}
0c5d3e1c
VZ
2023
2024\wxheading{Include files}
2025
2026<wx/gdicmn.h>
2027
a660d684
KB
2028\membersection{WXTRACE}\label{trace}
2029
34636400
VZ
2030\wxheading{Include files}
2031
2032<wx/object.h>
2033
a660d684
KB
2034\func{}{WXTRACE}{formatString, ...}
2035
2036Calls wxTrace with printf-style variable argument syntax. Output
2037is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
2038
6fb26ea3
JS
2039This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
2040
954b8ae6
JS
2041\wxheading{Include files}
2042
2043<wx/memory.h>
2044
a660d684
KB
2045\membersection{WXTRACELEVEL}\label{tracelevel}
2046
2047\func{}{WXTRACELEVEL}{level, formatString, ...}
2048
2049Calls wxTraceLevel with printf-style variable argument syntax. Output
2050is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
2051The first argument should be the level at which this information is appropriate.
2052It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
2053this value.
2054
6fb26ea3
JS
2055This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
2056
954b8ae6
JS
2057\wxheading{Include files}
2058
2059<wx/memory.h>
2060
a660d684
KB
2061\section{wxWindows resource functions}\label{resourcefuncs}
2062
2063\overview{wxWindows resource system}{resourceformats}
2064
2065This section details functions for manipulating wxWindows (.WXR) resource
2066files and loading user interface elements from resources.
2067
2068\normalbox{Please note that this use of the word `resource' is different from that used when talking
2069about initialisation file resource reading and writing, using such functions
2070as wxWriteResource and wxGetResource. It's just an unfortunate clash of terminology.}
2071
2072\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
2073
2074See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
2075loading from resource data.
2076
954b8ae6
JS
2077{\bf Warning:} this needs updating for wxWindows 2.
2078
a660d684
KB
2079\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
2080
2081\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
2082
2083Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
2084\verb$#$defining a name to an integer). Unlikely to be used by an application except
2085perhaps for implementing resource functionality for interpreted languages.
2086
2087\membersection{::wxResourceClear}
2088
2089\func{void}{wxResourceClear}{\void}
2090
2091Clears the wxWindows resource table.
2092
2093\membersection{::wxResourceCreateBitmap}
2094
2095\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
2096
2097Creates a new bitmap from a file, static data, or Windows resource, given a valid
2098wxWindows bitmap resource identifier. For example, if the .WXR file contains
2099the following:
2100
2101\begin{verbatim}
2102static const wxString\& aiai_resource = "bitmap(name = 'aiai_resource',\
2103 bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
2104 bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X']).";
2105\end{verbatim}
2106
2107then this function can be called as follows:
2108
2109\begin{verbatim}
2110 wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource");
2111\end{verbatim}
2112
2113\membersection{::wxResourceCreateIcon}
2114
2115\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
2116
2117Creates a new icon from a file, static data, or Windows resource, given a valid
2118wxWindows icon resource identifier. For example, if the .WXR file contains
2119the following:
2120
2121\begin{verbatim}
2122static const wxString\& aiai_resource = "icon(name = 'aiai_resource',\
2123 icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
2124 icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X']).";
2125\end{verbatim}
2126
2127then this function can be called as follows:
2128
2129\begin{verbatim}
2130 wxIcon *icon = wxResourceCreateIcon("aiai_resource");
2131\end{verbatim}
2132
2133\membersection{::wxResourceCreateMenuBar}
2134
2135\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
2136
2137Creates a new menu bar given a valid wxWindows menubar resource
2138identifier. For example, if the .WXR file contains the following:
2139
2140\begin{verbatim}
2141static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
2142 menu = \
2143 [\
2144 ['&File', 1, '', \
2145 ['&Open File', 2, 'Open a file'],\
2146 ['&Save File', 3, 'Save a file'],\
2147 [],\
2148 ['E&xit', 4, 'Exit program']\
2149 ],\
2150 ['&Help', 5, '', \
2151 ['&About', 6, 'About this program']\
2152 ]\
2153 ]).";
2154\end{verbatim}
2155
2156then this function can be called as follows:
2157
2158\begin{verbatim}
2159 wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
2160\end{verbatim}
2161
2162
2163\membersection{::wxResourceGetIdentifier}
2164
2165\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
2166
2167Used for retrieving the integer value associated with an identifier.
2168A zero value indicates that the identifier was not found.
2169
2170See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
2171
2172\membersection{::wxResourceParseData}\label{wxresourcedata}
2173
2174\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
2175
2176Parses a string containing one or more wxWindows resource objects. If
2177the resource objects are global static data that are included into the
2178C++ program, then this function must be called for each variable
2179containing the resource data, to make it known to wxWindows.
2180
2181{\it resource} should contain data in the following form:
2182
2183\begin{verbatim}
2184dialog(name = 'dialog1',
2185 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
2186 title = 'Test dialog box',
2187 x = 312, y = 234, width = 400, height = 300,
2188 modal = 0,
2189 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
2190 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
2191 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',
2192 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
2193 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
2194 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
2195\end{verbatim}
2196
2197This function will typically be used after including a {\tt .wxr} file into
2198a C++ program as follows:
2199
2200\begin{verbatim}
2201#include "dialog1.wxr"
2202\end{verbatim}
2203
2204Each of the contained resources will declare a new C++ variable, and each
2205of these variables should be passed to wxResourceParseData.
2206
2207\membersection{::wxResourceParseFile}
2208
2209\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
2210
2211Parses a file containing one or more wxWindows resource objects
2212in C++-compatible syntax. Use this function to dynamically load
2213wxWindows resource data.
2214
2215\membersection{::wxResourceParseString}\label{wxresourceparsestring}
2216
2217\func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
2218
2219Parses a string containing one or more wxWindows resource objects. If
2220the resource objects are global static data that are included into the
2221C++ program, then this function must be called for each variable
2222containing the resource data, to make it known to wxWindows.
2223
2224{\it resource} should contain data with the following form:
2225
2226\begin{verbatim}
2227static const wxString\& dialog1 = "dialog(name = 'dialog1',\
2228 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',\
2229 title = 'Test dialog box',\
2230 x = 312, y = 234, width = 400, height = 300,\
2231 modal = 0,\
2232 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,\
2233 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],\
2234 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',\
2235 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',\
2236 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
2237 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).";
2238\end{verbatim}
2239
2240This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
2241load an entire {\tt .wxr file} into a string.
2242
2243\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
2244
2245\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width},
2246\param{int }{height}, \param{wxResourceTable *}{table = NULL}}
2247
2248\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}}
2249
2250Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system.
2251This is required if other resources will use the bitmap data, since otherwise there
2252is no connection between names used in resources, and the global bitmap data.
2253
2254\membersection{::wxResourceRegisterIconData}
2255
2256Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
2257
6fb26ea3
JS
2258\section{Log functions}\label{logfunctions}
2259
2260These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
2261further information.
2262
954b8ae6
JS
2263\wxheading{Include files}
2264
2265<wx/log.h>
2266
6fb26ea3
JS
2267\membersection{::wxLogError}\label{wxlogerror}
2268
2269\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
2270
2271The function to use for error messages, i.e. the
2272messages that must be shown to the user. The default processing is to pop up a
2273message box to inform the user about it.
2274
2275\membersection{::wxLogFatalError}\label{wxlogfatalerror}
2276
2277\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}}
2278
2279Like \helpref{wxLogError}{wxlogerror}, but also
2280terminates the program with the exit code 3. Using {\it abort()} standard
2281function also terminates the program with this exit code.
2282
2283\membersection{::wxLogWarning}\label{wxlogwarning}
2284
2285\func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}}
2286
2287For warnings - they are also normally shown to the
2288user, but don't interrupt the program work.
2289
2290\membersection{::wxLogMessage}\label{wxlogmessage}
2291
2292\func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}}
2293
2294for all normal, informational messages. They also
2295appear in a message box by default (but it can be changed). Notice
2296that the standard behaviour is to not show informational messages if there are
2297any errors later - the logic being that the later error messages make the
2298informational messages preceding them meaningless.
2299
2300\membersection{::wxLogVerbose}\label{wxlogverbose}
2301
2302\func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}}
2303
2304For verbose output. Normally, it's suppressed, but
2305might be activated if the user wishes to know more details about the program
2306progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
2307
2308\membersection{::wxLogStatus}\label{wxlogstatus}
2309
2310\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}}
2311
2312For status messages - they will go into the status
2313bar of the active or specified (as the first argument) \helpref{wxFrame}{wxframe} if it has one.
2314
2315\membersection{::wxLogSysError}\label{wxlogsyserror}
2316
2317\func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}}
2318
2319Mostly used by wxWindows itself, but might be
2320handy for logging errors after system call (API function) failure. It logs the
2321specified message text as well as the last system error code ({\it errno} or {\it ::GetLastError()} depending
2322on the platform) and the corresponding error
2323message. The second form of this function takes the error code explitly as the
2324first argument.
2325
2326\membersection{::wxLogDebug}\label{wxlogdebug}
2327
2328\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}}
2329
2330The right function for debug output. It only
2331does anything at all in the debug mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined)
2332and expands to nothing in release mode (otherwise).
2333
2334\membersection{::wxLogTrace}\label{wxlogtrace}
2335
2336\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}}
2337
2338\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}}
2339
2340As {\bf wxLogDebug}, only does something in debug
2341build. The reason for making it a separate function from it is that usually
2342there are a lot of trace messages, so it might make sense to separate them
2343from other debug messages which would be flooded in them. Moreover, the second
2344version of this function takes a trace mask as the first argument which allows
2345to further restrict the amount of messages generated. The value of {\it mask} can be:
2346
2347\begin{itemize}\itemsep=0pt
2348\item wxTraceMemAlloc: trace memory allocation (new/delete)
2349\item wxTraceMessages: trace window messages/X callbacks
2350\item wxTraceResAlloc: trace GDI resource allocation
2351\item wxTraceRefCount: trace various ref counting operations
2352\end{itemize}
2353
2354\section{Debugging macros and functions}\label{debugmacros}
2355
2356Useful macros and functins for error checking and defensive programming. ASSERTs are only
2357compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
2358builds.
2359
954b8ae6
JS
2360\wxheading{Include files}
2361
2362<wx/debug.h>
2363
6fb26ea3
JS
2364\membersection{::wxOnAssert}\label{wxonassert}
2365
2366\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}}
2367
2368This function may be redefined to do something non trivial and is called
2369whenever one of debugging macros fails (i.e. condition is false in an
5b6aa0ff
JS
2370assertion).
2371% TODO: this should probably be an overridable in wxApp.
6fb26ea3
JS
2372
2373\membersection{wxASSERT}\label{wxassert}
2374
2375\func{}{wxASSERT}{\param{}{condition}}
2376
b207457c
VZ
2377Assert macro. An error message will be generated if the condition is FALSE in
2378debug mode, but nothing will be done in the release build.
2379
2380Please note that the condition in wxASSERT() should have no side effects
2381because it will not be executed in release mode at all.
2382
2383See also: \helpref{wxASSERT\_MSG}{wxassertmsg}
6fb26ea3
JS
2384
2385\membersection{wxASSERT\_MSG}\label{wxassertmsg}
2386
2387\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
2388
2389Assert macro with message. An error message will be generated if the condition is FALSE.
2390
b207457c
VZ
2391See also: \helpref{wxASSERT}{wxassert}
2392
6fb26ea3
JS
2393\membersection{wxFAIL}\label{wxfail}
2394
b207457c 2395\func{}{wxFAIL}{\void}
6fb26ea3
JS
2396
2397Will always generate an assert error if this code is reached (in debug mode).
2398
b207457c
VZ
2399See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
2400
6fb26ea3
JS
2401\membersection{wxFAIL\_MSG}\label{wxfailmsg}
2402
b207457c 2403\func{}{wxFAIL\_MSG}{\param{}{msg}}
6fb26ea3
JS
2404
2405Will always generate an assert error with specified message if this code is reached (in debug mode).
2406
b207457c
VZ
2407This macro is useful for marking unreachable" code areas, for example
2408it may be used in the "default:" branch of a switch statement if all possible
2409cases are processed above.
2410
2411See also: \helpref{wxFAIL}{wxfail}
2412
6fb26ea3
JS
2413\membersection{wxCHECK}\label{wxcheck}
2414
2415\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
2416
2417Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2418This check is done even in release mode.
2419
2420\membersection{wxCHECK\_MSG}\label{wxcheckmsg}
2421
2422\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
2423
2424Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2425This check is done even in release mode.
2426
b207457c
VZ
2427This macro may be only used in non void functions, see also
2428\helpref{wxCHECK\_RET}{wxcheckret}.
2429
2430\membersection{wxCHECK\_RET}\label{wxcheckret}
2431
2432\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}}
2433
2434Checks that the condition is true, and returns if not (FAILs with given error
2435message in debug mode). This check is done even in release mode.
2436
2437This macro should be used in void functions instead of
2438\helpref{wxCHECK\_MSG}{wxcheckmsg}.
2439
2440\membersection{wxCHECK2}\label{wxcheck2}
2441
2442\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}}
2443
2444Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute
2445{\it operation} if it is not. This is a generalisation of
2446\helpref{wxCHECK}{wxcheck} and may be used when something else than just
2447returning from the function must be done when the {\it condition} is false.
2448
2449This check is done even in release mode.
2450
2451\membersection{wxCHECK2\_MSG}\label{wxcheck2msg}
2452
2453\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}}
2454
2455This is the same as \helpref{wxCHECK2}{wxcheck2}, but
2456\helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
2457instead of wxFAIL() if the {\it condition} is false.
2458