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