]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \chapter{Functions}\label{functions} |
2 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% | |
3 | \setfooter{\thepage}{}{}{}{}{\thepage} | |
4 | ||
5 | The functions defined in wxWindows are described here. | |
6 | ||
7 | \section{File functions}\label{filefunctions} | |
8 | ||
954b8ae6 JS |
9 | \wxheading{Include files} |
10 | ||
11 | <wx/utils.h> | |
12 | ||
13 | \wxheading{See also} | |
14 | ||
15 | \helpref{wxPathList}{wxpathlist} | |
a660d684 KB |
16 | |
17 | \membersection{::wxDirExists} | |
18 | ||
19 | \func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} | |
20 | ||
21 | Returns TRUE if the directory exists. | |
22 | ||
23 | \membersection{::wxDos2UnixFilename} | |
24 | ||
25 | \func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}} | |
26 | ||
e2a6f233 | 27 | Converts a DOS to a Unix filename by replacing backslashes with forward |
a660d684 KB |
28 | slashes. |
29 | ||
30 | \membersection{::wxFileExists} | |
31 | ||
32 | \func{bool}{wxFileExists}{\param{const wxString\& }{filename}} | |
33 | ||
34 | Returns TRUE if the file exists. | |
35 | ||
36 | \membersection{::wxFileNameFromPath} | |
37 | ||
38 | \func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} | |
39 | ||
532372a3 JS |
40 | \func{char*}{wxFileNameFromPath}{\param{char* }{path}} |
41 | ||
42 | Returns the filename for a full path. The second form returns a pointer to | |
43 | temporary storage that should not be deallocated. | |
a660d684 KB |
44 | |
45 | \membersection{::wxFindFirstFile}\label{wxfindfirstfile} | |
46 | ||
532372a3 | 47 | \func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}} |
a660d684 KB |
48 | |
49 | This function does directory searching; returns the first file | |
532372a3 | 50 | that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to |
a660d684 KB |
51 | get the next matching file. |
52 | ||
53 | {\it spec} may contain wildcards. | |
54 | ||
55 | {\it flags} is reserved for future use. | |
56 | ||
57 | The returned filename is a pointer to static memory so should | |
58 | not be freed. | |
59 | ||
60 | For example: | |
61 | ||
62 | \begin{verbatim} | |
63 | wxString f = wxFindFirstFile("/home/project/*.*"); | |
532372a3 | 64 | while (f != "") |
a660d684 KB |
65 | { |
66 | ... | |
67 | f = wxFindNextFile(); | |
68 | } | |
69 | \end{verbatim} | |
70 | ||
71 | \membersection{::wxFindNextFile}\label{wxfindnextfile} | |
72 | ||
73 | \func{wxString}{wxFindFirstFile}{\void} | |
74 | ||
75 | Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. | |
76 | ||
631f1bfe JS |
77 | \membersection{::wxGetOSDirectory}\label{wxgetosdirectory} |
78 | ||
79 | \func{wxString}{wxGetOSDirectory}{\void} | |
80 | ||
81 | Returns the Windows directory under Windows; on other platforms returns the empty string. | |
82 | ||
a660d684 KB |
83 | \membersection{::wxIsAbsolutePath} |
84 | ||
85 | \func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} | |
86 | ||
87 | Returns TRUE if the argument is an absolute filename, i.e. with a slash | |
88 | or drive name at the beginning. | |
89 | ||
90 | \membersection{::wxPathOnly} | |
91 | ||
92 | \func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} | |
93 | ||
532372a3 | 94 | Returns the directory part of the filename. |
a660d684 KB |
95 | |
96 | \membersection{::wxUnix2DosFilename} | |
97 | ||
98 | \func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}} | |
99 | ||
e2a6f233 | 100 | Converts a Unix to a DOS filename by replacing forward |
a660d684 KB |
101 | slashes with backslashes. |
102 | ||
103 | \membersection{::wxConcatFiles} | |
104 | ||
105 | \func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, | |
106 | \param{const wxString\& }{file3}} | |
107 | ||
108 | Concatenates {\it file1} and {\it file2} to {\it file3}, returning | |
109 | TRUE if successful. | |
110 | ||
111 | \membersection{::wxCopyFile} | |
112 | ||
113 | \func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} | |
114 | ||
115 | Copies {\it file1} to {\it file2}, returning TRUE if successful. | |
116 | ||
7af89395 VZ |
117 | \membersection{::wxGetCwd}\label{wxgetcwd} |
118 | ||
119 | \func{wxString}{wxGetCwd}{\void} | |
120 | ||
121 | Returns a string containing the current (or working) directory. | |
122 | ||
a660d684 KB |
123 | \membersection{::wxGetHostName}\label{wxgethostname} |
124 | ||
125 | \func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int }{sz}} | |
126 | ||
127 | Copies the current host machine's name into the supplied buffer. | |
128 | ||
129 | Under Windows or NT, this function first looks in the environment | |
130 | variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp | |
131 | in the {\bf wxWindows} section of the WIN.INI file is tried. | |
132 | ||
133 | Returns TRUE if successful, FALSE otherwise. | |
134 | ||
135 | \membersection{::wxGetEmailAddress}\label{wxgetemailaddress} | |
136 | ||
137 | \func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}} | |
138 | ||
139 | Copies the user's email address into the supplied buffer, by | |
140 | concatenating the values returned by \helpref{wxGetHostName}{wxgethostname}\rtfsp | |
141 | and \helpref{wxGetUserId}{wxgetuserid}. | |
142 | ||
143 | Returns TRUE if successful, FALSE otherwise. | |
144 | ||
145 | \membersection{::wxGetUserId}\label{wxgetuserid} | |
146 | ||
147 | \func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int }{sz}} | |
148 | ||
149 | Copies the current user id into the supplied buffer. | |
150 | ||
151 | Under Windows or NT, this function first looks in the environment | |
152 | variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp | |
153 | in the {\bf wxWindows} section of the WIN.INI file is tried. | |
154 | ||
155 | Returns TRUE if successful, FALSE otherwise. | |
156 | ||
157 | \membersection{::wxGetUserName}\label{wxgetusername} | |
158 | ||
159 | \func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int }{sz}} | |
160 | ||
161 | Copies the current user name into the supplied buffer. | |
162 | ||
163 | Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp | |
164 | in the {\bf wxWindows} section of the WIN.INI file. If PenWindows | |
165 | is running, the entry {\bf Current} in the section {\bf User} of | |
166 | the PENWIN.INI file is used. | |
167 | ||
168 | Returns TRUE if successful, FALSE otherwise. | |
169 | ||
170 | \membersection{::wxGetWorkingDirectory} | |
171 | ||
532372a3 | 172 | \func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}} |
a660d684 | 173 | |
7af89395 VZ |
174 | This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead. |
175 | ||
a660d684 KB |
176 | Copies the current working directory into the buffer if supplied, or |
177 | copies the working directory into new storage (which you must delete yourself) | |
178 | if the buffer is NULL. | |
179 | ||
180 | {\it sz} is the size of the buffer if supplied. | |
181 | ||
182 | \membersection{::wxGetTempFileName} | |
183 | ||
532372a3 | 184 | \func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}} |
a660d684 KB |
185 | |
186 | Makes a temporary filename based on {\it prefix}, opens and closes the file, | |
187 | and places the name in {\it buf}. If {\it buf} is NULL, new store | |
188 | is allocated for the temporary filename using {\it new}. | |
189 | ||
190 | Under Windows, the filename will include the drive and name of the | |
191 | directory allocated for temporary files (usually the contents of the | |
e2a6f233 | 192 | TEMP variable). Under Unix, the {\tt /tmp} directory is used. |
a660d684 KB |
193 | |
194 | It is the application's responsibility to create and delete the file. | |
195 | ||
196 | \membersection{::wxIsWild}\label{wxiswild} | |
197 | ||
198 | \func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} | |
199 | ||
200 | Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. | |
201 | ||
202 | \membersection{::wxMatchWild}\label{wxmatchwild} | |
203 | ||
204 | \func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} | |
205 | ||
206 | Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it | |
207 | dot\_special}\/ is TRUE, filenames beginning with a dot are not matched | |
208 | with wildcard characters. See \helpref{wxIsWild}{wxiswild}. | |
209 | ||
210 | \membersection{::wxMkdir} | |
211 | ||
212 | \func{bool}{wxMkdir}{\param{const wxString\& }{dir}} | |
213 | ||
214 | Makes the directory {\it dir}, returning TRUE if successful. | |
215 | ||
216 | \membersection{::wxRemoveFile} | |
217 | ||
218 | \func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} | |
219 | ||
220 | Removes {\it file}, returning TRUE if successful. | |
221 | ||
222 | \membersection{::wxRenameFile} | |
223 | ||
224 | \func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} | |
225 | ||
226 | Renames {\it file1} to {\it file2}, returning TRUE if successful. | |
227 | ||
228 | \membersection{::wxRmdir} | |
229 | ||
230 | \func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}} | |
231 | ||
232 | Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS. | |
233 | ||
234 | The {\it flags} parameter is reserved for future use. | |
235 | ||
236 | \membersection{::wxSetWorkingDirectory} | |
237 | ||
238 | \func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}} | |
239 | ||
240 | Sets the current working directory, returning TRUE if the operation succeeded. | |
241 | Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification. | |
242 | ||
d37fd2fa VZ |
243 | \membersection{::wxSplitPath}\label{wxsplitfunction} |
244 | ||
245 | \func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{const wxString *}{ path}, \param{const wxString *}{ name}, \param{const wxString *}{ ext}} | |
246 | ||
247 | This function splits a full file name into components: the path (including possible disk/drive | |
248 | specification under Windows), the base name and the extension. Any of the output parameters | |
249 | ({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of | |
250 | a particular component. | |
251 | ||
252 | wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under | |
253 | Windows, however it will not consider backslashes as path separators under Unix (where backslash | |
254 | is a valid character in a filename). | |
255 | ||
256 | On entry, {\it fullname} should be non NULL (it may be empty though). | |
257 | ||
258 | On return, {\it path} contains the file path (without the trailing separator), {\it name} | |
259 | contains the file name and {\it ext} contains the file extension without leading dot. All | |
260 | three of them may be empty if the corresponding component is. The old contents of the | |
261 | strings pointed to by these parameters will be overwritten in any case (if the pointers | |
262 | are not NULL). | |
263 | ||
a660d684 KB |
264 | \section{String functions} |
265 | ||
266 | \membersection{::copystring} | |
267 | ||
268 | \func{char*}{copystring}{\param{const char* }{s}} | |
269 | ||
270 | Makes a copy of the string {\it s} using the C++ new operator, so it can be | |
271 | deleted with the {\it delete} operator. | |
272 | ||
273 | \membersection{::wxStringMatch} | |
274 | ||
275 | \func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\ | |
276 | \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}} | |
277 | ||
278 | Returns TRUE if the substring {\it s1} is found within {\it s2}, | |
279 | ignoring case if {\it exact} is FALSE. If {\it subString} is FALSE, | |
280 | no substring matching is done. | |
281 | ||
282 | \membersection{::wxStringEq}\label{wxstringeq} | |
283 | ||
284 | \func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} | |
285 | ||
286 | A macro defined as: | |
287 | ||
288 | \begin{verbatim} | |
289 | #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) | |
290 | \end{verbatim} | |
291 | ||
292 | \membersection{::wxTransferFileToStream}\label{wxtransferfiletostream} | |
293 | ||
294 | \func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}} | |
295 | ||
296 | Copies the given file to {\it stream}. Useful when converting an old application to | |
297 | use streams (within the document/view framework, for example). | |
298 | ||
299 | Use of this function requires the file wx\_doc.h to be included. | |
300 | ||
301 | \membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile} | |
302 | ||
303 | \func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}} | |
304 | ||
305 | Copies the given stream to the file {\it filename}. Useful when converting an old application to | |
306 | use streams (within the document/view framework, for example). | |
307 | ||
308 | Use of this function requires the file wx\_doc.h to be included. | |
309 | ||
310 | \section{Dialog functions}\label{dialogfunctions} | |
311 | ||
312 | Below are a number of convenience functions for getting input from the | |
313 | user or displaying messages. Note that in these functions the last three | |
314 | parameters are optional. However, it is recommended to pass a parent frame | |
315 | parameter, or (in MS Windows or Motif) the wrong window frame may be brought to | |
316 | the front when the dialog box is popped up. | |
317 | ||
318 | \membersection{::wxFileSelector}\label{wxfileselector} | |
319 | ||
320 | \func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = NULL},\\ | |
321 | \param{const wxString\& }{default\_filename = NULL}, \param{const wxString\& }{default\_extension = NULL},\\ | |
322 | \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\ | |
323 | \param{int}{ x = -1}, \param{int}{ y = -1}} | |
324 | ||
325 | Pops up a file selector box. In Windows, this is the common file selector | |
326 | dialog. In X, this is a file selector box with somewhat less functionality. | |
327 | The path and filename are distinct elements of a full file pathname. | |
328 | If path is NULL, the current directory will be used. If filename is NULL, | |
329 | no default filename will be supplied. The wildcard determines what files | |
330 | are displayed in the file selector, and file extension supplies a type | |
331 | extension for the required filename. Flags may be a combination of wxOPEN, | |
332 | wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, or 0. They are only significant | |
333 | at present in Windows. | |
334 | ||
335 | Both the X and Windows versions implement a wildcard filter. Typing a | |
336 | filename containing wildcards (*, ?) in the filename text item, and | |
337 | clicking on Ok, will result in only those files matching the pattern being | |
338 | displayed. In the X version, supplying no default name will result in the | |
339 | wildcard filter being inserted in the filename text item; the filter is | |
340 | ignored if a default name is supplied. | |
341 | ||
342 | Under Windows (only), the wildcard may be a specification for multiple | |
343 | types of file with a description for each, such as: | |
344 | ||
345 | \begin{verbatim} | |
346 | "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif" | |
347 | \end{verbatim} | |
348 | ||
349 | The application must check for a NULL return value (the user pressed | |
350 | Cancel). For example: | |
351 | ||
352 | \begin{verbatim} | |
353 | const wxString\& s = wxFileSelector("Choose a file to open"); | |
354 | if (s) | |
355 | { | |
356 | ... | |
357 | } | |
358 | \end{verbatim} | |
359 | ||
360 | Remember that the returned pointer is temporary and should be copied | |
361 | if other wxWindows calls will be made before the value is to be used. | |
362 | ||
954b8ae6 JS |
363 | \wxheading{Include files} |
364 | ||
365 | <wx/filedlg.h> | |
366 | ||
a660d684 KB |
367 | \membersection{::wxGetTextFromUser}\label{wxgettextfromuser} |
368 | ||
369 | \func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ | |
370 | \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ | |
371 | \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = TRUE}} | |
372 | ||
373 | Pop up a dialog box with title set to {\it caption}, message {\it message}, and a | |
374 | \rtfsp{\it default\_value}. The user may type in text and press OK to return this text, | |
532372a3 | 375 | or press Cancel to return the empty string. |
a660d684 KB |
376 | |
377 | If {\it centre} is TRUE, the message text (which may include new line characters) | |
378 | is centred; if FALSE, the message is left-justified. | |
379 | ||
954b8ae6 JS |
380 | \wxheading{Include files} |
381 | ||
382 | <wx/textdlg.h> | |
383 | ||
a660d684 KB |
384 | \membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice} |
385 | ||
386 | \func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ | |
387 | \param{int }{nsel}, \param{int *}{selection}, | |
388 | \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ | |
389 | \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} | |
390 | ||
391 | Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection | |
392 | listbox. The user may choose one or more item(s) and press OK or Cancel. | |
393 | ||
394 | The number of initially selected choices, and array of the selected indices, | |
395 | are passed in; this array will contain the user selections on exit, with | |
396 | the function returning the number of selections. {\it selection} must be | |
397 | as big as the number of choices, in case all are selected. | |
398 | ||
399 | If Cancel is pressed, -1 is returned. | |
400 | ||
401 | {\it choices} is an array of {\it n} strings for the listbox. | |
402 | ||
403 | If {\it centre} is TRUE, the message text (which may include new line characters) | |
404 | is centred; if FALSE, the message is left-justified. | |
405 | ||
954b8ae6 JS |
406 | \wxheading{Include files} |
407 | ||
408 | <wx/choicdlg.h> | |
409 | ||
a660d684 KB |
410 | \membersection{::wxGetSingleChoice}\label{wxgetsinglechoice} |
411 | ||
412 | \func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ | |
413 | \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ | |
414 | \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} | |
415 | ||
416 | Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection | |
417 | listbox. The user may choose an item and press OK to return a string or | |
532372a3 | 418 | Cancel to return the empty string. |
a660d684 KB |
419 | |
420 | {\it choices} is an array of {\it n} strings for the listbox. | |
421 | ||
422 | If {\it centre} is TRUE, the message text (which may include new line characters) | |
423 | is centred; if FALSE, the message is left-justified. | |
424 | ||
954b8ae6 JS |
425 | \wxheading{Include files} |
426 | ||
427 | <wx/choicdlg.h> | |
428 | ||
a660d684 KB |
429 | \membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex} |
430 | ||
431 | \func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ | |
432 | \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ | |
433 | \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} | |
434 | ||
435 | As {\bf wxGetSingleChoice} but returns the index representing the selected string. | |
436 | If the user pressed cancel, -1 is returned. | |
437 | ||
954b8ae6 JS |
438 | \wxheading{Include files} |
439 | ||
440 | <wx/choicdlg.h> | |
441 | ||
a660d684 KB |
442 | \membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata} |
443 | ||
444 | \func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ | |
445 | \param{const wxString\& }{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\ | |
446 | \param{int}{ y = -1}, \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} | |
447 | ||
448 | As {\bf wxGetSingleChoice} but takes an array of client data pointers | |
449 | corresponding to the strings, and returns one of these pointers. | |
450 | ||
954b8ae6 JS |
451 | \wxheading{Include files} |
452 | ||
453 | <wx/choicdlg.h> | |
454 | ||
a660d684 KB |
455 | \membersection{::wxMessageBox}\label{wxmessagebox} |
456 | ||
457 | \func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\ | |
458 | \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}} | |
459 | ||
460 | General purpose message dialog. {\it style} may be a bit list of the | |
461 | following identifiers: | |
462 | ||
463 | \begin{twocollist}\itemsep=0pt | |
464 | \twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with | |
465 | wxCANCEL.} | |
466 | \twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with | |
467 | wxYES\_NO or wxOK.} | |
468 | \twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.} | |
469 | \twocolitem{wxCENTRE}{Centres the text.} | |
470 | \twocolitem{wxICON\_EXCLAMATION}{Under Windows, displays an exclamation mark symbol.} | |
471 | \twocolitem{wxICON\_HAND}{Under Windows, displays a hand symbol.} | |
472 | \twocolitem{wxICON\_QUESTION}{Under Windows, displays a question mark symbol.} | |
473 | \twocolitem{wxICON\_INFORMATION}{Under Windows, displays an information symbol.} | |
474 | \end{twocollist} | |
475 | ||
476 | The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. | |
477 | ||
478 | For example: | |
479 | ||
480 | \begin{verbatim} | |
481 | ... | |
482 | int answer = wxMessageBox("Quit program?", "Confirm", | |
483 | wxYES_NO | wxCANCEL, main_frame); | |
484 | if (answer == wxYES) | |
485 | delete main_frame; | |
486 | ... | |
487 | \end{verbatim} | |
488 | ||
489 | {\it message} may contain newline characters, in which case the | |
490 | message will be split into separate lines, to cater for large messages. | |
491 | ||
492 | Under Windows, the native MessageBox function is used unless wxCENTRE | |
493 | is specified in the style, in which case a generic function is used. | |
494 | This is because the native MessageBox function cannot centre text. | |
495 | The symbols are not shown when the generic function is used. | |
496 | ||
954b8ae6 JS |
497 | \wxheading{Include files} |
498 | ||
499 | <wx/msgdlg.h> | |
500 | ||
a660d684 KB |
501 | \section{GDI functions}\label{gdifunctions} |
502 | ||
503 | The following are relevant to the GDI (Graphics Device Interface). | |
504 | ||
954b8ae6 JS |
505 | \wxheading{Include files} |
506 | ||
507 | <wx/gdicmn.h> | |
508 | ||
a660d684 KB |
509 | \membersection{::wxColourDisplay} |
510 | ||
511 | \func{bool}{wxColourDisplay}{\void} | |
512 | ||
513 | Returns TRUE if the display is colour, FALSE otherwise. | |
514 | ||
515 | \membersection{::wxDisplayDepth} | |
516 | ||
517 | \func{int}{wxDisplayDepth}{\void} | |
518 | ||
519 | Returns the depth of the display (a value of 1 denotes a monochrome display). | |
520 | ||
e2a6f233 | 521 | \membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable} |
a660d684 | 522 | |
e2a6f233 | 523 | \func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY}, |
a660d684 KB |
524 | \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}} |
525 | ||
e2a6f233 | 526 | Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc}) |
a660d684 KB |
527 | makes it into a placeable metafile by prepending a header containing the given |
528 | bounding box. The bounding box may be obtained from a device context after drawing | |
529 | into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. | |
530 | ||
531 | In addition to adding the placeable metafile header, this function adds | |
532 | the equivalent of the following code to the start of the metafile data: | |
533 | ||
534 | \begin{verbatim} | |
535 | SetMapMode(dc, MM_ANISOTROPIC); | |
536 | SetWindowOrg(dc, minX, minY); | |
537 | SetWindowExt(dc, maxX - minX, maxY - minY); | |
538 | \end{verbatim} | |
539 | ||
e3065973 | 540 | This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes. |
a660d684 KB |
541 | |
542 | Placeable metafiles may be imported by many Windows applications, and can be | |
543 | used in RTF (Rich Text Format) files. | |
544 | ||
545 | {\it scale} allows the specification of scale for the metafile. | |
546 | ||
547 | This function is only available under Windows. | |
548 | ||
549 | \membersection{::wxSetCursor}\label{wxsetcursor} | |
550 | ||
551 | \func{void}{wxSetCursor}{\param{wxCursor *}{cursor}} | |
552 | ||
553 | Globally sets the cursor; only has an effect in MS Windows. | |
554 | See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. | |
555 | ||
a660d684 KB |
556 | \section{Printer settings}\label{printersettings} |
557 | ||
558 | The following functions are used to control PostScript printing. Under | |
559 | Windows, PostScript output can only be sent to a file. | |
560 | ||
954b8ae6 JS |
561 | \wxheading{Include files} |
562 | ||
563 | <wx/dcps.h> | |
564 | ||
a660d684 KB |
565 | \membersection{::wxGetPrinterCommand} |
566 | ||
567 | \func{wxString}{wxGetPrinterCommand}{\void} | |
568 | ||
569 | Gets the printer command used to print a file. The default is {\tt lpr}. | |
570 | ||
571 | \membersection{::wxGetPrinterFile} | |
572 | ||
573 | \func{wxString}{wxGetPrinterFile}{\void} | |
574 | ||
575 | Gets the PostScript output filename. | |
576 | ||
577 | \membersection{::wxGetPrinterMode} | |
578 | ||
579 | \func{int}{wxGetPrinterMode}{\void} | |
580 | ||
581 | Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). | |
582 | The default is PS\_PREVIEW. | |
583 | ||
584 | \membersection{::wxGetPrinterOptions} | |
585 | ||
586 | \func{wxString}{wxGetPrinterOptions}{\void} | |
587 | ||
588 | Gets the additional options for the print command (e.g. specific printer). The default is nothing. | |
589 | ||
590 | \membersection{::wxGetPrinterOrientation} | |
591 | ||
592 | \func{int}{wxGetPrinterOrientation}{\void} | |
593 | ||
594 | Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. | |
595 | ||
596 | \membersection{::wxGetPrinterPreviewCommand} | |
597 | ||
598 | \func{wxString}{wxGetPrinterPreviewCommand}{\void} | |
599 | ||
600 | Gets the command used to view a PostScript file. The default depends on the platform. | |
601 | ||
602 | \membersection{::wxGetPrinterScaling} | |
603 | ||
604 | \func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}} | |
605 | ||
606 | Gets the scaling factor for PostScript output. The default is 1.0, 1.0. | |
607 | ||
608 | \membersection{::wxGetPrinterTranslation} | |
609 | ||
610 | \func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}} | |
611 | ||
612 | Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. | |
613 | ||
614 | \membersection{::wxSetPrinterCommand} | |
615 | ||
616 | \func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}} | |
617 | ||
618 | Sets the printer command used to print a file. The default is {\tt lpr}. | |
619 | ||
620 | \membersection{::wxSetPrinterFile} | |
621 | ||
622 | \func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}} | |
623 | ||
624 | Sets the PostScript output filename. | |
625 | ||
626 | \membersection{::wxSetPrinterMode} | |
627 | ||
628 | \func{void}{wxSetPrinterMode}{\param{int }{mode}} | |
629 | ||
630 | Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). | |
631 | The default is PS\_PREVIEW. | |
632 | ||
633 | \membersection{::wxSetPrinterOptions} | |
634 | ||
635 | \func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}} | |
636 | ||
637 | Sets the additional options for the print command (e.g. specific printer). The default is nothing. | |
638 | ||
639 | \membersection{::wxSetPrinterOrientation} | |
640 | ||
641 | \func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}} | |
642 | ||
643 | Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. | |
644 | ||
645 | \membersection{::wxSetPrinterPreviewCommand} | |
646 | ||
647 | \func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}} | |
648 | ||
649 | Sets the command used to view a PostScript file. The default depends on the platform. | |
650 | ||
651 | \membersection{::wxSetPrinterScaling} | |
652 | ||
653 | \func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}} | |
654 | ||
655 | Sets the scaling factor for PostScript output. The default is 1.0, 1.0. | |
656 | ||
657 | \membersection{::wxSetPrinterTranslation} | |
658 | ||
659 | \func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}} | |
660 | ||
661 | Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. | |
662 | ||
663 | \section{Clipboard functions}\label{clipsboard} | |
664 | ||
665 | These clipboard functions are implemented for Windows only. | |
666 | ||
954b8ae6 JS |
667 | \wxheading{Include files} |
668 | ||
669 | <wx/clipbrd.h> | |
670 | ||
a660d684 KB |
671 | \membersection{::wxClipboardOpen} |
672 | ||
673 | \func{bool}{wxClipboardOpen}{\void} | |
674 | ||
675 | Returns TRUE if this application has already opened the clipboard. | |
676 | ||
677 | \membersection{::wxCloseClipboard} | |
678 | ||
679 | \func{bool}{wxCloseClipboard}{\void} | |
680 | ||
681 | Closes the clipboard to allow other applications to use it. | |
682 | ||
683 | \membersection{::wxEmptyClipboard} | |
684 | ||
685 | \func{bool}{wxEmptyClipboard}{\void} | |
686 | ||
687 | Empties the clipboard. | |
688 | ||
689 | \membersection{::wxEnumClipboardFormats} | |
690 | ||
691 | \func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}} | |
692 | ||
693 | Enumerates the formats found in a list of available formats that belong | |
694 | to the clipboard. Each call to this function specifies a known | |
695 | available format; the function returns the format that appears next in | |
696 | the list. | |
697 | ||
698 | {\it dataFormat} specifies a known format. If this parameter is zero, | |
699 | the function returns the first format in the list. | |
700 | ||
701 | The return value specifies the next known clipboard data format if the | |
702 | function is successful. It is zero if the {\it dataFormat} parameter specifies | |
703 | the last format in the list of available formats, or if the clipboard | |
704 | is not open. | |
705 | ||
706 | Before it enumerates the formats function, an application must open the clipboard by using the | |
707 | wxOpenClipboard function. | |
708 | ||
709 | \membersection{::wxGetClipboardData} | |
710 | ||
711 | \func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}} | |
712 | ||
713 | Gets data from the clipboard. | |
714 | ||
715 | {\it dataFormat} may be one of: | |
716 | ||
717 | \begin{itemize}\itemsep=0pt | |
718 | \item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string. | |
719 | \item wxCF\_BITMAP: returns a new wxBitmap. | |
720 | \end{itemize} | |
721 | ||
722 | The clipboard must have previously been opened for this call to succeed. | |
723 | ||
724 | \membersection{::wxGetClipboardFormatName} | |
725 | ||
726 | \func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}} | |
727 | ||
728 | Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum | |
729 | length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format. | |
730 | ||
731 | \membersection{::wxIsClipboardFormatAvailable} | |
732 | ||
733 | \func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}} | |
734 | ||
735 | Returns TRUE if the given data format is available on the clipboard. | |
736 | ||
737 | \membersection{::wxOpenClipboard} | |
738 | ||
739 | \func{bool}{wxOpenClipboard}{\void} | |
740 | ||
741 | Opens the clipboard for passing data to it or getting data from it. | |
742 | ||
743 | \membersection{::wxRegisterClipboardFormat} | |
744 | ||
745 | \func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}} | |
746 | ||
747 | Registers the clipboard data format name and returns an identifier. | |
748 | ||
749 | \membersection{::wxSetClipboardData} | |
750 | ||
751 | \func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}} | |
752 | ||
753 | Passes data to the clipboard. | |
754 | ||
755 | {\it dataFormat} may be one of: | |
756 | ||
757 | \begin{itemize}\itemsep=0pt | |
758 | \item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string. | |
759 | \item wxCF\_BITMAP: {\it data} is a wxBitmap. | |
760 | \item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap). | |
e2a6f233 | 761 | \item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions. |
a660d684 KB |
762 | \end{itemize} |
763 | ||
764 | The clipboard must have previously been opened for this call to succeed. | |
765 | ||
766 | \section{Miscellaneous functions}\label{miscellany} | |
767 | ||
954b8ae6 | 768 | \membersection{::wxNewId} |
a660d684 | 769 | |
954b8ae6 | 770 | \func{long}{wxNewId}{\void} |
a660d684 KB |
771 | |
772 | Generates an integer identifier unique to this run of the program. | |
773 | ||
954b8ae6 JS |
774 | \wxheading{Include files} |
775 | ||
776 | <wx/utils.h> | |
a660d684 | 777 | |
954b8ae6 JS |
778 | \membersection{::wxRegisterId} |
779 | ||
780 | \func{void}{wxRegisterId}{\param{long}{ id}} | |
a660d684 KB |
781 | |
782 | Ensures that ids subsequently generated by {\bf NewId} do not clash with | |
783 | the given {\bf id}. | |
784 | ||
954b8ae6 JS |
785 | \wxheading{Include files} |
786 | ||
787 | <wx/utils.h> | |
788 | ||
a660d684 KB |
789 | \membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} |
790 | ||
791 | \func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}} | |
792 | ||
793 | Changes the cursor to the given cursor for all windows in the application. | |
794 | Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back | |
795 | to its previous state. These two calls can be nested, and a counter | |
796 | ensures that only the outer calls take effect. | |
797 | ||
e2a6f233 | 798 | See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. |
a660d684 | 799 | |
954b8ae6 JS |
800 | \wxheading{Include files} |
801 | ||
802 | <wx/utils.h> | |
803 | ||
a660d684 KB |
804 | \membersection{::wxBell} |
805 | ||
806 | \func{void}{wxBell}{\void} | |
807 | ||
808 | Ring the system bell. | |
809 | ||
954b8ae6 | 810 | \wxheading{Include files} |
a660d684 | 811 | |
954b8ae6 | 812 | <wx/utils.h> |
a660d684 KB |
813 | |
814 | \membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject} | |
815 | ||
816 | \func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}} | |
817 | ||
818 | Creates and returns an object of the given class, if the class has been | |
819 | registered with the dynamic class system using DECLARE... and IMPLEMENT... macros. | |
820 | ||
e2a6f233 JS |
821 | \membersection{::wxDDECleanUp}\label{wxddecleanup} |
822 | ||
823 | \func{void}{wxDDECleanUp}{\void} | |
824 | ||
825 | Called when wxWindows exits, to clean up the DDE system. This no longer needs to be | |
826 | called by the application. | |
827 | ||
828 | See also helpref{wxDDEInitialize}{wxddeinitialize}. | |
829 | ||
954b8ae6 JS |
830 | \wxheading{Include files} |
831 | ||
832 | <wx/dde.h> | |
833 | ||
e2a6f233 JS |
834 | \membersection{::wxDDEInitialize}\label{wxddeinitialize} |
835 | ||
836 | \func{void}{wxDDEInitialize}{\void} | |
837 | ||
838 | Initializes the DDE system. May be called multiple times without harm. | |
839 | ||
840 | This no longer needs to be called by the application: it will be called | |
841 | by wxWindows if necessary. | |
842 | ||
843 | See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection}, | |
844 | \helpref{wxDDECleanUp}{wxddecleanup}. | |
845 | ||
954b8ae6 JS |
846 | \wxheading{Include files} |
847 | ||
848 | <wx/dde.h> | |
849 | ||
e2a6f233 | 850 | \membersection{::wxDebugMsg}\label{wxdebugmsg} |
a660d684 KB |
851 | |
852 | \func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}} | |
853 | ||
854 | Display a debugging message; under Windows, this will appear on the | |
e2a6f233 | 855 | debugger command window, and under Unix, it will be written to standard |
a660d684 KB |
856 | error. |
857 | ||
858 | The syntax is identical to {\bf printf}: pass a format string and a | |
859 | variable list of arguments. | |
860 | ||
861 | Note that under Windows, you can see the debugging messages without a | |
862 | debugger if you have the DBWIN debug log application that comes with | |
863 | Microsoft C++. | |
864 | ||
865 | {\bf Tip:} under Windows, if your application crashes before the | |
866 | message appears in the debugging window, put a wxYield call after | |
867 | each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s | |
868 | (at least for Watcom C++): preformat your messages and use OutputDebugString | |
869 | instead. | |
870 | ||
6fb26ea3 JS |
871 | This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
872 | ||
954b8ae6 JS |
873 | \wxheading{Include files} |
874 | ||
875 | <wx/utils.h> | |
876 | ||
a660d684 KB |
877 | \membersection{::wxDisplaySize} |
878 | ||
879 | \func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} | |
880 | ||
881 | Gets the physical size of the display in pixels. | |
882 | ||
954b8ae6 JS |
883 | \wxheading{Include files} |
884 | ||
885 | <wx/gdicmn.h> | |
886 | ||
a660d684 KB |
887 | \membersection{::wxEntry}\label{wxentry} |
888 | ||
889 | This initializes wxWindows in a platform-dependent way. Use this if you | |
890 | are not using the default wxWindows entry code (e.g. main or WinMain). For example, | |
891 | you can initialize wxWindows from an Microsoft Foundation Classes application using | |
954b8ae6 | 892 | this function. |
a660d684 KB |
893 | |
894 | \func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, | |
895 | \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}} | |
896 | ||
897 | wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the | |
898 | function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows | |
899 | message loop will be entered. | |
900 | ||
901 | \func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, | |
902 | \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}} | |
903 | ||
904 | wxWindows initialization under Windows (for applications constructed as a DLL). | |
905 | ||
906 | \func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}} | |
907 | ||
e2a6f233 | 908 | wxWindows initialization under Unix. |
a660d684 | 909 | |
954b8ae6 JS |
910 | \wxheading{Remarks} |
911 | ||
912 | To clean up wxWindows, call wxApp::OnExit followed by the static function | |
913 | wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows: | |
914 | ||
915 | \begin{verbatim} | |
916 | int CTheApp::ExitInstance() | |
917 | { | |
918 | // OnExit isn't called by CleanUp so must be called explicitly. | |
919 | wxTheApp->OnExit(); | |
920 | wxApp::CleanUp(); | |
921 | ||
922 | return CWinApp::ExitInstance(); | |
923 | } | |
924 | \end{verbatim} | |
925 | ||
926 | \wxheading{Include files} | |
927 | ||
928 | <wx/app.h> | |
929 | ||
a660d684 KB |
930 | \membersection{::wxError}\label{wxerror} |
931 | ||
932 | \func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}} | |
933 | ||
934 | Displays {\it msg} and continues. This writes to standard error under | |
e2a6f233 | 935 | Unix, and pops up a message box under Windows. Used for internal |
a660d684 KB |
936 | wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}. |
937 | ||
954b8ae6 JS |
938 | \wxheading{Include files} |
939 | ||
940 | <wx/utils.h> | |
941 | ||
a660d684 KB |
942 | \membersection{::wxEndBusyCursor}\label{wxendbusycursor} |
943 | ||
944 | \func{void}{wxEndBusyCursor}{\void} | |
945 | ||
946 | Changes the cursor back to the original cursor, for all windows in the application. | |
947 | Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}. | |
948 | ||
e2a6f233 | 949 | See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. |
a660d684 | 950 | |
954b8ae6 JS |
951 | \wxheading{Include files} |
952 | ||
953 | <wx/utils.h> | |
954 | ||
a660d684 KB |
955 | \membersection{::wxExecute}\label{wxexecute} |
956 | ||
eafc087e | 957 | \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} |
a660d684 | 958 | |
e2a6f233 | 959 | \func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} |
a660d684 | 960 | |
e2a6f233 | 961 | Executes another program in Unix or Windows. |
a660d684 KB |
962 | |
963 | The first form takes a command string, such as {\tt "emacs file.txt"}. | |
964 | ||
965 | The second form takes an array of values: a command, any number of | |
966 | arguments, terminated by NULL. | |
967 | ||
968 | If {\it sync} is FALSE (the default), flow of control immediately returns. | |
969 | If TRUE, the current application waits until the other program has terminated. | |
970 | ||
e6045e08 VZ |
971 | In the case of synchronous execution, the return value is trhe exit code of |
972 | the process (which terminates by the moment the function returns) and will be | |
973 | $-1$ if the process couldn't be started and typically 0 if the process | |
974 | terminated successfully. | |
975 | ||
976 | For asynchronous execution, however, the return value is the process id and | |
977 | zero value indicates that the command could not be executed. | |
a660d684 | 978 | |
7e84f02d VZ |
979 | If callback isn't NULL and if execution is asynchronous (note that callback |
980 | parameter can not be non NULL for synchronous execution), | |
eafc087e GL |
981 | \helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when |
982 | the process finishes. | |
983 | ||
984 | See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}. | |
a660d684 | 985 | |
954b8ae6 JS |
986 | \wxheading{Include files} |
987 | ||
988 | <wx/utils.h> | |
989 | ||
a660d684 KB |
990 | \membersection{::wxExit}\label{wxexit} |
991 | ||
992 | \func{void}{wxExit}{\void} | |
993 | ||
994 | Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}. | |
995 | Should only be used in an emergency: normally the top-level frame | |
996 | should be deleted (after deleting all other frames) to terminate the | |
997 | application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}. | |
998 | ||
954b8ae6 JS |
999 | \wxheading{Include files} |
1000 | ||
1001 | <wx/app.h> | |
1002 | ||
a660d684 KB |
1003 | \membersection{::wxFatalError}\label{wxfatalerror} |
1004 | ||
1005 | \func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}} | |
1006 | ||
e2a6f233 | 1007 | Displays {\it msg} and exits. This writes to standard error under Unix, |
a660d684 KB |
1008 | and pops up a message box under Windows. Used for fatal internal |
1009 | wxWindows errors. See also \helpref{wxError}{wxerror}. | |
1010 | ||
954b8ae6 JS |
1011 | \wxheading{Include files} |
1012 | ||
1013 | <wx/utils.h> | |
1014 | ||
a660d684 KB |
1015 | \membersection{::wxFindMenuItemId} |
1016 | ||
1017 | \func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}} | |
1018 | ||
1019 | Find a menu item identifier associated with the given frame's menu bar. | |
1020 | ||
954b8ae6 JS |
1021 | \wxheading{Include files} |
1022 | ||
1023 | <wx/utils.h> | |
1024 | ||
a660d684 KB |
1025 | \membersection{::wxFindWindowByLabel} |
1026 | ||
1027 | \func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}} | |
1028 | ||
1029 | Find a window by its label. Depending on the type of window, the label may be a window title | |
1030 | or panel item label. If {\it parent} is NULL, the search will start from all top-level | |
1031 | frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. | |
1032 | The search is recursive in both cases. | |
1033 | ||
954b8ae6 JS |
1034 | \wxheading{Include files} |
1035 | ||
1036 | <wx/utils.h> | |
1037 | ||
a660d684 KB |
1038 | \membersection{::wxFindWindowByName}\label{wxfindwindowbyname} |
1039 | ||
1040 | \func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}} | |
1041 | ||
1042 | Find a window by its name (as given in a window constructor or {\bf Create} function call). | |
1043 | If {\it parent} is NULL, the search will start from all top-level | |
1044 | frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. | |
1045 | The search is recursive in both cases. | |
1046 | ||
1047 | If no such named window is found, {\bf wxFindWindowByLabel} is called. | |
1048 | ||
954b8ae6 JS |
1049 | \wxheading{Include files} |
1050 | ||
1051 | <wx/utils.h> | |
1052 | ||
a660d684 KB |
1053 | \membersection{::wxGetActiveWindow}\label{wxgetactivewindow} |
1054 | ||
1055 | \func{wxWindow *}{wxGetActiveWindow}{\void} | |
1056 | ||
1057 | Gets the currently active window (Windows only). | |
1058 | ||
954b8ae6 JS |
1059 | \wxheading{Include files} |
1060 | ||
1061 | <wx/windows.h> | |
1062 | ||
a660d684 KB |
1063 | \membersection{::wxGetDisplayName}\label{wxgetdisplayname} |
1064 | ||
1065 | \func{wxString}{wxGetDisplayName}{\void} | |
1066 | ||
1067 | Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}. | |
1068 | ||
954b8ae6 JS |
1069 | \wxheading{Include files} |
1070 | ||
1071 | <wx/utils.h> | |
1072 | ||
a660d684 KB |
1073 | \membersection{::wxGetHomeDir} |
1074 | ||
1075 | \func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}} | |
1076 | ||
e2a6f233 | 1077 | Fills the buffer with a string representing the user's home directory (Unix only). |
a660d684 | 1078 | |
954b8ae6 JS |
1079 | \wxheading{Include files} |
1080 | ||
1081 | <wx/utils.h> | |
1082 | ||
a660d684 KB |
1083 | \membersection{::wxGetHostName} |
1084 | ||
1085 | \func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} | |
1086 | ||
1087 | Copies the host name of the machine the program is running on into the | |
1088 | buffer {\it buf}, of maximum size {\it bufSize}, returning TRUE if | |
e2a6f233 | 1089 | successful. Under Unix, this will return a machine name. Under Windows, |
a660d684 KB |
1090 | this returns ``windows''. |
1091 | ||
954b8ae6 JS |
1092 | \wxheading{Include files} |
1093 | ||
1094 | <wx/utils.h> | |
1095 | ||
a660d684 KB |
1096 | \membersection{::wxGetElapsedTime}\label{wxgetelapsedtime} |
1097 | ||
1098 | \func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}} | |
1099 | ||
1100 | Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}. | |
1101 | ||
1102 | If {\it resetTimer} is TRUE (the default), the timer is reset to zero | |
1103 | by this call. | |
1104 | ||
1105 | See also \helpref{wxTimer}{wxtimer}. | |
1106 | ||
954b8ae6 JS |
1107 | \wxheading{Include files} |
1108 | ||
1109 | <wx/timer.h> | |
1110 | ||
e2a6f233 | 1111 | \membersection{::wxGetFreeMemory}\label{wxgetfreememory} |
a660d684 KB |
1112 | |
1113 | \func{long}{wxGetFreeMemory}{\void} | |
1114 | ||
1115 | Returns the amount of free memory in Kbytes under environments which | |
1116 | support it, and -1 if not supported. Currently, returns a positive value | |
e2a6f233 | 1117 | under Windows, and -1 under Unix. |
a660d684 | 1118 | |
954b8ae6 JS |
1119 | \wxheading{Include files} |
1120 | ||
1121 | <wx/utils.h> | |
1122 | ||
a660d684 KB |
1123 | \membersection{::wxGetMousePosition} |
1124 | ||
1125 | \func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}} | |
1126 | ||
1127 | Returns the mouse position in screen coordinates. | |
1128 | ||
954b8ae6 JS |
1129 | \wxheading{Include files} |
1130 | ||
1131 | <wx/utils.h> | |
1132 | ||
a660d684 KB |
1133 | \membersection{::wxGetOsVersion} |
1134 | ||
1135 | \func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} | |
1136 | ||
1137 | Gets operating system version information. | |
1138 | ||
1139 | \begin{twocollist}\itemsep=0pt | |
1140 | \twocolitemruled{Platform}{Return tyes} | |
1141 | \twocolitem{Macintosh}{Return value is wxMACINTOSH.} | |
12a44087 | 1142 | \twocolitem{GTK}{Return value is wxGTK, {\it major} is 1, {\it minor} is 0. (for GTK 1.0.X) } |
a660d684 KB |
1143 | \twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.} |
1144 | \twocolitem{OS/2}{Return value is wxOS2\_PM.} | |
1145 | \twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.} | |
1146 | \twocolitem{Windows NT}{Return value is wxWINDOWS\_NT, {\it major} is 3, {\it minor} is 1.} | |
1147 | \twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 3, {\it minor} is 1.} | |
1148 | \twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.} | |
1149 | \twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.} | |
1150 | \end{twocollist} | |
1151 | ||
954b8ae6 JS |
1152 | \wxheading{Include files} |
1153 | ||
1154 | <wx/utils.h> | |
1155 | ||
a660d684 KB |
1156 | \membersection{::wxGetResource}\label{wxgetresource} |
1157 | ||
1158 | \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1159 | \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}} | |
1160 | ||
1161 | \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1162 | \param{float *}{value}, \param{const wxString\& }{file = NULL}} | |
1163 | ||
1164 | \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1165 | \param{long *}{value}, \param{const wxString\& }{file = NULL}} | |
1166 | ||
1167 | \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1168 | \param{int *}{value}, \param{const wxString\& }{file = NULL}} | |
1169 | ||
1170 | Gets a resource value from the resource database (for example, WIN.INI, or | |
1171 | .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used, | |
1172 | otherwise the specified file is used. | |
1173 | ||
e2a6f233 | 1174 | Under X, if an application class (wxApp::GetClassName) has been defined, |
a660d684 KB |
1175 | it is appended to the string /usr/lib/X11/app-defaults/ to try to find |
1176 | an applications default file when merging all resource databases. | |
1177 | ||
1178 | The reason for passing the result in an argument is that it | |
1179 | can be convenient to define a default value, which gets overridden | |
1180 | if the value exists in the resource file. It saves a separate | |
1181 | test for that resource's existence, and it also allows | |
1182 | the overloading of the function for different types. | |
1183 | ||
e2a6f233 | 1184 | See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}. |
a660d684 | 1185 | |
954b8ae6 JS |
1186 | \wxheading{Include files} |
1187 | ||
1188 | <wx/utils.h> | |
1189 | ||
a660d684 KB |
1190 | \membersection{::wxGetUserId} |
1191 | ||
1192 | \func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} | |
1193 | ||
1194 | Copies the user's login identity (such as ``jacs'') into the buffer {\it | |
1195 | buf}, of maximum size {\it bufSize}, returning TRUE if successful. | |
1196 | Under Windows, this returns ``user''. | |
1197 | ||
954b8ae6 JS |
1198 | \wxheading{Include files} |
1199 | ||
1200 | <wx/utils.h> | |
1201 | ||
a660d684 KB |
1202 | \membersection{::wxGetUserName} |
1203 | ||
1204 | \func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} | |
1205 | ||
1206 | Copies the user's name (such as ``Julian Smart'') into the buffer {\it | |
1207 | buf}, of maximum size {\it bufSize}, returning TRUE if successful. | |
1208 | Under Windows, this returns ``unknown''. | |
1209 | ||
954b8ae6 JS |
1210 | \wxheading{Include files} |
1211 | ||
1212 | <wx/utils.h> | |
1213 | ||
a660d684 KB |
1214 | \membersection{::wxKill}\label{wxkill} |
1215 | ||
1216 | \func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}} | |
1217 | ||
e2a6f233 | 1218 | Under Unix (the only supported platform), equivalent to the Unix kill function. |
a660d684 KB |
1219 | Returns 0 on success, -1 on failure. |
1220 | ||
1221 | Tip: sending a signal of 0 to a process returns -1 if the process does not exist. | |
1222 | It does not raise a signal in the receiving process. | |
1223 | ||
954b8ae6 | 1224 | \wxheading{Include files} |
a660d684 | 1225 | |
954b8ae6 | 1226 | <wx/utils.h> |
a660d684 | 1227 | |
a660d684 KB |
1228 | \membersection{::wxIsBusy}\label{wxisbusy} |
1229 | ||
1230 | \func{bool}{wxIsBusy}{\void} | |
1231 | ||
1232 | Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp | |
1233 | \helpref{wxEndBusyCursor}{wxendbusycursor} calls. | |
1234 | ||
e2a6f233 JS |
1235 | See also \helpref{wxBusyCursor}{wxbusycursor}. |
1236 | ||
954b8ae6 JS |
1237 | \wxheading{Include files} |
1238 | ||
1239 | <wx/utils.h> | |
1240 | ||
a660d684 KB |
1241 | \membersection{::wxLoadUserResource}\label{wxloaduserresource} |
1242 | ||
1243 | \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} | |
1244 | ||
1245 | Loads a user-defined Windows resource as a string. If the resource is found, the function creates | |
1246 | a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned. | |
1247 | ||
1248 | The resource must be defined in the {\tt .rc} file using the following syntax: | |
1249 | ||
1250 | \begin{verbatim} | |
1251 | myResource TEXT file.ext | |
1252 | \end{verbatim} | |
1253 | ||
1254 | where {\tt file.ext} is a file that the resource compiler can find. | |
1255 | ||
1256 | One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers | |
1257 | cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed | |
1258 | using \helpref{wxResourceParseString}{wxresourceparsestring}. | |
1259 | ||
1260 | This function is available under Windows only. | |
1261 | ||
954b8ae6 JS |
1262 | \wxheading{Include files} |
1263 | ||
1264 | <wx/utils.h> | |
1265 | ||
a660d684 KB |
1266 | \membersection{::wxNow}\label{wxnow} |
1267 | ||
1268 | \func{wxString}{wxNow}{\void} | |
1269 | ||
1270 | Returns a string representing the current date and time. | |
1271 | ||
954b8ae6 JS |
1272 | \wxheading{Include files} |
1273 | ||
1274 | <wx/utils.h> | |
1275 | ||
a660d684 KB |
1276 | \membersection{::wxPostDelete}\label{wxpostdelete} |
1277 | ||
1278 | \func{void}{wxPostDelete}{\param{wxObject *}{object}} | |
1279 | ||
954b8ae6 | 1280 | Tells the system to delete the specified object when |
a660d684 KB |
1281 | all other events have been processed. In some environments, it is |
1282 | necessary to use this instead of deleting a frame directly with the | |
954b8ae6 | 1283 | delete operator, because some GUIs will still send events to a deleted window. |
a660d684 KB |
1284 | |
1285 | Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead. | |
1286 | ||
954b8ae6 JS |
1287 | \wxheading{Include files} |
1288 | ||
1289 | <wx/utils.h> | |
1290 | ||
a660d684 KB |
1291 | \membersection{::wxSetDisplayName}\label{wxsetdisplayname} |
1292 | ||
1293 | \func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}} | |
1294 | ||
1295 | Under X only, sets the current display name. This is the X host and display name such | |
1296 | as ``colonsay:0.0", and the function indicates which display should be used for creating | |
1297 | windows from this point on. Setting the display within an application allows multiple | |
1298 | displays to be used. | |
1299 | ||
1300 | See also \helpref{wxGetDisplayName}{wxgetdisplayname}. | |
1301 | ||
954b8ae6 JS |
1302 | \wxheading{Include files} |
1303 | ||
1304 | <wx/utils.h> | |
1305 | ||
a660d684 KB |
1306 | \membersection{::wxShell}\label{wxshell} |
1307 | ||
1308 | \func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} | |
1309 | ||
1310 | Executes a command in an interactive shell window. If no command is | |
1311 | specified, then just the shell is spawned. | |
1312 | ||
1313 | See also \helpref{wxExecute}{wxexecute}. | |
1314 | ||
954b8ae6 JS |
1315 | \wxheading{Include files} |
1316 | ||
1317 | <wx/utils.h> | |
1318 | ||
e2a6f233 | 1319 | \membersection{::wxSleep}\label{wxsleep} |
a660d684 KB |
1320 | |
1321 | \func{void}{wxSleep}{\param{int}{ secs}} | |
1322 | ||
e2a6f233 | 1323 | Sleeps for the specified number of seconds. |
a660d684 | 1324 | |
954b8ae6 JS |
1325 | \wxheading{Include files} |
1326 | ||
1327 | <wx/utils.h> | |
1328 | ||
a660d684 KB |
1329 | \membersection{::wxStripMenuCodes} |
1330 | ||
8a2c6ef8 JS |
1331 | \func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}} |
1332 | ||
1333 | \func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}} | |
a660d684 KB |
1334 | |
1335 | Strips any menu codes from {\it in} and places the result | |
8a2c6ef8 JS |
1336 | in {\it out} (or returns the new string, in the first form). |
1337 | ||
1338 | Menu codes include \& (mark the next character with an underline | |
a660d684 KB |
1339 | as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows). |
1340 | ||
954b8ae6 JS |
1341 | \wxheading{Include files} |
1342 | ||
1343 | <wx/utils.h> | |
1344 | ||
a660d684 KB |
1345 | \membersection{::wxStartTimer}\label{wxstarttimer} |
1346 | ||
1347 | \func{void}{wxStartTimer}{\void} | |
1348 | ||
1349 | Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time. | |
1350 | ||
1351 | See also \helpref{wxTimer}{wxtimer}. | |
1352 | ||
954b8ae6 JS |
1353 | \wxheading{Include files} |
1354 | ||
1355 | <wx/timer.h> | |
1356 | ||
a660d684 KB |
1357 | \membersection{::wxToLower}\label{wxtolower} |
1358 | ||
1359 | \func{char}{wxToLower}{\param{char }{ch}} | |
1360 | ||
1361 | Converts the character to lower case. This is implemented as a macro for efficiency. | |
1362 | ||
954b8ae6 JS |
1363 | \wxheading{Include files} |
1364 | ||
1365 | <wx/utils.h> | |
1366 | ||
a660d684 KB |
1367 | \membersection{::wxToUpper}\label{wxtoupper} |
1368 | ||
1369 | \func{char}{wxToUpper}{\param{char }{ch}} | |
1370 | ||
1371 | Converts the character to upper case. This is implemented as a macro for efficiency. | |
1372 | ||
954b8ae6 JS |
1373 | \wxheading{Include files} |
1374 | ||
1375 | <wx/utils.h> | |
1376 | ||
a660d684 KB |
1377 | \membersection{::wxTrace}\label{wxtrace} |
1378 | ||
1379 | \func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} | |
1380 | ||
1381 | Takes printf-style variable argument syntax. Output | |
1382 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). | |
1383 | ||
6fb26ea3 JS |
1384 | This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
1385 | ||
954b8ae6 JS |
1386 | \wxheading{Include files} |
1387 | ||
1388 | <wx/memory.h> | |
1389 | ||
a660d684 KB |
1390 | \membersection{::wxTraceLevel}\label{wxtracelevel} |
1391 | ||
1392 | \func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} | |
1393 | ||
1394 | Takes printf-style variable argument syntax. Output | |
1395 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). | |
1396 | The first argument should be the level at which this information is appropriate. | |
1397 | It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than | |
1398 | this value. | |
1399 | ||
6fb26ea3 JS |
1400 | This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
1401 | ||
954b8ae6 JS |
1402 | \wxheading{Include files} |
1403 | ||
1404 | <wx/memory.h> | |
1405 | ||
a660d684 KB |
1406 | \membersection{::wxWriteResource}\label{wxwriteresource} |
1407 | ||
1408 | \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1409 | \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}} | |
1410 | ||
1411 | \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1412 | \param{float }{value}, \param{const wxString\& }{file = NULL}} | |
1413 | ||
1414 | \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1415 | \param{long }{value}, \param{const wxString\& }{file = NULL}} | |
1416 | ||
1417 | \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, | |
1418 | \param{int }{value}, \param{const wxString\& }{file = NULL}} | |
1419 | ||
1420 | Writes a resource value into the resource database (for example, WIN.INI, or | |
1421 | .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used, | |
1422 | otherwise the specified file is used. | |
1423 | ||
1424 | Under X, the resource databases are cached until the internal function | |
1425 | \rtfsp{\bf wxFlushResources} is called automatically on exit, when | |
1426 | all updated resource databases are written to their files. | |
1427 | ||
1428 | Note that it is considered bad manners to write to the .Xdefaults | |
e2a6f233 | 1429 | file under Unix, although the WIN.INI file is fair game under Windows. |
a660d684 | 1430 | |
e2a6f233 | 1431 | See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}. |
a660d684 | 1432 | |
954b8ae6 JS |
1433 | \wxheading{Include files} |
1434 | ||
1435 | <wx/utils.h> | |
1436 | ||
fd34e3a5 | 1437 | \membersection{::wxYield}\label{wxyield} |
a660d684 KB |
1438 | |
1439 | \func{bool}{wxYield}{\void} | |
1440 | ||
1441 | Yields control to pending messages in the windowing system. This can be useful, for example, when a | |
1442 | time-consuming process writes to a text window. Without an occasional | |
1443 | yield, the text window will not be updated properly, and (since Windows | |
1444 | multitasking is cooperative) other processes will not respond. | |
1445 | ||
1446 | Caution should be exercised, however, since yielding may allow the | |
1447 | user to perform actions which are not compatible with the current task. | |
1448 | Disabling menu items or whole menus during processing can avoid unwanted | |
1449 | reentrance of code. | |
1450 | ||
954b8ae6 JS |
1451 | \wxheading{Include files} |
1452 | ||
1453 | <wx/utils.h> | |
1454 | ||
a660d684 KB |
1455 | \section{Macros}\label{macros} |
1456 | ||
1457 | These macros are defined in wxWindows. | |
1458 | ||
1459 | \membersection{CLASSINFO}\label{classinfo} | |
1460 | ||
1461 | \func{wxClassInfo *}{CLASSINFO}{className} | |
1462 | ||
1463 | Returns a pointer to the wxClassInfo object associated with this class. | |
1464 | ||
954b8ae6 JS |
1465 | \wxheading{Include files} |
1466 | ||
1467 | <wx/object.h> | |
1468 | ||
a660d684 KB |
1469 | \membersection{WXDEBUG\_NEW}\label{debugnew} |
1470 | ||
1471 | \func{}{WXDEBUG\_NEW}{arg} | |
1472 | ||
1473 | This is defined in debug mode to be call the redefined new operator | |
1474 | with filename and line number arguments. The definition is: | |
1475 | ||
1476 | \begin{verbatim} | |
1477 | #define WXDEBUG_NEW new(__FILE__,__LINE__) | |
1478 | \end{verbatim} | |
1479 | ||
1480 | In non-debug mode, this is defined as the normal new operator. | |
1481 | ||
954b8ae6 JS |
1482 | \wxheading{Include files} |
1483 | ||
1484 | <wx/object.h> | |
1485 | ||
a660d684 KB |
1486 | \membersection{DECLARE\_ABSTRACT\_CLASS} |
1487 | ||
1488 | \func{}{DECLARE\_ABSTRACT\_CLASS}{className} | |
1489 | ||
1490 | Used inside a class declaration to declare that the class should be | |
1491 | made known to the class hierarchy, but objects of this class cannot be created | |
1492 | dynamically. The same as DECLARE\_CLASS. | |
1493 | ||
1494 | Example: | |
1495 | ||
1496 | \begin{verbatim} | |
1497 | class wxCommand: public wxObject | |
1498 | { | |
1499 | DECLARE_ABSTRACT_CLASS(wxCommand) | |
1500 | ||
1501 | private: | |
1502 | ... | |
1503 | public: | |
1504 | ... | |
1505 | }; | |
1506 | \end{verbatim} | |
1507 | ||
954b8ae6 JS |
1508 | \wxheading{Include files} |
1509 | ||
1510 | <wx/object.h> | |
1511 | ||
a660d684 KB |
1512 | \membersection{DECLARE\_APP}\label{declareapp} |
1513 | ||
1514 | \func{}{DECLARE\_APP}{className} | |
1515 | ||
1516 | This is used in headers to create a forward declaration of the wxGetApp function implemented | |
1517 | by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}. | |
1518 | ||
1519 | Example: | |
1520 | ||
1521 | \begin{verbatim} | |
1522 | DECLARE_APP(MyApp) | |
1523 | \end{verbatim} | |
1524 | ||
954b8ae6 JS |
1525 | \wxheading{Include files} |
1526 | ||
1527 | <wx/app.h> | |
1528 | ||
a660d684 KB |
1529 | \membersection{DECLARE\_CLASS} |
1530 | ||
1531 | \func{}{DECLARE\_CLASS}{className} | |
1532 | ||
1533 | Used inside a class declaration to declare that the class should be | |
1534 | made known to the class hierarchy, but objects of this class cannot be created | |
1535 | dynamically. The same as DECLARE\_ABSTRACT\_CLASS. | |
1536 | ||
954b8ae6 JS |
1537 | \wxheading{Include files} |
1538 | ||
1539 | <wx/object.h> | |
1540 | ||
a660d684 KB |
1541 | \membersection{DECLARE\_DYNAMIC\_CLASS} |
1542 | ||
1543 | \func{}{DECLARE\_DYNAMIC\_CLASS}{className} | |
1544 | ||
1545 | Used inside a class declaration to declare that the objects of this class should be dynamically | |
1546 | createable from run-time type information. | |
1547 | ||
1548 | Example: | |
1549 | ||
1550 | \begin{verbatim} | |
1551 | class wxFrame: public wxWindow | |
1552 | { | |
1553 | DECLARE_DYNAMIC_CLASS(wxFrame) | |
1554 | ||
1555 | private: | |
1556 | const wxString\& frameTitle; | |
1557 | public: | |
1558 | ... | |
1559 | }; | |
1560 | \end{verbatim} | |
1561 | ||
954b8ae6 JS |
1562 | \wxheading{Include files} |
1563 | ||
1564 | <wx/object.h> | |
1565 | ||
a660d684 KB |
1566 | \membersection{IMPLEMENT\_ABSTRACT\_CLASS} |
1567 | ||
1568 | \func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName} | |
1569 | ||
1570 | Used in a C++ implementation file to complete the declaration of | |
1571 | a class that has run-time type information. The same as IMPLEMENT\_CLASS. | |
1572 | ||
1573 | Example: | |
1574 | ||
1575 | \begin{verbatim} | |
1576 | IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) | |
1577 | ||
1578 | wxCommand::wxCommand(void) | |
1579 | { | |
1580 | ... | |
1581 | } | |
1582 | \end{verbatim} | |
1583 | ||
954b8ae6 JS |
1584 | \wxheading{Include files} |
1585 | ||
1586 | <wx/object.h> | |
1587 | ||
a660d684 KB |
1588 | \membersection{IMPLEMENT\_ABSTRACT\_CLASS2} |
1589 | ||
1590 | \func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2} | |
1591 | ||
1592 | Used in a C++ implementation file to complete the declaration of | |
1593 | a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2. | |
1594 | ||
954b8ae6 JS |
1595 | \wxheading{Include files} |
1596 | ||
1597 | <wx/object.h> | |
1598 | ||
a660d684 KB |
1599 | \membersection{IMPLEMENT\_APP}\label{implementapp} |
1600 | ||
1601 | \func{}{IMPLEMENT\_APP}{className} | |
1602 | ||
1603 | This is used in the application class implementation file to make the application class known to | |
1604 | wxWindows for dynamic construction. You use this instead of | |
1605 | ||
1606 | Old form: | |
1607 | ||
1608 | \begin{verbatim} | |
1609 | MyApp myApp; | |
1610 | \end{verbatim} | |
1611 | ||
1612 | New form: | |
1613 | ||
1614 | \begin{verbatim} | |
1615 | IMPLEMENT_APP(MyApp) | |
1616 | \end{verbatim} | |
1617 | ||
1618 | See also \helpref{DECLARE\_APP}{declareapp}. | |
1619 | ||
954b8ae6 JS |
1620 | \wxheading{Include files} |
1621 | ||
1622 | <wx/app.h> | |
1623 | ||
a660d684 KB |
1624 | \membersection{IMPLEMENT\_CLASS} |
1625 | ||
1626 | \func{}{IMPLEMENT\_CLASS}{className, baseClassName} | |
1627 | ||
1628 | Used in a C++ implementation file to complete the declaration of | |
1629 | a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS. | |
1630 | ||
954b8ae6 JS |
1631 | \wxheading{Include files} |
1632 | ||
1633 | <wx/object.h> | |
1634 | ||
a660d684 KB |
1635 | \membersection{IMPLEMENT\_CLASS2} |
1636 | ||
1637 | \func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2} | |
1638 | ||
1639 | Used in a C++ implementation file to complete the declaration of a | |
1640 | class that has run-time type information and two base classes. The | |
1641 | same as IMPLEMENT\_ABSTRACT\_CLASS2. | |
1642 | ||
954b8ae6 JS |
1643 | \wxheading{Include files} |
1644 | ||
1645 | <wx/object.h> | |
1646 | ||
a660d684 KB |
1647 | \membersection{IMPLEMENT\_DYNAMIC\_CLASS} |
1648 | ||
1649 | \func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName} | |
1650 | ||
1651 | Used in a C++ implementation file to complete the declaration of | |
1652 | a class that has run-time type information, and whose instances | |
1653 | can be created dynamically. | |
1654 | ||
1655 | Example: | |
1656 | ||
1657 | \begin{verbatim} | |
1658 | IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) | |
1659 | ||
1660 | wxFrame::wxFrame(void) | |
1661 | { | |
1662 | ... | |
1663 | } | |
1664 | \end{verbatim} | |
1665 | ||
954b8ae6 JS |
1666 | \wxheading{Include files} |
1667 | ||
1668 | <wx/object.h> | |
1669 | ||
a660d684 KB |
1670 | \membersection{IMPLEMENT\_DYNAMIC\_CLASS2} |
1671 | ||
1672 | \func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2} | |
1673 | ||
1674 | Used in a C++ implementation file to complete the declaration of | |
1675 | a class that has run-time type information, and whose instances | |
1676 | can be created dynamically. Use this for classes derived from two | |
1677 | base classes. | |
1678 | ||
954b8ae6 JS |
1679 | \wxheading{Include files} |
1680 | ||
1681 | <wx/object.h> | |
1682 | ||
a660d684 KB |
1683 | \membersection{WXTRACE}\label{trace} |
1684 | ||
1685 | \func{}{WXTRACE}{formatString, ...} | |
1686 | ||
1687 | Calls wxTrace with printf-style variable argument syntax. Output | |
1688 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). | |
1689 | ||
6fb26ea3 JS |
1690 | This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
1691 | ||
954b8ae6 JS |
1692 | \wxheading{Include files} |
1693 | ||
1694 | <wx/memory.h> | |
1695 | ||
a660d684 KB |
1696 | \membersection{WXTRACELEVEL}\label{tracelevel} |
1697 | ||
1698 | \func{}{WXTRACELEVEL}{level, formatString, ...} | |
1699 | ||
1700 | Calls wxTraceLevel with printf-style variable argument syntax. Output | |
1701 | is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). | |
1702 | The first argument should be the level at which this information is appropriate. | |
1703 | It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than | |
1704 | this value. | |
1705 | ||
6fb26ea3 JS |
1706 | This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. |
1707 | ||
954b8ae6 JS |
1708 | \wxheading{Include files} |
1709 | ||
1710 | <wx/memory.h> | |
1711 | ||
a660d684 KB |
1712 | \section{wxWindows resource functions}\label{resourcefuncs} |
1713 | ||
1714 | \overview{wxWindows resource system}{resourceformats} | |
1715 | ||
1716 | This section details functions for manipulating wxWindows (.WXR) resource | |
1717 | files and loading user interface elements from resources. | |
1718 | ||
1719 | \normalbox{Please note that this use of the word `resource' is different from that used when talking | |
1720 | about initialisation file resource reading and writing, using such functions | |
1721 | as wxWriteResource and wxGetResource. It's just an unfortunate clash of terminology.} | |
1722 | ||
1723 | \helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.} | |
1724 | ||
1725 | See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for | |
1726 | loading from resource data. | |
1727 | ||
954b8ae6 JS |
1728 | {\bf Warning:} this needs updating for wxWindows 2. |
1729 | ||
a660d684 KB |
1730 | \membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier} |
1731 | ||
1732 | \func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}} | |
1733 | ||
1734 | Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp | |
1735 | \verb$#$defining a name to an integer). Unlikely to be used by an application except | |
1736 | perhaps for implementing resource functionality for interpreted languages. | |
1737 | ||
1738 | \membersection{::wxResourceClear} | |
1739 | ||
1740 | \func{void}{wxResourceClear}{\void} | |
1741 | ||
1742 | Clears the wxWindows resource table. | |
1743 | ||
1744 | \membersection{::wxResourceCreateBitmap} | |
1745 | ||
1746 | \func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}} | |
1747 | ||
1748 | Creates a new bitmap from a file, static data, or Windows resource, given a valid | |
1749 | wxWindows bitmap resource identifier. For example, if the .WXR file contains | |
1750 | the following: | |
1751 | ||
1752 | \begin{verbatim} | |
1753 | static const wxString\& aiai_resource = "bitmap(name = 'aiai_resource',\ | |
1754 | bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\ | |
1755 | bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X'])."; | |
1756 | \end{verbatim} | |
1757 | ||
1758 | then this function can be called as follows: | |
1759 | ||
1760 | \begin{verbatim} | |
1761 | wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource"); | |
1762 | \end{verbatim} | |
1763 | ||
1764 | \membersection{::wxResourceCreateIcon} | |
1765 | ||
1766 | \func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}} | |
1767 | ||
1768 | Creates a new icon from a file, static data, or Windows resource, given a valid | |
1769 | wxWindows icon resource identifier. For example, if the .WXR file contains | |
1770 | the following: | |
1771 | ||
1772 | \begin{verbatim} | |
1773 | static const wxString\& aiai_resource = "icon(name = 'aiai_resource',\ | |
1774 | icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\ | |
1775 | icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X'])."; | |
1776 | \end{verbatim} | |
1777 | ||
1778 | then this function can be called as follows: | |
1779 | ||
1780 | \begin{verbatim} | |
1781 | wxIcon *icon = wxResourceCreateIcon("aiai_resource"); | |
1782 | \end{verbatim} | |
1783 | ||
1784 | \membersection{::wxResourceCreateMenuBar} | |
1785 | ||
1786 | \func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}} | |
1787 | ||
1788 | Creates a new menu bar given a valid wxWindows menubar resource | |
1789 | identifier. For example, if the .WXR file contains the following: | |
1790 | ||
1791 | \begin{verbatim} | |
1792 | static const wxString\& menuBar11 = "menu(name = 'menuBar11',\ | |
1793 | menu = \ | |
1794 | [\ | |
1795 | ['&File', 1, '', \ | |
1796 | ['&Open File', 2, 'Open a file'],\ | |
1797 | ['&Save File', 3, 'Save a file'],\ | |
1798 | [],\ | |
1799 | ['E&xit', 4, 'Exit program']\ | |
1800 | ],\ | |
1801 | ['&Help', 5, '', \ | |
1802 | ['&About', 6, 'About this program']\ | |
1803 | ]\ | |
1804 | ])."; | |
1805 | \end{verbatim} | |
1806 | ||
1807 | then this function can be called as follows: | |
1808 | ||
1809 | \begin{verbatim} | |
1810 | wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11"); | |
1811 | \end{verbatim} | |
1812 | ||
1813 | ||
1814 | \membersection{::wxResourceGetIdentifier} | |
1815 | ||
1816 | \func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}} | |
1817 | ||
1818 | Used for retrieving the integer value associated with an identifier. | |
1819 | A zero value indicates that the identifier was not found. | |
1820 | ||
1821 | See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}. | |
1822 | ||
1823 | \membersection{::wxResourceParseData}\label{wxresourcedata} | |
1824 | ||
1825 | \func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} | |
1826 | ||
1827 | Parses a string containing one or more wxWindows resource objects. If | |
1828 | the resource objects are global static data that are included into the | |
1829 | C++ program, then this function must be called for each variable | |
1830 | containing the resource data, to make it known to wxWindows. | |
1831 | ||
1832 | {\it resource} should contain data in the following form: | |
1833 | ||
1834 | \begin{verbatim} | |
1835 | dialog(name = 'dialog1', | |
1836 | style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE', | |
1837 | title = 'Test dialog box', | |
1838 | x = 312, y = 234, width = 400, height = 300, | |
1839 | modal = 0, | |
1840 | control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262, | |
1841 | [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]], | |
1842 | control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3', | |
1843 | 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.', | |
1844 | [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0], | |
1845 | [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]). | |
1846 | \end{verbatim} | |
1847 | ||
1848 | This function will typically be used after including a {\tt .wxr} file into | |
1849 | a C++ program as follows: | |
1850 | ||
1851 | \begin{verbatim} | |
1852 | #include "dialog1.wxr" | |
1853 | \end{verbatim} | |
1854 | ||
1855 | Each of the contained resources will declare a new C++ variable, and each | |
1856 | of these variables should be passed to wxResourceParseData. | |
1857 | ||
1858 | \membersection{::wxResourceParseFile} | |
1859 | ||
1860 | \func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}} | |
1861 | ||
1862 | Parses a file containing one or more wxWindows resource objects | |
1863 | in C++-compatible syntax. Use this function to dynamically load | |
1864 | wxWindows resource data. | |
1865 | ||
1866 | \membersection{::wxResourceParseString}\label{wxresourceparsestring} | |
1867 | ||
1868 | \func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} | |
1869 | ||
1870 | Parses a string containing one or more wxWindows resource objects. If | |
1871 | the resource objects are global static data that are included into the | |
1872 | C++ program, then this function must be called for each variable | |
1873 | containing the resource data, to make it known to wxWindows. | |
1874 | ||
1875 | {\it resource} should contain data with the following form: | |
1876 | ||
1877 | \begin{verbatim} | |
1878 | static const wxString\& dialog1 = "dialog(name = 'dialog1',\ | |
1879 | style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',\ | |
1880 | title = 'Test dialog box',\ | |
1881 | x = 312, y = 234, width = 400, height = 300,\ | |
1882 | modal = 0,\ | |
1883 | control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,\ | |
1884 | [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],\ | |
1885 | control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',\ | |
1886 | 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',\ | |
1887 | [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\ | |
1888 | [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]])."; | |
1889 | \end{verbatim} | |
1890 | ||
1891 | This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to | |
1892 | load an entire {\tt .wxr file} into a string. | |
1893 | ||
1894 | \membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata} | |
1895 | ||
1896 | \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width}, | |
1897 | \param{int }{height}, \param{wxResourceTable *}{table = NULL}} | |
1898 | ||
1899 | \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}} | |
1900 | ||
1901 | Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system. | |
1902 | This is required if other resources will use the bitmap data, since otherwise there | |
1903 | is no connection between names used in resources, and the global bitmap data. | |
1904 | ||
1905 | \membersection{::wxResourceRegisterIconData} | |
1906 | ||
1907 | Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}. | |
1908 | ||
6fb26ea3 JS |
1909 | \section{Log functions}\label{logfunctions} |
1910 | ||
1911 | These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for | |
1912 | further information. | |
1913 | ||
954b8ae6 JS |
1914 | \wxheading{Include files} |
1915 | ||
1916 | <wx/log.h> | |
1917 | ||
6fb26ea3 JS |
1918 | \membersection{::wxLogError}\label{wxlogerror} |
1919 | ||
1920 | \func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}} | |
1921 | ||
1922 | The function to use for error messages, i.e. the | |
1923 | messages that must be shown to the user. The default processing is to pop up a | |
1924 | message box to inform the user about it. | |
1925 | ||
1926 | \membersection{::wxLogFatalError}\label{wxlogfatalerror} | |
1927 | ||
1928 | \func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}} | |
1929 | ||
1930 | Like \helpref{wxLogError}{wxlogerror}, but also | |
1931 | terminates the program with the exit code 3. Using {\it abort()} standard | |
1932 | function also terminates the program with this exit code. | |
1933 | ||
1934 | \membersection{::wxLogWarning}\label{wxlogwarning} | |
1935 | ||
1936 | \func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}} | |
1937 | ||
1938 | For warnings - they are also normally shown to the | |
1939 | user, but don't interrupt the program work. | |
1940 | ||
1941 | \membersection{::wxLogMessage}\label{wxlogmessage} | |
1942 | ||
1943 | \func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}} | |
1944 | ||
1945 | for all normal, informational messages. They also | |
1946 | appear in a message box by default (but it can be changed). Notice | |
1947 | that the standard behaviour is to not show informational messages if there are | |
1948 | any errors later - the logic being that the later error messages make the | |
1949 | informational messages preceding them meaningless. | |
1950 | ||
1951 | \membersection{::wxLogVerbose}\label{wxlogverbose} | |
1952 | ||
1953 | \func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}} | |
1954 | ||
1955 | For verbose output. Normally, it's suppressed, but | |
1956 | might be activated if the user wishes to know more details about the program | |
1957 | progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}). | |
1958 | ||
1959 | \membersection{::wxLogStatus}\label{wxlogstatus} | |
1960 | ||
1961 | \func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}} | |
1962 | ||
1963 | For status messages - they will go into the status | |
1964 | bar of the active or specified (as the first argument) \helpref{wxFrame}{wxframe} if it has one. | |
1965 | ||
1966 | \membersection{::wxLogSysError}\label{wxlogsyserror} | |
1967 | ||
1968 | \func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}} | |
1969 | ||
1970 | Mostly used by wxWindows itself, but might be | |
1971 | handy for logging errors after system call (API function) failure. It logs the | |
1972 | specified message text as well as the last system error code ({\it errno} or {\it ::GetLastError()} depending | |
1973 | on the platform) and the corresponding error | |
1974 | message. The second form of this function takes the error code explitly as the | |
1975 | first argument. | |
1976 | ||
1977 | \membersection{::wxLogDebug}\label{wxlogdebug} | |
1978 | ||
1979 | \func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}} | |
1980 | ||
1981 | The right function for debug output. It only | |
1982 | does anything at all in the debug mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) | |
1983 | and expands to nothing in release mode (otherwise). | |
1984 | ||
1985 | \membersection{::wxLogTrace}\label{wxlogtrace} | |
1986 | ||
1987 | \func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}} | |
1988 | ||
1989 | \func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}} | |
1990 | ||
1991 | As {\bf wxLogDebug}, only does something in debug | |
1992 | build. The reason for making it a separate function from it is that usually | |
1993 | there are a lot of trace messages, so it might make sense to separate them | |
1994 | from other debug messages which would be flooded in them. Moreover, the second | |
1995 | version of this function takes a trace mask as the first argument which allows | |
1996 | to further restrict the amount of messages generated. The value of {\it mask} can be: | |
1997 | ||
1998 | \begin{itemize}\itemsep=0pt | |
1999 | \item wxTraceMemAlloc: trace memory allocation (new/delete) | |
2000 | \item wxTraceMessages: trace window messages/X callbacks | |
2001 | \item wxTraceResAlloc: trace GDI resource allocation | |
2002 | \item wxTraceRefCount: trace various ref counting operations | |
2003 | \end{itemize} | |
2004 | ||
2005 | \section{Debugging macros and functions}\label{debugmacros} | |
2006 | ||
2007 | Useful macros and functins for error checking and defensive programming. ASSERTs are only | |
2008 | compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release | |
2009 | builds. | |
2010 | ||
954b8ae6 JS |
2011 | \wxheading{Include files} |
2012 | ||
2013 | <wx/debug.h> | |
2014 | ||
6fb26ea3 JS |
2015 | \membersection{::wxOnAssert}\label{wxonassert} |
2016 | ||
2017 | \func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}} | |
2018 | ||
2019 | This function may be redefined to do something non trivial and is called | |
2020 | whenever one of debugging macros fails (i.e. condition is false in an | |
5b6aa0ff JS |
2021 | assertion). |
2022 | % TODO: this should probably be an overridable in wxApp. | |
6fb26ea3 JS |
2023 | |
2024 | \membersection{wxASSERT}\label{wxassert} | |
2025 | ||
2026 | \func{}{wxASSERT}{\param{}{condition}} | |
2027 | ||
2028 | Assert macro. An error message will be generated if the condition is FALSE. | |
2029 | ||
2030 | \membersection{wxASSERT\_MSG}\label{wxassertmsg} | |
2031 | ||
2032 | \func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} | |
2033 | ||
2034 | Assert macro with message. An error message will be generated if the condition is FALSE. | |
2035 | ||
2036 | \membersection{wxFAIL}\label{wxfail} | |
2037 | ||
2038 | \func{}{wxFAIL}{\param{}{condition}} | |
2039 | ||
2040 | Will always generate an assert error if this code is reached (in debug mode). | |
2041 | ||
2042 | \membersection{wxFAIL\_MSG}\label{wxfailmsg} | |
2043 | ||
2044 | \func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}} | |
2045 | ||
2046 | Will always generate an assert error with specified message if this code is reached (in debug mode). | |
2047 | ||
2048 | \membersection{wxCHECK}\label{wxcheck} | |
2049 | ||
2050 | \func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} | |
2051 | ||
2052 | Checks that the condition is true, returns with the given return value if not (FAILs in debug mode). | |
2053 | This check is done even in release mode. | |
2054 | ||
2055 | \membersection{wxCHECK\_MSG}\label{wxcheckmsg} | |
2056 | ||
2057 | \func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}} | |
2058 | ||
2059 | Checks that the condition is true, returns with the given return value if not (FAILs in debug mode). | |
2060 | This check is done even in release mode. | |
2061 |