]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/function.tex
added/documented wxApp::FilterEvent
[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
b0fc8832
VZ
5The functions and macros defined in wxWindows are described here: you can
6either look up a function using the alphabetical listing of them or find it in
7the corresponding topic.
8
9\section{Alphabetical functions and macros list}
10
11\helpref{CLASSINFO}{classinfo}\\
8f5d9104 12\helpref{copystring}{copystring}\\
b0fc8832
VZ
13\helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\
14\helpref{DECLARE\_APP}{declareapp}\\
15\helpref{DECLARE\_CLASS}{declareclass}\\
16\helpref{DECLARE\_DYNAMIC\_CLASS}{declaredynamicclass}\\
17\helpref{IMPLEMENT\_ABSTRACT\_CLASS2}{implementabstractclass2}\\
18\helpref{IMPLEMENT\_ABSTRACT\_CLASS}{implementabstractclass}\\
19\helpref{IMPLEMENT\_APP}{implementapp}\\
20\helpref{IMPLEMENT\_CLASS2}{implementclass2}\\
21\helpref{IMPLEMENT\_CLASS}{implementclass}\\
22\helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\
23\helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\
24\helpref{WXDEBUG\_NEW}{debugnew}\\
25\helpref{WXTRACELEVEL}{tracelevel}\\
26\helpref{WXTRACE}{trace}\\
8f5d9104 27\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\
b0fc8832
VZ
28\helpref{wxASSERT\_MSG}{wxassertmsg}\\
29\helpref{wxASSERT}{wxassert}\\
30\helpref{wxBITMAP}{wxbitmapmacro}\\
31\helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\
32\helpref{wxBell}{wxbell}\\
33\helpref{wxCHECK2\_MSG}{wxcheck2msg}\\
34\helpref{wxCHECK2}{wxcheck2}\\
35\helpref{wxCHECK\_MSG}{wxcheckmsg}\\
36\helpref{wxCHECK\_RET}{wxcheckret}\\
37\helpref{wxCHECK\_VERSION}{wxcheckversion}\\
38\helpref{wxCHECK}{wxcheck}\\
39\helpref{wxClientDisplayRect}{wxclientdisplayrect}\\
f4fcc291 40\helpref{wxClipboardOpen}{functionwxclipboardopen}\\
b0fc8832
VZ
41\helpref{wxCloseClipboard}{wxcloseclipboard}\\
42\helpref{wxColourDisplay}{wxcolourdisplay}\\
8f5d9104 43\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\
5b8643ea 44\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}\\
b0fc8832
VZ
45\helpref{wxConcatFiles}{wxconcatfiles}\\
46\helpref{wxConstCast}{wxconstcast}\\
47\helpref{wxCopyFile}{wxcopyfile}\\
48\helpref{wxCreateDynamicObject}{wxcreatedynamicobject}\\
49\helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider}\\
50\helpref{wxDDECleanUp}{wxddecleanup}\\
51\helpref{wxDDEInitialize}{wxddeinitialize}\\
52\helpref{wxDROP\_ICON}{wxdropicon}\\
53\helpref{wxDebugMsg}{wxdebugmsg}\\
f4fcc291 54\helpref{wxDirExists}{functionwxdirexists}\\
b0fc8832
VZ
55\helpref{wxDirSelector}{wxdirselector}\\
56\helpref{wxDisplayDepth}{wxdisplaydepth}\\
b0fc8832 57\helpref{wxDisplaySize}{wxdisplaysize}\\
f4fcc291 58\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
b0fc8832
VZ
59\helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
60\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
61\helpref{wxDynamicCast}{wxdynamiccast}\\
62\helpref{wxEmptyClipboard}{wxemptyclipboard}\\
63\helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\
64\helpref{wxEndBusyCursor}{wxendbusycursor}\\
65\helpref{wxEntry}{wxentry}\\
66\helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\
67\helpref{wxError}{wxerror}\\
68\helpref{wxExecute}{wxexecute}\\
69\helpref{wxExit}{wxexit}\\
70\helpref{wxFAIL\_MSG}{wxfailmsg}\\
71\helpref{wxFAIL}{wxfail}\\
72\helpref{wxFatalError}{wxfatalerror}\\
f4fcc291 73\helpref{wxFileExists}{functionwxfileexists}\\
b0fc8832
VZ
74\helpref{wxFileModificationTime}{wxfilemodificationtime}\\
75\helpref{wxFileNameFromPath}{wxfilenamefrompath}\\
76\helpref{wxFileSelector}{wxfileselector}\\
77\helpref{wxFindFirstFile}{wxfindfirstfile}\\
78\helpref{wxFindMenuItemId}{wxfindmenuitemid}\\
79\helpref{wxFindNextFile}{wxfindnextfile}\\
80\helpref{wxFindWindowAtPointer}{wxfindwindowatpointer}\\
81\helpref{wxFindWindowAtPoint}{wxfindwindowatpoint}\\
82\helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\
83\helpref{wxFindWindowByName}{wxfindwindowbyname}\\
84\helpref{wxGetActiveWindow}{wxgetactivewindow}\\
85\helpref{wxGetClipboardData}{wxgetclipboarddata}\\
86\helpref{wxGetClipboardFormatName}{wxgetclipboardformatname}\\
87\helpref{wxGetColourFromUser}{wxgetcolourfromuser}\\
88\helpref{wxGetCwd}{wxgetcwd}\\
89\helpref{wxGetDiskSpace}{wxgetdiskspace}\\
90\helpref{wxGetDisplayName}{wxgetdisplayname}\\
91\helpref{wxGetElapsedTime}{wxgetelapsedtime}\\
92\helpref{wxGetEmailAddress}{wxgetemailaddress}\\
93\helpref{wxGetEnv}{wxgetenv}\\
d741c583 94\helpref{wxGetFontFromUser}{wxgetfontfromuser}\\
b0fc8832
VZ
95\helpref{wxGetFreeMemory}{wxgetfreememory}\\
96\helpref{wxGetFullHostName}{wxgetfullhostname}\\
97\helpref{wxGetHomeDir}{wxgethomedir}\\
98\helpref{wxGetHostName}{wxgethostname}\\
99\helpref{wxGetLocalTimeMillis}{wxgetlocaltimemillis}\\
100\helpref{wxGetLocalTime}{wxgetlocaltime}\\
101\helpref{wxGetMousePosition}{wxgetmouseposition}\\
102\helpref{wxGetMultipleChoices}{wxgetmultiplechoices}\\
103\helpref{wxGetMultipleChoice}{wxgetmultiplechoice}\\
104\helpref{wxGetNumberFromUser}{wxgetnumberfromuser}\\
105\helpref{wxGetOSDirectory}{wxgetosdirectory}\\
106\helpref{wxGetOsDescription}{wxgetosdescription}\\
107\helpref{wxGetOsVersion}{wxgetosversion}\\
108\helpref{wxGetPasswordFromUser}{wxgetpasswordfromuser}\\
109\helpref{wxGetPrinterCommand}{wxgetprintercommand}\\
110\helpref{wxGetPrinterFile}{wxgetprinterfile}\\
111\helpref{wxGetPrinterMode}{wxgetprintermode}\\
112\helpref{wxGetPrinterOptions}{wxgetprinteroptions}\\
113\helpref{wxGetPrinterOrientation}{wxgetprinterorientation}\\
114\helpref{wxGetPrinterPreviewCommand}{wxgetprinterpreviewcommand}\\
115\helpref{wxGetPrinterScaling}{wxgetprinterscaling}\\
116\helpref{wxGetPrinterTranslation}{wxgetprintertranslation}\\
117\helpref{wxGetResource}{wxgetresource}\\
118\helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\
119\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\
120\helpref{wxGetSingleChoice}{wxgetsinglechoice}\\
121\helpref{wxGetTempFileName}{wxgettempfilename}\\
122\helpref{wxGetTextFromUser}{wxgettextfromuser}\\
33b494d6 123\helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\
b0fc8832
VZ
124\helpref{wxGetTranslation}{wxgettranslation}\\
125\helpref{wxGetUTCTime}{wxgetutctime}\\
126\helpref{wxGetUserHome}{wxgetuserhome}\\
127\helpref{wxGetUserId}{wxgetuserid}\\
128\helpref{wxGetUserName}{wxgetusername}\\
129\helpref{wxGetWorkingDirectory}{wxgetworkingdirectory}\\
130\helpref{wxGetenv}{wxgetenvmacro}\\
131\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\
132\helpref{wxICON}{wxiconmacro}\\
133\helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\
134\helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\
135\helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\
136\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}\\
137\helpref{wxInitialize}{wxinitialize}\\
138\helpref{wxIsAbsolutePath}{wxisabsolutepath}\\
139\helpref{wxIsBusy}{wxisbusy}\\
140\helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\
141\helpref{wxIsEmpty}{wxisempty}\\
142\helpref{wxIsWild}{wxiswild}\\
143\helpref{wxKill}{wxkill}\\
144\helpref{wxLoadUserResource}{wxloaduserresource}\\
145\helpref{wxLogDebug}{wxlogdebug}\\
146\helpref{wxLogError}{wxlogerror}\\
147\helpref{wxLogFatalError}{wxlogfatalerror}\\
148\helpref{wxLogMessage}{wxlogmessage}\\
149\helpref{wxLogStatus}{wxlogstatus}\\
150\helpref{wxLogSysError}{wxlogsyserror}\\
151\helpref{wxLogTrace}{wxlogtrace}\\
152\helpref{wxLogVerbose}{wxlogverbose}\\
153\helpref{wxLogWarning}{wxlogwarning}\\
154\helpref{wxMakeMetafilePlaceable}{wxmakemetafileplaceable}\\
155\helpref{wxMatchWild}{wxmatchwild}\\
156\helpref{wxMessageBox}{wxmessagebox}\\
157\helpref{wxMkdir}{wxmkdir}\\
158\helpref{wxMutexGuiEnter}{wxmutexguienter}\\
159\helpref{wxMutexGuiLeave}{wxmutexguileave}\\
160\helpref{wxNewId}{wxnewid}\\
161\helpref{wxNow}{wxnow}\\
162\helpref{wxOnAssert}{wxonassert}\\
163\helpref{wxOpenClipboard}{wxopenclipboard}\\
164\helpref{wxPathOnly}{wxpathonly}\\
165\helpref{wxPostDelete}{wxpostdelete}\\
166\helpref{wxPostEvent}{wxpostevent}\\
167\helpref{wxRegisterClipboardFormat}{wxregisterclipboardformat}\\
168\helpref{wxRegisterId}{wxregisterid}\\
169\helpref{wxRemoveFile}{wxremovefile}\\
170\helpref{wxRenameFile}{wxrenamefile}\\
171\helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}\\
172\helpref{wxResourceClear}{wxresourceclear}\\
173\helpref{wxResourceCreateBitmap}{wxresourcecreatebitmap}\\
174\helpref{wxResourceCreateIcon}{wxresourcecreateicon}\\
175\helpref{wxResourceCreateMenuBar}{wxresourcecreatemenubar}\\
176\helpref{wxResourceGetIdentifier}{wxresourcegetidentifier}\\
177\helpref{wxResourceParseData}{wxresourcedata}\\
178\helpref{wxResourceParseFile}{wxresourceparsefile}\\
179\helpref{wxResourceParseString}{wxresourceparsestring}\\
180\helpref{wxResourceRegisterBitmapData}{registerbitmapdata}\\
181\helpref{wxResourceRegisterIconData}{wxresourceregistericondata}\\
182\helpref{wxRmdir}{wxrmdir}\\
c11d62a6 183\helpref{wxSafeShowMessage}{wxsafeshowmessage}\\
b0fc8832
VZ
184\helpref{wxSafeYield}{wxsafeyield}\\
185\helpref{wxSetClipboardData}{wxsetclipboarddata}\\
186\helpref{wxSetCursor}{wxsetcursor}\\
187\helpref{wxSetDisplayName}{wxsetdisplayname}\\
188\helpref{wxSetEnv}{wxsetenv}\\
189\helpref{wxSetPrinterCommand}{wxsetprintercommand}\\
190\helpref{wxSetPrinterFile}{wxsetprinterfile}\\
191\helpref{wxSetPrinterMode}{wxsetprintermode}\\
192\helpref{wxSetPrinterOptions}{wxsetprinteroptions}\\
193\helpref{wxSetPrinterOrientation}{wxsetprinterorientation}\\
194\helpref{wxSetPrinterPreviewCommand}{wxsetprinterpreviewcommand}\\
195\helpref{wxSetPrinterScaling}{wxsetprinterscaling}\\
196\helpref{wxSetPrinterTranslation}{wxsetprintertranslation}\\
197\helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\
198\helpref{wxShell}{wxshell}\\
199\helpref{wxShowTip}{wxshowtip}\\
f6ba47d9 200\helpref{wxShutdown}{wxshutdown}\\
b0fc8832
VZ
201\helpref{wxSleep}{wxsleep}\\
202\helpref{wxSnprintf}{wxsnprintf}\\
203\helpref{wxSplitPath}{wxsplitfunction}\\
204\helpref{wxStartTimer}{wxstarttimer}\\
205\helpref{wxStaticCast}{wxstaticcast}\\
206\helpref{wxStricmp}{wxstricmp}\\
207\helpref{wxStringEq}{wxstringeq}\\
208\helpref{wxStringMatch}{wxstringmatch}\\
209\helpref{wxStripMenuCodes}{wxstripmenucodes}\\
210\helpref{wxStrlen}{wxstrlen}\\
211\helpref{wxSysErrorCode}{wxsyserrorcode}\\
212\helpref{wxSysErrorMsg}{wxsyserrormsg}\\
213\helpref{wxToLower}{wxtolower}\\
214\helpref{wxToUpper}{wxtoupper}\\
215\helpref{wxTraceLevel}{wxtracelevel}\\
216\helpref{wxTrace}{wxtrace}\\
217\helpref{wxTransferFileToStream}{wxtransferfiletostream}\\
218\helpref{wxTransferStreamToFile}{wxtransferstreamtofile}\\
219\helpref{wxTrap}{wxtrap}\\
220\helpref{wxUninitialize}{wxuninitialize}\\
221\helpref{wxUnix2DosFilename}{wxunix2dosfilename}\\
222\helpref{wxUnsetEnv}{wxunsetenv}\\
223\helpref{wxUsleep}{wxusleep}\\
224\helpref{wxVsnprintf}{wxvsnprintf}\\
225\helpref{wxWakeUpIdle}{wxwakeupidle}\\
226\helpref{wxWriteResource}{wxwriteresource}\\
227\helpref{wxYield}{wxyield}
f6bcfd97
BP
228
229\section{Version macros}\label{versionfunctions}
230
231The following constants are defined in wxWindows:
232
233\begin{itemize}\itemsep=0pt
234\item {\tt wxMAJOR\_VERSION} is the major version of wxWindows
235\item {\tt wxMINOR\_VERSION} is the minor version of wxWindows
ff8fda36 236\item {\tt wxRELEASE\_NUMBER} is the release number
f6bcfd97
BP
237\end{itemize}
238
239For example, the values or these constants for wxWindows 2.1.15 are 2, 1 and
24015.
241
242Additionally, {\tt wxVERSION\_STRING} is a user-readable string containing
243the full wxWindows version and {\tt wxVERSION\_NUMBER} is a combination of the
244three version numbers above: for 2.1.15, it is 2115 and it is 2200 for
245wxWindows 2.2.
246
247\wxheading{Include files}
248
249<wx/version.h> or <wx/defs.h>
250
251\membersection{wxCHECK\_VERSION}\label{wxcheckversion}
252
253\func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}}
254
255This is a macro which evaluates to true if the current wxWindows version is at
256least major.minor.release.
257
258For example, to test if the program is compiled with wxWindows 2.2 or higher,
259the following can be done:
260
261\begin{verbatim}
262 wxString s;
263#if wxCHECK_VERSION(2, 2, 0)
264 if ( s.StartsWith("foo") )
265#else // replacement code for old version
266 if ( strncmp(s, "foo", 3) == 0 )
267#endif
268 {
269 ...
270 }
271\end{verbatim}
a660d684 272
b0fc8832 273\section{Application initialization and termination}\label{appinifunctions}
c88275cb 274
b0fc8832
VZ
275The functions in this section are used on application startup/shutdown and also
276to control the behaviour of the main event loop of the GUI programs.
c88275cb 277
b0fc8832 278\membersection{::wxEntry}\label{wxentry}
c88275cb 279
b0fc8832
VZ
280This initializes wxWindows in a platform-dependent way. Use this if you
281are not using the default wxWindows entry code (e.g. main or WinMain). For example,
282you can initialize wxWindows from an Microsoft Foundation Classes application using
283this function.
c88275cb 284
b0fc8832
VZ
285\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
286 \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
c88275cb 287
b0fc8832
VZ
288wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
289function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
290message loop will be entered.
c88275cb 291
b0fc8832
VZ
292\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
293 \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
c88275cb 294
b0fc8832 295wxWindows initialization under Windows (for applications constructed as a DLL).
c88275cb 296
b0fc8832 297\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
c88275cb 298
b0fc8832 299wxWindows initialization under Unix.
c88275cb 300
b0fc8832 301\wxheading{Remarks}
c88275cb 302
b0fc8832
VZ
303To clean up wxWindows, call wxApp::OnExit followed by the static function
304wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:
4aff28fc 305
b0fc8832
VZ
306\begin{verbatim}
307int CTheApp::ExitInstance()
308{
309 // OnExit isn't called by CleanUp so must be called explicitly.
310 wxTheApp->OnExit();
311 wxApp::CleanUp();
312
313 return CWinApp::ExitInstance();
c88275cb
RR
314}
315\end{verbatim}
316
b0fc8832 317\wxheading{Include files}
c88275cb 318
b0fc8832 319<wx/app.h>
c88275cb 320
b0fc8832 321\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions}
c88275cb 322
b0fc8832 323\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = TRUE}}
c88275cb 324
b0fc8832
VZ
325If {\it doIt} is TRUE, the fatal exceptions (also known as general protection
326faults under Windows or segmentation violations in the Unix world) will be
327caught and passed to \helpref{wxApp::OnFatalException}{wxapponfatalexception}.
328By default, i.e. before this function is called, they will be handled in the
329normal way which usually just means that the application will be terminated.
330Calling wxHandleFatalExceptions() with {\it doIt} equal to FALSE will restore
331this default behaviour.
c88275cb 332
b0fc8832 333\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
a660d684 334
b0fc8832 335\func{void}{wxInitAllImageHandlers}{\void}
954b8ae6 336
b0fc8832
VZ
337Initializes all available image handlers. For a list of available handlers,
338see \helpref{wxImage}{wximage}.
954b8ae6
JS
339
340\wxheading{See also}
341
b0fc8832 342\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
a660d684 343
b0fc8832 344\wxheading{Include files}
a660d684 345
b0fc8832 346<wx/image.h>
a660d684 347
b0fc8832 348\membersection{::wxInitialize}\label{wxinitialize}
a660d684 349
b0fc8832 350\func{bool}{wxInitialize}{\void}
a660d684 351
b0fc8832
VZ
352This function is used in wxBase only and only if you don't create
353\helpref{wxApp}{wxapp} object at all. In this case you must call it from your
354{\tt main()} function before calling any other wxWindows functions.
a660d684 355
b0fc8832
VZ
356If the function returns {\tt FALSE} the initialization could not be performed,
357in this case the library cannot be used and
358\helpref{wxUninitialize}{wxuninitialize} shouldn't be called neither.
a660d684 359
b0fc8832
VZ
360This function may be called several times but
361\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
362call to this function.
a660d684 363
b0fc8832 364\wxheading{Include files}
a47ce4a7 365
b0fc8832 366<wx/app.h>
a47ce4a7 367
b0fc8832 368\membersection{::wxSafeYield}\label{wxsafeyield}
a47ce4a7 369
b0fc8832 370\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
a660d684 371
b0fc8832
VZ
372This function is similar to wxYield, except that it disables the user input to
373all program windows before calling wxYield and re-enables it again
374afterwards. If {\it win} is not NULL, this window will remain enabled,
375allowing the implementation of some limited user interaction.
a660d684 376
b0fc8832 377Returns the result of the call to \helpref{::wxYield}{wxyield}.
532372a3 378
b0fc8832 379\wxheading{Include files}
a660d684 380
b0fc8832 381<wx/utils.h>
a660d684 382
b0fc8832 383\membersection{::wxUninitialize}\label{wxuninitialize}
a660d684 384
b0fc8832 385\func{void}{wxUninitialize}{\void}
a660d684 386
b0fc8832
VZ
387This function is for use in console (wxBase) programs only. It must be called
388once for each previous successful call to \helpref{wxInitialize}{wxinitialize}.
a660d684 389
b0fc8832 390\wxheading{Include files}
a660d684 391
b0fc8832 392<wx/app.h>
a660d684 393
b0fc8832 394\membersection{::wxYield}\label{wxyield}
a660d684 395
b0fc8832 396\func{bool}{wxYield}{\void}
a660d684 397
b0fc8832 398Calls \helpref{wxApp::Yield}{wxappyield}.
a660d684 399
b0fc8832
VZ
400This function is kept only for backwards compatibility, please use
401\helpref{wxApp::Yield}{wxappyield}method instead in any new code.
a660d684 402
b0fc8832 403\wxheading{Include files}
5ab656cd 404
b0fc8832 405<wx/app.h> or <wx/utils.h>
eadd7bd2 406
b0fc8832 407\membersection{::wxWakeUpIdle}\label{wxwakeupidle}
eadd7bd2 408
b0fc8832 409\func{void}{wxWakeUpIdle}{\void}
eadd7bd2 410
b0fc8832
VZ
411This functions wakes up the (internal and platform dependent) idle system, i.e. it
412will force the system to send an idle event even if the system currently {\it is}
413 idle and thus would not send any idle event until after some other event would get
414sent. This is also useful for sending events between two threads and is used by
415the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and
416\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
eadd7bd2 417
b0fc8832 418\wxheading{Include files}
eadd7bd2 419
b0fc8832 420<wx/app.h>
eadd7bd2 421
b0fc8832 422\section{Process control functions}\label{processfunctions}
eadd7bd2 423
b0fc8832
VZ
424The functions in this section are used to launch or terminate the other
425processes.
eadd7bd2 426
b0fc8832 427\membersection{::wxExecute}\label{wxexecute}
631f1bfe 428
fbf456aa 429\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
631f1bfe 430
fbf456aa 431\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
631f1bfe 432
b0fc8832 433\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
a660d684 434
9722642d
MB
435\perlnote{In wxPerl this function only takes the {\tt command} argument,
436and returns a 2-element list {\tt ( status, output )}, where {\tt output} is
437an array reference.}
438
b0fc8832 439\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}}
a660d684 440
9722642d
MB
441\perlnote{In wxPerl this function only takes the {\tt command} argument,
442and returns a 3-element list {\tt ( status, output, errors )}, where
443{\tt output} and {\tt errors} are array references.}
444
b0fc8832 445Executes another program in Unix or Windows.
a660d684 446
b0fc8832 447The first form takes a command string, such as {\tt "emacs file.txt"}.
a660d684 448
b0fc8832
VZ
449The second form takes an array of values: a command, any number of
450arguments, terminated by NULL.
a660d684 451
b0fc8832
VZ
452The semantics of the third and fourth versions is different from the first two
453and is described in more details below.
a660d684 454
fbf456aa
VZ
455If {\it flags} parameter contains {\tt wxEXEC\_ASYNC} flag (the default), flow
456of control immediately returns. If it contains {\tt wxEXEC\_SYNC}, the current
457application waits until the other program has terminated.
a660d684 458
b0fc8832
VZ
459In the case of synchronous execution, the return value is the exit code of
460the process (which terminates by the moment the function returns) and will be
461$-1$ if the process couldn't be started and typically 0 if the process
462terminated successfully. Also, while waiting for the process to
463terminate, wxExecute will call \helpref{wxYield}{wxyield}. The caller
464should ensure that this can cause no recursion, in the simplest case by
465calling \helpref{wxEnableTopLevelWindows(FALSE)}{wxenabletoplevelwindows}.
a660d684 466
b0fc8832
VZ
467For asynchronous execution, however, the return value is the process id and
468zero value indicates that the command could not be executed. As an added
469complication, the return value of $-1$ in this case indicattes that we didn't
470launch a new process, but connected to the running one (this can only happen in
471case of using DDE under Windows for command execution). In particular, in this,
472and only this, case the calling code will not get the notification about
473process termination.
a660d684 474
fbf456aa 475If callback isn't NULL and if execution is asynchronous,
b0fc8832 476\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
fbf456aa
VZ
477the process finishes. Specifying this parameter also allows you to redirect the
478standard input and/or output of the process being launched by calling
479\helpref{Redirect}{wxprocessredirect}. If the child process IO is redirected,
480under Windows the process window is not shown by default (this avoids having to
481flush an unnecessary console for the processes which don't create any windows
482anyhow) but a {\tt wxEXEC\_NOHIDE} flag can be used to prevent this from
483happening, i.e. with this flag the child process window will be shown normally.
a660d684 484
e1082c9f
VZ
485Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure
486that the new process is a group leader (this will create a new session if
487needed). Calling \helpref{wxKill}{wxkill} with the argument of -pid where pid
488is the process ID of the new process will kill this process as well as all of
489its children (except those which have started their own session).
490
b0fc8832
VZ
491Finally, you may use the third overloaded version of this function to execute
492a process (always synchronously) and capture its output in the array
493{\it output}. The fourth version adds the possibility to additionally capture
494the messages from standard error output in the {\it errors} array.
a660d684 495
b0fc8832
VZ
496See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
497\helpref{Exec sample}{sampleexec}.
a660d684 498
fbf456aa
VZ
499\wxheading{Parameters}
500
501\docparam{command}{The command to execute and any parameters to pass to it as a
502single string.}
503
504\docparam{argv}{The command to execute should be the first element of this
505array, any additional ones are the command parameters and the array must be
506terminated with a NULL pointer.}
507
508\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},
509{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}}
510
511\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}}
512
b0fc8832 513\wxheading{Include files}
a660d684 514
b0fc8832 515<wx/utils.h>
a660d684 516
b0fc8832 517\membersection{::wxExit}\label{wxexit}
a660d684 518
b0fc8832 519\func{void}{wxExit}{\void}
7af89395 520
b0fc8832
VZ
521Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
522Should only be used in an emergency: normally the top-level frame
523should be deleted (after deleting all other frames) to terminate the
f4fcc291 524application. See \helpref{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp}.
7af89395 525
b0fc8832 526\wxheading{Include files}
7af89395 527
b0fc8832 528<wx/app.h>
a660d684 529
b0fc8832 530\membersection{::wxKill}\label{wxkill}
a660d684 531
b0fc8832 532\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}}
7af89395 533
b0fc8832
VZ
534Equivalent to the Unix kill function: send the given signal {\it sig} to the
535process with PID {\it pid}. The valud signal values are
a660d684 536
b0fc8832
VZ
537\begin{verbatim}
538enum wxSignal
539{
540 wxSIGNONE = 0, // verify if the process exists under Unix
541 wxSIGHUP,
542 wxSIGINT,
543 wxSIGQUIT,
544 wxSIGILL,
545 wxSIGTRAP,
546 wxSIGABRT,
547 wxSIGEMT,
548 wxSIGFPE,
549 wxSIGKILL, // forcefully kill, dangerous!
550 wxSIGBUS,
551 wxSIGSEGV,
552 wxSIGSYS,
553 wxSIGPIPE,
554 wxSIGALRM,
555 wxSIGTERM // terminate the process gently
556};
557\end{verbatim}
a660d684 558
b0fc8832
VZ
559{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
560under both Unix and Windows but all the other signals are equivalent to
561{\tt wxSIGTERM} under Windows.
a660d684 562
b0fc8832
VZ
563Returns 0 on success, -1 on failure. If {\it rc} parameter is not NULL, it will
564be filled with an element of {\tt wxKillError} enum:
a660d684 565
b0fc8832
VZ
566\begin{verbatim}
567enum wxKillError
568{
569 wxKILL_OK, // no error
570 wxKILL_BAD_SIGNAL, // no such signal
571 wxKILL_ACCESS_DENIED, // permission denied
572 wxKILL_NO_PROCESS, // no such process
573 wxKILL_ERROR // another, unspecified error
574};
575\end{verbatim}
c0ab6adf 576
b0fc8832 577\wxheading{See also}
ade35f11 578
b0fc8832
VZ
579\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
580\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
581\helpref{Exec sample}{sampleexec}
a660d684 582
b0fc8832 583\wxheading{Include files}
a660d684 584
b0fc8832 585<wx/utils.h>
a660d684 586
b0fc8832 587\membersection{::wxShell}\label{wxshell}
a660d684 588
b0fc8832 589\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
a660d684 590
b0fc8832
VZ
591Executes a command in an interactive shell window. If no command is
592specified, then just the shell is spawned.
a660d684 593
b0fc8832 594See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
a660d684 595
b0fc8832 596\wxheading{Include files}
a660d684 597
b0fc8832 598<wx/utils.h>
a660d684 599
f6ba47d9
VZ
600\membersection{::wxShutdown}\label{wxshutdown}
601
602\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}}
603
604This function shuts down or reboots the computer depending on the value of the
605{\it flags}. Please notice that doing this requires the corresponding access
606rights (superuser under Unix, {\tt SE\_SHUTDOWN} privelege under Windows NT)
607and that this function is only implemented under Unix and Win32.
608
609\wxheading{Parameters}
610
611\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}}
612
613\wxheading{Returns}
614
615{\tt TRUE} on success, {\tt FALSE} if an error occured.
616
617\wxheading{Include files}
618
619<wx/utils.h>
a660d684 620
b0fc8832 621\section{Thread functions}\label{threadfunctions}
1a33c3ba 622
b0fc8832 623\wxheading{Include files}
a660d684 624
b0fc8832 625<wx/thread.h>
a660d684 626
b0fc8832 627\wxheading{See also}
a660d684 628
b0fc8832 629\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
a660d684 630
b0fc8832 631\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
a660d684 632
b0fc8832 633\func{void}{wxMutexGuiEnter}{\void}
a660d684 634
b0fc8832
VZ
635This function must be called when any thread other than the main GUI thread
636wants to get access to the GUI library. This function will block the execution
637of the calling thread until the main thread (or any other thread holding the
638main GUI lock) leaves the GUI library and no other thread will enter the GUI
639library until the calling thread calls \helpref{::wxMutexGuiLeave()}{wxmutexguileave}.
a660d684 640
b0fc8832 641Typically, these functions are used like this:
a660d684 642
b0fc8832
VZ
643\begin{verbatim}
644void MyThread::Foo(void)
645{
646 // before doing any GUI calls we must ensure that this thread is the only
647 // one doing it!
a660d684 648
b0fc8832 649 wxMutexGuiEnter();
a660d684 650
b0fc8832
VZ
651 // Call GUI here:
652 my_window->DrawSomething();
a660d684 653
b0fc8832
VZ
654 wxMutexGuiLeave();
655}
656\end{verbatim}
a660d684 657
b0fc8832
VZ
658Note that under GTK, no creation of top-level windows is allowed in any
659thread but the main one.
a660d684 660
b0fc8832
VZ
661This function is only defined on platforms which support preemptive
662threads.
d37fd2fa 663
b0fc8832 664\membersection{::wxMutexGuiLeave}\label{wxmutexguileave}
d37fd2fa 665
b0fc8832 666\func{void}{wxMutexGuiLeave}{\void}
d37fd2fa 667
b0fc8832 668See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
d37fd2fa 669
b0fc8832
VZ
670This function is only defined on platforms which support preemptive
671threads.
d37fd2fa 672
b0fc8832 673\section{File functions}\label{filefunctions}
d37fd2fa 674
b0fc8832 675\wxheading{Include files}
ed93168b 676
b0fc8832 677<wx/utils.h>
ed93168b 678
b0fc8832 679\wxheading{See also}
ed93168b 680
b0fc8832
VZ
681\helpref{wxPathList}{wxpathlist}\\
682\helpref{wxDir}{wxdir}\\
683\helpref{wxFile}{wxfile}\\
684\helpref{wxFileName}{wxfilename}
ed93168b 685
f4fcc291 686\membersection{::wxDirExists}\label{functionwxdirexists}
ed93168b 687
b0fc8832 688\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
ed93168b 689
b0fc8832 690Returns TRUE if the directory exists.
ed93168b 691
b0fc8832 692\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename}
ed93168b 693
b0fc8832 694\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}}
d524e22d 695
b0fc8832
VZ
696Converts a DOS to a Unix filename by replacing backslashes with forward
697slashes.
d524e22d 698
f4fcc291 699\membersection{::wxFileExists}\label{functionwxfileexists}
d524e22d 700
b0fc8832 701\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
d524e22d 702
b0fc8832
VZ
703Returns TRUE if the file exists. It also returns TRUE if the file is
704a directory.
e12be2f7 705
b0fc8832 706\membersection{::wxFileModificationTime}\label{wxfilemodificationtime}
d524e22d 707
b0fc8832 708\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}}
d524e22d 709
b0fc8832 710Returns time of last modification of given file.
d524e22d 711
b0fc8832 712\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath}
d524e22d 713
b0fc8832 714\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
d524e22d 715
7ac13b21 716\func{char *}{wxFileNameFromPath}{\param{char *}{path}}
d524e22d 717
b0fc8832
VZ
718Returns the filename for a full path. The second form returns a pointer to
719temporary storage that should not be deallocated.
d524e22d 720
b0fc8832 721\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
d524e22d 722
7ac13b21 723\func{wxString}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}}
d524e22d 724
b0fc8832
VZ
725This function does directory searching; returns the first file
726that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
727get the next matching file. Neither will report the current directory "." or the
728parent directory "..".
d524e22d 729
b0fc8832 730{\it spec} may contain wildcards.
85ec2f26 731
b0fc8832 732{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
d524e22d 733
b0fc8832 734For example:
d524e22d 735
b0fc8832
VZ
736\begin{verbatim}
737 wxString f = wxFindFirstFile("/home/project/*.*");
738 while ( !f.IsEmpty() )
739 {
740 ...
741 f = wxFindNextFile();
742 }
743\end{verbatim}
d524e22d 744
b0fc8832 745\membersection{::wxFindNextFile}\label{wxfindnextfile}
d524e22d 746
b0fc8832 747\func{wxString}{wxFindNextFile}{\void}
e12be2f7 748
b0fc8832 749Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
d524e22d 750
b0fc8832 751See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
d524e22d 752
b0fc8832 753\membersection{::wxGetDiskSpace}\label{wxgetdiskspace}
d524e22d 754
b0fc8832 755\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}}
d524e22d 756
b0fc8832
VZ
757This function returns the total number of bytes and number of free bytes on
758the disk containing the directory {\it path} (it should exist). Both
759{\it total} and {\it free} parameters may be {\tt NULL} if the corresponding
760information is not needed.
d524e22d 761
b0fc8832 762\wxheading{Returns}
85ec2f26 763
b0fc8832
VZ
764{\tt TRUE} on success, {\tt FALSE} if an error occured (for example, the
765directory doesn't exist).
d524e22d 766
b0fc8832 767\wxheading{Portability}
d524e22d 768
b0fc8832
VZ
769This function is implemented for Win16 (only for drives less than 2Gb), Win32,
770Mac OS and generic Unix provided the system has {\tt statfs()} function.
d524e22d 771
b0fc8832 772This function first appeared in wxWindows 2.3.2.
d524e22d 773
b0fc8832 774\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
e12be2f7 775
b0fc8832 776\func{wxString}{wxGetOSDirectory}{\void}
d524e22d 777
b0fc8832 778Returns the Windows directory under Windows; on other platforms returns the empty string.
d524e22d 779
b0fc8832 780\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath}
d524e22d 781
b0fc8832 782\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
d524e22d 783
b0fc8832
VZ
784Returns TRUE if the argument is an absolute filename, i.e. with a slash
785or drive name at the beginning.
85ec2f26 786
b0fc8832 787\membersection{::wxPathOnly}\label{wxpathonly}
d524e22d 788
b0fc8832 789\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
d524e22d 790
b0fc8832 791Returns the directory part of the filename.
d524e22d 792
b0fc8832 793\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename}
d524e22d 794
b0fc8832 795\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
e12be2f7 796
b0fc8832
VZ
797Converts a Unix to a DOS filename by replacing forward
798slashes with backslashes.
d524e22d 799
b0fc8832 800\membersection{::wxConcatFiles}\label{wxconcatfiles}
d524e22d 801
b0fc8832
VZ
802\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
803\param{const wxString\& }{file3}}
d524e22d 804
b0fc8832
VZ
805Concatenates {\it file1} and {\it file2} to {\it file3}, returning
806TRUE if successful.
a660d684 807
b0fc8832 808\membersection{::wxCopyFile}\label{wxcopyfile}
a660d684 809
b0fc8832 810\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = TRUE}}
a660d684 811
b0fc8832
VZ
812Copies {\it file1} to {\it file2}, returning TRUE if successful. If
813{\it overwrite} parameter is TRUE (default), the destination file is overwritten
814if it exists, but if {\it overwrite} is FALSE, the functions failes in this
815case.
a660d684 816
b0fc8832 817\membersection{::wxGetCwd}\label{wxgetcwd}
7ae8ee14 818
b0fc8832 819\func{wxString}{wxGetCwd}{\void}
7ae8ee14 820
b0fc8832 821Returns a string containing the current (or working) directory.
7ae8ee14 822
b0fc8832 823\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory}
7ae8ee14 824
7ac13b21 825\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}}
7ae8ee14 826
b0fc8832 827This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
7ae8ee14 828
b0fc8832
VZ
829Copies the current working directory into the buffer if supplied, or
830copies the working directory into new storage (which you must delete yourself)
831if the buffer is NULL.
7ae8ee14 832
b0fc8832 833{\it sz} is the size of the buffer if supplied.
a660d684 834
b0fc8832 835\membersection{::wxGetTempFileName}\label{wxgettempfilename}
a660d684 836
7ac13b21 837\func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}}
a660d684 838
b0fc8832 839\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
7ae8ee14 840
b0fc8832
VZ
841%% Makes a temporary filename based on {\it prefix}, opens and closes the file,
842%% and places the name in {\it buf}. If {\it buf} is NULL, new store
843%% is allocated for the temporary filename using {\it new}.
844%%
845%% Under Windows, the filename will include the drive and name of the
846%% directory allocated for temporary files (usually the contents of the
847%% TEMP variable). Under Unix, the {\tt /tmp} directory is used.
848%%
849%% It is the application's responsibility to create and delete the file.
a660d684 850
b0fc8832
VZ
851These functions are obsolete, please use\rtfsp
852\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp
853instead.
a660d684 854
b0fc8832 855\membersection{::wxIsWild}\label{wxiswild}
a660d684 856
b0fc8832 857\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
a660d684 858
b0fc8832 859Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
a660d684 860
b0fc8832 861\membersection{::wxMatchWild}\label{wxmatchwild}
ed93168b 862
b0fc8832 863\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
ed93168b 864
b0fc8832
VZ
865Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it
866dot\_special}\/ is TRUE, filenames beginning with a dot are not matched
867with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
ed93168b 868
b0fc8832 869\membersection{::wxMkdir}\label{wxmkdir}
ed93168b 870
b0fc8832 871\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
ed93168b 872
b0fc8832 873Makes the directory {\it dir}, returning TRUE if successful.
a660d684 874
b0fc8832
VZ
875{\it perm} is the access mask for the directory for the systems on which it is
876supported (Unix) and doesn't have effect for the other ones.
378b05f7 877
b0fc8832 878\membersection{::wxRemoveFile}\label{wxremovefile}
378b05f7 879
b0fc8832 880\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
378b05f7 881
b0fc8832 882Removes {\it file}, returning TRUE if successful.
378b05f7 883
b0fc8832 884\membersection{::wxRenameFile}\label{wxrenamefile}
e12be2f7 885
b0fc8832 886\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
378b05f7 887
b0fc8832 888Renames {\it file1} to {\it file2}, returning TRUE if successful.
378b05f7 889
b0fc8832 890\membersection{::wxRmdir}\label{wxrmdir}
378b05f7 891
b0fc8832 892\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
378b05f7 893
b0fc8832 894Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS.
e12be2f7 895
b0fc8832 896The {\it flags} parameter is reserved for future use.
378b05f7 897
b0fc8832 898\membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory}
a660d684 899
b0fc8832 900\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
a660d684 901
b0fc8832
VZ
902Sets the current working directory, returning TRUE if the operation succeeded.
903Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
c50f1fb9 904
b0fc8832 905\membersection{::wxSplitPath}\label{wxsplitfunction}
c50f1fb9 906
b0fc8832 907\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
c50f1fb9 908
b0fc8832
VZ
909This function splits a full file name into components: the path (including possible disk/drive
910specification under Windows), the base name and the extension. Any of the output parameters
911({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
912a particular component.
c50f1fb9 913
b0fc8832
VZ
914wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
915Windows, however it will not consider backslashes as path separators under Unix (where backslash
916is a valid character in a filename).
c50f1fb9 917
b0fc8832 918On entry, {\it fullname} should be non-NULL (it may be empty though).
c50f1fb9 919
b0fc8832
VZ
920On return, {\it path} contains the file path (without the trailing separator), {\it name}
921contains the file name and {\it ext} contains the file extension without leading dot. All
922three of them may be empty if the corresponding component is. The old contents of the
923strings pointed to by these parameters will be overwritten in any case (if the pointers
924are not NULL).
c50f1fb9 925
b0fc8832 926\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
c50f1fb9 927
b0fc8832 928\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
10eb1f1e 929
b0fc8832
VZ
930Copies the given file to {\it stream}. Useful when converting an old application to
931use streams (within the document/view framework, for example).
10eb1f1e 932
b0fc8832 933\wxheading{Include files}
10eb1f1e 934
b0fc8832 935<wx/docview.h>
10eb1f1e 936
b0fc8832
VZ
937\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
938
939\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
940
941Copies the given stream to the file {\it filename}. Useful when converting an old application to
942use streams (within the document/view framework, for example).
10eb1f1e
VZ
943
944\wxheading{Include files}
945
b0fc8832 946<wx/docview.h>
10eb1f1e 947
b0fc8832 948\section{Network, user and OS functions}\label{networkfunctions}
a660d684 949
b0fc8832
VZ
950The functions in this section are used to retrieve information about the
951current computer and/or user characteristics.
a660d684 952
b0fc8832 953\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
a660d684 954
b0fc8832 955\func{long}{wxGetFreeMemory}{\void}
a660d684 956
b0fc8832
VZ
957Returns the amount of free memory in bytes under environments which
958support it, and -1 if not supported. Currently, it is supported only
959under Windows, Linux and Solaris.
a660d684 960
b0fc8832 961\wxheading{Include files}
a660d684 962
b0fc8832 963<wx/utils.h>
a660d684 964
b0fc8832 965\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
a660d684 966
b0fc8832 967\func{wxString}{wxGetFullHostName}{\void}
954b8ae6 968
b0fc8832
VZ
969Returns the FQDN (fully qualified domain host name) or an empty string on
970error.
954b8ae6 971
b0fc8832 972\wxheading{See also}
c49245f8 973
b0fc8832 974\helpref{wxGetHostName}{wxgethostname}
4aff28fc 975
b0fc8832 976\wxheading{Include files}
4aff28fc 977
b0fc8832 978<wx/utils.h>
4aff28fc 979
b0fc8832 980\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
4aff28fc 981
b0fc8832
VZ
982\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
983
984Copies the user's email address into the supplied buffer, by
985concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
986and \helpref{wxGetUserId}{wxgetuserid}.
987
988Returns TRUE if successful, FALSE otherwise.
4aff28fc
VZ
989
990\wxheading{Include files}
991
b0fc8832 992<wx/utils.h>
4aff28fc 993
b0fc8832 994\membersection{::wxGetHomeDir}\label{wxgethomedir}
d6c9c1b7 995
b0fc8832 996\func{wxString}{wxGetHomeDir}{\void}
d6c9c1b7 997
b0fc8832 998Return the (current) user's home directory.
d6c9c1b7 999
b0fc8832 1000\wxheading{See also}
d6c9c1b7 1001
b0fc8832 1002\helpref{wxGetUserHome}{wxgetuserhome}
d6c9c1b7
VZ
1003
1004\wxheading{Include files}
1005
b0fc8832 1006<wx/utils.h>
d6c9c1b7 1007
b0fc8832 1008\membersection{::wxGetHostName}\label{wxgethostname}
f3539882 1009
b0fc8832 1010\func{wxString}{wxGetHostName}{\void}
4aff28fc 1011
b0fc8832 1012\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
c49245f8 1013
b0fc8832
VZ
1014Copies the current host machine's name into the supplied buffer. Please note
1015that the returned name is {\it not} fully qualified, i.e. it does not include
1016the domain name.
c49245f8 1017
b0fc8832
VZ
1018Under Windows or NT, this function first looks in the environment
1019variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
1020in the {\bf wxWindows} section of the WIN.INI file is tried.
c49245f8 1021
b0fc8832
VZ
1022The first variant of this function returns the hostname if successful or an
1023empty string otherwise. The second (deprecated) function returns TRUE
1024if successful, FALSE otherwise.
1025
1026\wxheading{See also}
1027
1028\helpref{wxGetFullHostName}{wxgetfullhostname}
c49245f8
VZ
1029
1030\wxheading{Include files}
a294c6d5 1031
b0fc8832 1032<wx/utils.h>
a294c6d5 1033
b0fc8832 1034\membersection{::wxGetUserId}\label{wxgetuserid}
a294c6d5 1035
b0fc8832 1036\func{wxString}{wxGetUserId}{\void}
a294c6d5 1037
b0fc8832
VZ
1038\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
1039
1040This function returns the "user id" also known as "login name" under Unix i.e.
1041something like "jsmith". It uniquely identifies the current user (on this system).
1042
1043Under Windows or NT, this function first looks in the environment
1044variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
1045in the {\bf wxWindows} section of the WIN.INI file is tried.
1046
1047The first variant of this function returns the login name if successful or an
1048empty string otherwise. The second (deprecated) function returns TRUE
1049if successful, FALSE otherwise.
1050
1051\wxheading{See also}
1052
1053\helpref{wxGetUserName}{wxgetusername}
a294c6d5
VZ
1054
1055\wxheading{Include files}
c49245f8 1056
b0fc8832 1057<wx/utils.h>
c49245f8 1058
b0fc8832 1059\membersection{::wxGetOsDescription}\label{wxgetosdescription}
a660d684 1060
b0fc8832 1061\func{wxString}{wxGetOsDescription}{\void}
a660d684 1062
b0fc8832
VZ
1063Returns the string containing the description of the current platform in a
1064user-readable form. For example, this function may return strings like
1065{\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}.
a660d684 1066
b0fc8832
VZ
1067\wxheading{See also}
1068
1069\helpref{::wxGetOsVersion}{wxgetosversion}
a660d684 1070
954b8ae6
JS
1071\wxheading{Include files}
1072
b0fc8832 1073<wx/utils.h>
954b8ae6 1074
b0fc8832 1075\membersection{::wxGetOsVersion}\label{wxgetosversion}
a660d684 1076
b0fc8832 1077\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
a660d684 1078
b0fc8832 1079Gets operating system version information.
a660d684 1080
b0fc8832
VZ
1081\begin{twocollist}\itemsep=0pt
1082\twocolitemruled{Platform}{Return types}
1083\twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X.}
1084\twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. }
1085\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
1086\twocolitem{OS/2}{Return value is wxOS2\_PM.}
1087\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
1088\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}}
1089\twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.}
1090\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.}
1091\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
1092\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
1093\end{twocollist}
a660d684 1094
b0fc8832 1095\wxheading{See also}
a660d684 1096
b0fc8832 1097\helpref{::wxGetOsDescription}{wxgetosdescription}
a660d684 1098
b0fc8832
VZ
1099\wxheading{Include files}
1100
1101<wx/utils.h>
1102
1103\membersection{::wxGetUserHome}\label{wxgetuserhome}
1104
1105\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
1106
1107Returns the home directory for the given user. If the username is empty
1108(default value), this function behaves like
1109\helpref{wxGetHomeDir}{wxgethomedir}.
a660d684 1110
954b8ae6
JS
1111\wxheading{Include files}
1112
b0fc8832 1113<wx/utils.h>
954b8ae6 1114
b0fc8832 1115\membersection{::wxGetUserName}\label{wxgetusername}
a660d684 1116
b0fc8832 1117\func{wxString}{wxGetUserName}{\void}
d6c9c1b7 1118
b0fc8832 1119\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
d6c9c1b7 1120
b0fc8832 1121This function returns the full user name (something like "Mr. John Smith").
d6c9c1b7 1122
b0fc8832
VZ
1123Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
1124in the {\bf wxWindows} section of the WIN.INI file. If PenWindows
1125is running, the entry {\bf Current} in the section {\bf User} of
1126the PENWIN.INI file is used.
d6c9c1b7 1127
b0fc8832
VZ
1128The first variant of this function returns the user name if successful or an
1129empty string otherwise. The second (deprecated) function returns {\tt TRUE}
1130if successful, {\tt FALSE} otherwise.
1131
1132\wxheading{See also}
1133
1134\helpref{wxGetUserId}{wxgetuserid}
a660d684 1135
954b8ae6
JS
1136\wxheading{Include files}
1137
b0fc8832 1138<wx/utils.h>
954b8ae6 1139
b0fc8832 1140\section{String functions}
f3539882 1141
b0fc8832 1142\membersection{::copystring}\label{copystring}
a660d684 1143
7ac13b21 1144\func{char *}{copystring}{\param{const char *}{s}}
a660d684 1145
b0fc8832
VZ
1146Makes a copy of the string {\it s} using the C++ new operator, so it can be
1147deleted with the {\it delete} operator.
d6c9c1b7 1148
b0fc8832 1149This function is deprecated, use \helpref{wxString}{wxstring} class instead.
a660d684 1150
b0fc8832 1151\membersection{::wxIsEmpty}\label{wxisempty}
954b8ae6 1152
b0fc8832 1153\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
954b8ae6 1154
b0fc8832
VZ
1155Returns {\tt TRUE} if the pointer is either {\tt NULL} or points to an empty
1156string, {\tt FALSE} otherwise.
f3539882 1157
b0fc8832 1158\membersection{::wxStricmp}\label{wxstricmp}
a660d684 1159
b0fc8832 1160\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
d6c9c1b7 1161
b0fc8832
VZ
1162Returns a negative value, 0, or positive value if {\it p1} is less than, equal
1163to or greater than {\it p2}. The comparison is case-insensitive.
a660d684 1164
b0fc8832
VZ
1165This function complements the standard C function {\it strcmp()} which performs
1166case-sensitive comparison.
a660d684 1167
b0fc8832 1168\membersection{::wxStringMatch}\label{wxstringmatch}
954b8ae6 1169
b0fc8832
VZ
1170\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
1171 \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
954b8ae6 1172
b0fc8832
VZ
1173Returns {\tt TRUE} if the substring {\it s1} is found within {\it s2},
1174ignoring case if {\it exact} is FALSE. If {\it subString} is {\tt FALSE},
1175no substring matching is done.
f3539882 1176
b0fc8832 1177This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
a660d684 1178
b0fc8832 1179\membersection{::wxStringEq}\label{wxstringeq}
a660d684 1180
b0fc8832 1181\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
a660d684 1182
b0fc8832
VZ
1183A macro defined as:
1184
1185\begin{verbatim}
1186#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
1187\end{verbatim}
1188
1189This function is obsolete, use \helpref{wxString}{wxstring} instead.
1190
1191\membersection{::wxStrlen}\label{wxstrlen}
1192
1193\func{size\_t}{wxStrlen}{\param{const char *}{ p}}
1194
1195This is a safe version of standard function {\it strlen()}: it does exactly the
1196same thing (i.e. returns the length of the string) except that it returns 0 if
1197{\it p} is the {\tt NULL} pointer.
1198
1199\membersection{::wxGetTranslation}\label{wxgettranslation}
1200
1201\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
1202
1203This function returns the translation of string {\it str} in the current
1204\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
1205message catalogs (see \helpref{internationalization overview}{internationalization}), the
1206original string is returned. In debug build, an error message is logged - this
1207should help to find the strings which were not yet translated. As this function
1208is used very often, an alternative syntax is provided: the \_() macro is
1209defined as wxGetTranslation().
1210
1211\membersection{::wxSnprintf}\label{wxsnprintf}
a660d684 1212
b0fc8832 1213\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
a660d684 1214
b0fc8832
VZ
1215This function replaces the dangerous standard function {\tt sprintf()} and is
1216like {\tt snprintf()} available on some platforms. The only difference with
1217sprintf() is that an additional argument - buffer size - is taken and the
1218buffer is never overflowed.
a660d684 1219
b0fc8832
VZ
1220Returns the number of characters copied to the buffer or -1 if there is not
1221enough space.
a660d684 1222
b0fc8832 1223\wxheading{See also}
a660d684 1224
b0fc8832
VZ
1225\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
1226
1227\membersection{::wxToLower}\label{wxtolower}
1228
1229\func{char}{wxToLower}{\param{char }{ch}}
1230
1231Converts the character to lower case. This is implemented as a macro for efficiency.
a660d684 1232
954b8ae6
JS
1233\wxheading{Include files}
1234
b0fc8832 1235<wx/utils.h>
954b8ae6 1236
b0fc8832 1237\membersection{::wxToUpper}\label{wxtoupper}
c50f1fb9 1238
b0fc8832 1239\func{char}{wxToUpper}{\param{char }{ch}}
c50f1fb9 1240
b0fc8832 1241Converts the character to upper case. This is implemented as a macro for efficiency.
c50f1fb9 1242
b0fc8832 1243\wxheading{Include files}
c50f1fb9 1244
b0fc8832 1245<wx/utils.h>
c50f1fb9 1246
b0fc8832
VZ
1247\membersection{::wxVsnprintf}\label{wxvsnprintf}
1248
ea44a631 1249\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
b0fc8832 1250
7ac13b21 1251The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list }
b0fc8832 1252argument instead of arbitrary number of parameters.
c50f1fb9 1253
e12be2f7 1254\wxheading{See also}
c50f1fb9 1255
b0fc8832 1256\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
c50f1fb9 1257
b0fc8832 1258\section{Dialog functions}\label{dialogfunctions}
c50f1fb9 1259
b0fc8832
VZ
1260Below are a number of convenience functions for getting input from the
1261user or displaying messages. Note that in these functions the last three
1262parameters are optional. However, it is recommended to pass a parent frame
1263parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
1264the front when the dialog box is popped up.
c50f1fb9 1265
b0fc8832 1266\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
a660d684 1267
b0fc8832
VZ
1268\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
1269
1270Changes the cursor to the given cursor for all windows in the application.
1271Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
1272to its previous state. These two calls can be nested, and a counter
1273ensures that only the outer calls take effect.
1274
1275See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
a660d684 1276
954b8ae6
JS
1277\wxheading{Include files}
1278
b0fc8832 1279<wx/utils.h>
954b8ae6 1280
b0fc8832 1281\membersection{::wxBell}\label{wxbell}
ec5d7799 1282
b0fc8832 1283\func{void}{wxBell}{\void}
ec5d7799 1284
b0fc8832 1285Ring the system bell.
ec5d7799 1286
b0fc8832 1287\wxheading{Include files}
ec5d7799 1288
b0fc8832 1289<wx/utils.h>
a660d684 1290
b0fc8832 1291\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
a660d684 1292
b0fc8832
VZ
1293\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
1294 \param{size\_t }{currentTip}}
a660d684 1295
b0fc8832
VZ
1296This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
1297used with \helpref{wxShowTip}{wxshowtip}.
a660d684 1298
b0fc8832
VZ
1299\docparam{filename}{The name of the file containing the tips, one per line}
1300\docparam{currentTip}{The index of the first tip to show - normally this index
1301is remembered between the 2 program runs.}
a660d684 1302
b0fc8832 1303\wxheading{See also}
a660d684 1304
b0fc8832 1305\helpref{Tips overview}{tipsoverview}
904a68b6 1306
b0fc8832 1307\wxheading{Include files}
904a68b6 1308
b0fc8832 1309<wx/tipdlg.h>
904a68b6 1310
b0fc8832 1311\membersection{::wxDirSelector}\label{wxdirselector}
904a68b6 1312
b0fc8832
VZ
1313\func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\
1314 \param{const wxString\& }{default\_path = ""},\\
1315 \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\
1316 \param{wxWindow *}{parent = NULL}}
904a68b6 1317
b0fc8832
VZ
1318Pops up a directory selector dialog. The arguments have the same meaning as
1319those of wxDirDialog::wxDirDialog(). The message is displayed at the top,
1320and the default\_path, if specified, is set as the initial selection.
904a68b6 1321
b0fc8832
VZ
1322The application must check for an empty return value (if the user pressed
1323Cancel). For example:
904a68b6 1324
b0fc8832
VZ
1325\begin{verbatim}
1326const wxString& dir = wxDirSelector("Choose a folder");
1327if ( !dir.empty() )
1328{
1329 ...
1330}
1331\end{verbatim}
904a68b6 1332
b0fc8832 1333\wxheading{Include files}
a660d684 1334
b0fc8832 1335<wx/dirdlg.h>
a660d684 1336
b0fc8832 1337\membersection{::wxFileSelector}\label{wxfileselector}
a660d684 1338
b0fc8832
VZ
1339\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
1340 \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\
1341 \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = ""},\\
1342 \param{int}{ x = -1}, \param{int}{ y = -1}}
a660d684 1343
b0fc8832
VZ
1344Pops up a file selector box. In Windows, this is the common file selector
1345dialog. In X, this is a file selector box with the same functionality.
1346The path and filename are distinct elements of a full file pathname.
1347If path is empty, the current directory will be used. If filename is empty,
1348no default filename will be supplied. The wildcard determines what files
1349are displayed in the file selector, and file extension supplies a type
1350extension for the required filename. Flags may be a combination of wxOPEN,
1351wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, wxFILE\_MUST\_EXIST, wxMULTIPLE or 0.
a660d684 1352
b0fc8832
VZ
1353Both the Unix and Windows versions implement a wildcard filter. Typing a
1354filename containing wildcards (*, ?) in the filename text item, and
1355clicking on Ok, will result in only those files matching the pattern being
1356displayed.
a660d684 1357
b0fc8832
VZ
1358The wildcard may be a specification for multiple types of file
1359with a description for each, such as:
a660d684 1360
b0fc8832
VZ
1361\begin{verbatim}
1362 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
1363\end{verbatim}
a660d684 1364
b0fc8832
VZ
1365The application must check for an empty return value (the user pressed
1366Cancel). For example:
a660d684 1367
b0fc8832
VZ
1368\begin{verbatim}
1369const wxString& s = wxFileSelector("Choose a file to open");
1370if (s)
1371{
1372 ...
1373}
1374\end{verbatim}
a660d684 1375
b0fc8832 1376\wxheading{Include files}
a660d684 1377
b0fc8832 1378<wx/filedlg.h>
a660d684 1379
b0fc8832 1380\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
a660d684 1381
b0fc8832 1382\func{void}{wxEndBusyCursor}{\void}
f53561f1 1383
b0fc8832
VZ
1384Changes the cursor back to the original cursor, for all windows in the application.
1385Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
1386
1387See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
a660d684 1388
954b8ae6
JS
1389\wxheading{Include files}
1390
b0fc8832 1391<wx/utils.h>
954b8ae6 1392
b0fc8832 1393\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
a660d684 1394
b0fc8832 1395\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}}
a660d684 1396
b0fc8832
VZ
1397Shows the colour selection dialog and returns the colour selected by user or
1398invalid colour (use \helpref{wxColour::Ok}{wxcolourok} to test whether a colour
1399is valid) if the dialog was cancelled.
a660d684 1400
b0fc8832 1401\wxheading{Parameters}
a660d684 1402
b0fc8832 1403\docparam{parent}{The parent window for the colour selection dialog}
a660d684 1404
b0fc8832 1405\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
a660d684 1406
b0fc8832 1407\wxheading{Include files}
a660d684 1408
b0fc8832 1409<wx/colordlg.h>
a660d684 1410
d741c583
VZ
1411\membersection{::wxGetFontFromUser}\label{wxgetfontfromuser}
1412
1413\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}}
1414
1415Shows the font selection dialog and returns the font selected by user or
1416invalid font (use \helpref{wxFont::Ok}{wxfontok} to test whether a font
1417is valid) if the dialog was cancelled.
1418
1419\wxheading{Parameters}
1420
65d877d2 1421\docparam{parent}{The parent window for the font selection dialog}
d741c583
VZ
1422
1423\docparam{fontInit}{If given, this will be the font initially selected in the dialog.}
1424
1425\wxheading{Include files}
1426
1427<wx/fontdlg.h>
1428
1429
b0fc8832 1430\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
a660d684 1431
b0fc8832
VZ
1432\func{size\_t}{wxGetMultipleChoices}{\\
1433 \param{wxArrayInt\& }{selections},\\
1434 \param{const wxString\& }{message},\\
1435 \param{const wxString\& }{caption},\\
1436 \param{const wxArrayString\& }{aChoices},\\
1437 \param{wxWindow *}{parent = NULL},\\
1438 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1439 \param{bool}{ centre = TRUE},\\
1440 \param{int }{width=150}, \param{int }{height=200}}
a660d684 1441
b0fc8832
VZ
1442\func{size\_t}{wxGetMultipleChoices}{\\
1443 \param{wxArrayInt\& }{selections},\\
1444 \param{const wxString\& }{message},\\
1445 \param{const wxString\& }{caption},\\
1446 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
1447 \param{wxWindow *}{parent = NULL},\\
1448 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1449 \param{bool}{ centre = TRUE},\\
1450 \param{int }{width=150}, \param{int }{height=200}}
a660d684 1451
b0fc8832
VZ
1452Pops up a dialog box containing a message, OK/Cancel buttons and a
1453multiple-selection listbox. The user may choose an arbitrary (including 0)
1454number of items in the listbox whose indices will be returned in
1455{\it selection} array. The initial contents of this array will be used to
1456select the items when the dialog is shown.
a660d684 1457
b0fc8832
VZ
1458You may pass the list of strings to choose from either using {\it choices}
1459which is an array of {\it n} strings for the listbox or by using a single
1460{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
a660d684 1461
b0fc8832
VZ
1462If {\it centre} is TRUE, the message text (which may include new line
1463characters) is centred; if FALSE, the message is left-justified.
a660d684 1464
b0fc8832 1465\wxheading{Include files}
a660d684 1466
b0fc8832 1467<wx/choicdlg.h>
a660d684 1468
b0fc8832
VZ
1469\perlnote{In wxPerl there is just an array reference in place of {\tt n}
1470and {\tt choices}, and no {\tt selections} parameter; the function
1471returns an array containing the user selections.}
a660d684 1472
b0fc8832 1473\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
a660d684 1474
b0fc8832
VZ
1475\func{long}{wxGetNumberFromUser}{
1476 \param{const wxString\& }{message},
1477 \param{const wxString\& }{prompt},
1478 \param{const wxString\& }{caption},
1479 \param{long }{value},
1480 \param{long }{min = 0},
1481 \param{long }{max = 100},
1482 \param{wxWindow *}{parent = NULL},
1483 \param{const wxPoint\& }{pos = wxDefaultPosition}}
a660d684 1484
b0fc8832
VZ
1485Shows a dialog asking the user for numeric input. The dialogs title is set to
1486{\it caption}, it contains a (possibly) multiline {\it message} above the
1487single line {\it prompt} and the zone for entering the number.
a660d684 1488
b0fc8832
VZ
1489The number entered must be in the range {\it min}..{\it max} (both of which
1490should be positive) and {\it value} is the initial value of it. If the user
1491enters an invalid value or cancels the dialog, the function will return -1.
a660d684 1492
b0fc8832
VZ
1493Dialog is centered on its {\it parent} unless an explicit position is given in
1494{\it pos}.
a660d684 1495
b0fc8832 1496\wxheading{Include files}
a660d684 1497
b0fc8832 1498<wx/textdlg.h>
a660d684 1499
b0fc8832 1500\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
a660d684 1501
b0fc8832
VZ
1502\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
1503 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}}
a660d684 1504
b0fc8832
VZ
1505Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered
1506in the dialog is not shown on screen but replaced with stars. This is intended
1507to be used for entering passwords as the function name implies.
a660d684 1508
b0fc8832 1509\wxheading{Include files}
a660d684 1510
b0fc8832 1511<wx/textdlg.h>
a660d684 1512
b0fc8832 1513\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
a660d684 1514
b0fc8832
VZ
1515\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
1516 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
1517 \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = TRUE}}
a660d684 1518
b0fc8832
VZ
1519Pop up a dialog box with title set to {\it caption}, {\it message}, and a
1520\rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
1521or press Cancel to return the empty string.
a660d684 1522
b0fc8832
VZ
1523If {\it centre} is TRUE, the message text (which may include new line characters)
1524is centred; if FALSE, the message is left-justified.
a660d684 1525
b0fc8832 1526\wxheading{Include files}
a660d684 1527
b0fc8832 1528<wx/textdlg.h>
a660d684 1529
b0fc8832 1530\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
a660d684 1531
b0fc8832
VZ
1532\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
1533 \param{int }{nsel}, \param{int *}{selection},
1534 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
1535 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684 1536
b0fc8832
VZ
1537Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
1538listbox. The user may choose one or more item(s) and press OK or Cancel.
a660d684 1539
b0fc8832
VZ
1540The number of initially selected choices, and array of the selected indices,
1541are passed in; this array will contain the user selections on exit, with
1542the function returning the number of selections. {\it selection} must be
1543as big as the number of choices, in case all are selected.
a660d684 1544
b0fc8832 1545If Cancel is pressed, -1 is returned.
a660d684 1546
b0fc8832 1547{\it choices} is an array of {\it n} strings for the listbox.
a660d684 1548
b0fc8832
VZ
1549If {\it centre} is TRUE, the message text (which may include new line characters)
1550is centred; if FALSE, the message is left-justified.
a660d684 1551
b0fc8832 1552\wxheading{Include files}
a660d684 1553
b0fc8832 1554<wx/choicdlg.h>
a660d684 1555
b0fc8832 1556\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
a660d684 1557
b0fc8832
VZ
1558\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
1559 \param{const wxString\& }{caption},\\
1560 \param{const wxArrayString\& }{aChoices},\\
1561 \param{wxWindow *}{parent = NULL},\\
1562 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1563 \param{bool}{ centre = TRUE},\\
1564 \param{int }{width=150}, \param{int }{height=200}}
a660d684 1565
b0fc8832
VZ
1566\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
1567 \param{const wxString\& }{caption},\\
1568 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
1569 \param{wxWindow *}{parent = NULL},\\
1570 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1571 \param{bool}{ centre = TRUE},\\
1572 \param{int }{width=150}, \param{int }{height=200}}
a660d684 1573
b0fc8832
VZ
1574Pops up a dialog box containing a message, OK/Cancel buttons and a
1575single-selection listbox. The user may choose an item and press OK to return a
1576string or Cancel to return the empty string. Use
1577\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex} if empty string is a
1578valid choice and if you want to be able to detect pressing Cancel reliably.
a660d684 1579
b0fc8832
VZ
1580You may pass the list of strings to choose from either using {\it choices}
1581which is an array of {\it n} strings for the listbox or by using a single
1582{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
a660d684 1583
b0fc8832
VZ
1584If {\it centre} is TRUE, the message text (which may include new line
1585characters) is centred; if FALSE, the message is left-justified.
a660d684 1586
954b8ae6
JS
1587\wxheading{Include files}
1588
b0fc8832 1589<wx/choicdlg.h>
954b8ae6 1590
b0fc8832
VZ
1591\perlnote{In wxPerl there is just an array reference in place of {\tt n}
1592and {\tt choices}.}
a660d684 1593
b0fc8832 1594\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
a660d684 1595
b0fc8832
VZ
1596\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
1597 \param{const wxString\& }{caption},\\
1598 \param{const wxArrayString\& }{aChoices},\\
1599 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
1600 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684 1601
b0fc8832
VZ
1602\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
1603 \param{const wxString\& }{caption},\\
1604 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
1605 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
1606 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684 1607
b0fc8832
VZ
1608As {\bf wxGetSingleChoice} but returns the index representing the selected
1609string. If the user pressed cancel, -1 is returned.
a660d684 1610
b0fc8832 1611\wxheading{Include files}
a660d684 1612
b0fc8832 1613<wx/choicdlg.h>
a660d684 1614
b0fc8832
VZ
1615\perlnote{In wxPerl there is just an array reference in place of {\tt n}
1616and {\tt choices}.}
a660d684 1617
b0fc8832 1618\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
a660d684 1619
b0fc8832
VZ
1620\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
1621 \param{const wxString\& }{caption},\\
1622 \param{const wxArrayString\& }{aChoices},\\
1623 \param{const wxString\& }{client\_data[]},\\
1624 \param{wxWindow *}{parent = NULL},\\
1625 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1626 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684 1627
b0fc8832
VZ
1628\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
1629 \param{const wxString\& }{caption},\\
1630 \param{int}{ n}, \param{const wxString\& }{choices[]},\\
1631 \param{const wxString\& }{client\_data[]},\\
1632 \param{wxWindow *}{parent = NULL},\\
1633 \param{int}{ x = -1}, \param{int}{ y = -1},\\
1634 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
a660d684 1635
b0fc8832
VZ
1636As {\bf wxGetSingleChoice} but takes an array of client data pointers
1637corresponding to the strings, and returns one of these pointers or NULL if
1638Cancel was pressed. The {\it client\_data} array must have the same number of
1639elements as {\it choices} or {\it aChoices}!
a660d684 1640
b0fc8832 1641\wxheading{Include files}
a660d684 1642
b0fc8832 1643<wx/choicdlg.h>
a660d684 1644
b0fc8832
VZ
1645\perlnote{In wxPerl there is just an array reference in place of {\tt n}
1646and {\tt choices}, and the client data array must have the
1647same length as the choices array.}
a660d684 1648
b0fc8832 1649\membersection{::wxIsBusy}\label{wxisbusy}
a660d684 1650
b0fc8832 1651\func{bool}{wxIsBusy}{\void}
a660d684 1652
b0fc8832
VZ
1653Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
1654\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
a660d684 1655
b0fc8832 1656See also \helpref{wxBusyCursor}{wxbusycursor}.
a660d684 1657
b0fc8832 1658\wxheading{Include files}
a660d684 1659
b0fc8832 1660<wx/utils.h>
a660d684 1661
b0fc8832 1662\membersection{::wxMessageBox}\label{wxmessagebox}
a660d684 1663
b0fc8832
VZ
1664\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
1665 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
a660d684 1666
b0fc8832
VZ
1667General purpose message dialog. {\it style} may be a bit list of the
1668following identifiers:
a660d684 1669
b0fc8832
VZ
1670\begin{twocollist}\itemsep=0pt
1671\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
1672wxCANCEL.}
1673\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
1674wxYES\_NO or wxOK.}
1675\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
1676\twocolitem{wxCENTRE}{Centres the text.}
1677\twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.}
1678\twocolitem{wxICON\_HAND}{Displays an error symbol.}
1679\twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.}
1680\twocolitem{wxICON\_QUESTION}{Displays a question mark symbol.}
1681\twocolitem{wxICON\_INFORMATION}{Displays an information symbol.}
1682\end{twocollist}
a660d684 1683
b0fc8832 1684The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
a660d684 1685
b0fc8832 1686For example:
a660d684 1687
b0fc8832
VZ
1688\begin{verbatim}
1689 ...
1690 int answer = wxMessageBox("Quit program?", "Confirm",
1691 wxYES_NO | wxCANCEL, main_frame);
1692 if (answer == wxYES)
1693 delete main_frame;
1694 ...
1695\end{verbatim}
a660d684 1696
b0fc8832
VZ
1697{\it message} may contain newline characters, in which case the
1698message will be split into separate lines, to cater for large messages.
a660d684 1699
b0fc8832
VZ
1700Under Windows, the native MessageBox function is used unless wxCENTRE
1701is specified in the style, in which case a generic function is used.
1702This is because the native MessageBox function cannot centre text.
1703The symbols are not shown when the generic function is used.
a660d684 1704
b0fc8832 1705\wxheading{Include files}
a660d684 1706
b0fc8832 1707<wx/msgdlg.h>
a660d684 1708
b0fc8832 1709\membersection{::wxShowTip}\label{wxshowtip}
a660d684 1710
b0fc8832
VZ
1711\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
1712 \param{wxTipProvider *}{tipProvider},
1713 \param{bool }{showAtStartup = TRUE}}
a660d684 1714
b0fc8832 1715This function shows a "startup tip" to the user.
a660d684 1716
b0fc8832 1717\docparam{parent}{The parent window for the modal dialog}
a660d684 1718
b0fc8832
VZ
1719\docparam{tipProvider}{An object which is used to get the text of the tips.
1720It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
a660d684 1721
b0fc8832
VZ
1722\docparam{showAtStartup}{Should be TRUE if startup tips are shown, FALSE
1723otherwise. This is used as the initial value for "Show tips at startup"
1724checkbox which is shown in the tips dialog.}
a660d684 1725
b0fc8832 1726\wxheading{See also}
a660d684 1727
b0fc8832 1728\helpref{Tips overview}{tipsoverview}
a660d684 1729
b0fc8832 1730\wxheading{Include files}
f6bcfd97 1731
b0fc8832 1732<wx/tipdlg.h>
f6bcfd97 1733
b0fc8832 1734\section{GDI functions}\label{gdifunctions}
f6bcfd97 1735
b0fc8832 1736The following are relevant to the GDI (Graphics Device Interface).
f6bcfd97
BP
1737
1738\wxheading{Include files}
1739
b0fc8832 1740<wx/gdicmn.h>
f6bcfd97 1741
b0fc8832 1742\membersection{wxBITMAP}\label{wxbitmapmacro}
a660d684 1743
b0fc8832 1744\func{}{wxBITMAP}{bitmapName}
a660d684 1745
b0fc8832
VZ
1746This macro loads a bitmap from either application resources (on the platforms
1747for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
1748avoid using {\tt \#ifdef}s when creating bitmaps.
a660d684 1749
b0fc8832 1750\wxheading{See also}
954b8ae6 1751
b0fc8832
VZ
1752\helpref{Bitmaps and icons overview}{wxbitmapoverview},
1753\helpref{wxICON}{wxiconmacro}
a660d684 1754
b0fc8832 1755\wxheading{Include files}
954b8ae6 1756
b0fc8832 1757<wx/gdicmn.h>
a660d684 1758
b0fc8832 1759\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect}
a660d684 1760
b0fc8832
VZ
1761\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
1762\param{int *}{width}, \param{int *}{height}}
954b8ae6 1763
b0fc8832 1764\func{wxRect}{wxGetClientDisplayRect}{\void}
954b8ae6 1765
b0fc8832
VZ
1766Returns the dimensions of the work area on the display. On Windows
1767this means the area not covered by the taskbar, etc. Other platforms
1768are currently defaulting to the whole display until a way is found to
1769provide this info for all window managers, etc.
a660d684 1770
b0fc8832 1771\membersection{::wxColourDisplay}\label{wxcolourdisplay}
a660d684 1772
b0fc8832 1773\func{bool}{wxColourDisplay}{\void}
a660d684 1774
b0fc8832 1775Returns TRUE if the display is colour, FALSE otherwise.
a660d684 1776
b0fc8832 1777\membersection{::wxDisplayDepth}\label{wxdisplaydepth}
954b8ae6 1778
b0fc8832 1779\func{int}{wxDisplayDepth}{\void}
954b8ae6 1780
b0fc8832 1781Returns the depth of the display (a value of 1 denotes a monochrome display).
a660d684 1782
b0fc8832 1783\membersection{::wxDisplaySize}\label{wxdisplaysize}
a660d684 1784
b0fc8832 1785\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
a660d684 1786
b0fc8832 1787\func{wxSize}{wxGetDisplaySize}{\void}
a660d684 1788
b0fc8832 1789Returns the display size in pixels.
a660d684 1790
b0fc8832 1791\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm}
a660d684 1792
b0fc8832 1793\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
a660d684 1794
b0fc8832 1795\func{wxSize}{wxGetDisplaySizeMM}{\void}
a660d684 1796
b0fc8832 1797Returns the display size in millimeters.
e2a6f233 1798
b0fc8832 1799\membersection{::wxDROP\_ICON}\label{wxdropicon}
e2a6f233 1800
b0fc8832 1801\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
e2a6f233 1802
b0fc8832
VZ
1803This macro creates either a cursor (MSW) or an icon (elsewhere) with the given
1804name. Under MSW, the cursor is loaded from the resource file and the icon is
1805loaded from XPM file under other platforms.
1806
1807This macro should be used with
1808\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}.
e2a6f233 1809
954b8ae6
JS
1810\wxheading{Include files}
1811
b0fc8832 1812<wx/dnd.h>
954b8ae6 1813
b0fc8832 1814\membersection{wxICON}\label{wxiconmacro}
e2a6f233 1815
b0fc8832 1816\func{}{wxICON}{iconName}
e2a6f233 1817
b0fc8832
VZ
1818This macro loads an icon from either application resources (on the platforms
1819for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
1820avoid using {\tt \#ifdef}s when creating icons.
e2a6f233 1821
b0fc8832 1822\wxheading{See also}
e2a6f233 1823
b0fc8832
VZ
1824\helpref{Bitmaps and icons overview}{wxbitmapoverview},
1825\helpref{wxBITMAP}{wxbitmapmacro}
e2a6f233 1826
954b8ae6
JS
1827\wxheading{Include files}
1828
b0fc8832 1829<wx/gdicmn.h>
a660d684 1830
b0fc8832 1831\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
de6019fb 1832
b0fc8832
VZ
1833\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
1834 \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
a660d684 1835
b0fc8832
VZ
1836Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
1837makes it into a placeable metafile by prepending a header containing the given
1838bounding box. The bounding box may be obtained from a device context after drawing
1839into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
a660d684 1840
b0fc8832
VZ
1841In addition to adding the placeable metafile header, this function adds
1842the equivalent of the following code to the start of the metafile data:
a660d684 1843
b0fc8832
VZ
1844\begin{verbatim}
1845 SetMapMode(dc, MM_ANISOTROPIC);
1846 SetWindowOrg(dc, minX, minY);
1847 SetWindowExt(dc, maxX - minX, maxY - minY);
1848\end{verbatim}
6fb26ea3 1849
b0fc8832 1850This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
954b8ae6 1851
b0fc8832
VZ
1852Placeable metafiles may be imported by many Windows applications, and can be
1853used in RTF (Rich Text Format) files.
954b8ae6 1854
b0fc8832 1855{\it scale} allows the specification of scale for the metafile.
a660d684 1856
b0fc8832 1857This function is only available under Windows.
a660d684 1858
b0fc8832 1859\membersection{::wxSetCursor}\label{wxsetcursor}
a660d684 1860
b0fc8832 1861\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
954b8ae6 1862
b0fc8832
VZ
1863Globally sets the cursor; only has an effect in Windows and GTK.
1864See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
954b8ae6 1865
b0fc8832 1866\section{Printer settings}\label{printersettings}
8e193f38 1867
b0fc8832 1868These routines are obsolete and should no longer be used!
8e193f38 1869
b0fc8832
VZ
1870The following functions are used to control PostScript printing. Under
1871Windows, PostScript output can only be sent to a file.
8e193f38
VZ
1872
1873\wxheading{Include files}
1874
b0fc8832 1875<wx/dcps.h>
a660d684 1876
b0fc8832 1877\membersection{::wxGetPrinterCommand}\label{wxgetprintercommand}
a660d684 1878
b0fc8832 1879\func{wxString}{wxGetPrinterCommand}{\void}
a660d684 1880
b0fc8832 1881Gets the printer command used to print a file. The default is {\tt lpr}.
a660d684 1882
b0fc8832 1883\membersection{::wxGetPrinterFile}\label{wxgetprinterfile}
a660d684 1884
b0fc8832 1885\func{wxString}{wxGetPrinterFile}{\void}
a660d684 1886
b0fc8832 1887Gets the PostScript output filename.
a660d684 1888
b0fc8832 1889\membersection{::wxGetPrinterMode}\label{wxgetprintermode}
a660d684 1890
b0fc8832 1891\func{int}{wxGetPrinterMode}{\void}
954b8ae6 1892
b0fc8832
VZ
1893Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
1894The default is PS\_PREVIEW.
954b8ae6 1895
b0fc8832 1896\membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions}
954b8ae6 1897
b0fc8832 1898\func{wxString}{wxGetPrinterOptions}{\void}
954b8ae6 1899
b0fc8832 1900Gets the additional options for the print command (e.g. specific printer). The default is nothing.
954b8ae6 1901
b0fc8832 1902\membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation}
954b8ae6 1903
b0fc8832 1904\func{int}{wxGetPrinterOrientation}{\void}
a660d684 1905
b0fc8832 1906Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
a660d684 1907
b0fc8832 1908\membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand}
8e193f38 1909
b0fc8832 1910\func{wxString}{wxGetPrinterPreviewCommand}{\void}
a660d684 1911
b0fc8832 1912Gets the command used to view a PostScript file. The default depends on the platform.
954b8ae6 1913
b0fc8832 1914\membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling}
954b8ae6 1915
b0fc8832 1916\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
a660d684 1917
b0fc8832 1918Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
a660d684 1919
b0fc8832 1920\membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation}
a660d684 1921
b0fc8832 1922\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
954b8ae6 1923
b0fc8832 1924Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
954b8ae6 1925
b0fc8832 1926\membersection{::wxSetPrinterCommand}\label{wxsetprintercommand}
a660d684 1927
b0fc8832 1928\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
a660d684 1929
b0fc8832 1930Sets the printer command used to print a file. The default is {\tt lpr}.
a660d684 1931
b0fc8832 1932\membersection{::wxSetPrinterFile}\label{wxsetprinterfile}
cd6ce4a9 1933
b0fc8832 1934\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
f6bcfd97 1935
b0fc8832 1936Sets the PostScript output filename.
a660d684 1937
b0fc8832 1938\membersection{::wxSetPrinterMode}\label{wxsetprintermode}
a660d684 1939
b0fc8832 1940\func{void}{wxSetPrinterMode}{\param{int }{mode}}
a660d684 1941
b0fc8832
VZ
1942Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
1943The default is PS\_PREVIEW.
cd6ce4a9 1944
b0fc8832 1945\membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions}
a660d684 1946
b0fc8832 1947\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
e6045e08 1948
b0fc8832 1949Sets the additional options for the print command (e.g. specific printer). The default is nothing.
a660d684 1950
b0fc8832 1951\membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation}
eafc087e 1952
b0fc8832 1953\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
cd6ce4a9 1954
b0fc8832 1955Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
a660d684 1956
b0fc8832 1957\membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand}
954b8ae6 1958
b0fc8832 1959\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
954b8ae6 1960
b0fc8832 1961Sets the command used to view a PostScript file. The default depends on the platform.
a660d684 1962
b0fc8832 1963\membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling}
a660d684 1964
b0fc8832 1965\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
a660d684 1966
b0fc8832 1967Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
954b8ae6 1968
b0fc8832 1969\membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation}
954b8ae6 1970
b0fc8832 1971\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
a660d684 1972
b0fc8832 1973Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
a660d684 1974
b0fc8832
VZ
1975\section{Clipboard functions}\label{clipsboard}
1976
1977These clipboard functions are implemented for Windows only. The use of these functions
1978is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard}
1979class instead.
a660d684 1980
954b8ae6
JS
1981\wxheading{Include files}
1982
b0fc8832 1983<wx/clipbrd.h>
954b8ae6 1984
f4fcc291 1985\membersection{::wxClipboardOpen}\label{functionwxclipboardopen}
a660d684 1986
b0fc8832 1987\func{bool}{wxClipboardOpen}{\void}
a660d684 1988
b0fc8832 1989Returns TRUE if this application has already opened the clipboard.
a660d684 1990
b0fc8832 1991\membersection{::wxCloseClipboard}\label{wxcloseclipboard}
954b8ae6 1992
b0fc8832 1993\func{bool}{wxCloseClipboard}{\void}
954b8ae6 1994
b0fc8832 1995Closes the clipboard to allow other applications to use it.
a660d684 1996
b0fc8832 1997\membersection{::wxEmptyClipboard}\label{wxemptyclipboard}
a660d684 1998
b0fc8832 1999\func{bool}{wxEmptyClipboard}{\void}
a660d684 2000
b0fc8832 2001Empties the clipboard.
954b8ae6 2002
b0fc8832 2003\membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats}
954b8ae6 2004
b0fc8832 2005\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
a660d684 2006
b0fc8832
VZ
2007Enumerates the formats found in a list of available formats that belong
2008to the clipboard. Each call to this function specifies a known
2009available format; the function returns the format that appears next in
2010the list.
a660d684 2011
b0fc8832
VZ
2012{\it dataFormat} specifies a known format. If this parameter is zero,
2013the function returns the first format in the list.
a660d684 2014
b0fc8832
VZ
2015The return value specifies the next known clipboard data format if the
2016function is successful. It is zero if the {\it dataFormat} parameter specifies
2017the last format in the list of available formats, or if the clipboard
2018is not open.
a660d684 2019
b0fc8832
VZ
2020Before it enumerates the formats function, an application must open the clipboard by using the
2021wxOpenClipboard function.
954b8ae6 2022
b0fc8832 2023\membersection{::wxGetClipboardData}\label{wxgetclipboarddata}
954b8ae6 2024
b0fc8832 2025\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
26a80c22 2026
b0fc8832 2027Gets data from the clipboard.
26a80c22 2028
b0fc8832 2029{\it dataFormat} may be one of:
26a80c22 2030
b0fc8832
VZ
2031\begin{itemize}\itemsep=0pt
2032\item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
2033\item wxCF\_BITMAP: returns a new wxBitmap.
2034\end{itemize}
26a80c22 2035
b0fc8832 2036The clipboard must have previously been opened for this call to succeed.
26a80c22 2037
b0fc8832 2038\membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname}
26a80c22 2039
b0fc8832 2040\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
a660d684 2041
b0fc8832
VZ
2042Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
2043length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
a660d684 2044
b0fc8832 2045\membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable}
a660d684 2046
b0fc8832 2047\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
954b8ae6 2048
b0fc8832 2049Returns TRUE if the given data format is available on the clipboard.
954b8ae6 2050
b0fc8832 2051\membersection{::wxOpenClipboard}\label{wxopenclipboard}
a660d684 2052
b0fc8832 2053\func{bool}{wxOpenClipboard}{\void}
a660d684 2054
b0fc8832 2055Opens the clipboard for passing data to it or getting data from it.
a660d684 2056
b0fc8832 2057\membersection{::wxRegisterClipboardFormat}\label{wxregisterclipboardformat}
954b8ae6 2058
b0fc8832 2059\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
954b8ae6 2060
b0fc8832 2061Registers the clipboard data format name and returns an identifier.
a660d684 2062
b0fc8832 2063\membersection{::wxSetClipboardData}\label{wxsetclipboarddata}
a660d684 2064
b0fc8832 2065\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
c51deffc 2066
b0fc8832 2067Passes data to the clipboard.
c51deffc 2068
b0fc8832 2069{\it dataFormat} may be one of:
a660d684 2070
b0fc8832
VZ
2071\begin{itemize}\itemsep=0pt
2072\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
2073\item wxCF\_BITMAP: {\it data} is a wxBitmap.
2074\item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
2075\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
2076\end{itemize}
954b8ae6 2077
b0fc8832 2078The clipboard must have previously been opened for this call to succeed.
954b8ae6 2079
b0fc8832 2080\section{Miscellaneous functions}\label{miscellany}
a660d684 2081
b0fc8832 2082\membersection{::wxNewId}\label{wxnewid}
a660d684 2083
b0fc8832
VZ
2084\func{long}{wxNewId}{\void}
2085
2086Generates an integer identifier unique to this run of the program.
a660d684 2087
954b8ae6
JS
2088\wxheading{Include files}
2089
2090<wx/utils.h>
2091
b0fc8832 2092\membersection{::wxRegisterId}\label{wxregisterid}
a660d684 2093
b0fc8832 2094\func{void}{wxRegisterId}{\param{long}{ id}}
a660d684 2095
b0fc8832
VZ
2096Ensures that ids subsequently generated by {\bf NewId} do not clash with
2097the given {\bf id}.
a660d684 2098
954b8ae6
JS
2099\wxheading{Include files}
2100
2101<wx/utils.h>
2102
b0fc8832 2103\membersection{::wxDDECleanUp}\label{wxddecleanup}
bdc72a22 2104
b0fc8832 2105\func{void}{wxDDECleanUp}{\void}
bdc72a22 2106
b0fc8832
VZ
2107Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
2108called by the application.
bdc72a22 2109
b0fc8832 2110See also \helpref{wxDDEInitialize}{wxddeinitialize}.
bdc72a22
VZ
2111
2112\wxheading{Include files}
2113
b0fc8832 2114<wx/dde.h>
a660d684 2115
b0fc8832 2116\membersection{::wxDDEInitialize}\label{wxddeinitialize}
a660d684 2117
b0fc8832 2118\func{void}{wxDDEInitialize}{\void}
a660d684 2119
b0fc8832 2120Initializes the DDE system. May be called multiple times without harm.
a660d684 2121
b0fc8832
VZ
2122This no longer needs to be called by the application: it will be called
2123by wxWindows if necessary.
bdc72a22 2124
b0fc8832
VZ
2125See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
2126\helpref{wxDDECleanUp}{wxddecleanup}.
bdc72a22 2127
954b8ae6
JS
2128\wxheading{Include files}
2129
b0fc8832 2130<wx/dde.h>
a660d684 2131
b0fc8832 2132\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
a660d684 2133
b0fc8832 2134\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
a660d684 2135
b0fc8832
VZ
2136This function enables or disables all top level windows. It is used by
2137\helpref{::wxSafeYield}{wxsafeyield}.
a660d684 2138
954b8ae6
JS
2139\wxheading{Include files}
2140
2141<wx/utils.h>
2142
b0fc8832 2143\membersection{::wxFindMenuItemId}\label{wxfindmenuitemid}
a660d684 2144
b0fc8832 2145\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
a660d684 2146
b0fc8832 2147Find a menu item identifier associated with the given frame's menu bar.
a660d684 2148
954b8ae6
JS
2149\wxheading{Include files}
2150
2151<wx/utils.h>
2152
b0fc8832 2153\membersection{::wxFindWindowByLabel}\label{wxfindwindowbylabel}
c51deffc 2154
b0fc8832 2155\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
c51deffc 2156
b0fc8832
VZ
2157Find a window by its label. Depending on the type of window, the label may be a window title
2158or panel item label. If {\it parent} is NULL, the search will start from all top-level
2159frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
2160The search is recursive in both cases.
c51deffc
VZ
2161
2162\wxheading{Include files}
2163
2164<wx/utils.h>
2165
b0fc8832
VZ
2166\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
2167
2168\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
a660d684 2169
b0fc8832
VZ
2170Find a window by its name (as given in a window constructor or {\bf Create} function call).
2171If {\it parent} is NULL, the search will start from all top-level
2172frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
2173The search is recursive in both cases.
a660d684 2174
b0fc8832 2175If no such named window is found, {\bf wxFindWindowByLabel} is called.
a660d684 2176
954b8ae6
JS
2177\wxheading{Include files}
2178
2179<wx/utils.h>
2180
b0fc8832 2181\membersection{::wxFindWindowAtPoint}\label{wxfindwindowatpoint}
6787e41e 2182
b0fc8832 2183\func{wxWindow *}{wxFindWindowAtPoint}{\param{const wxPoint\& }{pt}}
6787e41e 2184
b0fc8832
VZ
2185Find the deepest window at the given mouse position in screen coordinates,
2186returning the window if found, or NULL if not.
4d01e583 2187
b0fc8832 2188\membersection{::wxFindWindowAtPointer}\label{wxfindwindowatpointer}
4d01e583 2189
b0fc8832 2190\func{wxWindow *}{wxFindWindowAtPointer}{\param{wxPoint\& }{pt}}
4d01e583 2191
b0fc8832
VZ
2192Find the deepest window at the mouse pointer position, returning the window
2193and current pointer position in screen coordinates.
4d01e583 2194
b0fc8832 2195\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
4d01e583 2196
b0fc8832 2197\func{wxWindow *}{wxGetActiveWindow}{\void}
4d01e583 2198
b0fc8832 2199Gets the currently active window (Windows only).
4d01e583 2200
b0fc8832 2201\wxheading{Include files}
4d01e583 2202
b0fc8832 2203<wx/windows.h>
4d01e583 2204
b0fc8832 2205\membersection{::wxGetDisplayName}\label{wxgetdisplayname}
4d01e583 2206
b0fc8832 2207\func{wxString}{wxGetDisplayName}{\void}
4d01e583 2208
b0fc8832 2209Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
4d01e583
VZ
2210
2211\wxheading{Include files}
2212
b0fc8832 2213<wx/utils.h>
4d01e583 2214
b0fc8832 2215\membersection{::wxGetMousePosition}\label{wxgetmouseposition}
4d01e583 2216
b0fc8832 2217\func{wxPoint}{wxGetMousePosition}{\void}
4d01e583 2218
b0fc8832 2219Returns the mouse position in screen coordinates.
4d01e583
VZ
2220
2221\wxheading{Include files}
2222
2223<wx/utils.h>
2224
b0fc8832 2225\membersection{::wxGetResource}\label{wxgetresource}
a660d684 2226
b0fc8832
VZ
2227\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2228 \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
a660d684 2229
b0fc8832
VZ
2230\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2231 \param{float *}{value}, \param{const wxString\& }{file = NULL}}
a660d684 2232
b0fc8832
VZ
2233\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2234 \param{long *}{value}, \param{const wxString\& }{file = NULL}}
50567b69 2235
b0fc8832
VZ
2236\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2237 \param{int *}{value}, \param{const wxString\& }{file = NULL}}
50567b69 2238
b0fc8832
VZ
2239Gets a resource value from the resource database (for example, WIN.INI, or
2240.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
2241otherwise the specified file is used.
50567b69 2242
b0fc8832
VZ
2243Under X, if an application class (wxApp::GetClassName) has been defined,
2244it is appended to the string /usr/lib/X11/app-defaults/ to try to find
2245an applications default file when merging all resource databases.
50567b69 2246
b0fc8832
VZ
2247The reason for passing the result in an argument is that it
2248can be convenient to define a default value, which gets overridden
2249if the value exists in the resource file. It saves a separate
2250test for that resource's existence, and it also allows
2251the overloading of the function for different types.
50567b69 2252
b0fc8832 2253See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
a660d684 2254
954b8ae6 2255\wxheading{Include files}
a660d684 2256
954b8ae6 2257<wx/utils.h>
a660d684 2258
33b494d6
VZ
2259\membersection{::wxGetTopLevelParent}\label{wxgettoplevelparent}
2260
2261\func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}}
2262
2263Returns the first top level parent of the given window, or in other words, the
2264frame or dialog containing it, or {\tt NULL}.
2265
2266\wxheading{Include files}
2267
2268<wx/window.h>
2269
a660d684
KB
2270\membersection{::wxLoadUserResource}\label{wxloaduserresource}
2271
2272\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
2273
2274Loads a user-defined Windows resource as a string. If the resource is found, the function creates
2275a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
2276
2277The resource must be defined in the {\tt .rc} file using the following syntax:
2278
2279\begin{verbatim}
2280myResource TEXT file.ext
2281\end{verbatim}
2282
2283where {\tt file.ext} is a file that the resource compiler can find.
2284
2285One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers
2286cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed
2287using \helpref{wxResourceParseString}{wxresourceparsestring}.
2288
2289This function is available under Windows only.
2290
954b8ae6
JS
2291\wxheading{Include files}
2292
2293<wx/utils.h>
2294
a660d684
KB
2295\membersection{::wxPostDelete}\label{wxpostdelete}
2296
2297\func{void}{wxPostDelete}{\param{wxObject *}{object}}
2298
954b8ae6 2299Tells the system to delete the specified object when
a660d684
KB
2300all other events have been processed. In some environments, it is
2301necessary to use this instead of deleting a frame directly with the
954b8ae6 2302delete operator, because some GUIs will still send events to a deleted window.
a660d684
KB
2303
2304Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
2305
954b8ae6
JS
2306\wxheading{Include files}
2307
2308<wx/utils.h>
2309
8e193f38
VZ
2310\membersection{::wxPostEvent}\label{wxpostevent}
2311
2312\func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
2313
9a9e73f6
RR
2314In a GUI application, this function posts {\it event} to the specified {\it dest}
2315object using \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
2316Otherwise, it dispatches {\it event} immediately using
2317\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}.
2318See the respective documentation for details (and caveats).
8e193f38
VZ
2319
2320\wxheading{Include files}
2321
2322<wx/app.h>
2323
a660d684
KB
2324\membersection{::wxSetDisplayName}\label{wxsetdisplayname}
2325
2326\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
2327
2328Under X only, sets the current display name. This is the X host and display name such
2329as ``colonsay:0.0", and the function indicates which display should be used for creating
2330windows from this point on. Setting the display within an application allows multiple
2331displays to be used.
2332
2333See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
2334
954b8ae6
JS
2335\wxheading{Include files}
2336
2337<wx/utils.h>
2338
b0fc8832 2339\membersection{::wxStripMenuCodes}\label{wxstripmenucodes}
a660d684 2340
8a2c6ef8
JS
2341\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
2342
7ac13b21 2343\func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}}
a660d684 2344
b0fc8832
VZ
2345This function is obsolete, please use
2346\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead.
2347
a660d684 2348Strips any menu codes from {\it in} and places the result
8a2c6ef8
JS
2349in {\it out} (or returns the new string, in the first form).
2350
2351Menu codes include \& (mark the next character with an underline
a660d684
KB
2352as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
2353
954b8ae6
JS
2354\wxheading{Include files}
2355
2356<wx/utils.h>
2357
a660d684
KB
2358\membersection{::wxWriteResource}\label{wxwriteresource}
2359
2360\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2361 \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
2362
2363\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2364 \param{float }{value}, \param{const wxString\& }{file = NULL}}
2365
2366\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2367 \param{long }{value}, \param{const wxString\& }{file = NULL}}
2368
2369\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
2370 \param{int }{value}, \param{const wxString\& }{file = NULL}}
2371
2372Writes a resource value into the resource database (for example, WIN.INI, or
2373.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
2374otherwise the specified file is used.
2375
2376Under X, the resource databases are cached until the internal function
b0fc8832
VZ
2377\rtfsp{\bf wxFlushResources} is called automatically on exit, when
2378all updated resource databases are written to their files.
8a293590 2379
b0fc8832
VZ
2380Note that it is considered bad manners to write to the .Xdefaults
2381file under Unix, although the WIN.INI file is fair game under Windows.
8a293590 2382
b0fc8832 2383See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
8a293590
RR
2384
2385\wxheading{Include files}
2386
b0fc8832 2387<wx/utils.h>
8a293590 2388
81c9effa 2389\section{Byte order macros}\label{byteordermacros}
a660d684 2390
b0fc8832
VZ
2391The endian-ness issues (that is the difference between big-endian and
2392little-endian architectures) are important for the portable programs working
2393with the external binary data (for example, data files or data coming from
2394network) which is usually in some fixed, platform-independent format. The
2395macros are helpful for transforming the data to the correct format.
a660d684 2396
0180dad6
RR
2397\membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways}
2398
2399\func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}}
2400
2401\func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}}
2402
2403\func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}}
2404
2405\func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
2406
b0fc8832
VZ
2407These macros will swap the bytes of the {\it value} variable from little
2408endian to big endian or vice versa unconditionally, i.e. independently of the
2409current platform.
0180dad6
RR
2410
2411\membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe}
2412
2413\func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}}
2414
2415\func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}}
2416
2417\func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}}
2418
2419\func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}}
2420
2421This macro will swap the bytes of the {\it value} variable from little
2422endian to big endian or vice versa if the program is compiled on a
ec5d7799 2423big-endian architecture (such as Sun work stations). If the program has
0180dad6
RR
2424been compiled on a little-endian architecture, the value will be unchanged.
2425
ec5d7799 2426Use these macros to read data from and write data to a file that stores
b0fc8832 2427data in little-endian (for example Intel i386) format.
0180dad6
RR
2428
2429\membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
2430
2431\func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}}
2432
2433\func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}}
2434
2435\func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}}
2436
2437\func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}}
2438
2439This macro will swap the bytes of the {\it value} variable from little
2440endian to big endian or vice versa if the program is compiled on a
ec5d7799 2441little-endian architecture (such as Intel PCs). If the program has
0180dad6
RR
2442been compiled on a big-endian architecture, the value will be unchanged.
2443
ec5d7799 2444Use these macros to read data from and write data to a file that stores
b0fc8832
VZ
2445data in big-endian format.
2446
f4fcc291 2447\section{RTTI functions}\label{rttimacros}
b0fc8832
VZ
2448
2449wxWindows uses its own RTTI ("run-time type identification") system which
2450predates the current standard C++ RTTI and so is kept for backwards
2451compatribility reasons but also because it allows some things which the
2452standard RTTI doesn't directly support (such as creating a class from its
2453name).
2454
2455The standard C++ RTTI can be used in the user code without any problems and in
2456general you shouldn't need to use the functions and the macros in this section
2457unless you are thinking of modifying or adding any wxWindows classes.
2458
2459\wxheading{See also}
2460
2461\helpref{RTTI overview}{runtimeclassoverview}
0180dad6 2462
a660d684
KB
2463\membersection{CLASSINFO}\label{classinfo}
2464
2465\func{wxClassInfo *}{CLASSINFO}{className}
2466
2467Returns a pointer to the wxClassInfo object associated with this class.
2468
954b8ae6
JS
2469\wxheading{Include files}
2470
2471<wx/object.h>
2472
b0fc8832 2473\membersection{DECLARE\_ABSTRACT\_CLASS}\label{declareabstractclass}
a660d684
KB
2474
2475\func{}{DECLARE\_ABSTRACT\_CLASS}{className}
2476
2477Used inside a class declaration to declare that the class should be
2478made known to the class hierarchy, but objects of this class cannot be created
2479dynamically. The same as DECLARE\_CLASS.
2480
2481Example:
2482
2483\begin{verbatim}
2484class wxCommand: public wxObject
2485{
2486 DECLARE_ABSTRACT_CLASS(wxCommand)
2487
2488 private:
2489 ...
2490 public:
2491 ...
2492};
2493\end{verbatim}
2494
954b8ae6
JS
2495\wxheading{Include files}
2496
2497<wx/object.h>
2498
a660d684
KB
2499\membersection{DECLARE\_APP}\label{declareapp}
2500
2501\func{}{DECLARE\_APP}{className}
2502
2503This is used in headers to create a forward declaration of the wxGetApp function implemented
2504by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}.
2505
2506Example:
2507
2508\begin{verbatim}
2509 DECLARE_APP(MyApp)
2510\end{verbatim}
2511
954b8ae6
JS
2512\wxheading{Include files}
2513
2514<wx/app.h>
2515
b0fc8832 2516\membersection{DECLARE\_CLASS}\label{declareclass}
a660d684
KB
2517
2518\func{}{DECLARE\_CLASS}{className}
2519
2520Used inside a class declaration to declare that the class should be
2521made known to the class hierarchy, but objects of this class cannot be created
2522dynamically. The same as DECLARE\_ABSTRACT\_CLASS.
2523
954b8ae6
JS
2524\wxheading{Include files}
2525
2526<wx/object.h>
2527
b0fc8832 2528\membersection{DECLARE\_DYNAMIC\_CLASS}\label{declaredynamicclass}
a660d684
KB
2529
2530\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
2531
2532Used inside a class declaration to declare that the objects of this class should be dynamically
f6bcfd97 2533creatable from run-time type information.
a660d684
KB
2534
2535Example:
2536
2537\begin{verbatim}
2538class wxFrame: public wxWindow
2539{
2540 DECLARE_DYNAMIC_CLASS(wxFrame)
2541
2542 private:
2543 const wxString\& frameTitle;
2544 public:
2545 ...
2546};
2547\end{verbatim}
2548
954b8ae6
JS
2549\wxheading{Include files}
2550
2551<wx/object.h>
2552
b0fc8832 2553\membersection{IMPLEMENT\_ABSTRACT\_CLASS}\label{implementabstractclass}
a660d684
KB
2554
2555\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
2556
2557Used in a C++ implementation file to complete the declaration of
2558a class that has run-time type information. The same as IMPLEMENT\_CLASS.
2559
2560Example:
2561
2562\begin{verbatim}
2563IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
2564
2565wxCommand::wxCommand(void)
2566{
2567...
2568}
2569\end{verbatim}
2570
954b8ae6
JS
2571\wxheading{Include files}
2572
2573<wx/object.h>
2574
b0fc8832 2575\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}\label{implementabstractclass2}
a660d684
KB
2576
2577\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
2578
2579Used in a C++ implementation file to complete the declaration of
2580a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
2581
954b8ae6
JS
2582\wxheading{Include files}
2583
2584<wx/object.h>
2585
a660d684
KB
2586\membersection{IMPLEMENT\_APP}\label{implementapp}
2587
2588\func{}{IMPLEMENT\_APP}{className}
2589
2590This is used in the application class implementation file to make the application class known to
2591wxWindows for dynamic construction. You use this instead of
2592
2593Old form:
2594
2595\begin{verbatim}
2596 MyApp myApp;
2597\end{verbatim}
2598
2599New form:
2600
2601\begin{verbatim}
2602 IMPLEMENT_APP(MyApp)
2603\end{verbatim}
2604
2605See also \helpref{DECLARE\_APP}{declareapp}.
2606
954b8ae6
JS
2607\wxheading{Include files}
2608
2609<wx/app.h>
2610
b0fc8832 2611\membersection{IMPLEMENT\_CLASS}\label{implementclass}
a660d684
KB
2612
2613\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
2614
2615Used in a C++ implementation file to complete the declaration of
2616a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
2617
954b8ae6
JS
2618\wxheading{Include files}
2619
2620<wx/object.h>
2621
b0fc8832 2622\membersection{IMPLEMENT\_CLASS2}\label{implementclass2}
a660d684
KB
2623
2624\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
2625
2626Used in a C++ implementation file to complete the declaration of a
2627class that has run-time type information and two base classes. The
2628same as IMPLEMENT\_ABSTRACT\_CLASS2.
2629
954b8ae6
JS
2630\wxheading{Include files}
2631
2632<wx/object.h>
2633
b0fc8832 2634\membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass}
a660d684
KB
2635
2636\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
2637
2638Used in a C++ implementation file to complete the declaration of
2639a class that has run-time type information, and whose instances
2640can be created dynamically.
2641
2642Example:
2643
2644\begin{verbatim}
2645IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
2646
2647wxFrame::wxFrame(void)
2648{
2649...
2650}
2651\end{verbatim}
2652
954b8ae6
JS
2653\wxheading{Include files}
2654
2655<wx/object.h>
2656
b0fc8832 2657\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2}
a660d684
KB
2658
2659\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
2660
2661Used in a C++ implementation file to complete the declaration of
2662a class that has run-time type information, and whose instances
2663can be created dynamically. Use this for classes derived from two
2664base classes.
2665
954b8ae6
JS
2666\wxheading{Include files}
2667
2668<wx/object.h>
2669
f6bcfd97
BP
2670\membersection{wxConstCast}\label{wxconstcast}
2671
f7637829 2672\func{classname *}{wxConstCast}{ptr, classname}
f6bcfd97
BP
2673
2674This macro expands into {\tt const\_cast<classname *>(ptr)} if the compiler
2675supports {\it const\_cast} or into an old, C-style cast, otherwise.
2676
2677\wxheading{See also}
2678
2679\helpref{wxDynamicCast}{wxdynamiccast}\\
2680\helpref{wxStaticCast}{wxstaticcast}
2681
b0fc8832
VZ
2682\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
2683
2684\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
2685
2686Creates and returns an object of the given class, if the class has been
2687registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
2688
34636400
VZ
2689\membersection{WXDEBUG\_NEW}\label{debugnew}
2690
2691\func{}{WXDEBUG\_NEW}{arg}
2692
2693This is defined in debug mode to be call the redefined new operator
2694with filename and line number arguments. The definition is:
2695
2696\begin{verbatim}
2697#define WXDEBUG_NEW new(__FILE__,__LINE__)
2698\end{verbatim}
2699
2700In non-debug mode, this is defined as the normal new operator.
2701
2702\wxheading{Include files}
2703
2704<wx/object.h>
2705
2706\membersection{wxDynamicCast}\label{wxdynamiccast}
2707
f7637829 2708\func{classname *}{wxDynamicCast}{ptr, classname}
34636400
VZ
2709
2710This macro returns the pointer {\it ptr} cast to the type {\it classname *} if
8a7f3379 2711the pointer is of this type (the check is done during the run-time) or
f7637829
VZ
2712{\tt NULL} otherwise. Usage of this macro is preferred over obsoleted
2713wxObject::IsKindOf() function.
34636400 2714
f7637829
VZ
2715The {\it ptr} argument may be {\tt NULL}, in which case {\tt NULL} will be
2716returned.
34636400
VZ
2717
2718Example:
2719
2720\begin{verbatim}
2721 wxWindow *win = wxWindow::FindFocus();
2722 wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
2723 if ( text )
2724 {
2725 // a text control has the focus...
2726 }
2727 else
2728 {
f6bcfd97 2729 // no window has the focus or it is not a text control
34636400
VZ
2730 }
2731\end{verbatim}
2732
2733\wxheading{See also}
2734
f6bcfd97 2735\helpref{RTTI overview}{runtimeclassoverview}\\
f7637829 2736\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
f6bcfd97
BP
2737\helpref{wxConstCast}{wxconstcast}\\
2738\helpref{wxStatiicCast}{wxstaticcast}
34636400 2739
f7637829
VZ
2740\membersection{wxDynamicCastThis}\label{wxdynamiccastthis}
2741
2742\func{classname *}{wxDynamicCastThis}{classname}
2743
2744This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the
2745latter provokes spurious compilation warnings from some compilers (because it
2746tests whether {\tt this} pointer is non {\tt NULL} which is always true), so
2747this macro should be used to avoid them.
2748
2749\wxheading{See also}
2750
2751\helpref{wxDynamicCast}{wxdynamiccast}
2752
f6bcfd97
BP
2753\membersection{wxStaticCast}\label{wxstaticcast}
2754
f7637829 2755\func{classname *}{wxStaticCast}{ptr, classname}
f6bcfd97
BP
2756
2757This macro checks that the cast is valid in debug mode (an assert failure will
2758result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the
2759result of executing an equivalent of {\tt static\_cast<classname *>(ptr)}.
2760
2761\helpref{wxDynamicCast}{wxdynamiccast}\\
2762\helpref{wxConstCast}{wxconstcast}
2763
b0fc8832 2764\section{Resource functions}\label{resourcefuncs}
a660d684 2765
b0fc8832 2766\overview{Resource functions}{resourceformats}
a660d684
KB
2767
2768This section details functions for manipulating wxWindows (.WXR) resource
2769files and loading user interface elements from resources.
2770
2771\normalbox{Please note that this use of the word `resource' is different from that used when talking
2772about initialisation file resource reading and writing, using such functions
f6bcfd97 2773as wxWriteResource and wxGetResource. It is just an unfortunate clash of terminology.}
a660d684
KB
2774
2775\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
2776
2777See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
2778loading from resource data.
2779
2780\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
2781
2782\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
2783
2784Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
7af3ca16 2785{\tt\#}defining a name to an integer). Unlikely to be used by an application except
a660d684
KB
2786perhaps for implementing resource functionality for interpreted languages.
2787
b0fc8832 2788\membersection{::wxResourceClear}\label{wxresourceclear}
a660d684
KB
2789
2790\func{void}{wxResourceClear}{\void}
2791
2792Clears the wxWindows resource table.
2793
b0fc8832 2794\membersection{::wxResourceCreateBitmap}\label{wxresourcecreatebitmap}
a660d684
KB
2795
2796\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
2797
2798Creates a new bitmap from a file, static data, or Windows resource, given a valid
2799wxWindows bitmap resource identifier. For example, if the .WXR file contains
2800the following:
2801
2802\begin{verbatim}
f6bcfd97
BP
2803static const wxString\& project_resource = "bitmap(name = 'project_resource',\
2804 bitmap = ['project', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
2805 bitmap = ['project.xpm', wxBITMAP_TYPE_XPM, 'X']).";
a660d684
KB
2806\end{verbatim}
2807
2808then this function can be called as follows:
2809
2810\begin{verbatim}
f6bcfd97 2811 wxBitmap *bitmap = wxResourceCreateBitmap("project_resource");
a660d684
KB
2812\end{verbatim}
2813
b0fc8832 2814\membersection{::wxResourceCreateIcon}\label{wxresourcecreateicon}
a660d684
KB
2815
2816\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
2817
2818Creates a new icon from a file, static data, or Windows resource, given a valid
2819wxWindows icon resource identifier. For example, if the .WXR file contains
2820the following:
2821
2822\begin{verbatim}
f6bcfd97
BP
2823static const wxString\& project_resource = "icon(name = 'project_resource',\
2824 icon = ['project', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
2825 icon = ['project', wxBITMAP_TYPE_XBM_DATA, 'X']).";
a660d684
KB
2826\end{verbatim}
2827
2828then this function can be called as follows:
2829
2830\begin{verbatim}
f6bcfd97 2831 wxIcon *icon = wxResourceCreateIcon("project_resource");
a660d684
KB
2832\end{verbatim}
2833
b0fc8832 2834\membersection{::wxResourceCreateMenuBar}\label{wxresourcecreatemenubar}
a660d684
KB
2835
2836\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
2837
2838Creates a new menu bar given a valid wxWindows menubar resource
2839identifier. For example, if the .WXR file contains the following:
2840
2841\begin{verbatim}
2842static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
2843 menu = \
2844 [\
2845 ['&File', 1, '', \
2846 ['&Open File', 2, 'Open a file'],\
2847 ['&Save File', 3, 'Save a file'],\
2848 [],\
2849 ['E&xit', 4, 'Exit program']\
2850 ],\
2851 ['&Help', 5, '', \
2852 ['&About', 6, 'About this program']\
2853 ]\
2854 ]).";
2855\end{verbatim}
2856
2857then this function can be called as follows:
2858
2859\begin{verbatim}
2860 wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
2861\end{verbatim}
2862
2863
b0fc8832 2864\membersection{::wxResourceGetIdentifier}\label{wxresourcegetidentifier}
a660d684
KB
2865
2866\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
2867
2868Used for retrieving the integer value associated with an identifier.
2869A zero value indicates that the identifier was not found.
2870
2871See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
2872
2873\membersection{::wxResourceParseData}\label{wxresourcedata}
2874
2875\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
2876
2877Parses a string containing one or more wxWindows resource objects. If
2878the resource objects are global static data that are included into the
2879C++ program, then this function must be called for each variable
2880containing the resource data, to make it known to wxWindows.
2881
2882{\it resource} should contain data in the following form:
2883
2884\begin{verbatim}
2885dialog(name = 'dialog1',
2886 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
2887 title = 'Test dialog box',
2888 x = 312, y = 234, width = 400, height = 300,
2889 modal = 0,
f6bcfd97 2890 control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
a660d684 2891 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
f6bcfd97 2892 control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
a660d684
KB
2893 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
2894 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
2895 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
2896\end{verbatim}
2897
2898This function will typically be used after including a {\tt .wxr} file into
2899a C++ program as follows:
2900
2901\begin{verbatim}
2902#include "dialog1.wxr"
2903\end{verbatim}
2904
2905Each of the contained resources will declare a new C++ variable, and each
2906of these variables should be passed to wxResourceParseData.
2907
b0fc8832 2908\membersection{::wxResourceParseFile}\label{wxresourceparsefile}
a660d684
KB
2909
2910\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
2911
2912Parses a file containing one or more wxWindows resource objects
2913in C++-compatible syntax. Use this function to dynamically load
2914wxWindows resource data.
2915
2916\membersection{::wxResourceParseString}\label{wxresourceparsestring}
2917
7ac13b21 2918\func{bool}{wxResourceParseString}{\param{char *}{s}, \param{wxResourceTable *}{table = NULL}}
a660d684
KB
2919
2920Parses a string containing one or more wxWindows resource objects. If
2921the resource objects are global static data that are included into the
2922C++ program, then this function must be called for each variable
2923containing the resource data, to make it known to wxWindows.
2924
2925{\it resource} should contain data with the following form:
2926
2927\begin{verbatim}
f6bcfd97
BP
2928dialog(name = 'dialog1',
2929 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
2930 title = 'Test dialog box',
2931 x = 312, y = 234, width = 400, height = 300,
2932 modal = 0,
2933 control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
2934 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
2935 control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
2936 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
2937 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
2938 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
a660d684
KB
2939\end{verbatim}
2940
2941This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
2942load an entire {\tt .wxr file} into a string.
2943
2944\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
2945
7ac13b21 2946\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char *}{xbm\_data}, \param{int }{width},
a660d684
KB
2947\param{int }{height}, \param{wxResourceTable *}{table = NULL}}
2948
7ac13b21 2949\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char **}{xpm\_data}}
a660d684 2950
7af3ca16 2951Makes {\tt\#}included XBM or XPM bitmap data known to the wxWindows resource system.
a660d684
KB
2952This is required if other resources will use the bitmap data, since otherwise there
2953is no connection between names used in resources, and the global bitmap data.
2954
b0fc8832 2955\membersection{::wxResourceRegisterIconData}\label{wxresourceregistericondata}
a660d684
KB
2956
2957Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
2958
6fb26ea3
JS
2959\section{Log functions}\label{logfunctions}
2960
2961These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
f68586e5
VZ
2962further information. The functions use (implicitly) the currently active log
2963target, so their descriptions here may not apply if the log target is not the
2964standard one (installed by wxWindows in the beginning of the program).
6fb26ea3 2965
954b8ae6
JS
2966\wxheading{Include files}
2967
2968<wx/log.h>
2969
b0fc8832
VZ
2970\membersection{::wxDebugMsg}\label{wxdebugmsg}
2971
2972\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
2973
2974{\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogdebug} instead!}
2975
2976Display a debugging message; under Windows, this will appear on the
2977debugger command window, and under Unix, it will be written to standard
2978error.
2979
2980The syntax is identical to {\bf printf}: pass a format string and a
2981variable list of arguments.
2982
2983{\bf Tip:} under Windows, if your application crashes before the
2984message appears in the debugging window, put a wxYield call after
2985each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
2986(at least for Watcom C++): preformat your messages and use OutputDebugString
2987instead.
2988
2989This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
2990
2991\wxheading{Include files}
2992
2993<wx/utils.h>
2994
2995\membersection{::wxError}\label{wxerror}
2996
2997\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
2998
2999This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
3000instead.
3001
3002Displays {\it msg} and continues. This writes to standard error under
3003Unix, and pops up a message box under Windows. Used for internal
3004wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
3005
3006\wxheading{Include files}
3007
3008<wx/utils.h>
3009
3010\membersection{::wxFatalError}\label{wxfatalerror}
3011
3012\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
3013
3014This function is now obsolete, please use
3015\helpref{wxLogFatalError}{wxlogfatalerror} instead.
3016
3017Displays {\it msg} and exits. This writes to standard error under Unix,
3018and pops up a message box under Windows. Used for fatal internal
3019wxWindows errors. See also \helpref{wxError}{wxerror}.
3020
3021\wxheading{Include files}
3022
3023<wx/utils.h>
3024
6fb26ea3
JS
3025\membersection{::wxLogError}\label{wxlogerror}
3026
7ac13b21 3027\func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}}
6fb26ea3 3028
1d63fd6b
GD
3029\func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3030
ea44a631 3031The functions to use for error messages, i.e. the messages that must be shown
f68586e5
VZ
3032to the user. The default processing is to pop up a message box to inform the
3033user about it.
6fb26ea3
JS
3034
3035\membersection{::wxLogFatalError}\label{wxlogfatalerror}
3036
7ac13b21 3037\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}}
6fb26ea3 3038
1d63fd6b
GD
3039\func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3040
6fb26ea3
JS
3041Like \helpref{wxLogError}{wxlogerror}, but also
3042terminates the program with the exit code 3. Using {\it abort()} standard
3043function also terminates the program with this exit code.
3044
3045\membersection{::wxLogWarning}\label{wxlogwarning}
3046
7ac13b21 3047\func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}}
6fb26ea3 3048
1d63fd6b
GD
3049\func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3050
f68586e5
VZ
3051For warnings - they are also normally shown to the user, but don't interrupt
3052the program work.
6fb26ea3
JS
3053
3054\membersection{::wxLogMessage}\label{wxlogmessage}
3055
7ac13b21 3056\func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}}
6fb26ea3 3057
1d63fd6b
GD
3058\func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3059
ea44a631 3060For all normal, informational messages. They also appear in a message box by
f68586e5
VZ
3061default (but it can be changed). Notice that the standard behaviour is to not
3062show informational messages if there are any errors later - the logic being
3063that the later error messages make the informational messages preceding them
3064meaningless.
6fb26ea3
JS
3065
3066\membersection{::wxLogVerbose}\label{wxlogverbose}
3067
7ac13b21
GT
3068\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}}
3069
1d63fd6b 3070\func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
6fb26ea3 3071
f6bcfd97 3072For verbose output. Normally, it is suppressed, but
6fb26ea3
JS
3073might be activated if the user wishes to know more details about the program
3074progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
3075
3076\membersection{::wxLogStatus}\label{wxlogstatus}
3077
7ac13b21 3078\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}}
f68586e5 3079
1d63fd6b 3080\func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
7ac13b21
GT
3081
3082\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}}
6fb26ea3 3083
1d63fd6b
GD
3084\func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
3085
ea44a631 3086Messages logged by these functions will appear in the statusbar of the {\it
f68586e5 3087frame} or of the top level application window by default (i.e. when using
ea44a631 3088the second version of the functions).
f68586e5
VZ
3089
3090If the target frame doesn't have a statusbar, the message will be lost.
6fb26ea3
JS
3091
3092\membersection{::wxLogSysError}\label{wxlogsyserror}
3093
7ac13b21
GT
3094\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}}
3095
1d63fd6b 3096\func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
6fb26ea3 3097
f68586e5
VZ
3098Mostly used by wxWindows itself, but might be handy for logging errors after
3099system call (API function) failure. It logs the specified message text as well
3100as the last system error code ({\it errno} or {\it ::GetLastError()} depending
3101on the platform) and the corresponding error message. The second form
f6bcfd97 3102of this function takes the error code explicitly as the first argument.
6fb26ea3 3103
6d516e09
VZ
3104\wxheading{See also}
3105
3106\helpref{wxSysErrorCode}{wxsyserrorcode},
3107\helpref{wxSysErrorMsg}{wxsyserrormsg}
3108
6fb26ea3
JS
3109\membersection{::wxLogDebug}\label{wxlogdebug}
3110
7ac13b21
GT
3111\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}}
3112
1d63fd6b 3113\func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
6fb26ea3 3114
ea44a631
GD
3115The right functions for debug output. They only do something in debug
3116mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) and expand to
f68586e5 3117nothing in release mode (otherwise).
6fb26ea3
JS
3118
3119\membersection{::wxLogTrace}\label{wxlogtrace}
3120
7ac13b21 3121\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}}
1d63fd6b
GD
3122
3123\func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
6fb26ea3 3124
f68586e5 3125\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
7ac13b21 3126
1d63fd6b 3127\func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
f68586e5
VZ
3128
3129\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
7ac13b21 3130
1d63fd6b 3131\func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
f68586e5
VZ
3132
3133As {\bf wxLogDebug}, trace functions only do something in debug build and
3134expand to nothing in the release one. The reason for making
3135it a separate function from it is that usually there are a lot of trace
3136messages, so it might make sense to separate them from other debug messages.
3137
3138The trace messages also usually can be separated into different categories and
ec5d7799 3139the second and third versions of this function only log the message if the
f68586e5
VZ
3140{\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This
3141allows to selectively trace only some operations and not others by changing
3142the value of the trace mask (possible during the run-time).
3143
3144For the second function (taking a string mask), the message is logged only if
ec5d7799 3145the mask has been previously enabled by the call to
f68586e5
VZ
3146\helpref{AddTraceMask}{wxlogaddtracemask}. The predefined string trace masks
3147used by wxWindows are:
3148
3149\begin{itemize}\itemsep=0pt
3150\item wxTRACE\_MemAlloc: trace memory allocation (new/delete)
3151\item wxTRACE\_Messages: trace window messages/X callbacks
3152\item wxTRACE\_ResAlloc: trace GDI resource allocation
3153\item wxTRACE\_RefCount: trace various ref counting operations
3154\item wxTRACE\_OleCalls: trace OLE method calls (Win32 only)
3155\end{itemize}
6fb26ea3 3156
f68586e5
VZ
3157The third version of the function only logs the message if all the bit
3158corresponding to the {\it mask} are set in the wxLog trace mask which can be
3159set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less
3160flexible than the previous one because it doesn't allow defining the user
3161trace masks easily - this is why it is deprecated in favour of using string
3162trace masks.
6fb26ea3
JS
3163
3164\begin{itemize}\itemsep=0pt
3165\item wxTraceMemAlloc: trace memory allocation (new/delete)
3166\item wxTraceMessages: trace window messages/X callbacks
3167\item wxTraceResAlloc: trace GDI resource allocation
3168\item wxTraceRefCount: trace various ref counting operations
f68586e5 3169\item wxTraceOleCalls: trace OLE method calls (Win32 only)
6fb26ea3
JS
3170\end{itemize}
3171
c11d62a6
VZ
3172\membersection{::wxSafeShowMessage}\label{wxsafeshowmessage}
3173
3174\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}}
3175
3176This function shows a message to the user in a safe way and should be safe to
3177call even before the application has been initialized or if it is currently in
3178some other strange state (for example, about to crash). Under Windows this
3179function shows a message box using a native dialog instead of
3180\helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere
3181it simply prints the message to the standard output using the title as prefix.
3182
3183\wxheading{Parameters}
3184
3185\docparam{title}{The title of the message box shown to the user or the prefix
3186of the message string}
3187
3188\docparam{text}{The text to show to the user}
3189
3190\wxheading{See also}
3191
3192\helpref{wxLogFatalError}{wxlogfatalerror}
3193
3194\wxheading{Include files}
3195
3196<wx/log.h>
3197
6d516e09
VZ
3198\membersection{::wxSysErrorCode}\label{wxsyserrorcode}
3199
3200\func{unsigned long}{wxSysErrorCode}{\void}
3201
3202Returns the error code from the last system call. This function uses
3203{\tt errno} on Unix platforms and {\tt GetLastError} under Win32.
3204
3205\wxheading{See also}
3206
3207\helpref{wxSysErrorMsg}{wxsyserrormsg},
3208\helpref{wxLogSysError}{wxlogsyserror}
3209
3210\membersection{::wxSysErrorMsg}\label{wxsyserrormsg}
3211
3212\func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}}
3213
ec5d7799
RD
3214Returns the error message corresponding to the given system error code. If
3215{\it errCode} is $0$ (default), the last error code (as returned by
6d516e09
VZ
3216\helpref{wxSysErrorCode}{wxsyserrorcode}) is used.
3217
3218\wxheading{See also}
3219
3220\helpref{wxSysErrorCode}{wxsyserrorcode},
3221\helpref{wxLogSysError}{wxlogsyserror}
3222
b0fc8832
VZ
3223\membersection{WXTRACE}\label{trace}
3224
3225\wxheading{Include files}
3226
3227<wx/object.h>
3228
3229\func{}{WXTRACE}{formatString, ...}
3230
3231Calls wxTrace with printf-style variable argument syntax. Output
3232is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
3233
3234This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
3235
3236\wxheading{Include files}
3237
3238<wx/memory.h>
3239
3240\membersection{WXTRACELEVEL}\label{tracelevel}
3241
3242\func{}{WXTRACELEVEL}{level, formatString, ...}
3243
3244Calls wxTraceLevel with printf-style variable argument syntax. Output
3245is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
3246The first argument should be the level at which this information is appropriate.
3247It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
3248this value.
3249
3250This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
3251
3252\wxheading{Include files}
3253
3254<wx/memory.h>
3255
3256\membersection{::wxTrace}\label{wxtrace}
3257
3258\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
3259
3260Takes printf-style variable argument syntax. Output
3261is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
3262
3263This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
3264
3265\wxheading{Include files}
3266
3267<wx/memory.h>
3268
3269\membersection{::wxTraceLevel}\label{wxtracelevel}
3270
3271\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
3272
3273Takes printf-style variable argument syntax. Output
3274is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
3275The first argument should be the level at which this information is appropriate.
3276It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
3277this value.
3278
3279This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
3280
3281\wxheading{Include files}
3282
3283<wx/memory.h>
3284
f6bcfd97
BP
3285\section{Time functions}\label{timefunctions}
3286
3287The functions in this section deal with getting the current time and
3288starting/stopping the global timers. Please note that the timer functions are
ec5d7799 3289deprecated because they work with one global timer only and
f6bcfd97 3290\helpref{wxTimer}{wxtimer} and/or \helpref{wxStopWatch}{wxstopwatch} classes
ec5d7799
RD
3291should be used instead. For retrieving the current time, you may also use
3292\helpref{wxDateTime::Now}{wxdatetimenow} or
f6bcfd97
BP
3293\helpref{wxDateTime::UNow}{wxdatetimeunow} methods.
3294
3295\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
3296
3297\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}}
3298
3299Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
3300
3301If {\it resetTimer} is TRUE (the default), the timer is reset to zero
3302by this call.
3303
3304See also \helpref{wxTimer}{wxtimer}.
3305
3306\wxheading{Include files}
3307
3308<wx/timer.h>
3309
3310\membersection{::wxGetLocalTime}\label{wxgetlocaltime}
3311
3312\func{long}{wxGetLocalTime}{\void}
3313
3314Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
3315
3316\wxheading{See also}
3317
3318\helpref{wxDateTime::Now}{wxdatetimenow}
3319
3320\wxheading{Include files}
3321
3322<wx/timer.h>
3323
3324\membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis}
3325
a9d171bd 3326\func{wxLongLong}{wxGetLocalTimeMillis}{\void}
f6bcfd97
BP
3327
3328Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
3329
3330\wxheading{See also}
3331
3332\helpref{wxDateTime::Now}{wxdatetimenow},\\
a9d171bd 3333\helpref{wxLongLong}{wxlonglong}
f6bcfd97
BP
3334
3335\wxheading{Include files}
3336
3337<wx/timer.h>
3338
3339\membersection{::wxGetUTCTime}\label{wxgetutctime}
3340
3341\func{long}{wxGetUTCTime}{\void}
3342
3343Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
3344
3345\wxheading{See also}
3346
3347\helpref{wxDateTime::Now}{wxdatetimenow}
3348
3349\wxheading{Include files}
3350
3351<wx/timer.h>
3352
b0fc8832
VZ
3353\membersection{::wxNow}\label{wxnow}
3354
3355\func{wxString}{wxNow}{\void}
3356
3357Returns a string representing the current date and time.
3358
3359\wxheading{Include files}
3360
3361<wx/utils.h>
3362
3363\membersection{::wxSleep}\label{wxsleep}
3364
3365\func{void}{wxSleep}{\param{int}{ secs}}
3366
3367Sleeps for the specified number of seconds.
3368
3369\wxheading{Include files}
3370
3371<wx/utils.h>
3372
f6bcfd97
BP
3373\membersection{::wxStartTimer}\label{wxstarttimer}
3374
3375\func{void}{wxStartTimer}{\void}
3376
3377Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
3378
3379See also \helpref{wxTimer}{wxtimer}.
3380
3381\wxheading{Include files}
3382
3383<wx/timer.h>
3384
b0fc8832
VZ
3385\membersection{::wxUsleep}\label{wxusleep}
3386
3387\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
3388
3389Sleeps for the specified number of milliseconds. Notice that usage of this
3390function is encouraged instead of calling usleep(3) directly because the
3391standard usleep() function is not MT safe.
3392
3393\wxheading{Include files}
3394
3395<wx/utils.h>
3396
6fb26ea3
JS
3397\section{Debugging macros and functions}\label{debugmacros}
3398
8f5d9104
VZ
3399Useful macros and functions for error checking and defensive programming.
3400wxWindows defines three families of the assert-like macros:
3401the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined
3402(in other words, in the debug build) but disappear completely in the release
3403build. On the other hand, the wxCHECK macros stay event in release builds but a
3404check failure doesn't generate any user-visible effects then. Finally, the
3405compile time assertions don't happen during the run-time but result in the
3406compilation error messages if the condition they check fail.
6fb26ea3 3407
954b8ae6
JS
3408\wxheading{Include files}
3409
3410<wx/debug.h>
3411
6fb26ea3
JS
3412\membersection{::wxOnAssert}\label{wxonassert}
3413
7ac13b21 3414\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{msg = NULL}}
6fb26ea3 3415
8f5d9104
VZ
3416This function is called whenever one of debugging macros fails (i.e. condition
3417is false in an assertion). It is only defined in the debug mode, in release
3418builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything.
3419
3420To override the default behaviour in the debug builds which is to show the user
3421a dialog asking whether he wants to abort the program, continue or continue
3422ignoring any subsequent assert failures, you may override
3423\helpref{wxApp::OnAssert}{wxapponassert} which is called by this function if
3424the global application object exists.
6fb26ea3
JS
3425
3426\membersection{wxASSERT}\label{wxassert}
3427
3428\func{}{wxASSERT}{\param{}{condition}}
3429
b207457c
VZ
3430Assert macro. An error message will be generated if the condition is FALSE in
3431debug mode, but nothing will be done in the release build.
3432
3433Please note that the condition in wxASSERT() should have no side effects
3434because it will not be executed in release mode at all.
3435
8f5d9104
VZ
3436\wxheading{See also}
3437
3438\helpref{wxASSERT\_MSG}{wxassertmsg},\\
3439\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
3440
3441\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize}
3442
3443\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
3444
3445This macro results in a
9722642d 3446\helpref{compile time assertion failure}{wxcompiletimeassert} if the size
8f5d9104
VZ
3447of the given type {\it type} is less than {\it size} bits.
3448
3449You may use it like this, for example:
3450
3451\begin{verbatim}
3452 // we rely on the int being able to hold values up to 2^32
3453 wxASSERT_MIN_BITSIZE(int, 32);
3454
3455 // can't work with the platforms using UTF-8 for wchar_t
3456 wxASSERT_MIN_BITSIZE(wchar_t, 16);
3457\end{verbatim}
6fb26ea3
JS
3458
3459\membersection{wxASSERT\_MSG}\label{wxassertmsg}
3460
3461\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
3462
3463Assert macro with message. An error message will be generated if the condition is FALSE.
3464
8f5d9104
VZ
3465\wxheading{See also}
3466
3467\helpref{wxASSERT}{wxassert},\\
3468\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
3469
3470\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert}
3471
3472\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
3473
3474Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the
9722642d 3475specified {\it condition} is false. The compiler error message should include
8f5d9104
VZ
3476the {\it msg} identifier - please note that it must be a valid C++ identifier
3477and not a string unlike in the other cases.
3478
3479This macro is mostly useful for testing the expressions involing the
3480{\tt sizeof} operator as they can't be tested by the preprocessor but it is
3481sometimes desirable to test them at the compile time.
3482
5b8643ea
VZ
3483Note that this macro internally declares a struct whose name it tries to make
3484unique by using the {\tt \_\_LINE\_\_} in it but it may still not work if you
3485use it on the same line in two different source files. In this case you may
3486either change the line in which either of them appears on or use the
3487\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} macro.
3488
8f5d9104
VZ
3489\wxheading{See also}
3490
3491\helpref{wxASSERT\_MSG}{wxassertmsg},\\
3492\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}
b207457c 3493
5b8643ea
VZ
3494\membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2}
3495
3496\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}}
3497
3498This macro is identical to \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}
3499except that it allows you to specify a unique {\it name} for the struct
3500internally defined by this macro to avoid getting the compilation errors
3501described \helpref{above}{wxcompiletimeassert}.
3502
6fb26ea3
JS
3503\membersection{wxFAIL}\label{wxfail}
3504
b207457c 3505\func{}{wxFAIL}{\void}
6fb26ea3
JS
3506
3507Will always generate an assert error if this code is reached (in debug mode).
3508
b207457c
VZ
3509See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
3510
6fb26ea3
JS
3511\membersection{wxFAIL\_MSG}\label{wxfailmsg}
3512
b207457c 3513\func{}{wxFAIL\_MSG}{\param{}{msg}}
6fb26ea3
JS
3514
3515Will always generate an assert error with specified message if this code is reached (in debug mode).
3516
b207457c
VZ
3517This macro is useful for marking unreachable" code areas, for example
3518it may be used in the "default:" branch of a switch statement if all possible
3519cases are processed above.
3520
8f5d9104
VZ
3521\wxheading{See also}
3522
3523\helpref{wxFAIL}{wxfail}
b207457c 3524
6fb26ea3
JS
3525\membersection{wxCHECK}\label{wxcheck}
3526
3527\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
3528
3529Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
3530This check is done even in release mode.
3531
3532\membersection{wxCHECK\_MSG}\label{wxcheckmsg}
3533
3534\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
3535
3536Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
3537This check is done even in release mode.
3538
ec5d7799 3539This macro may be only used in non void functions, see also
b207457c
VZ
3540\helpref{wxCHECK\_RET}{wxcheckret}.
3541
3542\membersection{wxCHECK\_RET}\label{wxcheckret}
3543
3544\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}}
3545
3546Checks that the condition is true, and returns if not (FAILs with given error
3547message in debug mode). This check is done even in release mode.
3548
ec5d7799 3549This macro should be used in void functions instead of
b207457c
VZ
3550\helpref{wxCHECK\_MSG}{wxcheckmsg}.
3551
3552\membersection{wxCHECK2}\label{wxcheck2}
3553
3554\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}}
3555
ec5d7799
RD
3556Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute
3557{\it operation} if it is not. This is a generalisation of
b207457c
VZ
3558\helpref{wxCHECK}{wxcheck} and may be used when something else than just
3559returning from the function must be done when the {\it condition} is false.
3560
3561This check is done even in release mode.
3562
3563\membersection{wxCHECK2\_MSG}\label{wxcheck2msg}
3564
3565\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}}
3566
ec5d7799 3567This is the same as \helpref{wxCHECK2}{wxcheck2}, but
b207457c
VZ
3568\helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
3569instead of wxFAIL() if the {\it condition} is false.
3570
b0fc8832
VZ
3571\membersection{::wxTrap}\label{wxtrap}
3572
3573\func{void}{wxTrap}{\void}
3574
3575In debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) this function generates a
3576debugger exception meaning that the control is passed to the debugger if one is
3577attached to the process. Otherwise the program just terminates abnormally.
3578
3579In release mode this function does nothing.
3580
3581\wxheading{Include files}
3582
3583<wx/debug.h>
3584
5807634c
VZ
3585\section{Environment access functions}\label{environfunctions}
3586
3587The functions in this section allow to access (get) or change value of
3588environment variables in a portable way. They are currently implemented under
3589Win32 and POSIX-like systems (Unix).
3590
3591% TODO add some stuff about env var inheriting but not propagating upwards (VZ)
3592
3593\wxheading{Include files}
3594
3595<wx/utils.h>
3596
308978f6 3597\membersection{wxGetenv}\label{wxgetenvmacro}
5807634c
VZ
3598
3599\func{wxChar *}{wxGetEnv}{\param{const wxString\&}{ var}}
3600
308978f6
VZ
3601This is a macro defined as {\tt getenv()} or its wide char version in Unicode
3602mode.
3603
3604Note that under Win32 it may not return correct value for the variables set
3605with \helpref{wxSetEnv}{wxsetenv}, use \helpref{wxGetEnv}{wxgetenv} function
3606instead.
3607
3608\membersection{wxGetEnv}\label{wxgetenv}
3609
3610\func{bool}{wxGetEnv}{\param{const wxString\&}{ var}, \param{wxString *}{value}}
3611
3612Returns the current value of the environment variable {\it var} in {\it value}.
3613{\it value} may be {\tt NULL} if you just want to know if the variable exists
3614and are not interested in its value.
3615
3616Returns {\tt TRUE} if the variable exists, {\tt FALSE} otherwise.
5807634c
VZ
3617
3618\membersection{wxSetEnv}\label{wxsetenv}
3619
3620\func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxChar *}{value}}
3621
3622Sets the value of the environment variable {\it var} (adding it if necessary)
3623to {\it value}.
3624
3625Returns {\tt TRUE} on success.
3626
3627\membersection{wxUnsetEnv}\label{wxunsetenv}
3628
3629\func{bool}{wxUnsetEnv}{\param{const wxString\&}{ var}}
3630
ec5d7799 3631Removes the variable {\it var} from the environment.
5df6ed1c 3632\helpref{wxGetEnv}{wxgetenv} will return {\tt NULL} after the call to this
5807634c
VZ
3633function.
3634
3635Returns {\tt TRUE} on success.
3636