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