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