1 \chapter{Functions
}\label{functions
}
2 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
3 \setfooter{\thepage}{}{}{}{}{\thepage}
5 The functions defined in wxWindows are described here.
7 \section{File functions
}\label{filefunctions
}
9 \wxheading{Include files
}
15 \helpref{wxPathList
}{wxpathlist
},
\helpref{wxDir
}{wxdir
},
\helpref{wxFile
}{wxfile
}
17 \membersection{::wxDirExists
}
19 \func{bool
}{wxDirExists
}{\param{const wxString\&
}{dirname
}}
21 Returns TRUE if the directory exists.
23 \membersection{::wxDos2UnixFilename
}
25 \func{void
}{Dos2UnixFilename
}{\param{const wxString\&
}{s
}}
27 Converts a DOS to a Unix filename by replacing backslashes with forward
30 \membersection{::wxFileExists
}
32 \func{bool
}{wxFileExists
}{\param{const wxString\&
}{filename
}}
34 Returns TRUE if the file exists. It also returns TRUE if the file is
37 \membersection{::wxFileNameFromPath
}
39 \func{wxString
}{wxFileNameFromPath
}{\param{const wxString\&
}{path
}}
41 \func{char*
}{wxFileNameFromPath
}{\param{char*
}{path
}}
43 Returns the filename for a full path. The second form returns a pointer to
44 temporary storage that should not be deallocated.
46 \membersection{::wxFindFirstFile
}\label{wxfindfirstfile
}
48 \func{wxString
}{wxFindFirstFile
}{\param{const char*
}{spec
},
\param{int
}{ flags =
0}}
50 This function does directory searching; returns the first file
51 that matches the path
{\it spec
}, or the empty string. Use
\helpref{wxFindNextFile
}{wxfindnextfile
} to
52 get the next matching file. Neither will
report the current directory "." or the
53 parent directory "..".
55 {\it spec
} may contain wildcards.
57 {\it flags
} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
62 wxString f = wxFindFirstFile("/home/project/*.*");
63 while ( !f.IsEmpty() )
70 \membersection{::wxFindNextFile
}\label{wxfindnextfile
}
72 \func{wxString
}{wxFindNextFile
}{\void}
74 Returns the next file that matches the path passed to
\helpref{wxFindFirstFile
}{wxfindfirstfile
}.
76 See
\helpref{wxFindFirstFile
}{wxfindfirstfile
} for an example.
78 \membersection{::wxGetOSDirectory
}\label{wxgetosdirectory
}
80 \func{wxString
}{wxGetOSDirectory
}{\void}
82 Returns the Windows directory under Windows; on other platforms returns the empty string.
84 \membersection{::wxInitAllImageHandlers
}\label{wxinitallimagehandlers
}
86 \func{void
}{wxInitAllImageHandlers
}{\void}
88 Adds some common image format handlers, which, depending on wxWindows
89 configuration, can be handlers for BMP (loading) (always installed), GIF
90 (loading), PCX (loading), PNM (loading and saving as raw
91 rgb), PNG (loading and saving), JPEG (loading and saving), file formats.
93 See also:
\helpref{wxImage
}{wximage
} \helpref{wxImageHandler
}{wximagehandler
}
95 \membersection{::wxIsAbsolutePath
}
97 \func{bool
}{wxIsAbsolutePath
}{\param{const wxString\&
}{filename
}}
99 Returns TRUE if the argument is an absolute filename, i.e. with a slash
100 or drive name at the beginning.
102 \membersection{::wxPathOnly
}
104 \func{wxString
}{wxPathOnly
}{\param{const wxString\&
}{path
}}
106 Returns the directory part of the filename.
108 \membersection{::wxUnix2DosFilename
}
110 \func{void
}{wxUnix2DosFilename
}{\param{const wxString\&
}{s
}}
112 Converts a Unix to a DOS filename by replacing forward
113 slashes with backslashes.
115 \membersection{::wxConcatFiles
}
117 \func{bool
}{wxConcatFiles
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
},
118 \param{const wxString\&
}{file3
}}
120 Concatenates
{\it file1
} and
{\it file2
} to
{\it file3
}, returning
123 \membersection{::wxCopyFile
}
125 \func{bool
}{wxCopyFile
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
}}
127 Copies
{\it file1
} to
{\it file2
}, returning TRUE if successful.
129 \membersection{::wxGetCwd
}\label{wxgetcwd
}
131 \func{wxString
}{wxGetCwd
}{\void}
133 Returns a string containing the current (or working) directory.
135 \membersection{::wxGetWorkingDirectory
}
137 \func{wxString
}{wxGetWorkingDirectory
}{\param{char*
}{buf=NULL
},
\param{int
}{sz=
1000}}
139 This function is obsolete: use
\helpref{wxGetCwd
}{wxgetcwd
} instead.
141 Copies the current working directory into the buffer if supplied, or
142 copies the working directory into new storage (which you must delete yourself)
143 if the buffer is NULL.
145 {\it sz
} is the size of the buffer if supplied.
147 \membersection{::wxGetTempFileName
}
149 \func{char*
}{wxGetTempFileName
}{\param{const wxString\&
}{prefix
},
\param{char*
}{buf=NULL
}}
151 \func{bool
}{wxGetTempFileName
}{\param{const wxString\&
}{prefix
},
\param{wxString\&
}{buf
}}
153 Makes a temporary filename based on
{\it prefix
}, opens and closes the file,
154 and places the name in
{\it buf
}. If
{\it buf
} is NULL, new store
155 is allocated for the temporary filename using
{\it new
}.
157 Under Windows, the filename will include the drive and name of the
158 directory allocated for temporary files (usually the contents of the
159 TEMP variable). Under Unix, the
{\tt /tmp
} directory is used.
161 It is the application's responsibility to create and delete the file.
163 \membersection{::wxIsWild
}\label{wxiswild
}
165 \func{bool
}{wxIsWild
}{\param{const wxString\&
}{pattern
}}
167 Returns TRUE if the pattern contains wildcards. See
\helpref{wxMatchWild
}{wxmatchwild
}.
169 \membersection{::wxMatchWild
}\label{wxmatchwild
}
171 \func{bool
}{wxMatchWild
}{\param{const wxString\&
}{pattern
},
\param{const wxString\&
}{text
},
\param{bool
}{ dot
\_special}}
173 Returns TRUE if the
{\it pattern
}\/ matches the
{\it text
}\/; if
{\it
174 dot
\_special}\/ is TRUE, filenames beginning with a dot are not matched
175 with wildcard characters. See
\helpref{wxIsWild
}{wxiswild
}.
177 \membersection{::wxMkdir
}
179 \func{bool
}{wxMkdir
}{\param{const wxString\&
}{dir
},
\param{int
}{perm =
0777}}
181 Makes the directory
{\it dir
}, returning TRUE if successful.
183 {\it perm
} is the access mask for the directory for the systems on which it is
184 supported (Unix) and doesn't have effect for the other ones.
186 \membersection{::wxRemoveFile
}
188 \func{bool
}{wxRemoveFile
}{\param{const wxString\&
}{file
}}
190 Removes
{\it file
}, returning TRUE if successful.
192 \membersection{::wxRenameFile
}
194 \func{bool
}{wxRenameFile
}{\param{const wxString\&
}{file1
},
\param{const wxString\&
}{file2
}}
196 Renames
{\it file1
} to
{\it file2
}, returning TRUE if successful.
198 \membersection{::wxRmdir
}
200 \func{bool
}{wxRmdir
}{\param{const wxString\&
}{dir
},
\param{int
}{ flags=
0}}
202 Removes the directory
{\it dir
}, returning TRUE if successful. Does not work under VMS.
204 The
{\it flags
} parameter is reserved for future use.
206 \membersection{::wxSetWorkingDirectory
}
208 \func{bool
}{wxSetWorkingDirectory
}{\param{const wxString\&
}{dir
}}
210 Sets the current working directory, returning TRUE if the operation succeeded.
211 Under MS Windows, the current drive is also changed if
{\it dir
} contains a drive specification.
213 \membersection{::wxSplitPath
}\label{wxsplitfunction
}
215 \func{void
}{wxSplitPath
}{\param{const char *
}{ fullname
},
\param{const wxString *
}{ path
},
\param{const wxString *
}{ name
},
\param{const wxString *
}{ ext
}}
217 This function splits a full file name into components: the path (including possible disk/drive
218 specification under Windows), the base name and the extension. Any of the output parameters
219 (
{\it path
},
{\it name
} or
{\it ext
}) may be NULL if you are not interested in the value of
220 a particular component.
222 wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
223 Windows, however it will not consider backslashes as path separators under Unix (where backslash
224 is a valid character in a filename).
226 On entry,
{\it fullname
} should be non NULL (it may be empty though).
228 On return,
{\it path
} contains the file path (without the trailing separator),
{\it name
}
229 contains the file name and
{\it ext
} contains the file extension without leading dot. All
230 three of them may be empty if the corresponding component is. The old contents of the
231 strings pointed to by these parameters will be overwritten in any case (if the pointers
234 \membersection{::wxTransferFileToStream
}\label{wxtransferfiletostream
}
236 \func{bool
}{wxTransferFileToStream
}{\param{const wxString\&
}{filename
},
\param{ostream\&
}{stream
}}
238 Copies the given file to
{\it stream
}. Useful when converting an old application to
239 use streams (within the
document/view framework, for example).
241 Use of this function requires the file wx
\_doc.h to be included.
243 \membersection{::wxTransferStreamToFile
}\label{wxtransferstreamtofile
}
245 \func{bool
}{wxTransferStreamToFile
}{\param{istream\&
}{stream
} \param{const wxString\&
}{filename
}}
247 Copies the given stream to the file
{\it filename
}. Useful when converting an old application to
248 use streams (within the
document/view framework, for example).
250 Use of this function requires the file wx
\_doc.h to be included.
252 \section{Network functions
}\label{networkfunctions
}
254 \membersection{::wxGetFullHostName
}\label{wxgetfullhostname
}
256 \func{wxString
}{wxGetFullHostName
}{\void}
258 Returns the FQDN (fully qualified domain host name) or an empty string on
261 See also:
\helpref{wxGetHostName
}{wxgethostname
}
263 \wxheading{Include files
}
267 \membersection{::wxGetEmailAddress
}\label{wxgetemailaddress
}
269 \func{bool
}{wxGetEmailAddress
}{\param{const wxString\&
}{buf
},
\param{int
}{sz
}}
271 Copies the user's email address into the supplied buffer, by
272 concatenating the values returned by
\helpref{wxGetFullHostName
}{wxgetfullhostname
}\rtfsp
273 and
\helpref{wxGetUserId
}{wxgetuserid
}.
275 Returns TRUE if successful, FALSE otherwise.
277 \wxheading{Include files
}
281 \membersection{::wxGetHostName
}\label{wxgethostname
}
283 \func{wxString
}{wxGetHostName
}{\void}
285 \func{bool
}{wxGetHostName
}{\param{char *
}{buf
},
\param{int
}{sz
}}
287 Copies the current host machine's name into the supplied buffer. Please note
288 that the returned name is
{\it not
} fully qualified, i.e. it does not include
291 Under Windows or NT, this function first looks in the environment
292 variable SYSTEM
\_NAME; if this is not found, the entry
{\bf HostName
}\rtfsp
293 in the
{\bf wxWindows
} section of the WIN.INI file is tried.
295 The first variant of this function returns the hostname if successful or an
296 empty string otherwise. The second (deprecated) function returns TRUE
297 if successful, FALSE otherwise.
299 See also:
\helpref{wxGetFullHostName
}{wxgetfullhostname
}
301 \wxheading{Include files
}
305 \section{User identification
}\label{useridfunctions
}
307 \membersection{::wxGetUserId
}\label{wxgetuserid
}
309 \func{wxString
}{wxGetUserId
}{\void}
311 \func{bool
}{wxGetUserId
}{\param{char *
}{buf
},
\param{int
}{sz
}}
313 This function returns the "user id" also known as "login name" under Unix i.e.
314 something like "jsmith". It uniquely identifies the current user (on this system).
316 Under Windows or NT, this function first looks in the environment
317 variables USER and LOGNAME; if neither of these is found, the entry
{\bf UserId
}\rtfsp
318 in the
{\bf wxWindows
} section of the WIN.INI file is tried.
320 The first variant of this function returns the login name if successful or an
321 empty string otherwise. The second (deprecated) function returns TRUE
322 if successful, FALSE otherwise.
324 See also:
\helpref{wxGetUserName
}{wxgetusername
}
326 \wxheading{Include files
}
330 \membersection{::wxGetUserName
}\label{wxgetusername
}
332 \func{wxString
}{wxGetUserName
}{\void}
334 \func{bool
}{wxGetUserName
}{\param{char *
}{buf
},
\param{int
}{sz
}}
336 This function returns the full user name (something like "Mr. John Smith").
338 Under Windows or NT, this function looks for the entry
{\bf UserName
}\rtfsp
339 in the
{\bf wxWindows
} section of the WIN.INI file. If PenWindows
340 is running, the entry
{\bf Current
} in the section
{\bf User
} of
341 the PENWIN.INI file is used.
343 The first variant of this function returns the user name if successful or an
344 empty string otherwise. The second (deprecated) function returns TRUE
345 if successful, FALSE otherwise.
347 See also:
\helpref{wxGetUserId
}{wxgetuserid
}
349 \wxheading{Include files
}
353 \section{String functions
}
355 \membersection{::copystring
}
357 \func{char*
}{copystring
}{\param{const char*
}{s
}}
359 Makes a copy of the string
{\it s
} using the C++ new operator, so it can be
360 deleted with the
{\it delete
} operator.
362 \membersection{::wxStringMatch
}
364 \func{bool
}{wxStringMatch
}{\param{const wxString\&
}{s1
},
\param{const wxString\&
}{s2
},\\
365 \param{bool
}{ subString = TRUE
},
\param{bool
}{ exact = FALSE
}}
367 Returns TRUE if the substring
{\it s1
} is found within
{\it s2
},
368 ignoring case if
{\it exact
} is FALSE. If
{\it subString
} is FALSE,
369 no substring matching is done.
371 \membersection{::wxStringEq
}\label{wxstringeq
}
373 \func{bool
}{wxStringEq
}{\param{const wxString\&
}{s1
},
\param{const wxString\&
}{s2
}}
378 #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) ==
0))
381 \membersection{::IsEmpty
}\label{isempty
}
383 \func{bool
}{IsEmpty
}{\param{const char *
}{ p
}}
385 Returns TRUE if the string is empty, FALSE otherwise. It is safe to pass NULL
386 pointer to this function and it will return TRUE for it.
388 \membersection{::Stricmp
}\label{stricmp
}
390 \func{int
}{Stricmp
}{\param{const char *
}{p1
},
\param{const char *
}{p2
}}
392 Returns a negative value,
0, or positive value if
{\it p1
} is less than, equal
393 to or greater than
{\it p2
}. The comparison is case-insensitive.
395 This function complements the standard C function
{\it strcmp()
} which performs
396 case-sensitive comparison.
398 \membersection{::Strlen
}\label{strlen
}
400 \func{size
\_t}{Strlen
}{\param{const char *
}{ p
}}
402 This is a safe version of standard function
{\it strlen()
}: it does exactly the
403 same thing (i.e. returns the length of the string) except that it returns
0 if
404 {\it p
} is the NULL pointer.
406 \membersection{::wxGetTranslation
}\label{wxgettranslation
}
408 \func{const char *
}{wxGetTranslation
}{\param{const char *
}{str
}}
410 This function returns the translation of string
{\it str
} in the current
411 \helpref{locale
}{wxlocale
}. If the string is not found in any of the loaded
412 message catalogs (see
\helpref{i18n overview
}{internationalization
}), the
413 original string is returned. In debug build, an error message is logged - this
414 should help to find the strings which were not yet translated. As this function
415 is used very often, an alternative syntax is provided: the
\_() macro is
416 defined as wxGetTranslation().
418 \membersection{::wxSnprintf
}\label{wxsnprintf
}
420 \func{int
}{wxSnprintf
}{\param{wxChar *
}{buf
},
\param{size
\_t }{len
},
\param{const wxChar *
}{format
},
\param{}{...
}}
422 This function replaces the dangerous standard function
{\tt sprintf()
} and is
423 like
{\tt snprintf()
} available on some platforms. The only difference with
424 sprintf() is that an additional argument - buffer size - is taken and the
425 buffer is never overflowed.
427 Returns the number of characters copied to the buffer or -
1 if there is not
430 \wxheading{See also:
}
431 \helpref{wxVsnprintf
}{wxvsnprintf
},
432 \helpref{wxString::Printf
}{wxstringprintf
}
434 \membersection{::wxVsnprintf
}\label{wxsnprintf
}
436 \func{int
}{wxVsnprintf
}{\param{wxChar *
}{buf
},
\param{size
\_t }{len
},
\param{const wxChar *
}{format
},
\param{va
\_list }{argptr
}}
438 The same as
\helpref{wxSnprintf
}{wxsnprintf
} but takes a
{\tt va
\_list}
439 argument instead of arbitrary number of parameters.
441 \wxheading{See also:
}
442 \helpref{wxSnprintf
}{wxsnprintf
},
443 \helpref{wxString::PrintfV
}{wxstringprintfv
}
445 \section{Dialog functions
}\label{dialogfunctions
}
447 Below are a number of convenience functions for getting input from the
448 user or displaying messages. Note that in these functions the last three
449 parameters are optional. However, it is recommended to pass a parent frame
450 parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
451 the front when the dialog box is popped up.
453 \membersection{::wxCreateFileTipProvider
}\label{wxcreatefiletipprovider
}
455 \func{wxTipProvider *
}{wxCreateFileTipProvider
}{\param{const wxString\&
}{filename
},
456 \param{size
\_t }{currentTip
}}
458 This function creates a
\helpref{wxTipProvider
}{wxtipprovider
} which may be
459 used with
\helpref{wxShowTip
}{wxshowtip
}.
461 \docparam{filename
}{The name of the file containing the tips, one per line
}
462 \docparam{currentTip
}{The index of the first tip to show - normally this index
463 is remembered between the
2 program runs.
}
465 \wxheading{See also:
}
467 \helpref{Tips overview
}{tipsoverview
}
469 \wxheading{Include files
}
473 \membersection{::wxFileSelector
}\label{wxfileselector
}
475 \func{wxString
}{wxFileSelector
}{\param{const wxString\&
}{message
},
\param{const wxString\&
}{default
\_path = ""
},\\
476 \param{const wxString\&
}{default
\_filename = ""
},
\param{const wxString\&
}{default
\_extension = ""
},\\
477 \param{const wxString\&
}{wildcard = ``*.*''
},
\param{int
}{flags =
0},
\param{wxWindow *
}{parent = ""
},\\
478 \param{int
}{ x = -
1},
\param{int
}{ y = -
1}}
480 Pops up a file selector box. In Windows, this is the common file selector
481 dialog. In X, this is a file selector box with somewhat less functionality.
482 The path and filename are distinct elements of a full file pathname.
483 If path is empty, the current directory will be used. If filename is empty,
484 no default filename will be supplied. The wildcard determines what files
485 are displayed in the file selector, and file extension supplies a type
486 extension for the required filename. Flags may be a combination of wxOPEN,
487 wxSAVE, wxOVERWRITE
\_PROMPT, wxHIDE
\_READONLY, wxMULTIPLE or
0.
489 Both the Unix and Windows versions implement a wildcard filter. Typing a
490 filename containing wildcards
(*, ?) in the filename text item, and
491 clicking on Ok, will result in only those files matching the pattern being
494 The wildcard may be a specification for multiple types of file
495 with a description for each, such as:
498 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
501 The application must check for an empty return value (the user pressed
502 Cancel). For example:
505 const wxString& s = wxFileSelector("Choose a file to open");
512 \wxheading{Include files}
516 \membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
518 \func{long}{wxGetNumberFromUser}{
519 \param{const wxString\& }{message},
520 \param{const wxString\& }{prompt},
521 \param{const wxString\& }{caption},
522 \param{long }{value},
523 \param{long }{min = 0},
524 \param{long }{max = 100},
525 \param{wxWindow *}{parent = NULL},
526 \param{const wxPoint\& }{pos = wxDefaultPosition}}
528 Shows a dialog asking the user for numeric input. The dialogs title is set to
529 {\it caption}, it contains a (possibly) multiline {\it message} above the
530 single line {\it prompt} and the zone for entering the number.
532 The number entered must be in the range {\it min}..{\it max} (both of which
533 should be positive) and {\it value} is the initial value of it. If the user
534 enters an invalid value or cancels the dialog, the function will return -1.
536 Dialog is centered on its {\it parent} unless an explicit position is given in
539 \wxheading{Include files}
543 \membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
545 \func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
546 \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
547 \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = TRUE}}
549 Pop up a dialog box with title set to {\it caption}, message {\it message}, and a
550 \rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
551 or press Cancel to return the empty string.
553 If {\it centre} is TRUE, the message text (which may include new line characters)
554 is centred; if FALSE, the message is left-justified.
556 \wxheading{Include files}
560 \membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
562 \func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
563 \param{int }{nsel}, \param{int *}{selection},
564 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
565 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
567 Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
568 listbox. The user may choose one or more item(s) and press OK or Cancel.
570 The number of initially selected choices, and array of the selected indices,
571 are passed in; this array will contain the user selections on exit, with
572 the function returning the number of selections. {\it selection} must be
573 as big as the number of choices, in case all are selected.
575 If Cancel is pressed, -1 is returned.
577 {\it choices} is an array of {\it n} strings for the listbox.
579 If {\it centre} is TRUE, the message text (which may include new line characters)
580 is centred; if FALSE, the message is left-justified.
582 \wxheading{Include files}
586 \membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
588 \func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
589 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
590 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
592 Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection
593 listbox. The user may choose an item and press OK to return a string or
594 Cancel to return the empty string.
596 {\it choices} is an array of {\it n} strings for the listbox.
598 If {\it centre} is TRUE, the message text (which may include new line characters)
599 is centred; if FALSE, the message is left-justified.
601 \wxheading{Include files}
605 \membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
607 \func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
608 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
609 \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
611 As {\bf wxGetSingleChoice} but returns the index representing the selected string.
612 If the user pressed cancel, -1 is returned.
614 \wxheading{Include files}
618 \membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
620 \func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
621 \param{const wxString\& }{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\
622 \param{int}{ y = -1}, \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
624 As {\bf wxGetSingleChoice} but takes an array of client data pointers
625 corresponding to the strings, and returns one of these pointers.
627 \wxheading{Include files}
631 \membersection{::wxMessageBox}\label{wxmessagebox}
633 \func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
634 \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
636 General purpose message dialog. {\it style} may be a bit list of the
637 following identifiers:
639 \begin{twocollist}\itemsep=0pt
640 \twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
642 \twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
644 \twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
645 \twocolitem{wxCENTRE}{Centres the text.}
646 \twocolitem{wxICON\_EXCLAMATION}{Under Windows, displays an exclamation mark symbol.}
647 \twocolitem{wxICON\_HAND}{Under Windows, displays a hand symbol.}
648 \twocolitem{wxICON\_QUESTION}{Under Windows, displays a question mark symbol.}
649 \twocolitem{wxICON\_INFORMATION}{Under Windows, displays an information symbol.}
652 The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
658 int answer = wxMessageBox("Quit program?", "Confirm",
659 wxYES_NO | wxCANCEL, main_frame);
665 {\it message} may contain newline characters, in which case the
666 message will be split into separate lines, to cater for large messages.
668 Under Windows, the native MessageBox function is used unless wxCENTRE
669 is specified in the style, in which case a generic function is used.
670 This is because the native MessageBox function cannot centre text.
671 The symbols are not shown when the generic function is used.
673 \wxheading{Include files}
677 \membersection{::wxShowTip}\label{wxshowtip}
679 \func{bool}{wxShowTip}{\param{wxWindow *}{parent},
680 \param{wxTipProvider *}{tipProvider},
681 \param{bool }{showAtStartup = TRUE}}
683 This function shows a "startup tip" to the user.
685 \docparam{parent}{The parent window for the modal dialog}
687 \docparam{tipProvider}{An object which is used to get the text of the tips.
688 It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
690 \docparam{showAtStartup}{Should be TRUE if startup tips are shown, FALSE
691 otherwise. This is used as the initial value for "Show tips at startup"
692 checkbox which is shown in the tips dialog.}
694 \wxheading{See also:}
696 \helpref{Tips overview}{tipsoverview}
698 \wxheading{Include files}
702 \section{GDI functions}\label{gdifunctions}
704 The following are relevant to the GDI (Graphics Device Interface).
706 \wxheading{Include files}
710 \membersection{::wxColourDisplay}
712 \func{bool}{wxColourDisplay}{\void}
714 Returns TRUE if the display is colour, FALSE otherwise.
716 \membersection{::wxDisplayDepth}
718 \func{int}{wxDisplayDepth}{\void}
720 Returns the depth of the display (a value of 1 denotes a monochrome display).
722 \membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
724 \func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
725 \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
727 Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
728 makes it into a placeable metafile by prepending a header containing the given
729 bounding box. The bounding box may be obtained from a device context after drawing
730 into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
732 In addition to adding the placeable metafile header, this function adds
733 the equivalent of the following code to the start of the metafile data:
736 SetMapMode(dc, MM_ANISOTROPIC);
737 SetWindowOrg(dc, minX, minY);
738 SetWindowExt(dc, maxX - minX, maxY - minY);
741 This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
743 Placeable metafiles may be imported by many Windows applications, and can be
744 used in RTF (Rich Text Format) files.
746 {\it scale} allows the specification of scale for the metafile.
748 This function is only available under Windows.
750 \membersection{::wxSetCursor}\label{wxsetcursor}
752 \func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
754 Globally sets the cursor; only has an effect in Windows and GTK.
755 See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
757 \section{Printer settings}\label{printersettings}
759 These routines are obsolete and should no longer be used!
761 The following functions are used to control PostScript printing. Under
762 Windows, PostScript output can only be sent to a file.
764 \wxheading{Include files}
768 \membersection{::wxGetPrinterCommand}
770 \func{wxString}{wxGetPrinterCommand}{\void}
772 Gets the printer command used to print a file. The default is {\tt lpr}.
774 \membersection{::wxGetPrinterFile}
776 \func{wxString}{wxGetPrinterFile}{\void}
778 Gets the PostScript output filename.
780 \membersection{::wxGetPrinterMode}
782 \func{int}{wxGetPrinterMode}{\void}
784 Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
785 The default is PS\_PREVIEW.
787 \membersection{::wxGetPrinterOptions}
789 \func{wxString}{wxGetPrinterOptions}{\void}
791 Gets the additional options for the print command (e.g. specific printer). The default is nothing.
793 \membersection{::wxGetPrinterOrientation}
795 \func{int}{wxGetPrinterOrientation}{\void}
797 Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
799 \membersection{::wxGetPrinterPreviewCommand}
801 \func{wxString}{wxGetPrinterPreviewCommand}{\void}
803 Gets the command used to view a PostScript file. The default depends on the platform.
805 \membersection{::wxGetPrinterScaling}
807 \func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
809 Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
811 \membersection{::wxGetPrinterTranslation}
813 \func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
815 Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
817 \membersection{::wxSetPrinterCommand}
819 \func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
821 Sets the printer command used to print a file. The default is {\tt lpr}.
823 \membersection{::wxSetPrinterFile}
825 \func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
827 Sets the PostScript output filename.
829 \membersection{::wxSetPrinterMode}
831 \func{void}{wxSetPrinterMode}{\param{int }{mode}}
833 Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
834 The default is PS\_PREVIEW.
836 \membersection{::wxSetPrinterOptions}
838 \func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
840 Sets the additional options for the print command (e.g. specific printer). The default is nothing.
842 \membersection{::wxSetPrinterOrientation}
844 \func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
846 Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
848 \membersection{::wxSetPrinterPreviewCommand}
850 \func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
852 Sets the command used to view a PostScript file. The default depends on the platform.
854 \membersection{::wxSetPrinterScaling}
856 \func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
858 Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
860 \membersection{::wxSetPrinterTranslation}
862 \func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
864 Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
866 \section{Clipboard functions}\label{clipsboard}
868 These clipboard functions are implemented for Windows only. The use of these functions
869 is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard}
872 \wxheading{Include files}
876 \membersection{::wxClipboardOpen}
878 \func{bool}{wxClipboardOpen}{\void}
880 Returns TRUE if this application has already opened the clipboard.
882 \membersection{::wxCloseClipboard}
884 \func{bool}{wxCloseClipboard}{\void}
886 Closes the clipboard to allow other applications to use it.
888 \membersection{::wxEmptyClipboard}
890 \func{bool}{wxEmptyClipboard}{\void}
892 Empties the clipboard.
894 \membersection{::wxEnumClipboardFormats}
896 \func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
898 Enumerates the formats found in a list of available formats that belong
899 to the clipboard. Each call to this function specifies a known
900 available format; the function returns the format that appears next in
903 {\it dataFormat} specifies a known format. If this parameter is zero,
904 the function returns the first format in the list.
906 The return value specifies the next known clipboard data format if the
907 function is successful. It is zero if the {\it dataFormat} parameter specifies
908 the last format in the list of available formats, or if the clipboard
911 Before it enumerates the formats function, an application must open the clipboard by using the
912 wxOpenClipboard function.
914 \membersection{::wxGetClipboardData}
916 \func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
918 Gets data from the clipboard.
920 {\it dataFormat} may be one of:
922 \begin{itemize}\itemsep=0pt
923 \item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
924 \item wxCF\_BITMAP: returns a new wxBitmap.
927 The clipboard must have previously been opened for this call to succeed.
929 \membersection{::wxGetClipboardFormatName}
931 \func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
933 Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
934 length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
936 \membersection{::wxIsClipboardFormatAvailable}
938 \func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
940 Returns TRUE if the given data format is available on the clipboard.
942 \membersection{::wxOpenClipboard}
944 \func{bool}{wxOpenClipboard}{\void}
946 Opens the clipboard for passing data to it or getting data from it.
948 \membersection{::wxRegisterClipboardFormat}
950 \func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
952 Registers the clipboard data format name and returns an identifier.
954 \membersection{::wxSetClipboardData}
956 \func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
958 Passes data to the clipboard.
960 {\it dataFormat} may be one of:
962 \begin{itemize}\itemsep=0pt
963 \item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
964 \item wxCF\_BITMAP: {\it data} is a wxBitmap.
965 \item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
966 \item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
969 The clipboard must have previously been opened for this call to succeed.
971 \section{Miscellaneous functions}\label{miscellany}
973 \membersection{::wxNewId}
975 \func{long}{wxNewId}{\void}
977 Generates an integer identifier unique to this run of the program.
979 \wxheading{Include files}
983 \membersection{::wxRegisterId}
985 \func{void}{wxRegisterId}{\param{long}{ id}}
987 Ensures that ids subsequently generated by {\bf NewId} do not clash with
990 \wxheading{Include files}
994 \membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
996 \func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
998 Changes the cursor to the given cursor for all windows in the application.
999 Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
1000 to its previous state. These two calls can be nested, and a counter
1001 ensures that only the outer calls take effect.
1003 See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
1005 \wxheading{Include files}
1009 \membersection{::wxBell}
1011 \func{void}{wxBell}{\void}
1013 Ring the system bell.
1015 \wxheading{Include files}
1019 \membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
1021 \func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
1023 Creates and returns an object of the given class, if the class has been
1024 registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
1026 \membersection{::wxDDECleanUp}\label{wxddecleanup}
1028 \func{void}{wxDDECleanUp}{\void}
1030 Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
1031 called by the application.
1033 See also helpref{wxDDEInitialize}{wxddeinitialize}.
1035 \wxheading{Include files}
1039 \membersection{::wxDDEInitialize}\label{wxddeinitialize}
1041 \func{void}{wxDDEInitialize}{\void}
1043 Initializes the DDE system. May be called multiple times without harm.
1045 This no longer needs to be called by the application: it will be called
1046 by wxWindows if necessary.
1048 See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
1049 \helpref{wxDDECleanUp}{wxddecleanup}.
1051 \wxheading{Include files}
1055 \membersection{::wxDebugMsg}\label{wxdebugmsg}
1057 \func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
1059 {\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogdebug} instead!}
1061 Display a debugging message; under Windows, this will appear on the
1062 debugger command window, and under Unix, it will be written to standard
1065 The syntax is identical to {\bf printf}: pass a format string and a
1066 variable list of arguments.
1068 {\bf Tip:} under Windows, if your application crashes before the
1069 message appears in the debugging window, put a wxYield call after
1070 each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
1071 (at least for Watcom C++): preformat your messages and use OutputDebugString
1074 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1076 \wxheading{Include files}
1080 \membersection{::wxDisplaySize}
1082 \func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
1084 Gets the physical size of the display in pixels.
1086 \wxheading{Include files}
1090 \membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
1092 \func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
1094 This function enables or disables all top level windows. It is used by
1095 \helpref{::wxSafeYield}{wxsafeyield}.
1097 \wxheading{Include files}
1101 \membersection{::wxEntry}\label{wxentry}
1103 This initializes wxWindows in a platform-dependent way. Use this if you
1104 are not using the default wxWindows entry code (e.g. main or WinMain). For example,
1105 you can initialize wxWindows from an Microsoft Foundation Classes application using
1108 \func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
1109 \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
1111 wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
1112 function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
1113 message loop will be entered.
1115 \func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
1116 \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
1118 wxWindows initialization under Windows (for applications constructed as a DLL).
1120 \func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
1122 wxWindows initialization under Unix.
1126 To clean up wxWindows, call wxApp::OnExit followed by the static function
1127 wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:
1130 int CTheApp::ExitInstance()
1132 // OnExit isn't called by CleanUp so must be called explicitly.
1136 return CWinApp::ExitInstance();
1140 \wxheading{Include files}
1144 \membersection{::wxEndBusyCursor}\label{wxendbusycursor}
1146 \func{void}{wxEndBusyCursor}{\void}
1148 Changes the cursor back to the original cursor, for all windows in the application.
1149 Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
1151 See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
1153 \wxheading{Include files}
1157 \membersection{::wxError}\label{wxerror}
1159 \func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
1161 Displays {\it msg} and continues. This writes to standard error under
1162 Unix, and pops up a message box under Windows. Used for internal
1163 wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
1165 \wxheading{Include files}
1169 \membersection{::wxExecute}\label{wxexecute}
1171 \func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
1173 \func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
1175 Executes another program in Unix or Windows.
1177 The first form takes a command string, such as {\tt "emacs file.txt"}.
1179 The second form takes an array of values: a command, any number of
1180 arguments, terminated by NULL.
1182 If {\it sync} is FALSE (the default), flow of control immediately returns.
1183 If TRUE, the current application waits until the other program has terminated.
1185 In the case of synchronous execution, the return value is the exit code of
1186 the process (which terminates by the moment the function returns) and will be
1187 $-1$ if the process couldn't be started and typically 0 if the process
1188 terminated successfully. Also, while waiting for the process to
1189 terminate, wxExecute will call \helpref{wxYield}{wxyield}. The caller
1190 should ensure that this can cause no recursion, in the simples case by
1191 calling \helpref{wxEnableTopLevelWindows(FALSE)}{wxenabletoplevelwindows}.
1193 For asynchronous execution, however, the return value is the process id and
1194 zero value indicates that the command could not be executed.
1196 If callback isn't NULL and if execution is asynchronous (note that callback
1197 parameter can not be non NULL for synchronous execution),
1198 \helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
1199 the process finishes.
1201 See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}.
1203 \wxheading{Include files}
1207 \membersection{::wxExit}\label{wxexit}
1209 \func{void}{wxExit}{\void}
1211 Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
1212 Should only be used in an emergency: normally the top-level frame
1213 should be deleted (after deleting all other frames) to terminate the
1214 application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
1216 \wxheading{Include files}
1220 \membersection{::wxFatalError}\label{wxfatalerror}
1222 \func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
1224 Displays {\it msg} and exits. This writes to standard error under Unix,
1225 and pops up a message box under Windows. Used for fatal internal
1226 wxWindows errors. See also \helpref{wxError}{wxerror}.
1228 \wxheading{Include files}
1232 \membersection{::wxFindMenuItemId}
1234 \func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
1236 Find a menu item identifier associated with the given frame's menu bar.
1238 \wxheading{Include files}
1242 \membersection{::wxFindWindowByLabel}
1244 \func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
1246 Find a window by its label. Depending on the type of window, the label may be a window title
1247 or panel item label. If {\it parent} is NULL, the search will start from all top-level
1248 frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1249 The search is recursive in both cases.
1251 \wxheading{Include files}
1255 \membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
1257 \func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
1259 Find a window by its name (as given in a window constructor or {\bf Create} function call).
1260 If {\it parent} is NULL, the search will start from all top-level
1261 frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
1262 The search is recursive in both cases.
1264 If no such named window is found, {\bf wxFindWindowByLabel} is called.
1266 \wxheading{Include files}
1270 \membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
1272 \func{wxWindow *}{wxGetActiveWindow}{\void}
1274 Gets the currently active window (Windows only).
1276 \wxheading{Include files}
1280 \membersection{::wxGetDisplayName}\label{wxgetdisplayname}
1282 \func{wxString}{wxGetDisplayName}{\void}
1284 Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
1286 \wxheading{Include files}
1290 \membersection{::wxGetHomeDir}\label{wxgethomedir}
1292 \func{wxString}{wxGetHomeDir}{\void}
1294 Return the (current) user's home directory.
1296 \wxheading{See also:}
1298 \helpref{wxGetUserHome}{wxgetuserhome}
1300 \wxheading{Include files}
1304 \membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
1306 \func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}}
1308 Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
1310 If {\it resetTimer} is TRUE (the default), the timer is reset to zero
1313 See also \helpref{wxTimer}{wxtimer}.
1315 \wxheading{Include files}
1319 \membersection{::wxGetFreeMemory}\label{wxgetfreememory}
1321 \func{long}{wxGetFreeMemory}{\void}
1323 Returns the amount of free memory in Kbytes under environments which
1324 support it, and -1 if not supported. Currently, returns a positive value
1325 under Windows, and -1 under Unix.
1327 \wxheading{Include files}
1331 \membersection{::wxGetMousePosition}
1333 \func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}}
1335 Returns the mouse position in screen coordinates.
1337 \wxheading{Include files}
1341 \membersection{::wxGetOsDescription}\label{wxgetosdescription}
1343 \func{wxString}{wxGetOsDescription}{\void}
1345 Returns the string containing the description of the current platform in a
1346 user-readable form. For example, this function may return strings like
1347 {\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}.
1349 \wxheading{See also}
1351 \helpref{::wxGetOsVersion}{wxgetosversion}
1353 \wxheading{Include files}
1357 \membersection{::wxGetOsVersion}\label{wxgetosversion}
1359 \func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
1361 Gets operating system version information.
1363 \begin{twocollist}\itemsep=0pt
1364 \twocolitemruled{Platform}{Return tyes}
1365 \twocolitem{Macintosh}{Return value is wxMACINTOSH.}
1366 \twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. }
1367 \twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
1368 \twocolitem{OS/2}{Return value is wxOS2\_PM.}
1369 \twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
1370 \twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}}
1371 \twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.}
1372 \twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.}
1373 \twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
1374 \twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
1377 \wxheading{See also}
1379 \helpref{::wxGetOsDescription}{wxgetosdescription}
1381 \wxheading{Include files}
1385 \membersection{::wxGetResource}\label{wxgetresource}
1387 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1388 \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
1390 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1391 \param{float *}{value}, \param{const wxString\& }{file = NULL}}
1393 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1394 \param{long *}{value}, \param{const wxString\& }{file = NULL}}
1396 \func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1397 \param{int *}{value}, \param{const wxString\& }{file = NULL}}
1399 Gets a resource value from the resource database (for example, WIN.INI, or
1400 .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1401 otherwise the specified file is used.
1403 Under X, if an application class (wxApp::GetClassName) has been defined,
1404 it is appended to the string /usr/lib/X11/app-defaults/ to try to find
1405 an applications default file when merging all resource databases.
1407 The reason for passing the result in an argument is that it
1408 can be convenient to define a default value, which gets overridden
1409 if the value exists in the resource file. It saves a separate
1410 test for that resource's existence, and it also allows
1411 the overloading of the function for different types.
1413 See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
1415 \wxheading{Include files}
1419 \membersection{::wxGetUserId}
1421 \func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1423 Copies the user's login identity (such as ``jacs'') into the buffer {\it
1424 buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1425 Under Windows, this returns ``user''.
1427 \wxheading{Include files}
1431 \membersection{::wxGetUserHome}\label{wxgetuserhome}
1433 \func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
1435 Returns the home directory for the given user. If the username is empty
1436 (default value), this function behaves like
1437 \helpref{wxGetHomeDir}{wxgethomedir}.
1439 \wxheading{Include files}
1443 \membersection{::wxGetUserName}
1445 \func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
1447 Copies the user's name (such as ``Julian Smart'') into the buffer {\it
1448 buf}, of maximum size {\it bufSize}, returning TRUE if successful.
1449 Under Windows, this returns ``unknown''.
1451 \wxheading{Include files}
1455 \membersection{::wxKill}\label{wxkill}
1457 \func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
1459 Under Unix (the only supported platform), equivalent to the Unix kill function.
1460 Returns 0 on success, -1 on failure.
1462 Tip: sending a signal of 0 to a process returns -1 if the process does not exist.
1463 It does not raise a signal in the receiving process.
1465 \wxheading{Include files}
1469 \membersection{::wxIsBusy}\label{wxisbusy}
1471 \func{bool}{wxIsBusy}{\void}
1473 Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
1474 \helpref{wxEndBusyCursor}{wxendbusycursor} calls.
1476 See also \helpref{wxBusyCursor}{wxbusycursor}.
1478 \wxheading{Include files}
1482 \membersection{::wxLoadUserResource}\label{wxloaduserresource}
1484 \func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
1486 Loads a user-defined Windows resource as a string. If the resource is found, the function creates
1487 a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
1489 The resource must be defined in the {\tt .rc} file using the following syntax:
1492 myResource TEXT file.ext
1495 where {\tt file.ext} is a file that the resource compiler can find.
1497 One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers
1498 cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed
1499 using \helpref{wxResourceParseString}{wxresourceparsestring}.
1501 This function is available under Windows only.
1503 \wxheading{Include files}
1507 \membersection{::wxNow}\label{wxnow}
1509 \func{wxString}{wxNow}{\void}
1511 Returns a string representing the current date and time.
1513 \wxheading{Include files}
1517 \membersection{::wxPostDelete}\label{wxpostdelete}
1519 \func{void}{wxPostDelete}{\param{wxObject *}{object}}
1521 Tells the system to delete the specified object when
1522 all other events have been processed. In some environments, it is
1523 necessary to use this instead of deleting a frame directly with the
1524 delete operator, because some GUIs will still send events to a deleted window.
1526 Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
1528 \wxheading{Include files}
1532 \membersection{::wxPostEvent}\label{wxpostevent}
1534 \func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
1536 This function posts the event to the specified {\it dest} object. The
1537 difference between sending an event and posting it is that in the first case
1538 the event is processed before the function returns (in wxWindows, event sending
1539 is done with \helpref{ProcessEvent}{wxevthandlerprocessevent} function), but in
1540 the second, the function returns immediately and the event will be processed
1541 sometime later - usually during the next even loop iteration.
1543 Note that a copy of the {\it event} is made by the function, so the original
1544 copy can be deleted as soon as function returns. This function can also be used
1545 to send events between different threads safely. As this function makes a
1546 copy of the event, the event needs to have a fully implemented Clone() method,
1547 which may not be the case for all event in wxWindows.
1549 See also \helpref{AddPendingEvent}{wxevthandleraddpendingevent} (which this function
1552 \wxheading{Include files}
1556 \membersection{::wxSafeYield}\label{wxsafeyield}
1558 \func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
1560 This function is similar to wxYield, except that it disables the user input to
1561 all program windows before calling wxYield and re-enables it again
1562 afterwards. If {\it win} is not NULL, this window will remain enabled,
1563 allowing the implementation of some limited user interaction.
1565 Returns the result of the call to \helpref{::wxYield}{wxyield}.
1567 \wxheading{Include files}
1571 \membersection{::wxSetDisplayName}\label{wxsetdisplayname}
1573 \func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
1575 Under X only, sets the current display name. This is the X host and display name such
1576 as ``colonsay:0.0", and the function indicates which display should be used for creating
1577 windows from this point on. Setting the display within an application allows multiple
1578 displays to be used.
1580 See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
1582 \wxheading{Include files}
1586 \membersection{::wxShell}\label{wxshell}
1588 \func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
1590 Executes a command in an interactive shell window. If no command is
1591 specified, then just the shell is spawned.
1593 See also \helpref{wxExecute}{wxexecute}.
1595 \wxheading{Include files}
1599 \membersection{::wxSleep}\label{wxsleep}
1601 \func{void}{wxSleep}{\param{int}{ secs}}
1603 Sleeps for the specified number of seconds.
1605 \wxheading{Include files}
1609 \membersection{::wxStripMenuCodes}
1611 \func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
1613 \func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}}
1615 Strips any menu codes from {\it in} and places the result
1616 in {\it out} (or returns the new string, in the first form).
1618 Menu codes include \& (mark the next character with an underline
1619 as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
1621 \wxheading{Include files}
1625 \membersection{::wxStartTimer}\label{wxstarttimer}
1627 \func{void}{wxStartTimer}{\void}
1629 Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
1631 See also \helpref{wxTimer}{wxtimer}.
1633 \wxheading{Include files}
1637 \membersection{::wxToLower}\label{wxtolower}
1639 \func{char}{wxToLower}{\param{char }{ch}}
1641 Converts the character to lower case. This is implemented as a macro for efficiency.
1643 \wxheading{Include files}
1647 \membersection{::wxToUpper}\label{wxtoupper}
1649 \func{char}{wxToUpper}{\param{char }{ch}}
1651 Converts the character to upper case. This is implemented as a macro for efficiency.
1653 \wxheading{Include files}
1657 \membersection{::wxTrace}\label{wxtrace}
1659 \func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
1661 Takes printf-style variable argument syntax. Output
1662 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1664 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1666 \wxheading{Include files}
1670 \membersection{::wxTraceLevel}\label{wxtracelevel}
1672 \func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
1674 Takes printf-style variable argument syntax. Output
1675 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
1676 The first argument should be the level at which this information is appropriate.
1677 It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
1680 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
1682 \wxheading{Include files}
1686 \membersection{::wxUsleep}\label{wxusleep}
1688 \func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
1690 Sleeps for the specified number of milliseconds. Notice that usage of this
1691 function is encouraged instead of calling usleep(3) directly because the
1692 standard usleep() function is not MT safe.
1694 \wxheading{Include files}
1698 \membersection{::wxWriteResource}\label{wxwriteresource}
1700 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1701 \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
1703 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1704 \param{float }{value}, \param{const wxString\& }{file = NULL}}
1706 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1707 \param{long }{value}, \param{const wxString\& }{file = NULL}}
1709 \func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
1710 \param{int }{value}, \param{const wxString\& }{file = NULL}}
1712 Writes a resource value into the resource database (for example, WIN.INI, or
1713 .Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
1714 otherwise the specified file is used.
1716 Under X, the resource databases are cached until the internal function
1717 \rtfsp{\bf wxFlushResources} is called automatically on exit, when
1718 all updated resource databases are written to their files.
1720 Note that it is considered bad manners to write to the .Xdefaults
1721 file under Unix, although the WIN.INI file is fair game under Windows.
1723 See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
1725 \wxheading{Include files}
1729 \membersection{::wxYield}\label{wxyield}
1731 \func{bool}{wxYield}{\void}
1733 Yields control to pending messages in the windowing system. This can be useful, for example, when a
1734 time-consuming process writes to a text window. Without an occasional
1735 yield, the text window will not be updated properly, and (since Windows
1736 multitasking is cooperative) other processes will not respond.
1738 Caution should be exercised, however, since yielding may allow the
1739 user to perform actions which are not compatible with the current task.
1740 Disabling menu items or whole menus during processing can avoid unwanted
1741 reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better
1744 \wxheading{Include files}
1746 <wx/app.h> or <wx/utils.h>
1748 \membersection{::wxWakeUpIdle}\label{wxwakeupidle}
1750 \func{void}{wxWakeUpIdle}{\void}
1752 This functions wakes up the (internal and platform dependent) idle system, i.e. it
1753 will force the system to send an idle event even if the system currently {\it is}
1754 idle and thus would not send any idle event until after some other event would get
1755 sent. This is also useful for sending events between two threads and is used by
1756 the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and
1757 \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
1759 \wxheading{Include files}
1763 \section{Macros}\label{macros}
1765 These macros are defined in wxWindows.
1767 \membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways}
1769 \func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}}
1771 \func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}}
1773 \func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}}
1775 \func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
1777 This macro will swap the bytes of the {\it value} variable from little
1778 endian to big endian or vice versa.
1780 \membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe}
1782 \func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}}
1784 \func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}}
1786 \func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}}
1788 \func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}}
1790 This macro will swap the bytes of the {\it value} variable from little
1791 endian to big endian or vice versa if the program is compiled on a
1792 big-endian architecture (such as Sun work stations). If the program has
1793 been compiled on a little-endian architecture, the value will be unchanged.
1795 Use these macros to read data from and write data to a file that stores
1796 data in little endian (Intel i386) format.
1798 \membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
1800 \func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}}
1802 \func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}}
1804 \func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}}
1806 \func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}}
1808 This macro will swap the bytes of the {\it value} variable from little
1809 endian to big endian or vice versa if the program is compiled on a
1810 little-endian architecture (such as Intel PCs). If the program has
1811 been compiled on a big-endian architecture, the value will be unchanged.
1813 Use these macros to read data from and write data to a file that stores
1814 data in big endian format.
1816 \membersection{CLASSINFO}\label{classinfo}
1818 \func{wxClassInfo *}{CLASSINFO}{className}
1820 Returns a pointer to the wxClassInfo object associated with this class.
1822 \wxheading{Include files}
1826 \membersection{DECLARE\_ABSTRACT\_CLASS}
1828 \func{}{DECLARE\_ABSTRACT\_CLASS}{className}
1830 Used inside a class declaration to declare that the class should be
1831 made known to the class hierarchy, but objects of this class cannot be created
1832 dynamically. The same as DECLARE\_CLASS.
1837 class wxCommand: public wxObject
1839 DECLARE_ABSTRACT_CLASS(wxCommand)
1848 \wxheading{Include files}
1852 \membersection{DECLARE\_APP}\label{declareapp}
1854 \func{}{DECLARE\_APP}{className}
1856 This is used in headers to create a forward declaration of the wxGetApp function implemented
1857 by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}.
1865 \wxheading{Include files}
1869 \membersection{DECLARE\_CLASS}
1871 \func{}{DECLARE\_CLASS}{className}
1873 Used inside a class declaration to declare that the class should be
1874 made known to the class hierarchy, but objects of this class cannot be created
1875 dynamically. The same as DECLARE\_ABSTRACT\_CLASS.
1877 \wxheading{Include files}
1881 \membersection{DECLARE\_DYNAMIC\_CLASS}
1883 \func{}{DECLARE\_DYNAMIC\_CLASS}{className}
1885 Used inside a class declaration to declare that the objects of this class should be dynamically
1886 createable from run-time type information.
1891 class wxFrame: public wxWindow
1893 DECLARE_DYNAMIC_CLASS(wxFrame)
1896 const wxString\& frameTitle;
1902 \wxheading{Include files}
1906 \membersection{IMPLEMENT\_ABSTRACT\_CLASS}
1908 \func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
1910 Used in a C++ implementation file to complete the declaration of
1911 a class that has run-time type information. The same as IMPLEMENT\_CLASS.
1916 IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
1918 wxCommand::wxCommand(void)
1924 \wxheading{Include files}
1928 \membersection{IMPLEMENT\_ABSTRACT\_CLASS2}
1930 \func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
1932 Used in a C++ implementation file to complete the declaration of
1933 a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
1935 \wxheading{Include files}
1939 \membersection{IMPLEMENT\_APP}\label{implementapp}
1941 \func{}{IMPLEMENT\_APP}{className}
1943 This is used in the application class implementation file to make the application class known to
1944 wxWindows for dynamic construction. You use this instead of
1955 IMPLEMENT_APP(MyApp)
1958 See also \helpref{DECLARE\_APP}{declareapp}.
1960 \wxheading{Include files}
1964 \membersection{IMPLEMENT\_CLASS}
1966 \func{}{IMPLEMENT\_CLASS}{className, baseClassName}
1968 Used in a C++ implementation file to complete the declaration of
1969 a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
1971 \wxheading{Include files}
1975 \membersection{IMPLEMENT\_CLASS2}
1977 \func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
1979 Used in a C++ implementation file to complete the declaration of a
1980 class that has run-time type information and two base classes. The
1981 same as IMPLEMENT\_ABSTRACT\_CLASS2.
1983 \wxheading{Include files}
1987 \membersection{IMPLEMENT\_DYNAMIC\_CLASS}
1989 \func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
1991 Used in a C++ implementation file to complete the declaration of
1992 a class that has run-time type information, and whose instances
1993 can be created dynamically.
1998 IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
2000 wxFrame::wxFrame(void)
2006 \wxheading{Include files}
2010 \membersection{IMPLEMENT\_DYNAMIC\_CLASS2}
2012 \func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
2014 Used in a C++ implementation file to complete the declaration of
2015 a class that has run-time type information, and whose instances
2016 can be created dynamically. Use this for classes derived from two
2019 \wxheading{Include files}
2023 \membersection{wxBITMAP}\label{wxbitmapmacro}
2025 \func{}{wxBITMAP}{bitmapName}
2027 This macro loads a bitmap from either application resources (on the platforms
2028 for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
2029 avoid using {\tt #ifdef}s when creating bitmaps.
2031 \wxheading{See also}
2033 \helpref{Bitmaps and icons overview}{wxbitmapoverview},
2034 \helpref{wxICON}{wxiconmacro}
2036 \wxheading{Include files}
2040 \membersection{WXDEBUG\_NEW}\label{debugnew}
2042 \func{}{WXDEBUG\_NEW}{arg}
2044 This is defined in debug mode to be call the redefined new operator
2045 with filename and line number arguments. The definition is:
2048 #define WXDEBUG_NEW new(__FILE__,__LINE__)
2051 In non-debug mode, this is defined as the normal new operator.
2053 \wxheading{Include files}
2057 \membersection{wxDynamicCast}\label{wxdynamiccast}
2059 \func{}{wxDynamicCast}{ptr, classname}
2061 This macro returns the pointer {\it ptr} cast to the type {\it classname *} if
2062 the pointer is of this type (the check is done during the run-time) or NULL
2063 otherwise. Usage of this macro is prefered over obsoleted wxObject::IsKindOf()
2066 The {\it ptr} argument may be NULL, in which case NULL will be returned.
2071 wxWindow *win = wxWindow::FindFocus();
2072 wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
2075 // a text control has the focus...
2079 // no window has the focus or it's not a text control
2083 \wxheading{See also}
2085 \helpref{RTTI overview}{runtimeclassoverview}
2087 \membersection{wxICON}\label{wxiconmacro}
2089 \func{}{wxICON}{iconName}
2091 This macro loads an icon from either application resources (on the platforms
2092 for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
2093 avoid using {\tt #ifdef}s when creating icons.
2095 \wxheading{See also}
2097 \helpref{Bitmaps and icons overview}{wxbitmapoverview},
2098 \helpref{wxBITMAP}{wxbitmapmacro}
2100 \wxheading{Include files}
2104 \membersection{WXTRACE}\label{trace}
2106 \wxheading{Include files}
2110 \func{}{WXTRACE}{formatString, ...}
2112 Calls wxTrace with printf-style variable argument syntax. Output
2113 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
2115 This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
2117 \wxheading{Include files}
2121 \membersection{WXTRACELEVEL}\label{tracelevel}
2123 \func{}{WXTRACELEVEL}{level, formatString, ...}
2125 Calls wxTraceLevel with printf-style variable argument syntax. Output
2126 is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
2127 The first argument should be the level at which this information is appropriate.
2128 It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
2131 This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
2133 \wxheading{Include files}
2137 \section{wxWindows resource functions}\label{resourcefuncs}
2139 \overview{wxWindows resource system}{resourceformats}
2141 This section details functions for manipulating wxWindows (.WXR) resource
2142 files and loading user interface elements from resources.
2144 \normalbox{Please note that this use of the word `resource' is different from that used when talking
2145 about initialisation file resource reading and writing, using such functions
2146 as wxWriteResource and wxGetResource. It's just an unfortunate clash of terminology.}
2148 \helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
2150 See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
2151 loading from resource data.
2153 {\bf Warning:} this needs updating for wxWindows 2.
2155 \membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
2157 \func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
2159 Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
2160 \verb$#$defining a name to an integer). Unlikely to be used by an application except
2161 perhaps for implementing resource functionality for interpreted languages.
2163 \membersection{::wxResourceClear}
2165 \func{void}{wxResourceClear}{\void}
2167 Clears the wxWindows resource table.
2169 \membersection{::wxResourceCreateBitmap}
2171 \func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
2173 Creates a new bitmap from a file, static data, or Windows resource, given a valid
2174 wxWindows bitmap resource identifier. For example, if the .WXR file contains
2178 static const wxString\& aiai_resource = "bitmap(name = 'aiai_resource',\
2179 bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
2180 bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X']).";
2183 then this function can be called as follows:
2186 wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource");
2189 \membersection{::wxResourceCreateIcon}
2191 \func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
2193 Creates a new icon from a file, static data, or Windows resource, given a valid
2194 wxWindows icon resource identifier. For example, if the .WXR file contains
2198 static const wxString\& aiai_resource = "icon(name = 'aiai_resource',\
2199 icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
2200 icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X']).";
2203 then this function can be called as follows:
2206 wxIcon *icon = wxResourceCreateIcon("aiai_resource");
2209 \membersection{::wxResourceCreateMenuBar}
2211 \func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
2213 Creates a new menu bar given a valid wxWindows menubar resource
2214 identifier. For example, if the .WXR file contains the following:
2217 static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
2221 ['&Open File', 2, 'Open a file'],\
2222 ['&Save File', 3, 'Save a file'],\
2224 ['E&xit', 4, 'Exit program']\
2227 ['&About', 6, 'About this program']\
2232 then this function can be called as follows:
2235 wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
2239 \membersection{::wxResourceGetIdentifier}
2241 \func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
2243 Used for retrieving the integer value associated with an identifier.
2244 A zero value indicates that the identifier was not found.
2246 See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
2248 \membersection{::wxResourceParseData}\label{wxresourcedata}
2250 \func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
2252 Parses a string containing one or more wxWindows resource objects. If
2253 the resource objects are global static data that are included into the
2254 C++ program, then this function must be called for each variable
2255 containing the resource data, to make it known to wxWindows.
2257 {\it resource} should contain data in the following form:
2260 dialog(name = 'dialog1',
2261 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
2262 title = 'Test dialog box',
2263 x = 312, y = 234, width = 400, height = 300,
2265 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
2266 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
2267 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',
2268 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
2269 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
2270 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
2273 This function will typically be used after including a {\tt .wxr} file into
2274 a C++ program as follows:
2277 #include "dialog1.wxr"
2280 Each of the contained resources will declare a new C++ variable, and each
2281 of these variables should be passed to wxResourceParseData.
2283 \membersection{::wxResourceParseFile}
2285 \func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
2287 Parses a file containing one or more wxWindows resource objects
2288 in C++-compatible syntax. Use this function to dynamically load
2289 wxWindows resource data.
2291 \membersection{::wxResourceParseString}\label{wxresourceparsestring}
2293 \func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
2295 Parses a string containing one or more wxWindows resource objects. If
2296 the resource objects are global static data that are included into the
2297 C++ program, then this function must be called for each variable
2298 containing the resource data, to make it known to wxWindows.
2300 {\it resource} should contain data with the following form:
2303 static const wxString\& dialog1 = "dialog(name = 'dialog1',\
2304 style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',\
2305 title = 'Test dialog box',\
2306 x = 312, y = 234, width = 400, height = 300,\
2308 control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,\
2309 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],\
2310 control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',\
2311 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',\
2312 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
2313 [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).";
2316 This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
2317 load an entire {\tt .wxr file} into a string.
2319 \membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
2321 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width},
2322 \param{int }{height}, \param{wxResourceTable *}{table = NULL}}
2324 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}}
2326 Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system.
2327 This is required if other resources will use the bitmap data, since otherwise there
2328 is no connection between names used in resources, and the global bitmap data.
2330 \membersection{::wxResourceRegisterIconData}
2332 Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
2334 \section{Log functions}\label{logfunctions}
2336 These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
2337 further information. The functions use (implicitly) the currently active log
2338 target, so their descriptions here may not apply if the log target is not the
2339 standard one (installed by wxWindows in the beginning of the program).
2341 \wxheading{Include files}
2345 \membersection{::wxLogError}\label{wxlogerror}
2347 \func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
2349 The function to use for error messages, i.e. the messages that must be shown
2350 to the user. The default processing is to pop up a message box to inform the
2353 \membersection{::wxLogFatalError}\label{wxlogfatalerror}
2355 \func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}}
2357 Like \helpref{wxLogError}{wxlogerror}, but also
2358 terminates the program with the exit code 3. Using {\it abort()} standard
2359 function also terminates the program with this exit code.
2361 \membersection{::wxLogWarning}\label{wxlogwarning}
2363 \func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}}
2365 For warnings - they are also normally shown to the user, but don't interrupt
2368 \membersection{::wxLogMessage}\label{wxlogmessage}
2370 \func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}}
2372 for all normal, informational messages. They also appear in a message box by
2373 default (but it can be changed). Notice that the standard behaviour is to not
2374 show informational messages if there are any errors later - the logic being
2375 that the later error messages make the informational messages preceding them
2378 \membersection{::wxLogVerbose}\label{wxlogverbose}
2380 \func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}}
2382 For verbose output. Normally, it's suppressed, but
2383 might be activated if the user wishes to know more details about the program
2384 progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
2386 \membersection{::wxLogStatus}\label{wxlogstatus}
2388 \func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char*}{ formatString}, \param{...}{}}
2390 \func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}}
2392 Messages logged by this function will appear in the statusbar of the {\it
2393 frame} or of the top level application window by default (i.e. when using
2394 the second version of the function).
2396 If the target frame doesn't have a statusbar, the message will be lost.
2398 \membersection{::wxLogSysError}\label{wxlogsyserror}
2400 \func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}}
2402 Mostly used by wxWindows itself, but might be handy for logging errors after
2403 system call (API function) failure. It logs the specified message text as well
2404 as the last system error code ({\it errno} or {\it ::GetLastError()} depending
2405 on the platform) and the corresponding error message. The second form
2406 of this function takes the error code explitly as the first argument.
2408 \membersection{::wxLogDebug}\label{wxlogdebug}
2410 \func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}}
2412 The right function for debug output. It only does anything at all in the debug
2413 mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) and expands to
2414 nothing in release mode (otherwise).
2416 \membersection{::wxLogTrace}\label{wxlogtrace}
2418 \func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}}
2420 \func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
2422 \func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
2424 As {\bf wxLogDebug}, trace functions only do something in debug build and
2425 expand to nothing in the release one. The reason for making
2426 it a separate function from it is that usually there are a lot of trace
2427 messages, so it might make sense to separate them from other debug messages.
2429 The trace messages also usually can be separated into different categories and
2430 the second and third versions of this function only log the message if the
2431 {\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This
2432 allows to selectively trace only some operations and not others by changing
2433 the value of the trace mask (possible during the run-time).
2435 For the second function (taking a string mask), the message is logged only if
2436 the mask has been previously enabled by the call to
2437 \helpref{AddTraceMask}{wxlogaddtracemask}. The predefined string trace masks
2438 used by wxWindows are:
2440 \begin{itemize}\itemsep=0pt
2441 \item wxTRACE\_MemAlloc: trace memory allocation (new/delete)
2442 \item wxTRACE\_Messages: trace window messages/X callbacks
2443 \item wxTRACE\_ResAlloc: trace GDI resource allocation
2444 \item wxTRACE\_RefCount: trace various ref counting operations
2445 \item wxTRACE\_OleCalls: trace OLE method calls (Win32 only)
2448 The third version of the function only logs the message if all the bit
2449 corresponding to the {\it mask} are set in the wxLog trace mask which can be
2450 set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less
2451 flexible than the previous one because it doesn't allow defining the user
2452 trace masks easily - this is why it is deprecated in favour of using string
2455 \begin{itemize}\itemsep=0pt
2456 \item wxTraceMemAlloc: trace memory allocation (new/delete)
2457 \item wxTraceMessages: trace window messages/X callbacks
2458 \item wxTraceResAlloc: trace GDI resource allocation
2459 \item wxTraceRefCount: trace various ref counting operations
2460 \item wxTraceOleCalls: trace OLE method calls (Win32 only)
2463 \section{Debugging macros and functions}\label{debugmacros}
2465 Useful macros and functins for error checking and defensive programming. ASSERTs are only
2466 compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
2469 \wxheading{Include files}
2473 \membersection{::wxOnAssert}\label{wxonassert}
2475 \func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}}
2477 This function may be redefined to do something non trivial and is called
2478 whenever one of debugging macros fails (i.e. condition is false in an
2480 % TODO: this should probably be an overridable in wxApp.
2482 \membersection{wxASSERT}\label{wxassert}
2484 \func{}{wxASSERT}{\param{}{condition}}
2486 Assert macro. An error message will be generated if the condition is FALSE in
2487 debug mode, but nothing will be done in the release build.
2489 Please note that the condition in wxASSERT() should have no side effects
2490 because it will not be executed in release mode at all.
2492 See also: \helpref{wxASSERT\_MSG}{wxassertmsg}
2494 \membersection{wxASSERT\_MSG}\label{wxassertmsg}
2496 \func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
2498 Assert macro with message. An error message will be generated if the condition is FALSE.
2500 See also: \helpref{wxASSERT}{wxassert}
2502 \membersection{wxFAIL}\label{wxfail}
2504 \func{}{wxFAIL}{\void}
2506 Will always generate an assert error if this code is reached (in debug mode).
2508 See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
2510 \membersection{wxFAIL\_MSG}\label{wxfailmsg}
2512 \func{}{wxFAIL\_MSG}{\param{}{msg}}
2514 Will always generate an assert error with specified message if this code is reached (in debug mode).
2516 This macro is useful for marking unreachable" code areas, for example
2517 it may be used in the "default:" branch of a switch statement if all possible
2518 cases are processed above.
2520 See also: \helpref{wxFAIL}{wxfail}
2522 \membersection{wxCHECK}\label{wxcheck}
2524 \func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
2526 Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2527 This check is done even in release mode.
2529 \membersection{wxCHECK\_MSG}\label{wxcheckmsg}
2531 \func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
2533 Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
2534 This check is done even in release mode.
2536 This macro may be only used in non void functions, see also
2537 \helpref{wxCHECK\_RET}{wxcheckret}.
2539 \membersection{wxCHECK\_RET}\label{wxcheckret}
2541 \func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}}
2543 Checks that the condition is true, and returns if not (FAILs with given error
2544 message in debug mode). This check is done even in release mode.
2546 This macro should be used in void functions instead of
2547 \helpref{wxCHECK\_MSG}{wxcheckmsg}.
2549 \membersection{wxCHECK2}\label{wxcheck2}
2551 \func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}}
2553 Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute
2554 {\it operation} if it is not. This is a generalisation of
2555 \helpref{wxCHECK}{wxcheck} and may be used when something else than just
2556 returning from the function must be done when the {\it condition} is false.
2558 This check is done even in release mode.
2560 \membersection{wxCHECK2\_MSG}\label{wxcheck2msg}
2562 \func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}}
2564 This is the same as \helpref{wxCHECK2}{wxcheck2}, but
2565 \helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
2566 instead of wxFAIL() if the {\it condition} is false.
projects / wxWidgets.git / blob