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