+The first variant of this function returns the hostname if successful or an
+empty string otherwise. The second (deprecated) function returns true
+if successful, false otherwise.
+
+\wxheading{See also}
+
+\helpref{wxGetFullHostName}{wxgetfullhostname}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetUserId}\label{wxgetuserid}
+
+\func{wxString}{wxGetUserId}{\void}
+
+\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
+
+This function returns the "user id" also known as "login name" under Unix i.e.
+something like "jsmith". It uniquely identifies the current user (on this system).
+
+Under Windows or NT, this function first looks in the environment
+variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
+in the {\bf wxWidgets} section of the WIN.INI file is tried.
+
+The first variant of this function returns the login name if successful or an
+empty string otherwise. The second (deprecated) function returns true
+if successful, false otherwise.
+
+\wxheading{See also}
+
+\helpref{wxGetUserName}{wxgetusername}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetOsDescription}\label{wxgetosdescription}
+
+\func{wxString}{wxGetOsDescription}{\void}
+
+Returns the string containing the description of the current platform in a
+user-readable form. For example, this function may return strings like
+{\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}.
+
+\wxheading{See also}
+
+\helpref{::wxGetOsVersion}{wxgetosversion}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetOsVersion}\label{wxgetosversion}
+
+\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
+
+Gets operating system version information.
+
+\begin{twocollist}\itemsep=0pt
+\twocolitemruled{Platform}{Return types}
+\twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X.
+
+Both {\it major} and {\it minor} have to be looked at as hexadecimal numbers. So System 10.2.4 returns 0x10, resp 16 for {\it major} and 0x24, resp 36 for {\it minor}. }
+\twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. }
+\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
+\twocolitem{OS/2}{Return value is wxOS2\_PM.}
+\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
+\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}}
+\twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.}
+\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.}
+\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
+\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
+\end{twocollist}
+
+\wxheading{See also}
+
+\helpref{::wxGetOsDescription}{wxgetosdescription}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetUserHome}\label{wxgetuserhome}
+
+\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
+
+Returns the home directory for the given user. If the username is empty
+(default value), this function behaves like
+\helpref{wxGetHomeDir}{wxgethomedir}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetUserName}\label{wxgetusername}
+
+\func{wxString}{wxGetUserName}{\void}
+
+\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
+
+This function returns the full user name (something like "Mr. John Smith").
+
+Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
+in the {\bf wxWidgets} section of the WIN.INI file. If PenWindows
+is running, the entry {\bf Current} in the section {\bf User} of
+the PENWIN.INI file is used.
+
+The first variant of this function returns the user name if successful or an
+empty string otherwise. The second (deprecated) function returns {\tt true}
+if successful, {\tt false} otherwise.
+
+\wxheading{See also}
+
+\helpref{wxGetUserId}{wxgetuserid}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+
+\section{String functions}
+
+
+\membersection{::copystring}\label{copystring}
+
+\func{char *}{copystring}{\param{const char *}{s}}
+
+Makes a copy of the string {\it s} using the C++ new operator, so it can be
+deleted with the {\it delete} operator.
+
+This function is deprecated, use \helpref{wxString}{wxstring} class instead.
+
+
+\membersection{::wxGetTranslation}\label{wxgettranslation}
+
+\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
+
+\func{const char *}{wxGetTranslation}{\param{const char * }{str}, \param{const char * }{strPlural}, \param{size\_t }{n}}
+
+This function returns the translation of string {\it str} in the current
+\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
+message catalogs (see \helpref{internationalization overview}{internationalization}), the
+original string is returned. In debug build, an error message is logged -- this
+should help to find the strings which were not yet translated. As this function
+is used very often, an alternative (and also common in Unix world) syntax is
+provided: the \helpref{\_()}{underscore} macro is defined to do the same thing
+as wxGetTranslation.
+
+The second form is used when retrieving translation of string that has
+different singular and plural form in English or different plural forms in some
+other language. It takes two extra arguments: \arg{str}
+parameter must contain the singular form of the string to be converted.
+It is also used as the key for the search in the catalog.
+The \arg{strPlural} parameter is the plural form (in English).
+The parameter \arg{n} is used to determine the plural form. If no
+message catalog is found \arg{str} is returned if `n == 1',
+otherwise \arg{strPlural}.
+See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} for additional information on plural forms handling.
+
+Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}.
+
+\membersection{::wxIsEmpty}\label{wxisempty}
+
+\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
+
+Returns {\tt true} if the pointer is either {\tt NULL} or points to an empty
+string, {\tt false} otherwise.
+
+
+\membersection{::wxStrcmp}\label{wxstrcmp}
+
+\func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}}
+
+Returns a negative value, 0, or positive value if {\it p1} is less than, equal
+to or greater than {\it p2}. The comparison is case-sensitive.
+
+This function complements the standard C function {\it stricmp()} which performs
+case-insensitive comparison.
+
+
+\membersection{::wxStricmp}\label{wxstricmp}
+
+\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
+
+Returns a negative value, 0, or positive value if {\it p1} is less than, equal
+to or greater than {\it p2}. The comparison is case-insensitive.
+
+This function complements the standard C function {\it strcmp()} which performs
+case-sensitive comparison.
+
+
+\membersection{::wxStringMatch}\label{wxstringmatch}
+
+\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
+ \param{bool}{ subString = true}, \param{bool}{ exact = false}}
+
+{\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
+
+Returns {\tt true} if the substring {\it s1} is found within {\it s2},
+ignoring case if {\it exact} is false. If {\it subString} is {\tt false},
+no substring matching is done.
+
+
+\membersection{::wxStringEq}\label{wxstringeq}
+
+\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
+
+{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead.
+
+A macro defined as:
+
+\begin{verbatim}
+#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
+\end{verbatim}
+
+
+\membersection{::wxStrlen}\label{wxstrlen}
+
+\func{size\_t}{wxStrlen}{\param{const char *}{ p}}
+
+This is a safe version of standard function {\it strlen()}: it does exactly the
+same thing (i.e. returns the length of the string) except that it returns 0 if
+{\it p} is the {\tt NULL} pointer.
+
+
+\membersection{::wxSnprintf}\label{wxsnprintf}
+
+\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
+
+This function replaces the dangerous standard function {\tt sprintf()} and is
+like {\tt snprintf()} available on some platforms. The only difference with
+sprintf() is that an additional argument - buffer size - is taken and the
+buffer is never overflowed.
+
+Returns the number of characters copied to the buffer or -1 if there is not
+enough space.
+
+\wxheading{See also}
+
+\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
+
+
+\membersection{wxT}\label{wxt}
+
+\func{wxChar}{wxT}{\param{char }{ch}}
+
+\func{const wxChar *}{wxT}{\param{const char *}{s}}
+
+wxT() is a macro which can be used with character and string literals (in other
+words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in
+Unicode build configuration. Please see the
+\helpref{Unicode overview}{unicode} for more information.
+
+This macro is simply returns the value passed to it without changes in ASCII
+build. In fact, its definition is:
+\begin{verbatim}
+#ifdef UNICODE
+#define wxT(x) L ## x
+#else // !Unicode
+#define wxT(x) x
+#endif
+\end{verbatim}
+
+
+\membersection{wxTRANSLATE}\label{wxtranslate}
+
+\func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}}
+
+This macro doesn't do anything in the program code -- it simply expands to the
+value of its argument (except in Unicode build where it is equivalent to
+\helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT
+with the same string which would be really unreadable).
+
+However it does have a purpose and it is to mark the literal strings for the
+extraction into the message catalog created by {\tt xgettext} program. Usually
+this is achieved using \helpref{\_()}{underscore} but that macro not only marks
+the string for extraction but also expands into a
+\helpref{wxGetTranslation}{wxgettranslation} function call which means that it
+cannot be used in some situations, notably for static array
+initialization.
+
+Here is an example which should make it more clear: suppose that you have a
+static array of strings containing the weekday names and which have to be
+translated (note that it is a bad example, really, as
+\helpref{wxDateTime}{wxdatetime} already can be used to get the localized week
+day names already). If you write
+
+\begin{verbatim}
+static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
+...
+// use weekdays[n] as usual
+\end{verbatim}
+
+the code wouldn't compile because the function calls are forbidden in the array
+initializer. So instead you should do
+
+\begin{verbatim}
+static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
+...
+// use wxGetTranslation(weekdays[n])
+\end{verbatim}
+
+here.
+
+Note that although the code {\bf would} compile if you simply omit
+wxTRANSLATE() in the above, it wouldn't work as expected because there would be
+no translations for the weekday names in the program message catalog and
+wxGetTranslation wouldn't find them.
+
+\membersection{::wxVsnprintf}\label{wxvsnprintf}
+
+\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
+
+The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list }
+argument instead of arbitrary number of parameters.
+
+\wxheading{See also}
+
+\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
+
+
+
+\membersection{\_}\label{underscore}
+
+\func{const wxChar *}{\_}{\param{const char *}{s}}
+
+This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation}
+function, so it marks the message for the extraction by {\tt xgettext} just as
+\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of
+the string for the current locale during execution.
+
+Don't confuse this macro with \helpref{\_T()}{underscoret}!
+
+
+\membersection{\_T}\label{underscoret}
+
+\func{wxChar}{\_T}{\param{char }{ch}}
+
+\func{const wxChar *}{\_T}{\param{const wxChar }{ch}}
+
+This macro is exactly the same as \helpref{wxT}{wxt} and is defined in
+wxWidgets simply because it may be more intuitive for Windows programmers as
+the standard Win32 headers also define it (as well as yet another name for the
+same macro which is {\tt \_TEXT()}).
+
+Don't confuse this macro with \helpref{\_()}{underscore}!
+
+
+
+\section{Dialog functions}\label{dialogfunctions}
+
+Below are a number of convenience functions for getting input from the
+user or displaying messages. Note that in these functions the last three
+parameters are optional. However, it is recommended to pass a parent frame
+parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
+the front when the dialog box is popped up.
+
+
+\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
+
+\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
+
+Changes the cursor to the given cursor for all windows in the application.
+Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
+to its previous state. These two calls can be nested, and a counter
+ensures that only the outer calls take effect.
+
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxBell}\label{wxbell}
+
+\func{void}{wxBell}{\void}
+
+Ring the system bell.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
+
+\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
+ \param{size\_t }{currentTip}}
+
+This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
+used with \helpref{wxShowTip}{wxshowtip}.
+
+\docparam{filename}{The name of the file containing the tips, one per line}
+\docparam{currentTip}{The index of the first tip to show - normally this index
+is remembered between the 2 program runs.}
+
+\wxheading{See also}
+
+\helpref{Tips overview}{tipsoverview}
+
+\wxheading{Include files}
+
+<wx/tipdlg.h>
+
+
+\membersection{::wxDirSelector}\label{wxdirselector}
+
+\func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\
+ \param{const wxString\& }{default\_path = ""},\\
+ \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\
+ \param{wxWindow *}{parent = NULL}}
+
+Pops up a directory selector dialog. The arguments have the same meaning as
+those of wxDirDialog::wxDirDialog(). The message is displayed at the top,
+and the default\_path, if specified, is set as the initial selection.
+
+The application must check for an empty return value (if the user pressed
+Cancel). For example:
+
+\begin{verbatim}
+const wxString& dir = wxDirSelector("Choose a folder");
+if ( !dir.empty() )
+{
+ ...
+}
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/dirdlg.h>
+
+
+\membersection{::wxFileSelector}\label{wxfileselector}
+
+\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
+ \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\
+ \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = ""},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1}}
+
+Pops up a file selector box. In Windows, this is the common file selector
+dialog. In X, this is a file selector box with the same functionality.
+The path and filename are distinct elements of a full file pathname.
+If path is empty, the current directory will be used. If filename is empty,
+no default filename will be supplied. The wildcard determines what files
+are displayed in the file selector, and file extension supplies a type
+extension for the required filename. Flags may be a combination of wxOPEN,
+wxSAVE, wxOVERWRITE\_PROMPT, wxFILE\_MUST\_EXIST, wxMULTIPLE or 0.
+
+Both the Unix and Windows versions implement a wildcard filter. Typing a
+filename containing wildcards (*, ?) in the filename text item, and
+clicking on Ok, will result in only those files matching the pattern being
+displayed.
+
+The wildcard may be a specification for multiple types of file
+with a description for each, such as:
+
+\begin{verbatim}
+ "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
+\end{verbatim}
+
+The application must check for an empty return value (the user pressed
+Cancel). For example:
+
+\begin{verbatim}
+wxString filename = wxFileSelector("Choose a file to open");
+if ( !filename.empty() )
+{
+ // work with the file
+ ...
+}
+//else: cancelled by user
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/filedlg.h>
+
+
+\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
+
+\func{void}{wxEndBusyCursor}{\void}
+
+Changes the cursor back to the original cursor, for all windows in the application.
+Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
+
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
+
+\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}}
+
+Shows the colour selection dialog and returns the colour selected by user or
+invalid colour (use \helpref{wxColour::Ok}{wxcolourok} to test whether a colour
+is valid) if the dialog was cancelled.
+
+\wxheading{Parameters}
+
+\docparam{parent}{The parent window for the colour selection dialog}
+
+\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
+
+\wxheading{Include files}
+
+<wx/colordlg.h>
+
+
+\membersection{::wxGetFontFromUser}\label{wxgetfontfromuser}
+
+\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}}
+
+Shows the font selection dialog and returns the font selected by user or
+invalid font (use \helpref{wxFont::Ok}{wxfontok} to test whether a font
+is valid) if the dialog was cancelled.
+
+\wxheading{Parameters}
+
+\docparam{parent}{The parent window for the font selection dialog}
+
+\docparam{fontInit}{If given, this will be the font initially selected in the dialog.}
+
+\wxheading{Include files}
+
+<wx/fontdlg.h>
+
+
+
+\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
+
+\func{size\_t}{wxGetMultipleChoices}{\\
+ \param{wxArrayInt\& }{selections},\\
+ \param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{const wxArrayString\& }{aChoices},\\
+ \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true},\\
+ \param{int }{width=150}, \param{int }{height=200}}
+
+\func{size\_t}{wxGetMultipleChoices}{\\
+ \param{wxArrayInt\& }{selections},\\
+ \param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{int}{ n}, \param{const wxString\& }{choices[]},\\
+ \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true},\\
+ \param{int }{width=150}, \param{int }{height=200}}
+
+Pops up a dialog box containing a message, OK/Cancel buttons and a
+multiple-selection listbox. The user may choose an arbitrary (including 0)
+number of items in the listbox whose indices will be returned in
+{\it selection} array. The initial contents of this array will be used to
+select the items when the dialog is shown.
+
+You may pass the list of strings to choose from either using {\it choices}
+which is an array of {\it n} strings for the listbox or by using a single
+{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
+
+If {\it centre} is true, the message text (which may include new line
+characters) is centred; if false, the message is left-justified.
+
+\wxheading{Include files}
+
+<wx/choicdlg.h>
+
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}, and no {\tt selections} parameter; the function
+returns an array containing the user selections.}
+
+
+\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
+
+\func{long}{wxGetNumberFromUser}{
+ \param{const wxString\& }{message},
+ \param{const wxString\& }{prompt},
+ \param{const wxString\& }{caption},
+ \param{long }{value},
+ \param{long }{min = 0},
+ \param{long }{max = 100},
+ \param{wxWindow *}{parent = NULL},
+ \param{const wxPoint\& }{pos = wxDefaultPosition}}
+
+Shows a dialog asking the user for numeric input. The dialogs title is set to
+{\it caption}, it contains a (possibly) multiline {\it message} above the
+single line {\it prompt} and the zone for entering the number.
+
+The number entered must be in the range {\it min}..{\it max} (both of which
+should be positive) and {\it value} is the initial value of it. If the user
+enters an invalid value or cancels the dialog, the function will return -1.
+
+Dialog is centered on its {\it parent} unless an explicit position is given in
+{\it pos}.
+
+\wxheading{Include files}
+
+<wx/numdlg.h>
+
+
+\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
+
+\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
+ \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}}
+
+Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered
+in the dialog is not shown on screen but replaced with stars. This is intended
+to be used for entering passwords as the function name implies.
+
+\wxheading{Include files}
+
+<wx/textdlg.h>
+
+
+\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
+
+\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
+ \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = true}}
+
+Pop up a dialog box with title set to {\it caption}, {\it message}, and a
+\rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
+or press Cancel to return the empty string.
+
+If {\it centre} is true, the message text (which may include new line characters)
+is centred; if false, the message is left-justified.
+
+\wxheading{Include files}
+
+<wx/textdlg.h>
+
+
+\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
+
+\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
+ \param{int }{nsel}, \param{int *}{selection},
+ \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
+
+Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
+listbox. The user may choose one or more item(s) and press OK or Cancel.
+
+The number of initially selected choices, and array of the selected indices,
+are passed in; this array will contain the user selections on exit, with
+the function returning the number of selections. {\it selection} must be
+as big as the number of choices, in case all are selected.
+
+If Cancel is pressed, -1 is returned.
+
+{\it choices} is an array of {\it n} strings for the listbox.
+
+If {\it centre} is true, the message text (which may include new line characters)
+is centred; if false, the message is left-justified.
+
+\wxheading{Include files}
+
+<wx/choicdlg.h>
+
+
+\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
+
+\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{const wxArrayString\& }{aChoices},\\
+ \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true},\\
+ \param{int }{width=150}, \param{int }{height=200}}
+
+\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{int}{ n}, \param{const wxString\& }{choices[]},\\
+ \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true},\\
+ \param{int }{width=150}, \param{int }{height=200}}
+
+Pops up a dialog box containing a message, OK/Cancel buttons and a
+single-selection listbox. The user may choose an item and press OK to return a
+string or Cancel to return the empty string. Use
+\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex} if empty string is a
+valid choice and if you want to be able to detect pressing Cancel reliably.
+
+You may pass the list of strings to choose from either using {\it choices}
+which is an array of {\it n} strings for the listbox or by using a single
+{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
+
+If {\it centre} is true, the message text (which may include new line
+characters) is centred; if false, the message is left-justified.
+
+\wxheading{Include files}
+
+<wx/choicdlg.h>
+
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
+
+
+\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
+
+\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{const wxArrayString\& }{aChoices},\\
+ \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
+
+\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{int}{ n}, \param{const wxString\& }{choices[]},\\
+ \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
+
+As {\bf wxGetSingleChoice} but returns the index representing the selected
+string. If the user pressed cancel, -1 is returned.
+
+\wxheading{Include files}
+
+<wx/choicdlg.h>
+
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
+
+
+\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
+
+\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{const wxArrayString\& }{aChoices},\\
+ \param{const wxString\& }{client\_data[]},\\
+ \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
+
+\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{int}{ n}, \param{const wxString\& }{choices[]},\\
+ \param{const wxString\& }{client\_data[]},\\
+ \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
+
+As {\bf wxGetSingleChoice} but takes an array of client data pointers
+corresponding to the strings, and returns one of these pointers or NULL if
+Cancel was pressed. The {\it client\_data} array must have the same number of
+elements as {\it choices} or {\it aChoices}!
+
+\wxheading{Include files}
+
+<wx/choicdlg.h>
+
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}, and the client data array must have the
+same length as the choices array.}
+
+
+\membersection{::wxIsBusy}\label{wxisbusy}
+
+\func{bool}{wxIsBusy}{\void}
+
+Returns true if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
+\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
+
+See also \helpref{wxBusyCursor}{wxbusycursor}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxMessageBox}\label{wxmessagebox}
+
+\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK},\\
+ \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
+
+General purpose message dialog. {\it style} may be a bit list of the
+following identifiers:
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
+wxCANCEL.}
+\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
+wxYES\_NO or wxOK.}
+\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
+\twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.}
+\twocolitem{wxICON\_HAND}{Displays an error symbol.}
+\twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.}
+\twocolitem{wxICON\_QUESTION}{Displays a question mark symbol.}
+\twocolitem{wxICON\_INFORMATION}{Displays an information symbol.}
+\end{twocollist}
+
+The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
+
+For example:
+
+\begin{verbatim}
+ ...
+ int answer = wxMessageBox("Quit program?", "Confirm",
+ wxYES_NO | wxCANCEL, main_frame);
+ if (answer == wxYES)
+ main_frame->Close();
+ ...
+\end{verbatim}
+
+{\it message} may contain newline characters, in which case the
+message will be split into separate lines, to cater for large messages.
+
+\wxheading{Include files}
+
+<wx/msgdlg.h>
+
+
+\membersection{::wxShowTip}\label{wxshowtip}
+
+\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
+ \param{wxTipProvider *}{tipProvider},
+ \param{bool }{showAtStartup = true}}
+
+This function shows a "startup tip" to the user. The return value is the
+state of the ``Show tips at startup'' checkbox.
+
+\docparam{parent}{The parent window for the modal dialog}
+
+\docparam{tipProvider}{An object which is used to get the text of the tips.
+It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
+
+\docparam{showAtStartup}{Should be true if startup tips are shown, false
+otherwise. This is used as the initial value for "Show tips at startup"
+checkbox which is shown in the tips dialog.}
+
+\wxheading{See also}
+
+\helpref{Tips overview}{tipsoverview}
+
+\wxheading{Include files}
+
+<wx/tipdlg.h>
+
+
+
+
+\section{Math functions}
+
+\wxheading{Include files}
+
+<wx/math.h>
+
+
+\membersection{wxFinite}\label{wxfinite}
+
+\func{int}{wxFinite}{\param{double }{x}}
+
+Returns a non-zero value if {\it x} is neither infinite or NaN (not a number),
+returns 0 otherwise.
+
+
+\membersection{wxIsNaN}\label{wxisnan}
+
+\func{bool}{wxIsNaN}{\param{double }{x}}
+
+Returns a non-zero value if {\it x} is NaN (not a number), returns 0
+otherwise.
+
+
+
+
+\section{GDI functions}\label{gdifunctions}
+
+The following are relevant to the GDI (Graphics Device Interface).
+
+\wxheading{Include files}
+
+<wx/gdicmn.h>
+
+
+\membersection{wxBITMAP}\label{wxbitmapmacro}
+
+\func{}{wxBITMAP}{bitmapName}
+
+This macro loads a bitmap from either application resources (on the platforms
+for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
+avoid using {\tt \#ifdef}s when creating bitmaps.
+
+\wxheading{See also}
+
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxICON}{wxiconmacro}
+
+\wxheading{Include files}
+
+<wx/gdicmn.h>
+
+
+\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect}
+
+\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
+\param{int *}{width}, \param{int *}{height}}
+
+\func{wxRect}{wxGetClientDisplayRect}{\void}
+
+Returns the dimensions of the work area on the display. On Windows
+this means the area not covered by the taskbar, etc. Other platforms
+are currently defaulting to the whole display until a way is found to
+provide this info for all window managers, etc.
+
+
+\membersection{::wxColourDisplay}\label{wxcolourdisplay}
+
+\func{bool}{wxColourDisplay}{\void}
+
+Returns true if the display is colour, false otherwise.
+
+
+\membersection{::wxDisplayDepth}\label{wxdisplaydepth}
+
+\func{int}{wxDisplayDepth}{\void}
+
+Returns the depth of the display (a value of 1 denotes a monochrome display).
+
+
+\membersection{::wxDisplaySize}\label{wxdisplaysize}
+
+\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
+
+\func{wxSize}{wxGetDisplaySize}{\void}
+
+Returns the display size in pixels.
+
+
+\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm}
+
+\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
+
+\func{wxSize}{wxGetDisplaySizeMM}{\void}
+
+Returns the display size in millimeters.
+
+
+\membersection{::wxDROP\_ICON}\label{wxdropicon}
+
+\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
+
+This macro creates either a cursor (MSW) or an icon (elsewhere) with the given
+name. Under MSW, the cursor is loaded from the resource file and the icon is
+loaded from XPM file under other platforms.
+
+This macro should be used with
+\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}.
+
+\wxheading{Include files}
+
+<wx/dnd.h>
+
+
+\membersection{wxICON}\label{wxiconmacro}
+
+\func{}{wxICON}{iconName}
+
+This macro loads an icon from either application resources (on the platforms
+for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
+avoid using {\tt \#ifdef}s when creating icons.
+
+\wxheading{See also}
+
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxBITMAP}{wxbitmapmacro}
+
+\wxheading{Include files}
+
+<wx/gdicmn.h>
+
+
+\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
+
+\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
+ \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
+
+Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
+makes it into a placeable metafile by prepending a header containing the given
+bounding box. The bounding box may be obtained from a device context after drawing
+into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
+
+In addition to adding the placeable metafile header, this function adds
+the equivalent of the following code to the start of the metafile data:
+
+\begin{verbatim}
+ SetMapMode(dc, MM_ANISOTROPIC);
+ SetWindowOrg(dc, minX, minY);
+ SetWindowExt(dc, maxX - minX, maxY - minY);
+\end{verbatim}
+
+This simulates the wxMM\_TEXT mapping mode, which wxWidgets assumes.
+
+Placeable metafiles may be imported by many Windows applications, and can be
+used in RTF (Rich Text Format) files.
+
+{\it scale} allows the specification of scale for the metafile.
+
+This function is only available under Windows.
+
+
+\membersection{::wxSetCursor}\label{wxsetcursor}
+
+\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
+
+Globally sets the cursor; only has an effect in Windows and GTK.
+See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
+
+
+
+\section{Printer settings}\label{printersettings}
+
+{\bf NB:} These routines are obsolete and should no longer be used!
+
+The following functions are used to control PostScript printing. Under
+Windows, PostScript output can only be sent to a file.
+
+\wxheading{Include files}
+
+<wx/dcps.h>
+
+
+\membersection{::wxGetPrinterCommand}\label{wxgetprintercommand}
+
+\func{wxString}{wxGetPrinterCommand}{\void}
+
+Gets the printer command used to print a file. The default is {\tt lpr}.
+
+
+\membersection{::wxGetPrinterFile}\label{wxgetprinterfile}
+
+\func{wxString}{wxGetPrinterFile}{\void}
+
+Gets the PostScript output filename.
+
+
+\membersection{::wxGetPrinterMode}\label{wxgetprintermode}
+
+\func{int}{wxGetPrinterMode}{\void}
+
+Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
+The default is PS\_PREVIEW.
+
+
+\membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions}
+
+\func{wxString}{wxGetPrinterOptions}{\void}
+
+Gets the additional options for the print command (e.g. specific printer). The default is nothing.
+
+
+\membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation}
+
+\func{int}{wxGetPrinterOrientation}{\void}
+
+Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+
+
+\membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand}
+
+\func{wxString}{wxGetPrinterPreviewCommand}{\void}
+
+Gets the command used to view a PostScript file. The default depends on the platform.
+
+
+\membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling}
+
+\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
+
+Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
+
+
+\membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation}
+
+\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
+
+Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+
+
+\membersection{::wxSetPrinterCommand}\label{wxsetprintercommand}
+
+\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
+
+Sets the printer command used to print a file. The default is {\tt lpr}.
+
+
+\membersection{::wxSetPrinterFile}\label{wxsetprinterfile}
+
+\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
+
+Sets the PostScript output filename.
+
+
+\membersection{::wxSetPrinterMode}\label{wxsetprintermode}
+
+\func{void}{wxSetPrinterMode}{\param{int }{mode}}
+
+Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
+The default is PS\_PREVIEW.
+
+
+\membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions}
+
+\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
+
+Sets the additional options for the print command (e.g. specific printer). The default is nothing.
+
+
+\membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation}
+
+\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
+
+Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+
+
+\membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand}
+
+\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
+
+Sets the command used to view a PostScript file. The default depends on the platform.
+
+
+\membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling}
+
+\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
+
+Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
+
+
+\membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation}
+
+\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
+
+Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+
+
+
+\section{Clipboard functions}\label{clipsboard}
+
+These clipboard functions are implemented for Windows only. The use of these functions
+is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard}
+class instead.
+
+\wxheading{Include files}
+
+<wx/clipbrd.h>
+
+
+\membersection{::wxClipboardOpen}\label{functionwxclipboardopen}
+
+\func{bool}{wxClipboardOpen}{\void}
+
+Returns true if this application has already opened the clipboard.
+
+
+\membersection{::wxCloseClipboard}\label{wxcloseclipboard}
+
+\func{bool}{wxCloseClipboard}{\void}
+
+Closes the clipboard to allow other applications to use it.
+
+
+\membersection{::wxEmptyClipboard}\label{wxemptyclipboard}
+
+\func{bool}{wxEmptyClipboard}{\void}
+
+Empties the clipboard.
+
+
+\membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats}
+
+\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
+
+Enumerates the formats found in a list of available formats that belong
+to the clipboard. Each call to this function specifies a known
+available format; the function returns the format that appears next in
+the list.
+
+{\it dataFormat} specifies a known format. If this parameter is zero,
+the function returns the first format in the list.
+
+The return value specifies the next known clipboard data format if the
+function is successful. It is zero if the {\it dataFormat} parameter specifies
+the last format in the list of available formats, or if the clipboard
+is not open.
+
+Before it enumerates the formats function, an application must open the clipboard by using the
+wxOpenClipboard function.
+
+
+\membersection{::wxGetClipboardData}\label{wxgetclipboarddata}
+
+\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
+
+Gets data from the clipboard.
+
+{\it dataFormat} may be one of:
+
+\begin{itemize}\itemsep=0pt
+\item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string.
+\item wxCF\_BITMAP: returns a new wxBitmap.
+\end{itemize}
+
+The clipboard must have previously been opened for this call to succeed.
+
+
+\membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname}
+
+\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
+
+Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
+length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
+
+
+\membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable}
+
+\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
+
+Returns true if the given data format is available on the clipboard.
+
+
+\membersection{::wxOpenClipboard}\label{wxopenclipboard}
+
+\func{bool}{wxOpenClipboard}{\void}
+
+Opens the clipboard for passing data to it or getting data from it.
+
+
+\membersection{::wxRegisterClipboardFormat}\label{wxregisterclipboardformat}
+
+\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
+
+Registers the clipboard data format name and returns an identifier.
+
+
+\membersection{::wxSetClipboardData}\label{wxsetclipboarddata}
+
+\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
+
+Passes data to the clipboard.
+
+{\it dataFormat} may be one of:
+
+\begin{itemize}\itemsep=0pt
+\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
+\item wxCF\_BITMAP: {\it data} is a wxBitmap.
+\item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
+\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
+\end{itemize}
+
+The clipboard must have previously been opened for this call to succeed.
+
+
+
+
+\section{Miscellaneous functions}\label{miscellany}
+
+
+\membersection{wxCONCAT}\label{wxconcat}
+
+\func{}{wxCONCAT}{\param{}{x}, \param{}{y}}
+
+This macro returns the concatenation of two tokens \arg{x} and \arg{y}.
+
+
+\membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction}
+
+\func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}}
+
+When loading a function from a DLL you always have to cast the returned
+{\tt void *} pointer to the correct type and, even more annoyingly, you have to
+repeat this type twice if you want to declare and define a function pointer all
+in one line
+
+This macro makes this slightly less painful by allowing you to specify the
+type only once, as the first parameter, and creating a variable of this type
+named after the function but with {\tt pfn} prefix and initialized with the
+function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary}
+\arg{dynlib}.
+
+\wxheading{Parameters}
+
+\docparam{type}{the type of the function}
+
+\docparam{name}{the name of the function to load, not a string (without quotes,
+it is quoted automatically by the macro)}
+
+\docparam{dynlib}{the library to load the function from}
+
+
+
+\membersection{wxEXPLICIT}\label{wxexplicit}
+
+{\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if
+the compiler supports it or nothing otherwise. Thus, it can be used even in the
+code which might have to be compiled with an old compiler without support for
+this language feature but still take advantage of it when it is available.
+
+
+\membersection{::wxGetKeyState}\label{wxgetkeystate}
+
+\func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}}
+
+Returns \true if the key parameter is currently pressed on the keyboard, or
+with modifier keys, (caps lock, etc) if the key is active (the led light is
+on).
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{wxLL}\label{wxll}
+
+\func{wxLongLong\_t}{wxLL}{\param{}{number}}
+
+This macro is defined for the platforms with a native 64 bit integer type and
+allows to define 64 bit compile time constants:
+
+\begin{verbatim}
+ #ifdef wxLongLong_t
+ wxLongLong_t ll = wxLL(0x1234567890abcdef);
+ #endif
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/longlong.h>
+
+\wxheading{See also}
+
+\helpref{wxULL}{wxull}, \helpref{wxLongLong}{wxlonglong}
+
+
+\membersection{wxLongLongFmtSpec}\label{wxlonglongfmtspec}
+
+This macro is defined to contain the {\tt printf()} format specifier using
+which 64 bit integer numbers (i.e. those of type {\tt wxLongLong\_t}) can be
+printed. Example of using it:
+
+\begin{verbatim}
+ #ifdef wxLongLong_t
+ wxLongLong_t ll = wxLL(0x1234567890abcdef);
+ printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
+ #endif
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxLL}{wxll}
+
+\wxheading{Include files}
+
+<wx/longlong.h>
+
+
+\membersection{::wxNewId}\label{wxnewid}
+
+\func{long}{wxNewId}{\void}
+
+Generates an integer identifier unique to this run of the program.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxRegisterId}\label{wxregisterid}
+
+\func{void}{wxRegisterId}{\param{long}{ id}}
+
+Ensures that ids subsequently generated by {\bf NewId} do not clash with
+the given {\bf id}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxDDECleanUp}\label{wxddecleanup}
+
+\func{void}{wxDDECleanUp}{\void}
+
+Called when wxWidgets exits, to clean up the DDE system. This no longer needs to be
+called by the application.
+
+See also \helpref{wxDDEInitialize}{wxddeinitialize}.
+
+\wxheading{Include files}
+
+<wx/dde.h>
+
+
+\membersection{::wxDDEInitialize}\label{wxddeinitialize}
+
+\func{void}{wxDDEInitialize}{\void}
+
+Initializes the DDE system. May be called multiple times without harm.
+
+This no longer needs to be called by the application: it will be called
+by wxWidgets if necessary.
+
+See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},\rtfsp
+\helpref{wxDDECleanUp}{wxddecleanup}.
+
+\wxheading{Include files}
+
+<wx/dde.h>
+
+
+\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
+
+\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = true}}
+
+This function enables or disables all top level windows. It is used by
+\helpref{::wxSafeYield}{wxsafeyield}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxFindMenuItemId}\label{wxfindmenuitemid}
+
+\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
+
+Find a menu item identifier associated with the given frame's menu bar.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxFindWindowByLabel}\label{wxfindwindowbylabel}
+
+\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
+
+{\bf NB:} This function is obsolete, please use
+\helpref{wxWindow::FindWindowByLabel}{wxwindowfindwindowbylabel} instead.
+
+Find a window by its label. Depending on the type of window, the label may be a window title
+or panel item label. If {\it parent} is NULL, the search will start from all top-level
+frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
+The search is recursive in both cases.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
+
+\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
+
+{\bf NB:} This function is obsolete, please use
+\helpref{wxWindow::FindWindowByName}{wxwindowfindwindowbyname} instead.
+
+Find a window by its name (as given in a window constructor or {\bf Create} function call).
+If {\it parent} is NULL, the search will start from all top-level
+frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
+The search is recursive in both cases.
+
+If no such named window is found, {\bf wxFindWindowByLabel} is called.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxFindWindowAtPoint}\label{wxfindwindowatpoint}
+
+\func{wxWindow *}{wxFindWindowAtPoint}{\param{const wxPoint\& }{pt}}
+
+Find the deepest window at the given mouse position in screen coordinates,
+returning the window if found, or NULL if not.
+
+
+\membersection{::wxFindWindowAtPointer}\label{wxfindwindowatpointer}
+
+\func{wxWindow *}{wxFindWindowAtPointer}{\param{wxPoint\& }{pt}}
+
+Find the deepest window at the mouse pointer position, returning the window
+and current pointer position in screen coordinates.
+
+
+\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
+
+\func{wxWindow *}{wxGetActiveWindow}{\void}
+
+Gets the currently active window (Windows only).
+
+\wxheading{Include files}
+
+<wx/windows.h>
+
+
+\membersection{::wxGetDisplayName}\label{wxgetdisplayname}
+
+\func{wxString}{wxGetDisplayName}{\void}
+
+Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetMousePosition}\label{wxgetmouseposition}
+
+\func{wxPoint}{wxGetMousePosition}{\void}
+
+Returns the mouse position in screen coordinates.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetResource}\label{wxgetresource}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{float *}{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{long *}{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{int *}{value}, \param{const wxString\& }{file = NULL}}
+
+Gets a resource value from the resource database (for example, WIN.INI, or
+.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
+otherwise the specified file is used.
+
+Under X, if an application class (wxApp::GetClassName) has been defined,
+it is appended to the string /usr/lib/X11/app-defaults/ to try to find
+an applications default file when merging all resource databases.
+
+The reason for passing the result in an argument is that it
+can be convenient to define a default value, which gets overridden
+if the value exists in the resource file. It saves a separate
+test for that resource's existence, and it also allows
+the overloading of the function for different types.
+
+See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetTopLevelParent}\label{wxgettoplevelparent}
+
+\func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}}
+
+Returns the first top level parent of the given window, or in other words, the
+frame or dialog containing it, or {\tt NULL}.
+
+\wxheading{Include files}
+
+<wx/window.h>
+
+
+\membersection{::wxLoadUserResource}\label{wxloaduserresource}
+
+\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
+
+Loads a user-defined Windows resource as a string. If the resource is found, the function creates
+a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
+
+The resource must be defined in the {\tt .rc} file using the following syntax:
+
+\begin{verbatim}
+myResource TEXT file.ext
+\end{verbatim}
+
+where {\tt file.ext} is a file that the resource compiler can find.
+
+This function is available under Windows only.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxPostDelete}\label{wxpostdelete}
+
+\func{void}{wxPostDelete}{\param{wxObject *}{object}}
+
+Tells the system to delete the specified object when
+all other events have been processed. In some environments, it is
+necessary to use this instead of deleting a frame directly with the
+delete operator, because some GUIs will still send events to a deleted window.
+
+Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxPostEvent}\label{wxpostevent}
+
+\func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}}
+
+In a GUI application, this function posts {\it event} to the specified {\it dest}
+object using \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
+Otherwise, it dispatches {\it event} immediately using
+\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}.
+See the respective documentation for details (and caveats).
+
+\wxheading{Include files}
+
+<wx/app.h>
+
+
+\membersection{::wxSetDisplayName}\label{wxsetdisplayname}
+
+\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
+
+Under X only, sets the current display name. This is the X host and display name such
+as ``colonsay:0.0", and the function indicates which display should be used for creating
+windows from this point on. Setting the display within an application allows multiple
+displays to be used.
+
+See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxStripMenuCodes}\label{wxstripmenucodes}
+
+\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
+
+\func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}}
+
+{\bf NB:} This function is obsolete, please use
+\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead.
+
+Strips any menu codes from {\it in} and places the result
+in {\it out} (or returns the new string, in the first form).
+
+Menu codes include \& (mark the next character with an underline
+as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{wxULL}\label{wxull}
+
+\func{wxLongLong\_t}{wxULL}{\param{}{number}}
+
+This macro is defined for the platforms with a native 64 bit integer type and
+allows to define unsigned 64 bit compile time constants:
+
+\begin{verbatim}
+ #ifdef wxLongLong_t
+ unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef);
+ #endif
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/longlong.h>
+
+\wxheading{See also}
+
+\helpref{wxLL}{wxll}, \helpref{wxLongLong}{wxlonglong}
+
+
+\membersection{::wxWriteResource}\label{wxwriteresource}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{float }{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{long }{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{int }{value}, \param{const wxString\& }{file = NULL}}
+
+Writes a resource value into the resource database (for example, WIN.INI, or
+.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
+otherwise the specified file is used.
+
+Under X, the resource databases are cached until the internal function
+\rtfsp{\bf wxFlushResources} is called automatically on exit, when
+all updated resource databases are written to their files.
+
+Note that it is considered bad manners to write to the .Xdefaults
+file under Unix, although the WIN.INI file is fair game under Windows.
+
+See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+
+\section{Byte order macros}\label{byteordermacros}
+
+The endian-ness issues (that is the difference between big-endian and
+little-endian architectures) are important for the portable programs working
+with the external binary data (for example, data files or data coming from
+network) which is usually in some fixed, platform-independent format. The
+macros are helpful for transforming the data to the correct format.
+
+
+\membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways}
+
+\func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}}
+
+\func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}}
+
+\func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}}
+
+\func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
+
+These macros will swap the bytes of the {\it value} variable from little
+endian to big endian or vice versa unconditionally, i.e. independently of the
+current platform.
+
+
+\membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe}
+
+\func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}}
+
+\func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}}
+
+\func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}}
+
+\func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}}
+
+This macro will swap the bytes of the {\it value} variable from little
+endian to big endian or vice versa if the program is compiled on a
+big-endian architecture (such as Sun work stations). If the program has
+been compiled on a little-endian architecture, the value will be unchanged.
+
+Use these macros to read data from and write data to a file that stores
+data in little-endian (for example Intel i386) format.
+
+
+\membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
+
+\func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}}
+
+\func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}}
+
+\func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}}
+
+\func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}}
+
+This macro will swap the bytes of the {\it value} variable from little
+endian to big endian or vice versa if the program is compiled on a
+little-endian architecture (such as Intel PCs). If the program has
+been compiled on a big-endian architecture, the value will be unchanged.
+
+Use these macros to read data from and write data to a file that stores
+data in big-endian format.
+
+
+
+\section{RTTI functions}\label{rttimacros}
+
+wxWidgets uses its own RTTI ("run-time type identification") system which
+predates the current standard C++ RTTI and so is kept for backwards
+compatibility reasons but also because it allows some things which the
+standard RTTI doesn't directly support (such as creating a class from its
+name).
+
+The standard C++ RTTI can be used in the user code without any problems and in
+general you shouldn't need to use the functions and the macros in this section
+unless you are thinking of modifying or adding any wxWidgets classes.
+
+\wxheading{See also}
+
+\helpref{RTTI overview}{runtimeclassoverview}
+
+
+\membersection{CLASSINFO}\label{classinfo}
+
+\func{wxClassInfo *}{CLASSINFO}{className}
+
+Returns a pointer to the wxClassInfo object associated with this class.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{DECLARE\_ABSTRACT\_CLASS}\label{declareabstractclass}
+
+\func{}{DECLARE\_ABSTRACT\_CLASS}{className}
+
+Used inside a class declaration to declare that the class should be
+made known to the class hierarchy, but objects of this class cannot be created
+dynamically. The same as DECLARE\_CLASS.
+
+Example:
+
+\begin{verbatim}
+class wxCommand: public wxObject
+{
+ DECLARE_ABSTRACT_CLASS(wxCommand)
+
+ private:
+ ...
+ public:
+ ...
+};
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{DECLARE\_APP}\label{declareapp}
+
+\func{}{DECLARE\_APP}{className}
+
+This is used in headers to create a forward declaration of the
+\helpref{wxGetApp}{wxgetapp} function implemented by
+\helpref{IMPLEMENT\_APP}{implementapp}. It creates the declaration
+{\tt className\& wxGetApp(void)}.
+
+Example:
+
+\begin{verbatim}
+ DECLARE_APP(MyApp)
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/app.h>
+
+
+\membersection{DECLARE\_CLASS}\label{declareclass}
+
+\func{}{DECLARE\_CLASS}{className}
+
+Used inside a class declaration to declare that the class should be
+made known to the class hierarchy, but objects of this class cannot be created
+dynamically. The same as DECLARE\_ABSTRACT\_CLASS.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{DECLARE\_DYNAMIC\_CLASS}\label{declaredynamicclass}
+
+\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
+
+Used inside a class declaration to declare that the objects of this class should be dynamically
+creatable from run-time type information.
+
+Example:
+
+\begin{verbatim}
+class wxFrame: public wxWindow
+{
+ DECLARE_DYNAMIC_CLASS(wxFrame)
+
+ private:
+ const wxString& frameTitle;
+ public:
+ ...
+};
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_ABSTRACT\_CLASS}\label{implementabstractclass}
+
+\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information. The same as IMPLEMENT\_CLASS.
+
+Example:
+
+\begin{verbatim}
+IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
+
+wxCommand::wxCommand(void)
+{
+...
+}
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}\label{implementabstractclass2}
+
+\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_APP}\label{implementapp}
+
+\func{}{IMPLEMENT\_APP}{className}
+
+This is used in the application class implementation file to make the application class known to
+wxWidgets for dynamic construction. You use this instead of
+
+Old form:
+
+\begin{verbatim}
+ MyApp myApp;
+\end{verbatim}
+
+New form:
+
+\begin{verbatim}
+ IMPLEMENT_APP(MyApp)
+\end{verbatim}
+
+See also \helpref{DECLARE\_APP}{declareapp}.
+
+\wxheading{Include files}
+
+<wx/app.h>
+
+
+\membersection{IMPLEMENT\_CLASS}\label{implementclass}
+
+\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_CLASS2}\label{implementclass2}
+
+\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
+
+Used in a C++ implementation file to complete the declaration of a
+class that has run-time type information and two base classes. The
+same as IMPLEMENT\_ABSTRACT\_CLASS2.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass}
+
+\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information, and whose instances
+can be created dynamically.
+
+Example:
+
+\begin{verbatim}
+IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
+
+wxFrame::wxFrame(void)
+{
+...
+}
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2}
+
+\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information, and whose instances
+can be created dynamically. Use this for classes derived from two
+base classes.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{wxConstCast}\label{wxconstcast}
+
+\func{classname *}{wxConstCast}{ptr, classname}
+
+This macro expands into {\tt const\_cast<classname *>(ptr)} if the compiler
+supports {\it const\_cast} or into an old, C-style cast, otherwise.
+
+\wxheading{See also}
+
+\helpref{wx\_const\_cast}{wxconstcastraw}\\
+\helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxStaticCast}{wxstaticcast}
+
+
+\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
+
+\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
+
+Creates and returns an object of the given class, if the class has been
+registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
+
+
+\membersection{WXDEBUG\_NEW}\label{debugnew}
+
+\func{}{WXDEBUG\_NEW}{arg}
+
+This is defined in debug mode to be call the redefined new operator
+with filename and line number arguments. The definition is:
+
+\begin{verbatim}
+#define WXDEBUG_NEW new(__FILE__,__LINE__)
+\end{verbatim}
+
+In non-debug mode, this is defined as the normal new operator.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{wxDynamicCast}\label{wxdynamiccast}
+
+\func{classname *}{wxDynamicCast}{ptr, classname}
+
+This macro returns the pointer {\it ptr} cast to the type {\it classname *} if
+the pointer is of this type (the check is done during the run-time) or
+{\tt NULL} otherwise. Usage of this macro is preferred over obsoleted
+wxObject::IsKindOf() function.
+
+The {\it ptr} argument may be {\tt NULL}, in which case {\tt NULL} will be
+returned.
+
+Example:
+
+\begin{verbatim}
+ wxWindow *win = wxWindow::FindFocus();
+ wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
+ if ( text )
+ {
+ // a text control has the focus...
+ }
+ else
+ {
+ // no window has the focus or it is not a text control
+ }
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{RTTI overview}{runtimeclassoverview}\\
+\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
+\helpref{wxConstCast}{wxconstcast}\\
+\helpref{wxStatiicCast}{wxstaticcast}
+
+
+\membersection{wxDynamicCastThis}\label{wxdynamiccastthis}
+
+\func{classname *}{wxDynamicCastThis}{classname}
+
+This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the
+latter provokes spurious compilation warnings from some compilers (because it
+tests whether {\tt this} pointer is non {\tt NULL} which is always true), so
+this macro should be used to avoid them.
+
+\wxheading{See also}
+
+\helpref{wxDynamicCast}{wxdynamiccast}
+
+
+\membersection{wxStaticCast}\label{wxstaticcast}
+
+\func{classname *}{wxStaticCast}{ptr, classname}
+
+This macro checks that the cast is valid in debug mode (an assert failure will
+result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the
+result of executing an equivalent of {\tt static\_cast<classname *>(ptr)}.
+
+\wxheading{See also}
+
+\helpref{wx\_static\_cast}{wxstaticcastraw}\\
+\helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxConstCast}{wxconstcast}
+
+
+\membersection{wx\_const\_cast}\label{wxconstcastraw}
+
+\func{T}{wx\_const\_cast}{T, x}
+
+Same as \texttt{const\_cast<T>(x)} if the compiler supports const cast or
+\texttt{(T)x} for old compilers. Unlike \helpref{wxConstCast}{wxconstcast},
+the cast it to the type \arg{T} and not to \texttt{T *} and also the order of
+arguments is the same as for the standard cast.
+
+\wxheading{See also}
+
+\helpref{wx\_static\_cast}{wxstaticcastraw}\\
+
+
+\membersection{wx\_static\_cast}\label{wxstaticcastraw}
+
+\func{T}{wx\_static\_cast}{T, x}
+
+Same as \texttt{static\_cast<T>(x)} if the compiler supports static cast or
+\texttt{(T)x} for old compilers. Unlike \helpref{wxStaticCast}{wxstaticcast},
+there are no checks being done and the meaning of the macro arguments is exactly
+the same as for the standard static cast, i.e. \arg{T} is the full type name and
+star is not appended to it.
+
+\wxheading{See also}
+
+\helpref{wx\_const\_cast}{wxconstcastraw}\\
+
+
+
+\section{Log functions}\label{logfunctions}
+
+These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
+further information. The functions use (implicitly) the currently active log
+target, so their descriptions here may not apply if the log target is not the
+standard one (installed by wxWidgets in the beginning of the program).
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+
+\membersection{::wxDebugMsg}\label{wxdebugmsg}
+
+\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
+
+{\bf NB:} This function is now obsolete, replaced by \helpref{Log
+functions}{logfunctions} and \helpref{wxLogDebug}{wxlogdebug} in particular.
+
+Display a debugging message; under Windows, this will appear on the
+debugger command window, and under Unix, it will be written to standard
+error.
+
+The syntax is identical to {\bf printf}: pass a format string and a
+variable list of arguments.
+
+{\bf Tip:} under Windows, if your application crashes before the
+message appears in the debugging window, put a wxYield call after
+each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
+(at least for Watcom C++): preformat your messages and use OutputDebugString
+instead.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxError}\label{wxerror}
+
+\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Internal Error"}}
+
+{\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
+instead.
+
+Displays {\it msg} and continues. This writes to standard error under
+Unix, and pops up a message box under Windows. Used for internal
+wxWidgets errors. See also \helpref{wxFatalError}{wxfatalerror}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxFatalError}\label{wxfatalerror}
+
+\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Fatal Error"}}
+
+{\bf NB:} This function is now obsolete, please use
+\helpref{wxLogFatalError}{wxlogfatalerror} instead.
+
+Displays {\it msg} and exits. This writes to standard error under Unix,
+and pops up a message box under Windows. Used for fatal internal
+wxWidgets errors. See also \helpref{wxError}{wxerror}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxLogError}\label{wxlogerror}
+
+\func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+The functions to use for error messages, i.e. the messages that must be shown
+to the user. The default processing is to pop up a message box to inform the
+user about it.
+
+
+\membersection{::wxLogFatalError}\label{wxlogfatalerror}
+
+\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+Like \helpref{wxLogError}{wxlogerror}, but also
+terminates the program with the exit code 3. Using {\it abort()} standard
+function also terminates the program with this exit code.
+
+
+\membersection{::wxLogWarning}\label{wxlogwarning}
+
+\func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+For warnings - they are also normally shown to the user, but don't interrupt
+the program work.
+
+
+\membersection{::wxLogMessage}\label{wxlogmessage}
+
+\func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+For all normal, informational messages. They also appear in a message box by
+default (but it can be changed). Notice that the standard behaviour is to not
+show informational messages if there are any errors later - the logic being
+that the later error messages make the informational messages preceding them
+meaningless.
+
+
+\membersection{::wxLogVerbose}\label{wxlogverbose}
+
+\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+For verbose output. Normally, it is suppressed, but
+might be activated if the user wishes to know more details about the program
+progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
+
+
+\membersection{::wxLogStatus}\label{wxlogstatus}
+
+\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+Messages logged by these functions will appear in the statusbar of the {\it
+frame} or of the top level application window by default (i.e. when using
+the second version of the functions).
+
+If the target frame doesn't have a statusbar, the message will be lost.
+
+
+\membersection{::wxLogSysError}\label{wxlogsyserror}
+
+\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+Mostly used by wxWidgets itself, but might be handy for logging errors after
+system call (API function) failure. It logs the specified message text as well
+as the last system error code ({\it errno} or {\it ::GetLastError()} depending
+on the platform) and the corresponding error message. The second form
+of this function takes the error code explicitly as the first argument.
+
+\wxheading{See also}
+
+\helpref{wxSysErrorCode}{wxsyserrorcode},
+\helpref{wxSysErrorMsg}{wxsyserrormsg}
+
+
+\membersection{::wxLogDebug}\label{wxlogdebug}
+
+\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+The right functions for debug output. They only do something in debug
+mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined) and expand to
+nothing in release mode (otherwise).
+
+
+\membersection{::wxLogTrace}\label{wxlogtrace}
+
+\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
+
+\func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
+
+As {\bf wxLogDebug}, trace functions only do something in debug build and
+expand to nothing in the release one. The reason for making
+it a separate function from it is that usually there are a lot of trace
+messages, so it might make sense to separate them from other debug messages.
+
+The trace messages also usually can be separated into different categories and
+the second and third versions of this function only log the message if the
+{\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This
+allows to selectively trace only some operations and not others by changing
+the value of the trace mask (possible during the run-time).
+
+For the second function (taking a string mask), the message is logged only if
+the mask has been previously enabled by the call to
+\helpref{AddTraceMask}{wxlogaddtracemask} or by setting
+\helpref{{\tt WXTRACE} environment variable}{envvars}.
+The predefined string trace masks
+used by wxWidgets are:
+
+\begin{itemize}\itemsep=0pt
+\item wxTRACE\_MemAlloc: trace memory allocation (new/delete)
+\item wxTRACE\_Messages: trace window messages/X callbacks
+\item wxTRACE\_ResAlloc: trace GDI resource allocation
+\item wxTRACE\_RefCount: trace various ref counting operations
+\item wxTRACE\_OleCalls: trace OLE method calls (Win32 only)
+\end{itemize}
+
+The third version of the function only logs the message if all the bit
+corresponding to the {\it mask} are set in the wxLog trace mask which can be
+set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less
+flexible than the previous one because it doesn't allow defining the user
+trace masks easily - this is why it is deprecated in favour of using string
+trace masks.
+
+\begin{itemize}\itemsep=0pt
+\item wxTraceMemAlloc: trace memory allocation (new/delete)
+\item wxTraceMessages: trace window messages/X callbacks
+\item wxTraceResAlloc: trace GDI resource allocation
+\item wxTraceRefCount: trace various ref counting operations
+\item wxTraceOleCalls: trace OLE method calls (Win32 only)
+\end{itemize}
+
+
+\membersection{::wxSafeShowMessage}\label{wxsafeshowmessage}
+
+\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}}
+
+This function shows a message to the user in a safe way and should be safe to
+call even before the application has been initialized or if it is currently in
+some other strange state (for example, about to crash). Under Windows this
+function shows a message box using a native dialog instead of
+\helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere
+it simply prints the message to the standard output using the title as prefix.
+
+\wxheading{Parameters}
+
+\docparam{title}{The title of the message box shown to the user or the prefix
+of the message string}
+
+\docparam{text}{The text to show to the user}
+
+\wxheading{See also}
+
+\helpref{wxLogFatalError}{wxlogfatalerror}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+
+\membersection{::wxSysErrorCode}\label{wxsyserrorcode}
+
+\func{unsigned long}{wxSysErrorCode}{\void}
+
+Returns the error code from the last system call. This function uses
+{\tt errno} on Unix platforms and {\tt GetLastError} under Win32.
+
+\wxheading{See also}
projects / wxWidgets.git / blobdiff