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