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