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