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