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