\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}
-The functions defined in wxWindows are described here.
+The functions and macros defined in wxWindows are described here: you can
+either look up a function using the alphabetical listing of them or find it in
+the corresponding topic.
+
+\section{Alphabetical functions and macros list}
+
+\helpref{CLASSINFO}{classinfo}\\
+\helpref{copystring}{copystring}\\
+\helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\
+\helpref{DECLARE\_APP}{declareapp}\\
+\helpref{DECLARE\_CLASS}{declareclass}\\
+\helpref{DECLARE\_DYNAMIC\_CLASS}{declaredynamicclass}\\
+\helpref{IMPLEMENT\_ABSTRACT\_CLASS2}{implementabstractclass2}\\
+\helpref{IMPLEMENT\_ABSTRACT\_CLASS}{implementabstractclass}\\
+\helpref{IMPLEMENT\_APP}{implementapp}\\
+\helpref{IMPLEMENT\_CLASS2}{implementclass2}\\
+\helpref{IMPLEMENT\_CLASS}{implementclass}\\
+\helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\
+\helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\
+\helpref{WXDEBUG\_NEW}{debugnew}\\
+\helpref{WXTRACELEVEL}{tracelevel}\\
+\helpref{WXTRACE}{trace}\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\
+\helpref{wxASSERT\_MSG}{wxassertmsg}\\
+\helpref{wxASSERT}{wxassert}\\
+\helpref{wxBITMAP}{wxbitmapmacro}\\
+\helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\
+\helpref{wxBell}{wxbell}\\
+\helpref{wxCHECK2\_MSG}{wxcheck2msg}\\
+\helpref{wxCHECK2}{wxcheck2}\\
+\helpref{wxCHECK\_MSG}{wxcheckmsg}\\
+\helpref{wxCHECK\_RET}{wxcheckret}\\
+\helpref{wxCHECK\_VERSION}{wxcheckversion}\\
+\helpref{wxCHECK}{wxcheck}\\
+\helpref{wxClientDisplayRect}{wxclientdisplayrect}\\
+\helpref{wxClipboardOpen}{functionwxclipboardopen}\\
+\helpref{wxCloseClipboard}{wxcloseclipboard}\\
+\helpref{wxColourDisplay}{wxcolourdisplay}\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\
+\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}\\
+\helpref{wxConcatFiles}{wxconcatfiles}\\
+\helpref{wxConstCast}{wxconstcast}\\
+\helpref{wxCopyFile}{wxcopyfile}\\
+\helpref{wxCreateDynamicObject}{wxcreatedynamicobject}\\
+\helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider}\\
+\helpref{wxDDECleanUp}{wxddecleanup}\\
+\helpref{wxDDEInitialize}{wxddeinitialize}\\
+\helpref{wxDROP\_ICON}{wxdropicon}\\
+\helpref{wxDebugMsg}{wxdebugmsg}\\
+\helpref{wxDirExists}{functionwxdirexists}\\
+\helpref{wxDirSelector}{wxdirselector}\\
+\helpref{wxDisplayDepth}{wxdisplaydepth}\\
+\helpref{wxDisplaySize}{wxdisplaysize}\\
+\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
+\helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
+\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
+\helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxEmptyClipboard}{wxemptyclipboard}\\
+\helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\
+\helpref{wxEndBusyCursor}{wxendbusycursor}\\
+\helpref{wxEntry}{wxentry}\\
+\helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\
+\helpref{wxError}{wxerror}\\
+\helpref{wxExecute}{wxexecute}\\
+\helpref{wxExit}{wxexit}\\
+\helpref{wxFAIL\_MSG}{wxfailmsg}\\
+\helpref{wxFAIL}{wxfail}\\
+\helpref{wxFatalError}{wxfatalerror}\\
+\helpref{wxFileExists}{functionwxfileexists}\\
+\helpref{wxFileModificationTime}{wxfilemodificationtime}\\
+\helpref{wxFileNameFromPath}{wxfilenamefrompath}\\
+\helpref{wxFileSelector}{wxfileselector}\\
+\helpref{wxFindFirstFile}{wxfindfirstfile}\\
+\helpref{wxFindMenuItemId}{wxfindmenuitemid}\\
+\helpref{wxFindNextFile}{wxfindnextfile}\\
+\helpref{wxFindWindowAtPointer}{wxfindwindowatpointer}\\
+\helpref{wxFindWindowAtPoint}{wxfindwindowatpoint}\\
+\helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\
+\helpref{wxFindWindowByName}{wxfindwindowbyname}\\
+\helpref{wxGetActiveWindow}{wxgetactivewindow}\\
+\helpref{wxGetClipboardData}{wxgetclipboarddata}\\
+\helpref{wxGetClipboardFormatName}{wxgetclipboardformatname}\\
+\helpref{wxGetColourFromUser}{wxgetcolourfromuser}\\
+\helpref{wxGetCwd}{wxgetcwd}\\
+\helpref{wxGetDiskSpace}{wxgetdiskspace}\\
+\helpref{wxGetDisplayName}{wxgetdisplayname}\\
+\helpref{wxGetElapsedTime}{wxgetelapsedtime}\\
+\helpref{wxGetEmailAddress}{wxgetemailaddress}\\
+\helpref{wxGetEnv}{wxgetenv}\\
+\helpref{wxGetFontFromUser}{wxgetfontfromuser}\\
+\helpref{wxGetFreeMemory}{wxgetfreememory}\\
+\helpref{wxGetFullHostName}{wxgetfullhostname}\\
+\helpref{wxGetHomeDir}{wxgethomedir}\\
+\helpref{wxGetHostName}{wxgethostname}\\
+\helpref{wxGetLocalTimeMillis}{wxgetlocaltimemillis}\\
+\helpref{wxGetLocalTime}{wxgetlocaltime}\\
+\helpref{wxGetMousePosition}{wxgetmouseposition}\\
+\helpref{wxGetMultipleChoices}{wxgetmultiplechoices}\\
+\helpref{wxGetMultipleChoice}{wxgetmultiplechoice}\\
+\helpref{wxGetNumberFromUser}{wxgetnumberfromuser}\\
+\helpref{wxGetOSDirectory}{wxgetosdirectory}\\
+\helpref{wxGetOsDescription}{wxgetosdescription}\\
+\helpref{wxGetOsVersion}{wxgetosversion}\\
+\helpref{wxGetPasswordFromUser}{wxgetpasswordfromuser}\\
+\helpref{wxGetPrinterCommand}{wxgetprintercommand}\\
+\helpref{wxGetPrinterFile}{wxgetprinterfile}\\
+\helpref{wxGetPrinterMode}{wxgetprintermode}\\
+\helpref{wxGetPrinterOptions}{wxgetprinteroptions}\\
+\helpref{wxGetPrinterOrientation}{wxgetprinterorientation}\\
+\helpref{wxGetPrinterPreviewCommand}{wxgetprinterpreviewcommand}\\
+\helpref{wxGetPrinterScaling}{wxgetprinterscaling}\\
+\helpref{wxGetPrinterTranslation}{wxgetprintertranslation}\\
+\helpref{wxGetResource}{wxgetresource}\\
+\helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\
+\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\
+\helpref{wxGetSingleChoice}{wxgetsinglechoice}\\
+\helpref{wxGetTempFileName}{wxgettempfilename}\\
+\helpref{wxGetTextFromUser}{wxgettextfromuser}\\
+\helpref{wxGetTranslation}{wxgettranslation}\\
+\helpref{wxGetUTCTime}{wxgetutctime}\\
+\helpref{wxGetUserHome}{wxgetuserhome}\\
+\helpref{wxGetUserId}{wxgetuserid}\\
+\helpref{wxGetUserName}{wxgetusername}\\
+\helpref{wxGetWorkingDirectory}{wxgetworkingdirectory}\\
+\helpref{wxGetenv}{wxgetenvmacro}\\
+\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\
+\helpref{wxICON}{wxiconmacro}\\
+\helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\
+\helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\
+\helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\
+\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}\\
+\helpref{wxInitialize}{wxinitialize}\\
+\helpref{wxIsAbsolutePath}{wxisabsolutepath}\\
+\helpref{wxIsBusy}{wxisbusy}\\
+\helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\
+\helpref{wxIsEmpty}{wxisempty}\\
+\helpref{wxIsWild}{wxiswild}\\
+\helpref{wxKill}{wxkill}\\
+\helpref{wxLoadUserResource}{wxloaduserresource}\\
+\helpref{wxLogDebug}{wxlogdebug}\\
+\helpref{wxLogError}{wxlogerror}\\
+\helpref{wxLogFatalError}{wxlogfatalerror}\\
+\helpref{wxLogMessage}{wxlogmessage}\\
+\helpref{wxLogStatus}{wxlogstatus}\\
+\helpref{wxLogSysError}{wxlogsyserror}\\
+\helpref{wxLogTrace}{wxlogtrace}\\
+\helpref{wxLogVerbose}{wxlogverbose}\\
+\helpref{wxLogWarning}{wxlogwarning}\\
+\helpref{wxMakeMetafilePlaceable}{wxmakemetafileplaceable}\\
+\helpref{wxMatchWild}{wxmatchwild}\\
+\helpref{wxMessageBox}{wxmessagebox}\\
+\helpref{wxMkdir}{wxmkdir}\\
+\helpref{wxMutexGuiEnter}{wxmutexguienter}\\
+\helpref{wxMutexGuiLeave}{wxmutexguileave}\\
+\helpref{wxNewId}{wxnewid}\\
+\helpref{wxNow}{wxnow}\\
+\helpref{wxOnAssert}{wxonassert}\\
+\helpref{wxOpenClipboard}{wxopenclipboard}\\
+\helpref{wxPathOnly}{wxpathonly}\\
+\helpref{wxPostDelete}{wxpostdelete}\\
+\helpref{wxPostEvent}{wxpostevent}\\
+\helpref{wxRegisterClipboardFormat}{wxregisterclipboardformat}\\
+\helpref{wxRegisterId}{wxregisterid}\\
+\helpref{wxRemoveFile}{wxremovefile}\\
+\helpref{wxRenameFile}{wxrenamefile}\\
+\helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}\\
+\helpref{wxResourceClear}{wxresourceclear}\\
+\helpref{wxResourceCreateBitmap}{wxresourcecreatebitmap}\\
+\helpref{wxResourceCreateIcon}{wxresourcecreateicon}\\
+\helpref{wxResourceCreateMenuBar}{wxresourcecreatemenubar}\\
+\helpref{wxResourceGetIdentifier}{wxresourcegetidentifier}\\
+\helpref{wxResourceParseData}{wxresourcedata}\\
+\helpref{wxResourceParseFile}{wxresourceparsefile}\\
+\helpref{wxResourceParseString}{wxresourceparsestring}\\
+\helpref{wxResourceRegisterBitmapData}{registerbitmapdata}\\
+\helpref{wxResourceRegisterIconData}{wxresourceregistericondata}\\
+\helpref{wxRmdir}{wxrmdir}\\
+\helpref{wxSafeYield}{wxsafeyield}\\
+\helpref{wxSetClipboardData}{wxsetclipboarddata}\\
+\helpref{wxSetCursor}{wxsetcursor}\\
+\helpref{wxSetDisplayName}{wxsetdisplayname}\\
+\helpref{wxSetEnv}{wxsetenv}\\
+\helpref{wxSetPrinterCommand}{wxsetprintercommand}\\
+\helpref{wxSetPrinterFile}{wxsetprinterfile}\\
+\helpref{wxSetPrinterMode}{wxsetprintermode}\\
+\helpref{wxSetPrinterOptions}{wxsetprinteroptions}\\
+\helpref{wxSetPrinterOrientation}{wxsetprinterorientation}\\
+\helpref{wxSetPrinterPreviewCommand}{wxsetprinterpreviewcommand}\\
+\helpref{wxSetPrinterScaling}{wxsetprinterscaling}\\
+\helpref{wxSetPrinterTranslation}{wxsetprintertranslation}\\
+\helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\
+\helpref{wxShell}{wxshell}\\
+\helpref{wxShowTip}{wxshowtip}\\
+\helpref{wxSleep}{wxsleep}\\
+\helpref{wxSnprintf}{wxsnprintf}\\
+\helpref{wxSplitPath}{wxsplitfunction}\\
+\helpref{wxStartTimer}{wxstarttimer}\\
+\helpref{wxStaticCast}{wxstaticcast}\\
+\helpref{wxStricmp}{wxstricmp}\\
+\helpref{wxStringEq}{wxstringeq}\\
+\helpref{wxStringMatch}{wxstringmatch}\\
+\helpref{wxStripMenuCodes}{wxstripmenucodes}\\
+\helpref{wxStrlen}{wxstrlen}\\
+\helpref{wxSysErrorCode}{wxsyserrorcode}\\
+\helpref{wxSysErrorMsg}{wxsyserrormsg}\\
+\helpref{wxToLower}{wxtolower}\\
+\helpref{wxToUpper}{wxtoupper}\\
+\helpref{wxTraceLevel}{wxtracelevel}\\
+\helpref{wxTrace}{wxtrace}\\
+\helpref{wxTransferFileToStream}{wxtransferfiletostream}\\
+\helpref{wxTransferStreamToFile}{wxtransferstreamtofile}\\
+\helpref{wxTrap}{wxtrap}\\
+\helpref{wxUninitialize}{wxuninitialize}\\
+\helpref{wxUnix2DosFilename}{wxunix2dosfilename}\\
+\helpref{wxUnsetEnv}{wxunsetenv}\\
+\helpref{wxUsleep}{wxusleep}\\
+\helpref{wxVsnprintf}{wxvsnprintf}\\
+\helpref{wxWakeUpIdle}{wxwakeupidle}\\
+\helpref{wxWriteResource}{wxwriteresource}\\
+\helpref{wxYield}{wxyield}
+
+\section{Version macros}\label{versionfunctions}
+
+The following constants are defined in wxWindows:
-\section{File functions}\label{filefunctions}
-
-\wxheading{Include files}
-
-<wx/utils.h>
+\begin{itemize}\itemsep=0pt
+\item {\tt wxMAJOR\_VERSION} is the major version of wxWindows
+\item {\tt wxMINOR\_VERSION} is the minor version of wxWindows
+\item {\tt wxRELEASE\_NUMBER} is the release number
+\end{itemize}
-\wxheading{See also}
+For example, the values or these constants for wxWindows 2.1.15 are 2, 1 and
+15.
-\helpref{wxPathList}{wxpathlist}
+Additionally, {\tt wxVERSION\_STRING} is a user-readable string containing
+the full wxWindows version and {\tt wxVERSION\_NUMBER} is a combination of the
+three version numbers above: for 2.1.15, it is 2115 and it is 2200 for
+wxWindows 2.2.
-\membersection{::wxDirExists}
+\wxheading{Include files}
-\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
+<wx/version.h> or <wx/defs.h>
-Returns TRUE if the directory exists.
+\membersection{wxCHECK\_VERSION}\label{wxcheckversion}
-\membersection{::wxDos2UnixFilename}
+\func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}}
-\func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}}
+This is a macro which evaluates to true if the current wxWindows version is at
+least major.minor.release.
-Converts a DOS to a Unix filename by replacing backslashes with forward
-slashes.
+For example, to test if the program is compiled with wxWindows 2.2 or higher,
+the following can be done:
-\membersection{::wxFileExists}
+\begin{verbatim}
+ wxString s;
+#if wxCHECK_VERSION(2, 2, 0)
+ if ( s.StartsWith("foo") )
+#else // replacement code for old version
+ if ( strncmp(s, "foo", 3) == 0 )
+#endif
+ {
+ ...
+ }
+\end{verbatim}
-\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
+\section{Application initialization and termination}\label{appinifunctions}
-Returns TRUE if the file exists.
+The functions in this section are used on application startup/shutdown and also
+to control the behaviour of the main event loop of the GUI programs.
-\membersection{::wxFileNameFromPath}
+\membersection{::wxEntry}\label{wxentry}
-\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
+This initializes wxWindows in a platform-dependent way. Use this if you
+are not using the default wxWindows entry code (e.g. main or WinMain). For example,
+you can initialize wxWindows from an Microsoft Foundation Classes application using
+this function.
-\func{char*}{wxFileNameFromPath}{\param{char* }{path}}
+\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
+ \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
-Returns the filename for a full path. The second form returns a pointer to
-temporary storage that should not be deallocated.
+wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
+function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
+message loop will be entered.
-\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
+\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
+ \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
-\func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}}
+wxWindows initialization under Windows (for applications constructed as a DLL).
-This function does directory searching; returns the first file
-that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
-get the next matching file.
+\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
-{\it spec} may contain wildcards.
+wxWindows initialization under Unix.
-{\it flags} is reserved for future use.
+\wxheading{Remarks}
-For example:
+To clean up wxWindows, call wxApp::OnExit followed by the static function
+wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:
\begin{verbatim}
- wxString f = wxFindFirstFile("/home/project/*.*");
- while ( !f.IsEmpty() )
- {
- ...
- f = wxFindNextFile();
- }
+int CTheApp::ExitInstance()
+{
+ // OnExit isn't called by CleanUp so must be called explicitly.
+ wxTheApp->OnExit();
+ wxApp::CleanUp();
+
+ return CWinApp::ExitInstance();
+}
\end{verbatim}
-\membersection{::wxFindNextFile}\label{wxfindnextfile}
+\wxheading{Include files}
-\func{wxString}{wxFindFirstFile}{\void}
+<wx/app.h>
-Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
+\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions}
-\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
+\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = TRUE}}
-\func{wxString}{wxGetOSDirectory}{\void}
+If {\it doIt} is TRUE, the fatal exceptions (also known as general protection
+faults under Windows or segmentation violations in the Unix world) will be
+caught and passed to \helpref{wxApp::OnFatalException}{wxapponfatalexception}.
+By default, i.e. before this function is called, they will be handled in the
+normal way which usually just means that the application will be terminated.
+Calling wxHandleFatalExceptions() with {\it doIt} equal to FALSE will restore
+this default behaviour.
-Returns the Windows directory under Windows; on other platforms returns the empty string.
+\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
-\membersection{::wxIsAbsolutePath}
+\func{void}{wxInitAllImageHandlers}{\void}
-\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
+Initializes all available image handlers. For a list of available handlers,
+see \helpref{wxImage}{wximage}.
-Returns TRUE if the argument is an absolute filename, i.e. with a slash
-or drive name at the beginning.
+\wxheading{See also}
-\membersection{::wxPathOnly}
+\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
-\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
+\wxheading{Include files}
-Returns the directory part of the filename.
+<wx/image.h>
-\membersection{::wxUnix2DosFilename}
+\membersection{::wxInitialize}\label{wxinitialize}
-\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
+\func{bool}{wxInitialize}{\void}
-Converts a Unix to a DOS filename by replacing forward
-slashes with backslashes.
+This function is used in wxBase only and only if you don't create
+\helpref{wxApp}{wxapp} object at all. In this case you must call it from your
+{\tt main()} function before calling any other wxWindows functions.
-\membersection{::wxConcatFiles}
+If the function returns {\tt FALSE} the initialization could not be performed,
+in this case the library cannot be used and
+\helpref{wxUninitialize}{wxuninitialize} shouldn't be called neither.
-\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
-\param{const wxString\& }{file3}}
+This function may be called several times but
+\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
+call to this function.
-Concatenates {\it file1} and {\it file2} to {\it file3}, returning
-TRUE if successful.
+\wxheading{Include files}
-\membersection{::wxCopyFile}
+<wx/app.h>
-\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
+\membersection{::wxSafeYield}\label{wxsafeyield}
-Copies {\it file1} to {\it file2}, returning TRUE if successful.
+\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
-\membersection{::wxGetCwd}\label{wxgetcwd}
+This function is similar to wxYield, except that it disables the user input to
+all program windows before calling wxYield and re-enables it again
+afterwards. If {\it win} is not NULL, this window will remain enabled,
+allowing the implementation of some limited user interaction.
-\func{wxString}{wxGetCwd}{\void}
+Returns the result of the call to \helpref{::wxYield}{wxyield}.
-Returns a string containing the current (or working) directory.
+\wxheading{Include files}
-\membersection{::wxGetHostName}\label{wxgethostname}
+<wx/utils.h>
-\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int }{sz}}
+\membersection{::wxUninitialize}\label{wxuninitialize}
-Copies the current host machine's name into the supplied buffer.
+\func{void}{wxUninitialize}{\void}
-Under Windows or NT, this function first looks in the environment
-variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
-in the {\bf wxWindows} section of the WIN.INI file is tried.
+This function is for use in console (wxBase) programs only. It must be called
+once for each previous successful call to \helpref{wxInitialize}{wxinitialize}.
-Returns TRUE if successful, FALSE otherwise.
+\wxheading{Include files}
-\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
+<wx/app.h>
-\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
+\membersection{::wxYield}\label{wxyield}
-Copies the user's email address into the supplied buffer, by
-concatenating the values returned by \helpref{wxGetHostName}{wxgethostname}\rtfsp
-and \helpref{wxGetUserId}{wxgetuserid}.
+\func{bool}{wxYield}{\void}
-Returns TRUE if successful, FALSE otherwise.
+Calls \helpref{wxApp::Yield}{wxappyield}.
-\membersection{::wxGetUserId}\label{wxgetuserid}
+This function is kept only for backwards compatibility, please use
+\helpref{wxApp::Yield}{wxappyield}method instead in any new code.
-\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int }{sz}}
+\wxheading{Include files}
-Copies the current user id into the supplied buffer.
+<wx/app.h> or <wx/utils.h>
-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 wxWindows} section of the WIN.INI file is tried.
+\membersection{::wxWakeUpIdle}\label{wxwakeupidle}
-Returns TRUE if successful, FALSE otherwise.
+\func{void}{wxWakeUpIdle}{\void}
-\membersection{::wxGetUserName}\label{wxgetusername}
+This functions wakes up the (internal and platform dependent) idle system, i.e. it
+will force the system to send an idle event even if the system currently {\it is}
+ idle and thus would not send any idle event until after some other event would get
+sent. This is also useful for sending events between two threads and is used by
+the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and
+\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
-\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int }{sz}}
+\wxheading{Include files}
-Copies the current user name into the supplied buffer.
+<wx/app.h>
-Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
-in the {\bf wxWindows} 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.
+\section{Process control functions}\label{processfunctions}
-Returns TRUE if successful, FALSE otherwise.
+The functions in this section are used to launch or terminate the other
+processes.
-\membersection{::wxGetWorkingDirectory}
+\membersection{::wxExecute}\label{wxexecute}
-\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
-This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
+\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
-Copies the current working directory into the buffer if supplied, or
-copies the working directory into new storage (which you must delete yourself)
-if the buffer is NULL.
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
-{\it sz} is the size of the buffer if supplied.
+\perlnote{In wxPerl this function only takes the {\tt command} argument,
+and returns a 2-element list {\tt ( status, output )}, where {\tt output} is
+an array reference.}
-\membersection{::wxGetTempFileName}
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}}
-\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}}
+\perlnote{In wxPerl this function only takes the {\tt command} argument,
+and returns a 3-element list {\tt ( status, output, errors )}, where
+{\tt output} and {\tt errors} are array references.}
-Makes a temporary filename based on {\it prefix}, opens and closes the file,
-and places the name in {\it buf}. If {\it buf} is NULL, new store
-is allocated for the temporary filename using {\it new}.
+Executes another program in Unix or Windows.
-Under Windows, the filename will include the drive and name of the
-directory allocated for temporary files (usually the contents of the
-TEMP variable). Under Unix, the {\tt /tmp} directory is used.
+The first form takes a command string, such as {\tt "emacs file.txt"}.
-It is the application's responsibility to create and delete the file.
+The second form takes an array of values: a command, any number of
+arguments, terminated by NULL.
-\membersection{::wxIsWild}\label{wxiswild}
+The semantics of the third and fourth versions is different from the first two
+and is described in more details below.
-\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
+If {\it flags} parameter contains {\tt wxEXEC\_ASYNC} flag (the default), flow
+of control immediately returns. If it contains {\tt wxEXEC\_SYNC}, the current
+application waits until the other program has terminated.
-Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
+In the case of synchronous execution, the return value is the exit code of
+the process (which terminates by the moment the function returns) and will be
+$-1$ if the process couldn't be started and typically 0 if the process
+terminated successfully. Also, while waiting for the process to
+terminate, wxExecute will call \helpref{wxYield}{wxyield}. The caller
+should ensure that this can cause no recursion, in the simplest case by
+calling \helpref{wxEnableTopLevelWindows(FALSE)}{wxenabletoplevelwindows}.
-\membersection{::wxMatchWild}\label{wxmatchwild}
+For asynchronous execution, however, the return value is the process id and
+zero value indicates that the command could not be executed. As an added
+complication, the return value of $-1$ in this case indicattes that we didn't
+launch a new process, but connected to the running one (this can only happen in
+case of using DDE under Windows for command execution). In particular, in this,
+and only this, case the calling code will not get the notification about
+process termination.
+
+If callback isn't NULL and if execution is asynchronous,
+\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
+the process finishes. Specifying this parameter also allows you to redirect the
+standard input and/or output of the process being launched by calling
+\helpref{Redirect}{wxprocessredirect}. If the child process IO is redirected,
+under Windows the process window is not shown by default (this avoids having to
+flush an unnecessary console for the processes which don't create any windows
+anyhow) but a {\tt wxEXEC\_NOHIDE} flag can be used to prevent this from
+happening, i.e. with this flag the child process window will be shown normally.
-\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
+Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure
+that the new process is a group leader (this will create a new session if
+needed). Calling \helpref{wxKill}{wxkill} with the argument of -pid where pid
+is the process ID of the new process will kill this process as well as all of
+its children (except those which have started their own session).
-Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it
-dot\_special}\/ is TRUE, filenames beginning with a dot are not matched
-with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
+Finally, you may use the third overloaded version of this function to execute
+a process (always synchronously) and capture its output in the array
+{\it output}. The fourth version adds the possibility to additionally capture
+the messages from standard error output in the {\it errors} array.
-\membersection{::wxMkdir}
+See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
+\helpref{Exec sample}{sampleexec}.
-\func{bool}{wxMkdir}{\param{const wxString\& }{dir}}
+\wxheading{Parameters}
-Makes the directory {\it dir}, returning TRUE if successful.
+\docparam{command}{The command to execute and any parameters to pass to it as a
+single string.}
-\membersection{::wxRemoveFile}
+\docparam{argv}{The command to execute should be the first element of this
+array, any additional ones are the command parameters and the array must be
+terminated with a NULL pointer.}
-\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
+\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},
+{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}}
-Removes {\it file}, returning TRUE if successful.
+\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}}
-\membersection{::wxRenameFile}
+\wxheading{Include files}
-\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
+<wx/utils.h>
-Renames {\it file1} to {\it file2}, returning TRUE if successful.
+\membersection{::wxExit}\label{wxexit}
-\membersection{::wxRmdir}
+\func{void}{wxExit}{\void}
-\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
+Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
+Should only be used in an emergency: normally the top-level frame
+should be deleted (after deleting all other frames) to terminate the
+application. See \helpref{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp}.
-Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS.
+\wxheading{Include files}
-The {\it flags} parameter is reserved for future use.
+<wx/app.h>
-\membersection{::wxSetWorkingDirectory}
+\membersection{::wxKill}\label{wxkill}
-\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
+\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}}
-Sets the current working directory, returning TRUE if the operation succeeded.
-Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
+Equivalent to the Unix kill function: send the given signal {\it sig} to the
+process with PID {\it pid}. The valud signal values are
-\membersection{::wxSplitPath}\label{wxsplitfunction}
+\begin{verbatim}
+enum wxSignal
+{
+ wxSIGNONE = 0, // verify if the process exists under Unix
+ wxSIGHUP,
+ wxSIGINT,
+ wxSIGQUIT,
+ wxSIGILL,
+ wxSIGTRAP,
+ wxSIGABRT,
+ wxSIGEMT,
+ wxSIGFPE,
+ wxSIGKILL, // forcefully kill, dangerous!
+ wxSIGBUS,
+ wxSIGSEGV,
+ wxSIGSYS,
+ wxSIGPIPE,
+ wxSIGALRM,
+ wxSIGTERM // terminate the process gently
+};
+\end{verbatim}
-\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{const wxString *}{ path}, \param{const wxString *}{ name}, \param{const wxString *}{ ext}}
+{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
+under both Unix and Windows but all the other signals are equivalent to
+{\tt wxSIGTERM} under Windows.
-This function splits a full file name into components: the path (including possible disk/drive
-specification under Windows), the base name and the extension. Any of the output parameters
-({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
-a particular component.
+Returns 0 on success, -1 on failure. If {\it rc} parameter is not NULL, it will
+be filled with an element of {\tt wxKillError} enum:
-wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
-Windows, however it will not consider backslashes as path separators under Unix (where backslash
-is a valid character in a filename).
+\begin{verbatim}
+enum wxKillError
+{
+ wxKILL_OK, // no error
+ wxKILL_BAD_SIGNAL, // no such signal
+ wxKILL_ACCESS_DENIED, // permission denied
+ wxKILL_NO_PROCESS, // no such process
+ wxKILL_ERROR // another, unspecified error
+};
+\end{verbatim}
-On entry, {\it fullname} should be non NULL (it may be empty though).
+\wxheading{See also}
-On return, {\it path} contains the file path (without the trailing separator), {\it name}
-contains the file name and {\it ext} contains the file extension without leading dot. All
-three of them may be empty if the corresponding component is. The old contents of the
-strings pointed to by these parameters will be overwritten in any case (if the pointers
-are not NULL).
+\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
+\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
+\helpref{Exec sample}{sampleexec}
-\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
+\wxheading{Include files}
-\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
+<wx/utils.h>
-Copies the given file to {\it stream}. Useful when converting an old application to
-use streams (within the document/view framework, for example).
+\membersection{::wxShell}\label{wxshell}
-Use of this function requires the file wx\_doc.h to be included.
+\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
-\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
+Executes a command in an interactive shell window. If no command is
+specified, then just the shell is spawned.
-\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
+See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
-Copies the given stream to the file {\it filename}. Useful when converting an old application to
-use streams (within the document/view framework, for example).
+\wxheading{Include files}
-Use of this function requires the file wx\_doc.h to be included.
+<wx/utils.h>
-\section{String functions}
-\membersection{::copystring}
+\section{Thread functions}\label{threadfunctions}
-\func{char*}{copystring}{\param{const char* }{s}}
+\wxheading{Include files}
-Makes a copy of the string {\it s} using the C++ new operator, so it can be
-deleted with the {\it delete} operator.
+<wx/thread.h>
-\membersection{::wxStringMatch}
+\wxheading{See also}
-\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
- \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
+\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
-Returns TRUE if the substring {\it s1} is found within {\it s2},
-ignoring case if {\it exact} is FALSE. If {\it subString} is FALSE,
-no substring matching is done.
+\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
-\membersection{::wxStringEq}\label{wxstringeq}
+\func{void}{wxMutexGuiEnter}{\void}
-\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
+This function must be called when any thread other than the main GUI thread
+wants to get access to the GUI library. This function will block the execution
+of the calling thread until the main thread (or any other thread holding the
+main GUI lock) leaves the GUI library and no other thread will enter the GUI
+library until the calling thread calls \helpref{::wxMutexGuiLeave()}{wxmutexguileave}.
-A macro defined as:
+Typically, these functions are used like this:
\begin{verbatim}
-#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
-\end{verbatim}
+void MyThread::Foo(void)
+{
+ // before doing any GUI calls we must ensure that this thread is the only
+ // one doing it!
-\membersection{::IsEmpty}\label{isempty}
+ wxMutexGuiEnter();
-\func{bool}{IsEmpty}{\param{const char *}{ p}}
+ // Call GUI here:
+ my_window->DrawSomething();
-Returns TRUE if the string is empty, FALSE otherwise. It is safe to pass NULL
-pointer to this function and it will return TRUE for it.
+ wxMutexGuiLeave();
+}
+\end{verbatim}
-\membersection{::Stricmp}\label{stricmp}
+Note that under GTK, no creation of top-level windows is allowed in any
+thread but the main one.
-\func{int}{Stricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
+This function is only defined on platforms which support preemptive
+threads.
-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.
+\membersection{::wxMutexGuiLeave}\label{wxmutexguileave}
-This function complements the standard C function {\it strcmp()} which performs
-case-sensitive comparison.
+\func{void}{wxMutexGuiLeave}{\void}
-\membersection{::Strlen}\label{strlen}
+See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
-\func{size\_t}{Strlen}{\param{const char *}{ p}}
+This function is only defined on platforms which support preemptive
+threads.
-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 NULL pointer.
+\section{File functions}\label{filefunctions}
-\membersection{::wxGetTranslation}\label{wxgettranslation}
+\wxheading{Include files}
-\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
+<wx/utils.h>
-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{i18n 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 syntax is provided: the \_() macro is
-defined as wxGetTranslation().
+\wxheading{See also}
-\section{Dialog functions}\label{dialogfunctions}
+\helpref{wxPathList}{wxpathlist}\\
+\helpref{wxDir}{wxdir}\\
+\helpref{wxFile}{wxfile}\\
+\helpref{wxFileName}{wxfilename}
-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{::wxDirExists}\label{functionwxdirexists}
-\membersection{::wxFileSelector}\label{wxfileselector}
+\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
-\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}}
+Returns TRUE if the directory exists.
-Pops up a file selector box. In Windows, this is the common file selector
-dialog. In X, this is a file selector box with somewhat less functionality.
-The path and filename are distinct elements of a full file pathname.
-If path is NULL, the current directory will be used. If filename is NULL,
-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, wxHIDE\_READONLY, or 0. They are only significant
-at present in Windows.
+\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename}
-Both the X 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. In the X version, supplying no default name will result in the
-wildcard filter being inserted in the filename text item; the filter is
-ignored if a default name is supplied.
+\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}}
-Under Windows (only), the wildcard may be a specification for multiple
-types of file with a description for each, such as:
+Converts a DOS to a Unix filename by replacing backslashes with forward
+slashes.
-\begin{verbatim}
- "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif"
-\end{verbatim}
+\membersection{::wxFileExists}\label{functionwxfileexists}
-The application must check for a NULL return value (the user pressed
-Cancel). For example:
+\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
-\begin{verbatim}
-const wxString& s = wxFileSelector("Choose a file to open");
-if (s)
-{
- ...
-}
-\end{verbatim}
+Returns TRUE if the file exists. It also returns TRUE if the file is
+a directory.
-\wxheading{Include files}
+\membersection{::wxFileModificationTime}\label{wxfilemodificationtime}
-<wx/filedlg.h>
+\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}}
-\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
+Returns time of last modification of given file.
-\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}}
+\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath}
-Pop up a dialog box with title set to {\it caption}, message {\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.
+\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+\func{char *}{wxFileNameFromPath}{\param{char *}{path}}
-\wxheading{Include files}
+Returns the filename for a full path. The second form returns a pointer to
+temporary storage that should not be deallocated.
-<wx/textdlg.h>
+\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
-\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
+\func{wxString}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}}
-\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}}
+This function does directory searching; returns the first file
+that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
+get the next matching file. Neither will report the current directory "." or the
+parent directory "..".
-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.
+{\it spec} may contain wildcards.
-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.
+{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
-If Cancel is pressed, -1 is returned.
+For example:
-{\it choices} is an array of {\it n} strings for the listbox.
+\begin{verbatim}
+ wxString f = wxFindFirstFile("/home/project/*.*");
+ while ( !f.IsEmpty() )
+ {
+ ...
+ f = wxFindNextFile();
+ }
+\end{verbatim}
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+\membersection{::wxFindNextFile}\label{wxfindnextfile}
-\wxheading{Include files}
+\func{wxString}{wxFindNextFile}{\void}
-<wx/choicdlg.h>
+Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
-\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
+See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
-\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}}
+\membersection{::wxGetDiskSpace}\label{wxgetdiskspace}
-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.
+\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}}
-{\it choices} is an array of {\it n} strings for the listbox.
+This function returns the total number of bytes and number of free bytes on
+the disk containing the directory {\it path} (it should exist). Both
+{\it total} and {\it free} parameters may be {\tt NULL} if the corresponding
+information is not needed.
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+\wxheading{Returns}
-\wxheading{Include files}
+{\tt TRUE} on success, {\tt FALSE} if an error occured (for example, the
+directory doesn't exist).
-<wx/choicdlg.h>
+\wxheading{Portability}
-\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
+This function is implemented for Win16 (only for drives less than 2Gb), Win32,
+Mac OS and generic Unix provided the system has {\tt statfs()} function.
-\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}}
+This function first appeared in wxWindows 2.3.2.
-As {\bf wxGetSingleChoice} but returns the index representing the selected string.
-If the user pressed cancel, -1 is returned.
+\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
-\wxheading{Include files}
+\func{wxString}{wxGetOSDirectory}{\void}
-<wx/choicdlg.h>
+Returns the Windows directory under Windows; on other platforms returns the empty string.
-\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
+\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath}
-\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}}
+\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
-As {\bf wxGetSingleChoice} but takes an array of client data pointers
-corresponding to the strings, and returns one of these pointers.
+Returns TRUE if the argument is an absolute filename, i.e. with a slash
+or drive name at the beginning.
-\wxheading{Include files}
+\membersection{::wxPathOnly}\label{wxpathonly}
-<wx/choicdlg.h>
+\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
-\membersection{::wxMessageBox}\label{wxmessagebox}
+Returns the directory part of the filename.
-\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
- \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
+\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename}
-General purpose message dialog. {\it style} may be a bit list of the
-following identifiers:
+\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
-\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{wxCENTRE}{Centres the text.}
-\twocolitem{wxICON\_EXCLAMATION}{Under Windows, displays an exclamation mark symbol.}
-\twocolitem{wxICON\_HAND}{Under Windows, displays a hand symbol.}
-\twocolitem{wxICON\_QUESTION}{Under Windows, displays a question mark symbol.}
-\twocolitem{wxICON\_INFORMATION}{Under Windows, displays an information symbol.}
-\end{twocollist}
+Converts a Unix to a DOS filename by replacing forward
+slashes with backslashes.
-The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
+\membersection{::wxConcatFiles}\label{wxconcatfiles}
-For example:
+\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
+\param{const wxString\& }{file3}}
-\begin{verbatim}
- ...
- int answer = wxMessageBox("Quit program?", "Confirm",
- wxYES_NO | wxCANCEL, main_frame);
- if (answer == wxYES)
- delete main_frame;
- ...
-\end{verbatim}
+Concatenates {\it file1} and {\it file2} to {\it file3}, returning
+TRUE if successful.
-{\it message} may contain newline characters, in which case the
-message will be split into separate lines, to cater for large messages.
+\membersection{::wxCopyFile}\label{wxcopyfile}
-Under Windows, the native MessageBox function is used unless wxCENTRE
-is specified in the style, in which case a generic function is used.
-This is because the native MessageBox function cannot centre text.
-The symbols are not shown when the generic function is used.
+\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = TRUE}}
-\wxheading{Include files}
+Copies {\it file1} to {\it file2}, returning TRUE if successful. If
+{\it overwrite} parameter is TRUE (default), the destination file is overwritten
+if it exists, but if {\it overwrite} is FALSE, the functions failes in this
+case.
-<wx/msgdlg.h>
+\membersection{::wxGetCwd}\label{wxgetcwd}
-\section{GDI functions}\label{gdifunctions}
+\func{wxString}{wxGetCwd}{\void}
-The following are relevant to the GDI (Graphics Device Interface).
+Returns a string containing the current (or working) directory.
-\wxheading{Include files}
+\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory}
-<wx/gdicmn.h>
+\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}}
-\membersection{::wxColourDisplay}
+This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
-\func{bool}{wxColourDisplay}{\void}
+Copies the current working directory into the buffer if supplied, or
+copies the working directory into new storage (which you must delete yourself)
+if the buffer is NULL.
-Returns TRUE if the display is colour, FALSE otherwise.
+{\it sz} is the size of the buffer if supplied.
-\membersection{::wxDisplayDepth}
+\membersection{::wxGetTempFileName}\label{wxgettempfilename}
-\func{int}{wxDisplayDepth}{\void}
+\func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}}
-Returns the depth of the display (a value of 1 denotes a monochrome display).
+\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
-\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
+%% Makes a temporary filename based on {\it prefix}, opens and closes the file,
+%% and places the name in {\it buf}. If {\it buf} is NULL, new store
+%% is allocated for the temporary filename using {\it new}.
+%%
+%% Under Windows, the filename will include the drive and name of the
+%% directory allocated for temporary files (usually the contents of the
+%% TEMP variable). Under Unix, the {\tt /tmp} directory is used.
+%%
+%% It is the application's responsibility to create and delete the file.
-\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
- \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
+These functions are obsolete, please use\rtfsp
+\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp
+instead.
-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.
+\membersection{::wxIsWild}\label{wxiswild}
-In addition to adding the placeable metafile header, this function adds
-the equivalent of the following code to the start of the metafile data:
+\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
-\begin{verbatim}
- SetMapMode(dc, MM_ANISOTROPIC);
- SetWindowOrg(dc, minX, minY);
- SetWindowExt(dc, maxX - minX, maxY - minY);
-\end{verbatim}
+Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
-This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
+\membersection{::wxMatchWild}\label{wxmatchwild}
-Placeable metafiles may be imported by many Windows applications, and can be
-used in RTF (Rich Text Format) files.
+\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
-{\it scale} allows the specification of scale for the metafile.
+Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it
+dot\_special}\/ is TRUE, filenames beginning with a dot are not matched
+with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
-This function is only available under Windows.
+\membersection{::wxMkdir}\label{wxmkdir}
-\membersection{::wxSetCursor}\label{wxsetcursor}
+\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
-\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
+Makes the directory {\it dir}, returning TRUE if successful.
-Globally sets the cursor; only has an effect in MS Windows.
-See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
+{\it perm} is the access mask for the directory for the systems on which it is
+supported (Unix) and doesn't have effect for the other ones.
-\section{Printer settings}\label{printersettings}
+\membersection{::wxRemoveFile}\label{wxremovefile}
-The following functions are used to control PostScript printing. Under
-Windows, PostScript output can only be sent to a file.
+\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
-\wxheading{Include files}
+Removes {\it file}, returning TRUE if successful.
-<wx/dcps.h>
+\membersection{::wxRenameFile}\label{wxrenamefile}
-\membersection{::wxGetPrinterCommand}
+\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
-\func{wxString}{wxGetPrinterCommand}{\void}
+Renames {\it file1} to {\it file2}, returning TRUE if successful.
-Gets the printer command used to print a file. The default is {\tt lpr}.
+\membersection{::wxRmdir}\label{wxrmdir}
-\membersection{::wxGetPrinterFile}
+\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
-\func{wxString}{wxGetPrinterFile}{\void}
+Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS.
-Gets the PostScript output filename.
+The {\it flags} parameter is reserved for future use.
-\membersection{::wxGetPrinterMode}
+\membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory}
-\func{int}{wxGetPrinterMode}{\void}
+\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
-Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
-The default is PS\_PREVIEW.
+Sets the current working directory, returning TRUE if the operation succeeded.
+Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
-\membersection{::wxGetPrinterOptions}
+\membersection{::wxSplitPath}\label{wxsplitfunction}
-\func{wxString}{wxGetPrinterOptions}{\void}
+\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
-Gets the additional options for the print command (e.g. specific printer). The default is nothing.
+This function splits a full file name into components: the path (including possible disk/drive
+specification under Windows), the base name and the extension. Any of the output parameters
+({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
+a particular component.
-\membersection{::wxGetPrinterOrientation}
+wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
+Windows, however it will not consider backslashes as path separators under Unix (where backslash
+is a valid character in a filename).
-\func{int}{wxGetPrinterOrientation}{\void}
+On entry, {\it fullname} should be non-NULL (it may be empty though).
-Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+On return, {\it path} contains the file path (without the trailing separator), {\it name}
+contains the file name and {\it ext} contains the file extension without leading dot. All
+three of them may be empty if the corresponding component is. The old contents of the
+strings pointed to by these parameters will be overwritten in any case (if the pointers
+are not NULL).
-\membersection{::wxGetPrinterPreviewCommand}
+\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
-\func{wxString}{wxGetPrinterPreviewCommand}{\void}
+\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
-Gets the command used to view a PostScript file. The default depends on the platform.
+Copies the given file to {\it stream}. Useful when converting an old application to
+use streams (within the document/view framework, for example).
-\membersection{::wxGetPrinterScaling}
+\wxheading{Include files}
-\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
+<wx/docview.h>
-Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
+\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
-\membersection{::wxGetPrinterTranslation}
+\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
-\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
+Copies the given stream to the file {\it filename}. Useful when converting an old application to
+use streams (within the document/view framework, for example).
-Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+\wxheading{Include files}
-\membersection{::wxSetPrinterCommand}
+<wx/docview.h>
-\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
+\section{Network, user and OS functions}\label{networkfunctions}
-Sets the printer command used to print a file. The default is {\tt lpr}.
+The functions in this section are used to retrieve information about the
+current computer and/or user characteristics.
-\membersection{::wxSetPrinterFile}
+\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
-\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
+\func{long}{wxGetFreeMemory}{\void}
-Sets the PostScript output filename.
+Returns the amount of free memory in bytes under environments which
+support it, and -1 if not supported. Currently, it is supported only
+under Windows, Linux and Solaris.
-\membersection{::wxSetPrinterMode}
+\wxheading{Include files}
-\func{void}{wxSetPrinterMode}{\param{int }{mode}}
+<wx/utils.h>
-Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
-The default is PS\_PREVIEW.
+\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
-\membersection{::wxSetPrinterOptions}
+\func{wxString}{wxGetFullHostName}{\void}
-\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
+Returns the FQDN (fully qualified domain host name) or an empty string on
+error.
-Sets the additional options for the print command (e.g. specific printer). The default is nothing.
+\wxheading{See also}
-\membersection{::wxSetPrinterOrientation}
+\helpref{wxGetHostName}{wxgethostname}
-\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
+\wxheading{Include files}
-Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+<wx/utils.h>
-\membersection{::wxSetPrinterPreviewCommand}
+\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
-\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
+\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
-Sets the command used to view a PostScript file. The default depends on the platform.
+Copies the user's email address into the supplied buffer, by
+concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
+and \helpref{wxGetUserId}{wxgetuserid}.
-\membersection{::wxSetPrinterScaling}
+Returns TRUE if successful, FALSE otherwise.
-\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
+\wxheading{Include files}
-Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
+<wx/utils.h>
-\membersection{::wxSetPrinterTranslation}
+\membersection{::wxGetHomeDir}\label{wxgethomedir}
-\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
+\func{wxString}{wxGetHomeDir}{\void}
-Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+Return the (current) user's home directory.
-\section{Clipboard functions}\label{clipsboard}
+\wxheading{See also}
-These clipboard functions are implemented for Windows only.
+\helpref{wxGetUserHome}{wxgetuserhome}
\wxheading{Include files}
-<wx/clipbrd.h>
+<wx/utils.h>
-\membersection{::wxClipboardOpen}
+\membersection{::wxGetHostName}\label{wxgethostname}
-\func{bool}{wxClipboardOpen}{\void}
+\func{wxString}{wxGetHostName}{\void}
-Returns TRUE if this application has already opened the clipboard.
+\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
-\membersection{::wxCloseClipboard}
+Copies the current host machine's name into the supplied buffer. Please note
+that the returned name is {\it not} fully qualified, i.e. it does not include
+the domain name.
-\func{bool}{wxCloseClipboard}{\void}
+Under Windows or NT, this function first looks in the environment
+variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
+in the {\bf wxWindows} section of the WIN.INI file is tried.
-Closes the clipboard to allow other applications to use it.
+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.
-\membersection{::wxEmptyClipboard}
+\wxheading{See also}
-\func{bool}{wxEmptyClipboard}{\void}
+\helpref{wxGetFullHostName}{wxgetfullhostname}
-Empties the clipboard.
+\wxheading{Include files}
-\membersection{::wxEnumClipboardFormats}
+<wx/utils.h>
-\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
+\membersection{::wxGetUserId}\label{wxgetuserid}
-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.
+\func{wxString}{wxGetUserId}{\void}
-{\it dataFormat} specifies a known format. If this parameter is zero,
-the function returns the first format in the list.
+\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
-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.
+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).
-Before it enumerates the formats function, an application must open the clipboard by using the
-wxOpenClipboard function.
+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 wxWindows} section of the WIN.INI file is tried.
-\membersection{::wxGetClipboardData}
+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.
-\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
+\wxheading{See also}
-Gets data from the clipboard.
+\helpref{wxGetUserName}{wxgetusername}
-{\it dataFormat} may be one of:
+\wxheading{Include files}
-\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}
+<wx/utils.h>
-The clipboard must have previously been opened for this call to succeed.
+\membersection{::wxGetOsDescription}\label{wxgetosdescription}
-\membersection{::wxGetClipboardFormatName}
+\func{wxString}{wxGetOsDescription}{\void}
-\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
+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}.
-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.
+\wxheading{See also}
-\membersection{::wxIsClipboardFormatAvailable}
+\helpref{::wxGetOsVersion}{wxgetosversion}
-\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
+\wxheading{Include files}
-Returns TRUE if the given data format is available on the clipboard.
+<wx/utils.h>
-\membersection{::wxOpenClipboard}
+\membersection{::wxGetOsVersion}\label{wxgetosversion}
-\func{bool}{wxOpenClipboard}{\void}
+\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
-Opens the clipboard for passing data to it or getting data from it.
+Gets operating system version information.
-\membersection{::wxRegisterClipboardFormat}
+\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.}
+\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}
-\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
+\wxheading{See also}
-Registers the clipboard data format name and returns an identifier.
+\helpref{::wxGetOsDescription}{wxgetosdescription}
-\membersection{::wxSetClipboardData}
+\wxheading{Include files}
-\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
+<wx/utils.h>
-Passes data to the clipboard.
+\membersection{::wxGetUserHome}\label{wxgetuserhome}
-{\it dataFormat} may be one of:
+\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
-\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}
+Returns the home directory for the given user. If the username is empty
+(default value), this function behaves like
+\helpref{wxGetHomeDir}{wxgethomedir}.
-The clipboard must have previously been opened for this call to succeed.
+\wxheading{Include files}
-\section{Miscellaneous functions}\label{miscellany}
+<wx/utils.h>
-\membersection{::wxNewId}
+\membersection{::wxGetUserName}\label{wxgetusername}
-\func{long}{wxNewId}{\void}
+\func{wxString}{wxGetUserName}{\void}
-Generates an integer identifier unique to this run of the program.
+\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
-\wxheading{Include files}
+This function returns the full user name (something like "Mr. John Smith").
-<wx/utils.h>
+Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
+in the {\bf wxWindows} 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.
-\membersection{::wxRegisterId}
+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.
-\func{void}{wxRegisterId}{\param{long}{ id}}
+\wxheading{See also}
-Ensures that ids subsequently generated by {\bf NewId} do not clash with
-the given {\bf id}.
+\helpref{wxGetUserId}{wxgetuserid}
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
+\section{String functions}
-\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
+\membersection{::copystring}\label{copystring}
-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.
+\func{char *}{copystring}{\param{const char *}{s}}
-See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+Makes a copy of the string {\it s} using the C++ new operator, so it can be
+deleted with the {\it delete} operator.
-\wxheading{Include files}
+This function is deprecated, use \helpref{wxString}{wxstring} class instead.
-<wx/utils.h>
+\membersection{::wxIsEmpty}\label{wxisempty}
-\membersection{::wxBell}
+\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
-\func{void}{wxBell}{\void}
+Returns {\tt TRUE} if the pointer is either {\tt NULL} or points to an empty
+string, {\tt FALSE} otherwise.
-Ring the system bell.
+\membersection{::wxStricmp}\label{wxstricmp}
-\wxheading{Include files}
+\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
-<wx/utils.h>
+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.
-\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
+This function complements the standard C function {\it strcmp()} which performs
+case-sensitive comparison.
-\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
+\membersection{::wxStringMatch}\label{wxstringmatch}
-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.
+\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
+ \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
-\membersection{::wxDDECleanUp}\label{wxddecleanup}
+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.
-\func{void}{wxDDECleanUp}{\void}
+This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
-Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
-called by the application.
+\membersection{::wxStringEq}\label{wxstringeq}
-See also helpref{wxDDEInitialize}{wxddeinitialize}.
+\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
-\wxheading{Include files}
+A macro defined as:
-<wx/dde.h>
+\begin{verbatim}
+#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
+\end{verbatim}
-\membersection{::wxDDEInitialize}\label{wxddeinitialize}
+This function is obsolete, use \helpref{wxString}{wxstring} instead.
-\func{void}{wxDDEInitialize}{\void}
+\membersection{::wxStrlen}\label{wxstrlen}
-Initializes the DDE system. May be called multiple times without harm.
+\func{size\_t}{wxStrlen}{\param{const char *}{ p}}
-This no longer needs to be called by the application: it will be called
-by wxWindows if necessary.
+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.
-See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
-\helpref{wxDDECleanUp}{wxddecleanup}.
+\membersection{::wxGetTranslation}\label{wxgettranslation}
-\wxheading{Include files}
+\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
-<wx/dde.h>
+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 syntax is provided: the \_() macro is
+defined as wxGetTranslation().
-\membersection{::wxDebugMsg}\label{wxdebugmsg}
+\membersection{::wxSnprintf}\label{wxsnprintf}
-\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
+\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
-Display a debugging message; under Windows, this will appear on the
-debugger command window, and under Unix, it will be written to standard
-error.
+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.
-The syntax is identical to {\bf printf}: pass a format string and a
-variable list of arguments.
+Returns the number of characters copied to the buffer or -1 if there is not
+enough space.
-Note that under Windows, you can see the debugging messages without a
-debugger if you have the DBWIN debug log application that comes with
-Microsoft C++.
+\wxheading{See also}
-{\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.
+\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+\membersection{::wxToLower}\label{wxtolower}
+
+\func{char}{wxToLower}{\param{char }{ch}}
+
+Converts the character to lower case. This is implemented as a macro for efficiency.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxDisplaySize}
+\membersection{::wxToUpper}\label{wxtoupper}
-\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
+\func{char}{wxToUpper}{\param{char }{ch}}
-Gets the physical size of the display in pixels.
+Converts the character to upper case. This is implemented as a macro for efficiency.
\wxheading{Include files}
-<wx/gdicmn.h>
-
-\membersection{::wxEntry}\label{wxentry}
+<wx/utils.h>
-This initializes wxWindows in a platform-dependent way. Use this if you
-are not using the default wxWindows entry code (e.g. main or WinMain). For example,
-you can initialize wxWindows from an Microsoft Foundation Classes application using
-this function.
+\membersection{::wxVsnprintf}\label{wxvsnprintf}
-\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
- \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
+\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
-wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
-function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
-message loop will be entered.
+The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list }
+argument instead of arbitrary number of parameters.
-\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
- \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
+\wxheading{See also}
-wxWindows initialization under Windows (for applications constructed as a DLL).
+\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
-\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
+\section{Dialog functions}\label{dialogfunctions}
-wxWindows initialization under Unix.
+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.
-\wxheading{Remarks}
+\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
-To clean up wxWindows, call wxApp::OnExit followed by the static function
-wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:
+\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
-\begin{verbatim}
-int CTheApp::ExitInstance()
-{
- // OnExit isn't called by CleanUp so must be called explicitly.
- wxTheApp->OnExit();
- wxApp::CleanUp();
+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.
- return CWinApp::ExitInstance();
-}
-\end{verbatim}
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
\wxheading{Include files}
-<wx/app.h>
+<wx/utils.h>
-\membersection{::wxError}\label{wxerror}
+\membersection{::wxBell}\label{wxbell}
-\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
+\func{void}{wxBell}{\void}
-Displays {\it msg} and continues. This writes to standard error under
-Unix, and pops up a message box under Windows. Used for internal
-wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
+Ring the system bell.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
+\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
-\func{void}{wxEndBusyCursor}{\void}
+\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
+ \param{size\_t }{currentTip}}
-Changes the cursor back to the original cursor, for all windows in the application.
-Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
+This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
+used with \helpref{wxShowTip}{wxshowtip}.
-See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+\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{Include files}
+\wxheading{See also}
-<wx/utils.h>
+\helpref{Tips overview}{tipsoverview}
-\membersection{::wxExecute}\label{wxexecute}
+\wxheading{Include files}
-\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+<wx/tipdlg.h>
-\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\membersection{::wxDirSelector}\label{wxdirselector}
-Executes another program in Unix or Windows.
+\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}}
-The first form takes a command string, such as {\tt "emacs file.txt"}.
+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 second form takes an array of values: a command, any number of
-arguments, terminated by NULL.
+The application must check for an empty return value (if the user pressed
+Cancel). For example:
-If {\it sync} is FALSE (the default), flow of control immediately returns.
-If TRUE, the current application waits until the other program has terminated.
+\begin{verbatim}
+const wxString& dir = wxDirSelector("Choose a folder");
+if ( !dir.empty() )
+{
+ ...
+}
+\end{verbatim}
-In the case of synchronous execution, the return value is trhe exit code of
-the process (which terminates by the moment the function returns) and will be
-$-1$ if the process couldn't be started and typically 0 if the process
-terminated successfully.
+\wxheading{Include files}
-For asynchronous execution, however, the return value is the process id and
-zero value indicates that the command could not be executed.
+<wx/dirdlg.h>
-If callback isn't NULL and if execution is asynchronous (note that callback
-parameter can not be non NULL for synchronous execution),
-\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
-the process finishes.
+\membersection{::wxFileSelector}\label{wxfileselector}
-See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}.
+\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}}
-\wxheading{Include files}
+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, wxHIDE\_READONLY, wxFILE\_MUST\_EXIST, wxMULTIPLE or 0.
-<wx/utils.h>
+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.
-\membersection{::wxExit}\label{wxexit}
+The wildcard may be a specification for multiple types of file
+with a description for each, such as:
-\func{void}{wxExit}{\void}
+\begin{verbatim}
+ "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
+\end{verbatim}
-Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
-Should only be used in an emergency: normally the top-level frame
-should be deleted (after deleting all other frames) to terminate the
-application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
+The application must check for an empty return value (the user pressed
+Cancel). For example:
+
+\begin{verbatim}
+const wxString& s = wxFileSelector("Choose a file to open");
+if (s)
+{
+ ...
+}
+\end{verbatim}
\wxheading{Include files}
-<wx/app.h>
+<wx/filedlg.h>
-\membersection{::wxFatalError}\label{wxfatalerror}
-
-\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
-
-Displays {\it msg} and exits. This writes to standard error under Unix,
-and pops up a message box under Windows. Used for fatal internal
-wxWindows errors. See also \helpref{wxError}{wxerror}.
-
-\wxheading{Include files}
-
-<wx/utils.h>
+\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
-\membersection{::wxFindMenuItemId}
+\func{void}{wxEndBusyCursor}{\void}
-\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
+Changes the cursor back to the original cursor, for all windows in the application.
+Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
-Find a menu item identifier associated with the given frame's menu bar.
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxFindWindowByLabel}
-
-\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
-
-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}
+\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
-<wx/utils.h>
+\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}}
-\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
+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.
-\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
+\wxheading{Parameters}
-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.
+\docparam{parent}{The parent window for the colour selection dialog}
-If no such named window is found, {\bf wxFindWindowByLabel} is called.
+\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
-
-\func{wxWindow *}{wxGetActiveWindow}{\void}
+<wx/colordlg.h>
-Gets the currently active window (Windows only).
+\membersection{::wxGetFontFromUser}\label{wxgetfontfromuser}
-\wxheading{Include files}
+\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}}
-<wx/windows.h>
+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.
-\membersection{::wxGetDisplayName}\label{wxgetdisplayname}
+\wxheading{Parameters}
-\func{wxString}{wxGetDisplayName}{\void}
+\docparam{parent}{The parent window for the font selection dialog}
-Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
+\docparam{fontInit}{If given, this will be the font initially selected in the dialog.}
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxGetHomeDir}
+<wx/fontdlg.h>
-\func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}}
-Fills the buffer with a string representing the user's home directory (Unix only).
+\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
-\wxheading{Include files}
+\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}}
-<wx/utils.h>
+\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}}
-\membersection{::wxGetHostName}
+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.
-\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
+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}.
-Copies the host name of the machine the program is running on into the
-buffer {\it buf}, of maximum size {\it bufSize}, returning TRUE if
-successful. Under Unix, this will return a machine name. Under Windows,
-this returns ``windows''.
+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/utils.h>
+<wx/choicdlg.h>
-\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
+\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.}
-\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}}
+\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
-Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
+\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}}
-If {\it resetTimer} is TRUE (the default), the timer is reset to zero
-by this call.
+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.
-See also \helpref{wxTimer}{wxtimer}.
+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/timer.h>
+<wx/textdlg.h>
-\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
+\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
-\func{long}{wxGetFreeMemory}{\void}
+\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
+ \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}}
-Returns the amount of free memory in Kbytes under environments which
-support it, and -1 if not supported. Currently, returns a positive value
-under Windows, and -1 under Unix.
+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/utils.h>
+<wx/textdlg.h>
-\membersection{::wxGetMousePosition}
+\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
-\func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}}
+\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}}
-Returns the mouse position in screen coordinates.
+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/utils.h>
+<wx/textdlg.h>
-\membersection{::wxGetOsVersion}
+\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
-\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
+\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}}
-Gets operating system version information.
+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.
-\begin{twocollist}\itemsep=0pt
-\twocolitemruled{Platform}{Return tyes}
-\twocolitem{Macintosh}{Return value is wxMACINTOSH.}
-\twocolitem{GTK}{Return value is wxGTK, {\it major} is 1, {\it minor} is 0. (for GTK 1.0.X) }
-\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}{Return value is wxWINDOWS\_NT, {\it major} is 3, {\it minor} is 1.}
-\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 3, {\it minor} is 1.}
-\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}
+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.
-\wxheading{Include files}
+If Cancel is pressed, -1 is returned.
-<wx/utils.h>
+{\it choices} is an array of {\it n} strings for the listbox.
-\membersection{::wxGetResource}\label{wxgetresource}
+If {\it centre} is TRUE, the message text (which may include new line characters)
+is centred; if FALSE, the message is left-justified.
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
+\wxheading{Include files}
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{float *}{value}, \param{const wxString\& }{file = NULL}}
+<wx/choicdlg.h>
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{long *}{value}, \param{const wxString\& }{file = NULL}}
+\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{int *}{value}, \param{const wxString\& }{file = NULL}}
+\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}}
-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.
+\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}}
-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.
+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.
-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.
+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}.
-See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
+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/utils.h>
-
-\membersection{::wxGetUserId}
-
-\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
-
-Copies the user's login identity (such as ``jacs'') into the buffer {\it
-buf}, of maximum size {\it bufSize}, returning TRUE if successful.
-Under Windows, this returns ``user''.
+<wx/choicdlg.h>
-\wxheading{Include files}
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
-<wx/utils.h>
+\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
-\membersection{::wxGetUserName}
+\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{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
+\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}}
-Copies the user's name (such as ``Julian Smart'') into the buffer {\it
-buf}, of maximum size {\it bufSize}, returning TRUE if successful.
-Under Windows, this returns ``unknown''.
+As {\bf wxGetSingleChoice} but returns the index representing the selected
+string. If the user pressed cancel, -1 is returned.
\wxheading{Include files}
-<wx/utils.h>
+<wx/choicdlg.h>
-\membersection{::wxKill}\label{wxkill}
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
-\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
+\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
-Under Unix (the only supported platform), equivalent to the Unix kill function.
-Returns 0 on success, -1 on failure.
+\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}}
-Tip: sending a signal of 0 to a process returns -1 if the process does not exist.
-It does not raise a signal in the receiving process.
+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/utils.h>
+<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}
<wx/utils.h>
-\membersection{::wxLoadUserResource}\label{wxloaduserresource}
+\membersection{::wxMessageBox}\label{wxmessagebox}
-\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
+\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
+ \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
-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.
+General purpose message dialog. {\it style} may be a bit list of the
+following identifiers:
-The resource must be defined in the {\tt .rc} file using the following syntax:
+\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{wxCENTRE}{Centres the text.}
+\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}
-myResource TEXT file.ext
+ ...
+ int answer = wxMessageBox("Quit program?", "Confirm",
+ wxYES_NO | wxCANCEL, main_frame);
+ if (answer == wxYES)
+ delete main_frame;
+ ...
\end{verbatim}
-where {\tt file.ext} is a file that the resource compiler can find.
-
-One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers
-cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed
-using \helpref{wxResourceParseString}{wxresourceparsestring}.
+{\it message} may contain newline characters, in which case the
+message will be split into separate lines, to cater for large messages.
-This function is available under Windows only.
+Under Windows, the native MessageBox function is used unless wxCENTRE
+is specified in the style, in which case a generic function is used.
+This is because the native MessageBox function cannot centre text.
+The symbols are not shown when the generic function is used.
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxNow}\label{wxnow}
+<wx/msgdlg.h>
-\func{wxString}{wxNow}{\void}
+\membersection{::wxShowTip}\label{wxshowtip}
-Returns a string representing the current date and time.
+\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
+ \param{wxTipProvider *}{tipProvider},
+ \param{bool }{showAtStartup = TRUE}}
-\wxheading{Include files}
+This function shows a "startup tip" to the user.
-<wx/utils.h>
+\docparam{parent}{The parent window for the modal dialog}
-\membersection{::wxPostDelete}\label{wxpostdelete}
+\docparam{tipProvider}{An object which is used to get the text of the tips.
+It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
-\func{void}{wxPostDelete}{\param{wxObject *}{object}}
+\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.}
-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.
+\wxheading{See also}
-Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
+\helpref{Tips overview}{tipsoverview}
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxSetDisplayName}\label{wxsetdisplayname}
-
-\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
+<wx/tipdlg.h>
-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.
+\section{GDI functions}\label{gdifunctions}
-See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
+The following are relevant to the GDI (Graphics Device Interface).
\wxheading{Include files}
-<wx/utils.h>
+<wx/gdicmn.h>
-\membersection{::wxShell}\label{wxshell}
+\membersection{wxBITMAP}\label{wxbitmapmacro}
-\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
+\func{}{wxBITMAP}{bitmapName}
-Executes a command in an interactive shell window. If no command is
-specified, then just the shell is spawned.
+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.
-See also \helpref{wxExecute}{wxexecute}.
+\wxheading{See also}
+
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxICON}{wxiconmacro}
\wxheading{Include files}
-<wx/utils.h>
+<wx/gdicmn.h>
-\membersection{::wxSleep}\label{wxsleep}
+\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect}
-\func{void}{wxSleep}{\param{int}{ secs}}
+\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
+\param{int *}{width}, \param{int *}{height}}
-Sleeps for the specified number of seconds.
+\func{wxRect}{wxGetClientDisplayRect}{\void}
-\wxheading{Include files}
+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.
-<wx/utils.h>
+\membersection{::wxColourDisplay}\label{wxcolourdisplay}
-\membersection{::wxStripMenuCodes}
+\func{bool}{wxColourDisplay}{\void}
-\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
+Returns TRUE if the display is colour, FALSE otherwise.
-\func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}}
+\membersection{::wxDisplayDepth}\label{wxdisplaydepth}
-Strips any menu codes from {\it in} and places the result
-in {\it out} (or returns the new string, in the first form).
+\func{int}{wxDisplayDepth}{\void}
-Menu codes include \& (mark the next character with an underline
-as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
+Returns the depth of the display (a value of 1 denotes a monochrome display).
-\wxheading{Include files}
+\membersection{::wxDisplaySize}\label{wxdisplaysize}
-<wx/utils.h>
+\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
-\membersection{::wxStartTimer}\label{wxstarttimer}
+\func{wxSize}{wxGetDisplaySize}{\void}
-\func{void}{wxStartTimer}{\void}
+Returns the display size in pixels.
-Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
+\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm}
-See also \helpref{wxTimer}{wxtimer}.
+\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
-\wxheading{Include files}
+\func{wxSize}{wxGetDisplaySizeMM}{\void}
-<wx/timer.h>
+Returns the display size in millimeters.
-\membersection{::wxToLower}\label{wxtolower}
+\membersection{::wxDROP\_ICON}\label{wxdropicon}
-\func{char}{wxToLower}{\param{char }{ch}}
+\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
-Converts the character to lower case. This is implemented as a macro for efficiency.
+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/utils.h>
+<wx/dnd.h>
-\membersection{::wxToUpper}\label{wxtoupper}
+\membersection{wxICON}\label{wxiconmacro}
-\func{char}{wxToUpper}{\param{char }{ch}}
+\func{}{wxICON}{iconName}
-Converts the character to upper case. This is implemented as a macro for efficiency.
+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{Include files}
+\wxheading{See also}
-<wx/utils.h>
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxBITMAP}{wxbitmapmacro}
-\membersection{::wxTrace}\label{wxtrace}
+\wxheading{Include files}
-\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
+<wx/gdicmn.h>
-Takes printf-style variable argument syntax. Output
-is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
+\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 wxWindows 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}
+
+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{::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 wxWindows 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 wxWindows if necessary.
+
+See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
+\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}}
+
+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}}
+
+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{::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.
+
+One use of this is to store {\tt .wxr} files instead of including the data in the C++ file; some compilers
+cannot cope with the long strings in a {\tt .wxr} file. The resource data can then be parsed
+using \helpref{wxResourceParseString}{wxresourceparsestring}.
+
+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}}
+
+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{::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}
+
+wxWindows uses its own RTTI ("run-time type identification") system which
+predates the current standard C++ RTTI and so is kept for backwards
+compatribility 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 wxWindows 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 wxGetApp function implemented
+by IMPLEMENT\_APP. 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
+wxWindows for dynamic construction. You use this instead of
+
+Old form:
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+\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{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)}.
+
+\helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxConstCast}{wxconstcast}
+
+\section{Resource functions}\label{resourcefuncs}
+
+\overview{Resource functions}{resourceformats}
+
+This section details functions for manipulating wxWindows (.WXR) resource
+files and loading user interface elements from resources.
+
+\normalbox{Please note that this use of the word `resource' is different from that used when talking
+about initialisation file resource reading and writing, using such functions
+as wxWriteResource and wxGetResource. It is just an unfortunate clash of terminology.}
+
+\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
+
+See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
+loading from resource data.
+
+\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
+
+\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
+
+Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
+\tt{#}defining a name to an integer). Unlikely to be used by an application except
+perhaps for implementing resource functionality for interpreted languages.
+
+\membersection{::wxResourceClear}\label{wxresourceclear}
+
+\func{void}{wxResourceClear}{\void}
+
+Clears the wxWindows resource table.
+
+\membersection{::wxResourceCreateBitmap}\label{wxresourcecreatebitmap}
+
+\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
+
+Creates a new bitmap from a file, static data, or Windows resource, given a valid
+wxWindows bitmap resource identifier. For example, if the .WXR file contains
+the following:
+
+\begin{verbatim}
+static const wxString\& project_resource = "bitmap(name = 'project_resource',\
+ bitmap = ['project', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
+ bitmap = ['project.xpm', wxBITMAP_TYPE_XPM, 'X']).";
+\end{verbatim}
+
+then this function can be called as follows:
+
+\begin{verbatim}
+ wxBitmap *bitmap = wxResourceCreateBitmap("project_resource");
+\end{verbatim}
+
+\membersection{::wxResourceCreateIcon}\label{wxresourcecreateicon}
+
+\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
+
+Creates a new icon from a file, static data, or Windows resource, given a valid
+wxWindows icon resource identifier. For example, if the .WXR file contains
+the following:
+
+\begin{verbatim}
+static const wxString\& project_resource = "icon(name = 'project_resource',\
+ icon = ['project', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
+ icon = ['project', wxBITMAP_TYPE_XBM_DATA, 'X']).";
+\end{verbatim}
+
+then this function can be called as follows:
+
+\begin{verbatim}
+ wxIcon *icon = wxResourceCreateIcon("project_resource");
+\end{verbatim}
+
+\membersection{::wxResourceCreateMenuBar}\label{wxresourcecreatemenubar}
+
+\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
+
+Creates a new menu bar given a valid wxWindows menubar resource
+identifier. For example, if the .WXR file contains the following:
+
+\begin{verbatim}
+static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
+ menu = \
+ [\
+ ['&File', 1, '', \
+ ['&Open File', 2, 'Open a file'],\
+ ['&Save File', 3, 'Save a file'],\
+ [],\
+ ['E&xit', 4, 'Exit program']\
+ ],\
+ ['&Help', 5, '', \
+ ['&About', 6, 'About this program']\
+ ]\
+ ]).";
+\end{verbatim}
+
+then this function can be called as follows:
+
+\begin{verbatim}
+ wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
+\end{verbatim}
+
+
+\membersection{::wxResourceGetIdentifier}\label{wxresourcegetidentifier}
+
+\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
+
+Used for retrieving the integer value associated with an identifier.
+A zero value indicates that the identifier was not found.
+
+See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
+
+\membersection{::wxResourceParseData}\label{wxresourcedata}
+
+\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
+
+Parses a string containing one or more wxWindows resource objects. If
+the resource objects are global static data that are included into the
+C++ program, then this function must be called for each variable
+containing the resource data, to make it known to wxWindows.
+
+{\it resource} should contain data in the following form:
+
+\begin{verbatim}
+dialog(name = 'dialog1',
+ style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
+ title = 'Test dialog box',
+ x = 312, y = 234, width = 400, height = 300,
+ modal = 0,
+ control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
+ control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
+ 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
+\end{verbatim}
+
+This function will typically be used after including a {\tt .wxr} file into
+a C++ program as follows:
+
+\begin{verbatim}
+#include "dialog1.wxr"
+\end{verbatim}
+
+Each of the contained resources will declare a new C++ variable, and each
+of these variables should be passed to wxResourceParseData.
+
+\membersection{::wxResourceParseFile}\label{wxresourceparsefile}
+
+\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
+
+Parses a file containing one or more wxWindows resource objects
+in C++-compatible syntax. Use this function to dynamically load
+wxWindows resource data.
+
+\membersection{::wxResourceParseString}\label{wxresourceparsestring}
-\wxheading{Include files}
+\func{bool}{wxResourceParseString}{\param{char *}{s}, \param{wxResourceTable *}{table = NULL}}
-<wx/memory.h>
+Parses a string containing one or more wxWindows resource objects. If
+the resource objects are global static data that are included into the
+C++ program, then this function must be called for each variable
+containing the resource data, to make it known to wxWindows.
-\membersection{::wxTraceLevel}\label{wxtracelevel}
+{\it resource} should contain data with the following form:
-\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
+\begin{verbatim}
+dialog(name = 'dialog1',
+ style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
+ title = 'Test dialog box',
+ x = 312, y = 234, width = 400, height = 300,
+ modal = 0,
+ control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
+ control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
+ 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
+ [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
+\end{verbatim}
-Takes printf-style variable argument syntax. Output
-is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
-The first argument should be the level at which this information is appropriate.
-It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
-this value.
+This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
+load an entire {\tt .wxr file} into a string.
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
-\wxheading{Include files}
+\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char *}{xbm\_data}, \param{int }{width},
+\param{int }{height}, \param{wxResourceTable *}{table = NULL}}
-<wx/memory.h>
+\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char **}{xpm\_data}}
-\membersection{::wxUsleep}\label{wxusleep}
+Makes \tt{#}included XBM or XPM bitmap data known to the wxWindows resource system.
+This is required if other resources will use the bitmap data, since otherwise there
+is no connection between names used in resources, and the global bitmap data.
-\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
+\membersection{::wxResourceRegisterIconData}\label{wxresourceregistericondata}
-Sleeps for the specified number of milliseconds. Notice that usage of this
-function is encouraged instead of calling usleep(3) directly because the
-standard usleep() function is not MT safe.
+Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
-\wxheading{Include files}
+\section{Log functions}\label{logfunctions}
-<wx/utils.h>
+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 wxWindows in the beginning of the program).
-\membersection{::wxWriteResource}\label{wxwriteresource}
+\wxheading{Include files}
-\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
+<wx/log.h>
-\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{float }{value}, \param{const wxString\& }{file = NULL}}
+\membersection{::wxDebugMsg}\label{wxdebugmsg}
-\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{long }{value}, \param{const wxString\& }{file = NULL}}
+\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
-\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{int }{value}, \param{const wxString\& }{file = NULL}}
+{\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogdebug} instead!}
-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.
+Display a debugging message; under Windows, this will appear on the
+debugger command window, and under Unix, it will be written to standard
+error.
-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.
+The syntax is identical to {\bf printf}: pass a format string and a
+variable list of arguments.
-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.
+{\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.
-See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
+This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxYield}\label{wxyield}
+\membersection{::wxError}\label{wxerror}
-\func{bool}{wxYield}{\void}
+\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
-Yields control to pending messages in the windowing system. This can be useful, for example, when a
-time-consuming process writes to a text window. Without an occasional
-yield, the text window will not be updated properly, and (since Windows
-multitasking is cooperative) other processes will not respond.
+This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
+instead.
-Caution should be exercised, however, since yielding may allow the
-user to perform actions which are not compatible with the current task.
-Disabling menu items or whole menus during processing can avoid unwanted
-reentrance of code.
+Displays {\it msg} and continues. This writes to standard error under
+Unix, and pops up a message box under Windows. Used for internal
+wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
\wxheading{Include files}
<wx/utils.h>
-\section{Macros}\label{macros}
-
-These macros are defined in wxWindows.
+\membersection{::wxFatalError}\label{wxfatalerror}
-\membersection{CLASSINFO}\label{classinfo}
+\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
-\func{wxClassInfo *}{CLASSINFO}{className}
+This function is now obsolete, please use
+\helpref{wxLogFatalError}{wxlogfatalerror} instead.
-Returns a pointer to the wxClassInfo object associated with this class.
+Displays {\it msg} and exits. This writes to standard error under Unix,
+and pops up a message box under Windows. Used for fatal internal
+wxWindows errors. See also \helpref{wxError}{wxerror}.
\wxheading{Include files}
-<wx/object.h>
+<wx/utils.h>
-\membersection{WXDEBUG\_NEW}\label{debugnew}
+\membersection{::wxLogError}\label{wxlogerror}
-\func{}{WXDEBUG\_NEW}{arg}
+\func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}}
-This is defined in debug mode to be call the redefined new operator
-with filename and line number arguments. The definition is:
+\func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\begin{verbatim}
-#define WXDEBUG_NEW new(__FILE__,__LINE__)
-\end{verbatim}
+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.
-In non-debug mode, this is defined as the normal new operator.
+\membersection{::wxLogFatalError}\label{wxlogfatalerror}
-\wxheading{Include files}
+\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}}
-<wx/object.h>
+\func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\membersection{DECLARE\_ABSTRACT\_CLASS}
+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.
-\func{}{DECLARE\_ABSTRACT\_CLASS}{className}
+\membersection{::wxLogWarning}\label{wxlogwarning}
-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.
+\func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}}
-Example:
+\func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\begin{verbatim}
-class wxCommand: public wxObject
-{
- DECLARE_ABSTRACT_CLASS(wxCommand)
+For warnings - they are also normally shown to the user, but don't interrupt
+the program work.
- private:
- ...
- public:
- ...
-};
-\end{verbatim}
+\membersection{::wxLogMessage}\label{wxlogmessage}
-\wxheading{Include files}
+\func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}}
-<wx/object.h>
+\func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\membersection{DECLARE\_APP}\label{declareapp}
+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.
-\func{}{DECLARE\_APP}{className}
+\membersection{::wxLogVerbose}\label{wxlogverbose}
-This is used in headers to create a forward declaration of the wxGetApp function implemented
-by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}.
+\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}}
-Example:
+\func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\begin{verbatim}
- DECLARE_APP(MyApp)
-\end{verbatim}
+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}).
-\wxheading{Include files}
+\membersection{::wxLogStatus}\label{wxlogstatus}
-<wx/app.h>
+\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}}
-\membersection{DECLARE\_CLASS}
+\func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\func{}{DECLARE\_CLASS}{className}
+\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}}
-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.
+\func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\wxheading{Include files}
+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).
-<wx/object.h>
+If the target frame doesn't have a statusbar, the message will be lost.
-\membersection{DECLARE\_DYNAMIC\_CLASS}
+\membersection{::wxLogSysError}\label{wxlogsyserror}
-\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
+\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}}
-Used inside a class declaration to declare that the objects of this class should be dynamically
-createable from run-time type information.
+\func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-Example:
+Mostly used by wxWindows 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.
-\begin{verbatim}
-class wxFrame: public wxWindow
-{
- DECLARE_DYNAMIC_CLASS(wxFrame)
+\wxheading{See also}
- private:
- const wxString\& frameTitle;
- public:
- ...
-};
-\end{verbatim}
+\helpref{wxSysErrorCode}{wxsyserrorcode},
+\helpref{wxSysErrorMsg}{wxsyserrormsg}
-\wxheading{Include files}
+\membersection{::wxLogDebug}\label{wxlogdebug}
-<wx/object.h>
+\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}}
-\membersection{IMPLEMENT\_ABSTRACT\_CLASS}
+\func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
+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).
-Used in a C++ implementation file to complete the declaration of
-a class that has run-time type information. The same as IMPLEMENT\_CLASS.
+\membersection{::wxLogTrace}\label{wxlogtrace}
-Example:
+\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}}
-\begin{verbatim}
-IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
+\func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}}
-wxCommand::wxCommand(void)
-{
-...
-}
-\end{verbatim}
+\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
-\wxheading{Include files}
+\func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
-<wx/object.h>
+\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
-\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}
+\func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}}
-\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
+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.
-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.
+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).
-\wxheading{Include files}
+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}. The predefined string trace masks
+used by wxWindows are:
-<wx/object.h>
+\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}
-\membersection{IMPLEMENT\_APP}\label{implementapp}
+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.
-\func{}{IMPLEMENT\_APP}{className}
+\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}
-This is used in the application class implementation file to make the application class known to
-wxWindows for dynamic construction. You use this instead of
+\membersection{::wxSysErrorCode}\label{wxsyserrorcode}
-Old form:
+\func{unsigned long}{wxSysErrorCode}{\void}
-\begin{verbatim}
- MyApp myApp;
-\end{verbatim}
+Returns the error code from the last system call. This function uses
+{\tt errno} on Unix platforms and {\tt GetLastError} under Win32.
-New form:
+\wxheading{See also}
-\begin{verbatim}
- IMPLEMENT_APP(MyApp)
-\end{verbatim}
+\helpref{wxSysErrorMsg}{wxsyserrormsg},
+\helpref{wxLogSysError}{wxlogsyserror}
-See also \helpref{DECLARE\_APP}{declareapp}.
+\membersection{::wxSysErrorMsg}\label{wxsyserrormsg}
-\wxheading{Include files}
+\func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}}
-<wx/app.h>
+Returns the error message corresponding to the given system error code. If
+{\it errCode} is $0$ (default), the last error code (as returned by
+\helpref{wxSysErrorCode}{wxsyserrorcode}) is used.
-\membersection{IMPLEMENT\_CLASS}
+\wxheading{See also}
-\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
+\helpref{wxSysErrorCode}{wxsyserrorcode},
+\helpref{wxLogSysError}{wxlogsyserror}
-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.
+\membersection{WXTRACE}\label{trace}
\wxheading{Include files}
<wx/object.h>
-\membersection{IMPLEMENT\_CLASS2}
+\func{}{WXTRACE}{formatString, ...}
-\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
+Calls wxTrace with printf-style variable argument syntax. Output
+is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
-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.
+This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
\wxheading{Include files}
-<wx/object.h>
-
-\membersection{IMPLEMENT\_DYNAMIC\_CLASS}
-
-\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/memory.h>
-<wx/object.h>
+\membersection{WXTRACELEVEL}\label{tracelevel}
-\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}
+\func{}{WXTRACELEVEL}{level, formatString, ...}
-\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
+Calls wxTraceLevel with printf-style variable argument syntax. Output
+is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
+The first argument should be the level at which this information is appropriate.
+It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
+this value.
-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.
+This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
\wxheading{Include files}
-<wx/object.h>
+<wx/memory.h>
-\membersection{WXTRACE}\label{trace}
+\membersection{::wxTrace}\label{wxtrace}
-\func{}{WXTRACE}{formatString, ...}
+\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
-Calls wxTrace with printf-style variable argument syntax. Output
+Takes printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
-This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
\wxheading{Include files}
<wx/memory.h>
-\membersection{WXTRACELEVEL}\label{tracelevel}
+\membersection{::wxTraceLevel}\label{wxtracelevel}
-\func{}{WXTRACELEVEL}{level, formatString, ...}
+\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
-Calls wxTraceLevel with printf-style variable argument syntax. Output
+Takes printf-style variable argument syntax. Output
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
The first argument should be the level at which this information is appropriate.
It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
<wx/memory.h>
-\section{wxWindows resource functions}\label{resourcefuncs}
+\section{Time functions}\label{timefunctions}
-\overview{wxWindows resource system}{resourceformats}
+The functions in this section deal with getting the current time and
+starting/stopping the global timers. Please note that the timer functions are
+deprecated because they work with one global timer only and
+\helpref{wxTimer}{wxtimer} and/or \helpref{wxStopWatch}{wxstopwatch} classes
+should be used instead. For retrieving the current time, you may also use
+\helpref{wxDateTime::Now}{wxdatetimenow} or
+\helpref{wxDateTime::UNow}{wxdatetimeunow} methods.
-This section details functions for manipulating wxWindows (.WXR) resource
-files and loading user interface elements from resources.
+\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
-\normalbox{Please note that this use of the word `resource' is different from that used when talking
-about initialisation file resource reading and writing, using such functions
-as wxWriteResource and wxGetResource. It's just an unfortunate clash of terminology.}
+\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}}
-\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
+Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
-See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
-loading from resource data.
+If {\it resetTimer} is TRUE (the default), the timer is reset to zero
+by this call.
-{\bf Warning:} this needs updating for wxWindows 2.
+See also \helpref{wxTimer}{wxtimer}.
-\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
+\wxheading{Include files}
-\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
+<wx/timer.h>
-Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
-\verb$#$defining a name to an integer). Unlikely to be used by an application except
-perhaps for implementing resource functionality for interpreted languages.
+\membersection{::wxGetLocalTime}\label{wxgetlocaltime}
-\membersection{::wxResourceClear}
+\func{long}{wxGetLocalTime}{\void}
-\func{void}{wxResourceClear}{\void}
+Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
-Clears the wxWindows resource table.
+\wxheading{See also}
-\membersection{::wxResourceCreateBitmap}
+\helpref{wxDateTime::Now}{wxdatetimenow}
-\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
+\wxheading{Include files}
-Creates a new bitmap from a file, static data, or Windows resource, given a valid
-wxWindows bitmap resource identifier. For example, if the .WXR file contains
-the following:
+<wx/timer.h>
-\begin{verbatim}
-static const wxString\& aiai_resource = "bitmap(name = 'aiai_resource',\
- bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
- bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X']).";
-\end{verbatim}
+\membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis}
-then this function can be called as follows:
+\func{wxLongLone}{wxGetLocalTimeMillis}{\void}
-\begin{verbatim}
- wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource");
-\end{verbatim}
+Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
-\membersection{::wxResourceCreateIcon}
+\wxheading{See also}
-\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
+\helpref{wxDateTime::Now}{wxdatetimenow},\\
+\helpref{wxLongLone}{wxlonglong}
-Creates a new icon from a file, static data, or Windows resource, given a valid
-wxWindows icon resource identifier. For example, if the .WXR file contains
-the following:
+\wxheading{Include files}
-\begin{verbatim}
-static const wxString\& aiai_resource = "icon(name = 'aiai_resource',\
- icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
- icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X']).";
-\end{verbatim}
+<wx/timer.h>
-then this function can be called as follows:
+\membersection{::wxGetUTCTime}\label{wxgetutctime}
-\begin{verbatim}
- wxIcon *icon = wxResourceCreateIcon("aiai_resource");
-\end{verbatim}
+\func{long}{wxGetUTCTime}{\void}
-\membersection{::wxResourceCreateMenuBar}
+Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
-\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
+\wxheading{See also}
-Creates a new menu bar given a valid wxWindows menubar resource
-identifier. For example, if the .WXR file contains the following:
+\helpref{wxDateTime::Now}{wxdatetimenow}
-\begin{verbatim}
-static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
- menu = \
- [\
- ['&File', 1, '', \
- ['&Open File', 2, 'Open a file'],\
- ['&Save File', 3, 'Save a file'],\
- [],\
- ['E&xit', 4, 'Exit program']\
- ],\
- ['&Help', 5, '', \
- ['&About', 6, 'About this program']\
- ]\
- ]).";
-\end{verbatim}
+\wxheading{Include files}
-then this function can be called as follows:
+<wx/timer.h>
-\begin{verbatim}
- wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
-\end{verbatim}
+\membersection{::wxNow}\label{wxnow}
+\func{wxString}{wxNow}{\void}
-\membersection{::wxResourceGetIdentifier}
+Returns a string representing the current date and time.
-\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
+\wxheading{Include files}
-Used for retrieving the integer value associated with an identifier.
-A zero value indicates that the identifier was not found.
+<wx/utils.h>
-See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
+\membersection{::wxSleep}\label{wxsleep}
-\membersection{::wxResourceParseData}\label{wxresourcedata}
+\func{void}{wxSleep}{\param{int}{ secs}}
-\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
+Sleeps for the specified number of seconds.
-Parses a string containing one or more wxWindows resource objects. If
-the resource objects are global static data that are included into the
-C++ program, then this function must be called for each variable
-containing the resource data, to make it known to wxWindows.
+\wxheading{Include files}
-{\it resource} should contain data in the following form:
+<wx/utils.h>
-\begin{verbatim}
-dialog(name = 'dialog1',
- style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
- title = 'Test dialog box',
- x = 312, y = 234, width = 400, height = 300,
- modal = 0,
- control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
- [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
- control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',
- 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
- [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
- [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
-\end{verbatim}
+\membersection{::wxStartTimer}\label{wxstarttimer}
-This function will typically be used after including a {\tt .wxr} file into
-a C++ program as follows:
+\func{void}{wxStartTimer}{\void}
-\begin{verbatim}
-#include "dialog1.wxr"
-\end{verbatim}
+Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
-Each of the contained resources will declare a new C++ variable, and each
-of these variables should be passed to wxResourceParseData.
+See also \helpref{wxTimer}{wxtimer}.
-\membersection{::wxResourceParseFile}
+\wxheading{Include files}
-\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
+<wx/timer.h>
-Parses a file containing one or more wxWindows resource objects
-in C++-compatible syntax. Use this function to dynamically load
-wxWindows resource data.
+\membersection{::wxUsleep}\label{wxusleep}
-\membersection{::wxResourceParseString}\label{wxresourceparsestring}
+\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
+
+Sleeps for the specified number of milliseconds. Notice that usage of this
+function is encouraged instead of calling usleep(3) directly because the
+standard usleep() function is not MT safe.
-\func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
+\wxheading{Include files}
-Parses a string containing one or more wxWindows resource objects. If
-the resource objects are global static data that are included into the
-C++ program, then this function must be called for each variable
-containing the resource data, to make it known to wxWindows.
+<wx/utils.h>
-{\it resource} should contain data with the following form:
+\section{Debugging macros and functions}\label{debugmacros}
+
+Useful macros and functions for error checking and defensive programming.
+wxWindows defines three families of the assert-like macros:
+the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined
+(in other words, in the debug build) but disappear completely in the release
+build. On the other hand, the wxCHECK macros stay event in release builds but a
+check failure doesn't generate any user-visible effects then. Finally, the
+compile time assertions don't happen during the run-time but result in the
+compilation error messages if the condition they check fail.
+
+\wxheading{Include files}
+
+<wx/debug.h>
+
+\membersection{::wxOnAssert}\label{wxonassert}
+
+\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{msg = NULL}}
+
+This function is called whenever one of debugging macros fails (i.e. condition
+is false in an assertion). It is only defined in the debug mode, in release
+builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything.
+
+To override the default behaviour in the debug builds which is to show the user
+a dialog asking whether he wants to abort the program, continue or continue
+ignoring any subsequent assert failures, you may override
+\helpref{wxApp::OnAssert}{wxapponassert} which is called by this function if
+the global application object exists.
+
+\membersection{wxASSERT}\label{wxassert}
+
+\func{}{wxASSERT}{\param{}{condition}}
+
+Assert macro. An error message will be generated if the condition is FALSE in
+debug mode, but nothing will be done in the release build.
+
+Please note that the condition in wxASSERT() should have no side effects
+because it will not be executed in release mode at all.
+
+\wxheading{See also}
+
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
+
+\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize}
+
+\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
+
+This macro results in a
+\helpref{compile time assertion failure}{wxcompiletimeassert} if the size
+of the given type {\it type} is less than {\it size} bits.
+
+You may use it like this, for example:
\begin{verbatim}
-static const wxString\& dialog1 = "dialog(name = 'dialog1',\
- style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',\
- title = 'Test dialog box',\
- x = 312, y = 234, width = 400, height = 300,\
- modal = 0,\
- control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,\
- [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],\
- control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3',\
- 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',\
- [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
- [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).";
+ // we rely on the int being able to hold values up to 2^32
+ wxASSERT_MIN_BITSIZE(int, 32);
+
+ // can't work with the platforms using UTF-8 for wchar_t
+ wxASSERT_MIN_BITSIZE(wchar_t, 16);
\end{verbatim}
-This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
-load an entire {\tt .wxr file} into a string.
+\membersection{wxASSERT\_MSG}\label{wxassertmsg}
-\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
+\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
-\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width},
-\param{int }{height}, \param{wxResourceTable *}{table = NULL}}
+Assert macro with message. An error message will be generated if the condition is FALSE.
-\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}}
+\wxheading{See also}
-Makes \verb$#$included XBM or XPM bitmap data known to the wxWindows resource system.
-This is required if other resources will use the bitmap data, since otherwise there
-is no connection between names used in resources, and the global bitmap data.
+\helpref{wxASSERT}{wxassert},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
-\membersection{::wxResourceRegisterIconData}
+\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert}
-Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
+\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
-\section{Log functions}\label{logfunctions}
+Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the
+specified {\it condition} is false. The compiler error message should include
+the {\it msg} identifier - please note that it must be a valid C++ identifier
+and not a string unlike in the other cases.
-These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
-further information.
+This macro is mostly useful for testing the expressions involing the
+{\tt sizeof} operator as they can't be tested by the preprocessor but it is
+sometimes desirable to test them at the compile time.
-\wxheading{Include files}
+Note that this macro internally declares a struct whose name it tries to make
+unique by using the {\tt \_\_LINE\_\_} in it but it may still not work if you
+use it on the same line in two different source files. In this case you may
+either change the line in which either of them appears on or use the
+\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} macro.
-<wx/log.h>
+\wxheading{See also}
-\membersection{::wxLogError}\label{wxlogerror}
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}
-\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
+\membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2}
-The function 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.
+\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}}
-\membersection{::wxLogFatalError}\label{wxlogfatalerror}
+This macro is identical to \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}
+except that it allows you to specify a unique {\it name} for the struct
+internally defined by this macro to avoid getting the compilation errors
+described \helpref{above}{wxcompiletimeassert}.
-\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}}
+\membersection{wxFAIL}\label{wxfail}
-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.
+\func{}{wxFAIL}{\void}
-\membersection{::wxLogWarning}\label{wxlogwarning}
+Will always generate an assert error if this code is reached (in debug mode).
-\func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}}
+See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
-For warnings - they are also normally shown to the
-user, but don't interrupt the program work.
+\membersection{wxFAIL\_MSG}\label{wxfailmsg}
-\membersection{::wxLogMessage}\label{wxlogmessage}
+\func{}{wxFAIL\_MSG}{\param{}{msg}}
-\func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}}
+Will always generate an assert error with specified message if this code is reached (in debug mode).
-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.
+This macro is useful for marking unreachable" code areas, for example
+it may be used in the "default:" branch of a switch statement if all possible
+cases are processed above.
-\membersection{::wxLogVerbose}\label{wxlogverbose}
+\wxheading{See also}
-\func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}}
+\helpref{wxFAIL}{wxfail}
-For verbose output. Normally, it's 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{wxCHECK}\label{wxcheck}
-\membersection{::wxLogStatus}\label{wxlogstatus}
+\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
-\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}}
+Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
+This check is done even in release mode.
-For status messages - they will go into the status
-bar of the active or specified (as the first argument) \helpref{wxFrame}{wxframe} if it has one.
+\membersection{wxCHECK\_MSG}\label{wxcheckmsg}
-\membersection{::wxLogSysError}\label{wxlogsyserror}
+\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
-\func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}}
+Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
+This check is done even in release mode.
-Mostly used by wxWindows 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 explitly as the
-first argument.
+This macro may be only used in non void functions, see also
+\helpref{wxCHECK\_RET}{wxcheckret}.
-\membersection{::wxLogDebug}\label{wxlogdebug}
+\membersection{wxCHECK\_RET}\label{wxcheckret}
-\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}}
+\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}}
-The right function for debug output. It only
-does anything at all in the debug mode (when the preprocessor symbol \_\_WXDEBUG\_\_ is defined)
-and expands to nothing in release mode (otherwise).
+Checks that the condition is true, and returns if not (FAILs with given error
+message in debug mode). This check is done even in release mode.
-\membersection{::wxLogTrace}\label{wxlogtrace}
+This macro should be used in void functions instead of
+\helpref{wxCHECK\_MSG}{wxcheckmsg}.
-\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}}
+\membersection{wxCHECK2}\label{wxcheck2}
-\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}}
+\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}}
-As {\bf wxLogDebug}, only does something in debug
-build. 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 which would be flooded in them. Moreover, the second
-version of this function takes a trace mask as the first argument which allows
-to further restrict the amount of messages generated. The value of {\it mask} can be:
+Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute
+{\it operation} if it is not. This is a generalisation of
+\helpref{wxCHECK}{wxcheck} and may be used when something else than just
+returning from the function must be done when the {\it condition} is false.
-\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
-\end{itemize}
+This check is done even in release mode.
-\section{Debugging macros and functions}\label{debugmacros}
+\membersection{wxCHECK2\_MSG}\label{wxcheck2msg}
+
+\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}}
+
+This is the same as \helpref{wxCHECK2}{wxcheck2}, but
+\helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
+instead of wxFAIL() if the {\it condition} is false.
-Useful macros and functins for error checking and defensive programming. ASSERTs are only
-compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
-builds.
+\membersection{::wxTrap}\label{wxtrap}
+
+\func{void}{wxTrap}{\void}
+
+In debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) this function generates a
+debugger exception meaning that the control is passed to the debugger if one is
+attached to the process. Otherwise the program just terminates abnormally.
+
+In release mode this function does nothing.
\wxheading{Include files}
<wx/debug.h>
-\membersection{::wxOnAssert}\label{wxonassert}
+\section{Environment access functions}\label{environfunctions}
-\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}}
+The functions in this section allow to access (get) or change value of
+environment variables in a portable way. They are currently implemented under
+Win32 and POSIX-like systems (Unix).
-This function may be redefined to do something non trivial and is called
-whenever one of debugging macros fails (i.e. condition is false in an
-assertion).
-% TODO: this should probably be an overridable in wxApp.
+% TODO add some stuff about env var inheriting but not propagating upwards (VZ)
-\membersection{wxASSERT}\label{wxassert}
+\wxheading{Include files}
-\func{}{wxASSERT}{\param{}{condition}}
+<wx/utils.h>
-Assert macro. An error message will be generated if the condition is FALSE.
+\membersection{wxGetenv}\label{wxgetenvmacro}
-\membersection{wxASSERT\_MSG}\label{wxassertmsg}
+\func{wxChar *}{wxGetEnv}{\param{const wxString\&}{ var}}
-\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
+This is a macro defined as {\tt getenv()} or its wide char version in Unicode
+mode.
-Assert macro with message. An error message will be generated if the condition is FALSE.
+Note that under Win32 it may not return correct value for the variables set
+with \helpref{wxSetEnv}{wxsetenv}, use \helpref{wxGetEnv}{wxgetenv} function
+instead.
-\membersection{wxFAIL}\label{wxfail}
+\membersection{wxGetEnv}\label{wxgetenv}
-\func{}{wxFAIL}{\param{}{condition}}
+\func{bool}{wxGetEnv}{\param{const wxString\&}{ var}, \param{wxString *}{value}}
-Will always generate an assert error if this code is reached (in debug mode).
+Returns the current value of the environment variable {\it var} in {\it value}.
+{\it value} may be {\tt NULL} if you just want to know if the variable exists
+and are not interested in its value.
-\membersection{wxFAIL\_MSG}\label{wxfailmsg}
+Returns {\tt TRUE} if the variable exists, {\tt FALSE} otherwise.
-\func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}}
+\membersection{wxSetEnv}\label{wxsetenv}
-Will always generate an assert error with specified message if this code is reached (in debug mode).
+\func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxChar *}{value}}
-\membersection{wxCHECK}\label{wxcheck}
+Sets the value of the environment variable {\it var} (adding it if necessary)
+to {\it value}.
-\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
+Returns {\tt TRUE} on success.
-Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
-This check is done even in release mode.
+\membersection{wxUnsetEnv}\label{wxunsetenv}
-\membersection{wxCHECK\_MSG}\label{wxcheckmsg}
+\func{bool}{wxUnsetEnv}{\param{const wxString\&}{ var}}
-\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}}
+Removes the variable {\it var} from the environment.
+\helpref{wxGetEnv}{wxgetenv} will return {\tt NULL} after the call to this
+function.
-Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
-This check is done even in release mode.
+Returns {\tt TRUE} on success.
projects / wxWidgets.git / blobdiff