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