\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}
-The functions and macros 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{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{copystring}{copystring}\\
+\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}{wxclipboardopen}\\
+\helpref{wxCloseClipboard}{wxcloseclipboard}\\
+\helpref{wxColourDisplay}{wxcolourdisplay}\\
+\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}{wxdirexists}\\
+\helpref{wxDirSelector}{wxdirselector}\\
+\helpref{wxDisplayDepth}{wxdisplaydepth}\\
+\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
+\helpref{wxDisplaySize}{wxdisplaysize}\\
+\helpref{wxDisplaySize}{wxdisplaysize}\\
+\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}{wxfileexists}\\
+\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{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}
\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 wxRELASE\_NUMBER} is the release number
+\item {\tt wxRELEASE\_NUMBER} is the release number
\end{itemize}
For example, the values or these constants for wxWindows 2.1.15 are 2, 1 and
}
\end{verbatim}
-\section{Thread functions}\label{threadfunctions}
+\section{Application initialization and termination}\label{appinifunctions}
-\wxheading{Include files}
+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.
-<wx/thread.h>
+\membersection{::wxEntry}\label{wxentry}
-\wxheading{See also}
+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.
-\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
+\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
+ \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
-\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
+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.
-\func{void}{wxMutexGuiEnter}{\void}
+\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
+ \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
-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}.
+wxWindows initialization under Windows (for applications constructed as a DLL).
-Typically, these functions are used like this:
+\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
-\begin{verbatim}
-void MyThread::Foo(void)
-{
- // before doing any GUI calls we must ensure that this thread is the only
- // one doing it!
+wxWindows initialization under Unix.
- wxMutexGuiEnter();
+\wxheading{Remarks}
- // Call GUI here:
- my_window->DrawSomething();
+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:
- wxMutexGuiLeave();
+\begin{verbatim}
+int CTheApp::ExitInstance()
+{
+ // OnExit isn't called by CleanUp so must be called explicitly.
+ wxTheApp->OnExit();
+ wxApp::CleanUp();
+
+ return CWinApp::ExitInstance();
}
\end{verbatim}
-Note that under GTK, no creation of top-level windows is allowed in any
-thread but the main one.
-
-This function is only defined on platforms which support preemptive
-threads.
-
-\membersection{::wxMutexGuiLeave}\label{wxmutexguileave}
-
-\func{void}{wxMutexGuiLeave}{\void}
-
-See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
-
-This function is only defined on platforms which support preemptive
-threads.
-
-\section{File functions}\label{filefunctions}
-
\wxheading{Include files}
-<wx/utils.h>
-
-\wxheading{See also}
+<wx/app.h>
-\helpref{wxPathList}{wxpathlist}, \helpref{wxDir}{wxdir}, \helpref{wxFile}{wxfile}
+\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions}
-\membersection{::wxDirExists}
+\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = TRUE}}
-\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
+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 TRUE if the directory exists.
+\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
-\membersection{::wxDos2UnixFilename}
+\func{void}{wxInitAllImageHandlers}{\void}
-\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}}
+Initializes all available image handlers. For a list of available handlers,
+see \helpref{wxImage}{wximage}.
-Converts a DOS to a Unix filename by replacing backslashes with forward
-slashes.
+\wxheading{See also}
-\membersection{::wxFileExists}
+\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
-\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
+\wxheading{Include files}
-Returns TRUE if the file exists. It also returns TRUE if the file is
-a directory.
+<wx/image.h>
-\membersection{::wxFileModificationTime}\label{wxfilemodificationtime}
+\membersection{::wxInitialize}\label{wxinitialize}
-\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}}
+\func{bool}{wxInitialize}{\void}
-Returns time of last modification of given file.
+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{::wxFileNameFromPath}
+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{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
+This function may be called several times but
+\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
+call to this function.
-\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/app.h>
-\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
+\membersection{::wxSafeYield}\label{wxsafeyield}
-\func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}}
+\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
-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 "..".
+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.
-{\it spec} may contain wildcards.
+Returns the result of the call to \helpref{::wxYield}{wxyield}.
-{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
+\wxheading{Include files}
-For example:
+<wx/utils.h>
-\begin{verbatim}
- wxString f = wxFindFirstFile("/home/project/*.*");
- while ( !f.IsEmpty() )
- {
- ...
- f = wxFindNextFile();
- }
-\end{verbatim}
+\membersection{::wxUninitialize}\label{wxuninitialize}
-\membersection{::wxFindNextFile}\label{wxfindnextfile}
+\func{void}{wxUninitialize}{\void}
-\func{wxString}{wxFindNextFile}{\void}
+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 the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
+\wxheading{Include files}
-See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
+<wx/app.h>
-\membersection{::wxGetDiskSpace}\label{wxgetdiskspace}
+\membersection{::wxYield}\label{wxyield}
-\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \path{wxLongLong }{*total = NULL}, \path{wxLongLong }{*free = NULL}}
+\func{bool}{wxYield}{\void}
-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.
+Calls \helpref{wxApp::Yield}{wxappyield}.
-\wxheading{Returns}
+This function is kept only for backwards compatibility, please use
+\helpref{wxApp::Yield}{wxappyield}method instead in any new code.
-{\tt TRUE} on success, {\tt FALSE} if an error occured (for example, the
-directory doesn't exist).
+\wxheading{Include files}
-\wxheading{Portability}
+<wx/app.h> or <wx/utils.h>
-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.
+\membersection{::wxWakeUpIdle}\label{wxwakeupidle}
-This function first appeared in wxWindows 2.3.2.
+\func{void}{wxWakeUpIdle}{\void}
-\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
+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{wxString}{wxGetOSDirectory}{\void}
+\wxheading{Include files}
-Returns the Windows directory under Windows; on other platforms returns the empty string.
+<wx/app.h>
-\membersection{::wxIsAbsolutePath}
+\section{Process control functions}\label{processfunctions}
-\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
+The functions in this section are used to launch or terminate the other
+processes.
-Returns TRUE if the argument is an absolute filename, i.e. with a slash
-or drive name at the beginning.
+\membersection{::wxExecute}\label{wxexecute}
-\membersection{::wxPathOnly}
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
-\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
+\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
-Returns the directory part of the filename.
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
-\membersection{::wxUnix2DosFilename}
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}}
-\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
+Executes another program in Unix or Windows.
-Converts a Unix to a DOS filename by replacing forward
-slashes with backslashes.
+The first form takes a command string, such as {\tt "emacs file.txt"}.
-\membersection{::wxConcatFiles}
+The second form takes an array of values: a command, any number of
+arguments, terminated by NULL.
-\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
-\param{const wxString\& }{file3}}
+The semantics of the third and fourth versions is different from the first two
+and is described in more details below.
-Concatenates {\it file1} and {\it file2} to {\it file3}, returning
-TRUE if successful.
+If {\it sync} is FALSE (the default), flow of control immediately returns.
+If TRUE, the current application waits until the other program has terminated.
-\membersection{::wxCopyFile}
+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}.
-\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = TRUE}}
+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.
-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.
+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{::wxGetCwd}\label{wxgetcwd}
+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.
-\func{wxString}{wxGetCwd}{\void}
+See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
+\helpref{Exec sample}{sampleexec}.
-Returns a string containing the current (or working) directory.
+\wxheading{Include files}
-\membersection{::wxGetWorkingDirectory}
+<wx/utils.h>
-\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
+\membersection{::wxExit}\label{wxexit}
-This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
+\func{void}{wxExit}{\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.
+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}.
-{\it sz} is the size of the buffer if supplied.
+\wxheading{Include files}
-\membersection{::wxGetTempFileName}
+<wx/app.h>
-\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}}
+\membersection{::wxKill}\label{wxkill}
-\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
+\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}}
-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}.
+Equivalent to the Unix kill function: send the given signal {\it sig} to the
+process with PID {\it pid}. The valud signal values are
-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.
+\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}
-It is the application's responsibility to create and delete the file.
+{\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.
-\membersection{::wxIsWild}\label{wxiswild}
+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:
-\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
+\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}
-Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
+\wxheading{See also}
-\membersection{::wxMatchWild}\label{wxmatchwild}
+\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
+\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
+\helpref{Exec sample}{sampleexec}
-\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
+\wxheading{Include files}
-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}.
+<wx/utils.h>
-\membersection{::wxMkdir}
+\membersection{::wxShell}\label{wxshell}
-\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
+\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
-Makes the directory {\it dir}, returning TRUE if successful.
+Executes a command in an interactive shell window. If no command is
+specified, then just the shell is spawned.
-{\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.
+See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
-\membersection{::wxRemoveFile}
+\wxheading{Include files}
-\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
+<wx/utils.h>
-Removes {\it file}, returning TRUE if successful.
-\membersection{::wxRenameFile}
+\section{Thread functions}\label{threadfunctions}
-\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
+\wxheading{Include files}
-Renames {\it file1} to {\it file2}, returning TRUE if successful.
+<wx/thread.h>
-\membersection{::wxRmdir}
+\wxheading{See also}
-\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
+\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
-Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS.
+\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
-The {\it flags} parameter is reserved for future use.
+\func{void}{wxMutexGuiEnter}{\void}
-\membersection{::wxSetWorkingDirectory}
+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}.
-\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
+Typically, these functions are used like this:
-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.
+\begin{verbatim}
+void MyThread::Foo(void)
+{
+ // before doing any GUI calls we must ensure that this thread is the only
+ // one doing it!
-\membersection{::wxSplitPath}\label{wxsplitfunction}
+ wxMutexGuiEnter();
-\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
+ // Call GUI here:
+ my_window->DrawSomething();
-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.
+ wxMutexGuiLeave();
+}
+\end{verbatim}
-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).
+Note that under GTK, no creation of top-level windows is allowed in any
+thread but the main one.
-On entry, {\it fullname} should be non-NULL (it may be empty though).
+This function is only defined on platforms which support preemptive
+threads.
-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{::wxMutexGuiLeave}\label{wxmutexguileave}
-\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
+\func{void}{wxMutexGuiLeave}{\void}
-\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
+See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
-Copies the given file to {\it stream}. Useful when converting an old application to
-use streams (within the document/view framework, for example).
+This function is only defined on platforms which support preemptive
+threads.
-Use of this function requires the file wx\_doc.h to be included.
+\section{File functions}\label{filefunctions}
-\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
+\wxheading{Include files}
-\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
+<wx/utils.h>
-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{See also}
-Use of this function requires the file wx\_doc.h to be included.
+\helpref{wxPathList}{wxpathlist}\\
+\helpref{wxDir}{wxdir}\\
+\helpref{wxFile}{wxfile}\\
+\helpref{wxFileName}{wxfilename}
-\section{Network functions}\label{networkfunctions}
+\membersection{::wxDirExists}\label{wxdirexists}
-\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
+\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
-\func{wxString}{wxGetFullHostName}{\void}
+Returns TRUE if the directory exists.
-Returns the FQDN (fully qualified domain host name) or an empty string on
-error.
+\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename}
-\wxheading{See also}
+\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}}
-\helpref{wxGetHostName}{wxgethostname}
+Converts a DOS to a Unix filename by replacing backslashes with forward
+slashes.
-\wxheading{Include files}
+\membersection{::wxFileExists}\label{wxfileexists}
-<wx/utils.h>
+\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
-\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
+Returns TRUE if the file exists. It also returns TRUE if the file is
+a directory.
-\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
+\membersection{::wxFileModificationTime}\label{wxfilemodificationtime}
-Copies the user's email address into the supplied buffer, by
-concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
-and \helpref{wxGetUserId}{wxgetuserid}.
+\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}}
-Returns TRUE if successful, FALSE otherwise.
+Returns time of last modification of given file.
-\wxheading{Include files}
+\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath}
-<wx/utils.h>
+\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
-\membersection{::wxGetHostName}\label{wxgethostname}
+\func{char*}{wxFileNameFromPath}{\param{char* }{path}}
-\func{wxString}{wxGetHostName}{\void}
+Returns the filename for a full path. The second form returns a pointer to
+temporary storage that should not be deallocated.
-\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
+\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
-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{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}}
-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 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 "..".
-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.
+{\it spec} may contain wildcards.
-\wxheading{See also}
+{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
-\helpref{wxGetFullHostName}{wxgetfullhostname}
+For example:
-\wxheading{Include files}
+\begin{verbatim}
+ wxString f = wxFindFirstFile("/home/project/*.*");
+ while ( !f.IsEmpty() )
+ {
+ ...
+ f = wxFindNextFile();
+ }
+\end{verbatim}
-<wx/utils.h>
+\membersection{::wxFindNextFile}\label{wxfindnextfile}
-\section{User identification}\label{useridfunctions}
+\func{wxString}{wxFindNextFile}{\void}
-\membersection{::wxGetUserId}\label{wxgetuserid}
+Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
-\func{wxString}{wxGetUserId}{\void}
+See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
-\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
+\membersection{::wxGetDiskSpace}\label{wxgetdiskspace}
-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).
+\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}}
-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.
+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.
-The first variant of this function returns the login name if successful or an
-empty string otherwise. The second (deprecated) function returns TRUE
-if successful, FALSE otherwise.
+\wxheading{Returns}
-\wxheading{See also}
+{\tt TRUE} on success, {\tt FALSE} if an error occured (for example, the
+directory doesn't exist).
-\helpref{wxGetUserName}{wxgetusername}
+\wxheading{Portability}
-\wxheading{Include files}
+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.
-<wx/utils.h>
+This function first appeared in wxWindows 2.3.2.
-\membersection{::wxGetUserName}\label{wxgetusername}
+\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
-\func{wxString}{wxGetUserName}{\void}
+\func{wxString}{wxGetOSDirectory}{\void}
-\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
+Returns the Windows directory under Windows; on other platforms returns the empty string.
-This function returns the full user name (something like "Mr. John Smith").
+\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath}
-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.
+\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
-The first variant of this function returns the user name if successful or an
-empty string otherwise. The second (deprecated) function returns TRUE
-if successful, FALSE otherwise.
+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}\label{wxpathonly}
-\helpref{wxGetUserId}{wxgetuserid}
+\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
-\wxheading{Include files}
+Returns the directory part of the filename.
-<wx/utils.h>
+\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename}
-\section{String functions}
+\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
-\membersection{::copystring}
+Converts a Unix to a DOS filename by replacing forward
+slashes with backslashes.
-\func{char*}{copystring}{\param{const char* }{s}}
+\membersection{::wxConcatFiles}\label{wxconcatfiles}
-Makes a copy of the string {\it s} using the C++ new operator, so it can be
-deleted with the {\it delete} operator.
+\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
+\param{const wxString\& }{file3}}
-\membersection{::wxIsEmpty}\label{wxisempty}
+Concatenates {\it file1} and {\it file2} to {\it file3}, returning
+TRUE if successful.
-\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
+\membersection{::wxCopyFile}\label{wxcopyfile}
-Returns {\tt TRUE} if the pointer is either {\tt NULL} or points to an empty
-string, {\tt FALSE} otherwise.
+\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = TRUE}}
-\membersection{::wxStricmp}\label{wxstricmp}
+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.
-\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
+\membersection{::wxGetCwd}\label{wxgetcwd}
-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.
+\func{wxString}{wxGetCwd}{\void}
-This function complements the standard C function {\it strcmp()} which performs
-case-sensitive comparison.
+Returns a string containing the current (or working) directory.
-\membersection{::wxStringMatch}
+\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory}
-\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
- \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
+\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
-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.
+This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
-This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
+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.
-\membersection{::wxStringEq}\label{wxstringeq}
+{\it sz} is the size of the buffer if supplied.
-\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
+\membersection{::wxGetTempFileName}\label{wxgettempfilename}
-A macro defined as:
+\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}}
-\begin{verbatim}
-#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
-\end{verbatim}
+\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
-This function is obsolete, use \helpref{wxString}{wxstring} instead.
+%% 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.
+
+These functions are obsolete, please use\rtfsp
+\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp
+instead.
-\membersection{::wxStrlen}\label{wxstrlen}
+\membersection{::wxIsWild}\label{wxiswild}
-\func{size\_t}{wxStrlen}{\param{const char *}{ p}}
+\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
-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.
+Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
-\membersection{::wxGetTranslation}\label{wxgettranslation}
+\membersection{::wxMatchWild}\label{wxmatchwild}
-\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
+\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
-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().
+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}.
-\membersection{::wxSnprintf}\label{wxsnprintf}
+\membersection{::wxMkdir}\label{wxmkdir}
-\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
+\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
-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.
+Makes the directory {\it dir}, returning TRUE if successful.
-Returns the number of characters copied to the buffer or -1 if there is not
-enough space.
+{\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.
-\wxheading{See also}
+\membersection{::wxRemoveFile}\label{wxremovefile}
-\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
+\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
-\membersection{::wxVsnprintf}\label{wxvsnprintf}
+Removes {\it file}, returning TRUE if successful.
-\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argptr}}
+\membersection{::wxRenameFile}\label{wxrenamefile}
-The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list}
-argument instead of arbitrary number of parameters.
+\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
-\wxheading{See also}
+Renames {\it file1} to {\it file2}, returning TRUE if successful.
-\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
+\membersection{::wxRmdir}\label{wxrmdir}
-\section{Dialog functions}\label{dialogfunctions}
+\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
-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.
+Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS.
-\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
+The {\it flags} parameter is reserved for future use.
-\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
- \param{size\_t }{currentTip}}
+\membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory}
-This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
-used with \helpref{wxShowTip}{wxshowtip}.
+\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
-\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.}
+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.
-\wxheading{See also}
+\membersection{::wxSplitPath}\label{wxsplitfunction}
-\helpref{Tips overview}{tipsoverview}
+\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
-\wxheading{Include files}
+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.
-<wx/tipdlg.h>
+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).
-\membersection{::wxFileSelector}\label{wxfileselector}
+On entry, {\it fullname} should be non-NULL (it may be empty though).
-\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}}
+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).
-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.
+\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
-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.
+\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
-The wildcard may be a specification for multiple types of file
-with a description for each, such as:
+Copies the given file to {\it stream}. Useful when converting an old application to
+use streams (within the document/view framework, for example).
-\begin{verbatim}
- "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
-\end{verbatim}
+\wxheading{Include files}
-The application must check for an empty return value (the user pressed
-Cancel). For example:
+<wx/docview.h>
-\begin{verbatim}
-const wxString& s = wxFileSelector("Choose a file to open");
-if (s)
-{
- ...
-}
-\end{verbatim}
+\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
-\wxheading{Include files}
+\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
-<wx/filedlg.h>
+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).
-\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
+\wxheading{Include files}
-\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}}
+<wx/docview.h>
-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.
+\section{Network, user and OS functions}\label{networkfunctions}
-\wxheading{Parameters}
+The functions in this section are used to retrieve information about the
+current computer and/or user characteristics.
-\docparam{parent}{The parent window for the colour selection dialog}
+\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
-\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
+\func{long}{wxGetFreeMemory}{\void}
-\wxheading{Include files}
+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.
-<wx/colordlg.h>
+\wxheading{Include files}
-\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
+<wx/utils.h>
-\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}}
+\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
-\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}}
+\func{wxString}{wxGetFullHostName}{\void}
-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.
+Returns the FQDN (fully qualified domain host name) or an empty string on
+error.
-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}.
+\wxheading{See also}
-If {\it centre} is TRUE, the message text (which may include new line
-characters) is centred; if FALSE, the message is left-justified.
+\helpref{wxGetHostName}{wxgethostname}
\wxheading{Include files}
-<wx/choicdlg.h>
-
-\perlnote{In wxPerl there is just an array reference in place of {\tt n}
-and {\tt choices}, and no {\tt selections} parameter; the function
-returns an array containing the user selections.}
-
-\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
+<wx/utils.h>
-\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}}
+\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
-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.
+\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
-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.
+Copies the user's email address into the supplied buffer, by
+concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
+and \helpref{wxGetUserId}{wxgetuserid}.
-Dialog is centered on its {\it parent} unless an explicit position is given in
-{\it pos}.
+Returns TRUE if successful, FALSE otherwise.
\wxheading{Include files}
-<wx/textdlg.h>
+<wx/utils.h>
-\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
+\membersection{::wxGetHomeDir}\label{wxgethomedir}
-\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
- \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}}
+\func{wxString}{wxGetHomeDir}{\void}
-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.
+Return the (current) user's home directory.
+
+\wxheading{See also}
+
+\helpref{wxGetUserHome}{wxgetuserhome}
\wxheading{Include files}
-<wx/textdlg.h>
+<wx/utils.h>
-\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
+\membersection{::wxGetHostName}\label{wxgethostname}
-\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}}
+\func{wxString}{wxGetHostName}{\void}
-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.
+\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+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.
+
+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.
+
+The first variant of this function returns the hostname if successful or an
+empty string otherwise. The second (deprecated) function returns TRUE
+if successful, FALSE otherwise.
+
+\wxheading{See also}
+
+\helpref{wxGetFullHostName}{wxgetfullhostname}
\wxheading{Include files}
-<wx/textdlg.h>
+<wx/utils.h>
-\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
+\membersection{::wxGetUserId}\label{wxgetuserid}
-\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}}
+\func{wxString}{wxGetUserId}{\void}
-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.
+\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
-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.
+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).
-If Cancel is pressed, -1 is returned.
+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.
-{\it choices} is an array of {\it n} strings for the listbox.
+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.
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+\wxheading{See also}
-\wxheading{Include files}
+\helpref{wxGetUserName}{wxgetusername}
-<wx/choicdlg.h>
+\wxheading{Include files}
-\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
+<wx/utils.h>
-\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}}
+\membersection{::wxGetOsDescription}\label{wxgetosdescription}
-\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}}
+\func{wxString}{wxGetOsDescription}{\void}
-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.
+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}.
-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}.
+\wxheading{See also}
-If {\it centre} is TRUE, the message text (which may include new line
-characters) is centred; if FALSE, the message is left-justified.
+\helpref{::wxGetOsVersion}{wxgetosversion}
\wxheading{Include files}
-<wx/choicdlg.h>
+<wx/utils.h>
-\perlnote{In wxPerl there is just an array reference in place of {\tt n}
-and {\tt choices}.}
+\membersection{::wxGetOsVersion}\label{wxgetosversion}
-\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
+\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
-\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}}
+Gets operating system version information.
-\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}}
+\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}
-As {\bf wxGetSingleChoice} but returns the index representing the selected
-string. If the user pressed cancel, -1 is returned.
+\wxheading{See also}
+
+\helpref{::wxGetOsDescription}{wxgetosdescription}
\wxheading{Include files}
-<wx/choicdlg.h>
+<wx/utils.h>
-\perlnote{In wxPerl there is just an array reference in place of {\tt n}
-and {\tt choices}.}
+\membersection{::wxGetUserHome}\label{wxgetuserhome}
-\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
+\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
-\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}}
+Returns the home directory for the given user. If the username is empty
+(default value), this function behaves like
+\helpref{wxGetHomeDir}{wxgethomedir}.
-\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}}
+\wxheading{Include files}
-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}!
+<wx/utils.h>
+
+\membersection{::wxGetUserName}\label{wxgetusername}
+
+\func{wxString}{wxGetUserName}{\void}
+
+\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
+
+This function returns the full user name (something like "Mr. John Smith").
+
+Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
+in the {\bf 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.
+
+The first variant of this function returns the user name if successful or an
+empty string otherwise. The second (deprecated) function returns {\tt TRUE}
+if successful, {\tt FALSE} otherwise.
+
+\wxheading{See also}
+
+\helpref{wxGetUserId}{wxgetuserid}
\wxheading{Include files}
-<wx/choicdlg.h>
+<wx/utils.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.}
+\section{String functions}
-\membersection{::wxMessageBox}\label{wxmessagebox}
+\membersection{::copystring}\label{copystring}
-\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}}
+\func{char*}{copystring}{\param{const char* }{s}}
-General purpose message dialog. {\it style} may be a bit list of the
-following identifiers:
+Makes a copy of the string {\it s} using the C++ new operator, so it can be
+deleted with the {\it delete} operator.
-\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}
+This function is deprecated, use \helpref{wxString}{wxstring} class instead.
-The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
+\membersection{::wxIsEmpty}\label{wxisempty}
-For example:
+\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
+
+Returns {\tt TRUE} if the pointer is either {\tt NULL} or points to an empty
+string, {\tt FALSE} otherwise.
+
+\membersection{::wxStricmp}\label{wxstricmp}
+
+\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
+
+Returns a negative value, 0, or positive value if {\it p1} is less than, equal
+to or greater than {\it p2}. The comparison is case-insensitive.
+
+This function complements the standard C function {\it strcmp()} which performs
+case-sensitive comparison.
+
+\membersection{::wxStringMatch}\label{wxstringmatch}
+
+\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
+ \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
+
+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.
+
+This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
+
+\membersection{::wxStringEq}\label{wxstringeq}
+
+\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
+
+A macro defined as:
\begin{verbatim}
- ...
- int answer = wxMessageBox("Quit program?", "Confirm",
- wxYES_NO | wxCANCEL, main_frame);
- if (answer == wxYES)
- delete main_frame;
- ...
+#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
\end{verbatim}
-{\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 obsolete, use \helpref{wxString}{wxstring} instead.
-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.
+\membersection{::wxStrlen}\label{wxstrlen}
-\wxheading{Include files}
+\func{size\_t}{wxStrlen}{\param{const char *}{ p}}
-<wx/msgdlg.h>
+This is a safe version of standard function {\it strlen()}: it does exactly the
+same thing (i.e. returns the length of the string) except that it returns 0 if
+{\it p} is the {\tt NULL} pointer.
-\membersection{::wxShowTip}\label{wxshowtip}
+\membersection{::wxGetTranslation}\label{wxgettranslation}
-\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
- \param{wxTipProvider *}{tipProvider},
- \param{bool }{showAtStartup = TRUE}}
+\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
-This function shows a "startup tip" to the user.
+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().
-\docparam{parent}{The parent window for the modal dialog}
+\membersection{::wxSnprintf}\label{wxsnprintf}
-\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{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
-\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.}
+This function replaces the dangerous standard function {\tt sprintf()} and is
+like {\tt snprintf()} available on some platforms. The only difference with
+sprintf() is that an additional argument - buffer size - is taken and the
+buffer is never overflowed.
+
+Returns the number of characters copied to the buffer or -1 if there is not
+enough space.
\wxheading{See also}
-\helpref{Tips overview}{tipsoverview}
+\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
+
+\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/tipdlg.h>
+<wx/utils.h>
-\section{GDI functions}\label{gdifunctions}
+\membersection{::wxToUpper}\label{wxtoupper}
-The following are relevant to the GDI (Graphics Device Interface).
+\func{char}{wxToUpper}{\param{char }{ch}}
+
+Converts the character to upper case. This is implemented as a macro for efficiency.
\wxheading{Include files}
-<wx/gdicmn.h>
+<wx/utils.h>
-\membersection{::wxClientDisplayRect}
+\membersection{::wxVsnprintf}\label{wxvsnprintf}
-\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
-\param{int *}{width}, \param{int *}{height}}
+\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argptr}}
-\func{wxRect}{wxGetClientDisplayRect}{\void}
+The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list}
+argument instead of arbitrary number of parameters.
-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.
+\wxheading{See also}
-\membersection{::wxColourDisplay}
+\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
-\func{bool}{wxColourDisplay}{\void}
+\section{Dialog functions}\label{dialogfunctions}
-Returns TRUE if the display is colour, FALSE otherwise.
+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{::wxDisplayDepth}
+\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
-\func{int}{wxDisplayDepth}{\void}
+\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
-Returns the depth of the display (a value of 1 denotes a monochrome display).
+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.
-\membersection{::wxDisplaySize}
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
-\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
+\wxheading{Include files}
-\func{wxSize}{wxGetDisplaySize}{\void}
+<wx/utils.h>
-Returns the display size in pixels.
+\membersection{::wxBell}\label{wxbell}
-\membersection{::wxDisplaySizeMM}
+\func{void}{wxBell}{\void}
-\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
+Ring the system bell.
-\func{wxSize}{wxGetDisplaySizeMM}{\void}
+\wxheading{Include files}
-Returns the display size in millimeters.
+<wx/utils.h>
-\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
+\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
-\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
- \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
+\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
+ \param{size\_t }{currentTip}}
-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.
+This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
+used with \helpref{wxShowTip}{wxshowtip}.
-In addition to adding the placeable metafile header, this function adds
-the equivalent of the following code to the start of the metafile data:
+\docparam{filename}{The name of the file containing the tips, one per line}
+\docparam{currentTip}{The index of the first tip to show - normally this index
+is remembered between the 2 program runs.}
+
+\wxheading{See also}
+
+\helpref{Tips overview}{tipsoverview}
+
+\wxheading{Include files}
+
+<wx/tipdlg.h>
+
+\membersection{::wxDirSelector}\label{wxdirselector}
+
+\func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\
+ \param{const wxString\& }{default\_path = ""},\\
+ \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\
+ \param{wxWindow *}{parent = NULL}}
+
+Pops up a directory selector dialog. The arguments have the same meaning as
+those of wxDirDialog::wxDirDialog(). The message is displayed at the top,
+and the default\_path, if specified, is set as the initial selection.
+
+The application must check for an empty return value (if the user pressed
+Cancel). For example:
\begin{verbatim}
- SetMapMode(dc, MM_ANISOTROPIC);
- SetWindowOrg(dc, minX, minY);
- SetWindowExt(dc, maxX - minX, maxY - minY);
+const wxString& dir = wxDirSelector("Choose a folder");
+if ( !dir.empty() )
+{
+ ...
+}
\end{verbatim}
-This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
+\wxheading{Include files}
-Placeable metafiles may be imported by many Windows applications, and can be
-used in RTF (Rich Text Format) files.
+<wx/dirdlg.h>
-{\it scale} allows the specification of scale for the metafile.
+\membersection{::wxFileSelector}\label{wxfileselector}
-This function is only available under Windows.
+\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}}
-\membersection{::wxSetCursor}\label{wxsetcursor}
+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.
-\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
+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.
-Globally sets the cursor; only has an effect in Windows and GTK.
-See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
+The wildcard may be a specification for multiple types of file
+with a description for each, such as:
-\section{Printer settings}\label{printersettings}
+\begin{verbatim}
+ "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
+\end{verbatim}
-These routines are obsolete and should no longer be used!
+The application must check for an empty return value (the user pressed
+Cancel). For example:
-The following functions are used to control PostScript printing. Under
-Windows, PostScript output can only be sent to a file.
+\begin{verbatim}
+const wxString& s = wxFileSelector("Choose a file to open");
+if (s)
+{
+ ...
+}
+\end{verbatim}
\wxheading{Include files}
-<wx/dcps.h>
+<wx/filedlg.h>
-\membersection{::wxGetPrinterCommand}
+\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
-\func{wxString}{wxGetPrinterCommand}{\void}
+\func{void}{wxEndBusyCursor}{\void}
-Gets the printer command used to print a file. The default is {\tt lpr}.
+Changes the cursor back to the original cursor, for all windows in the application.
+Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
-\membersection{::wxGetPrinterFile}
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
-\func{wxString}{wxGetPrinterFile}{\void}
+\wxheading{Include files}
-Gets the PostScript output filename.
+<wx/utils.h>
-\membersection{::wxGetPrinterMode}
+\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
-\func{int}{wxGetPrinterMode}{\void}
+\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}}
-Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
-The default is PS\_PREVIEW.
+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.
-\membersection{::wxGetPrinterOptions}
+\wxheading{Parameters}
-\func{wxString}{wxGetPrinterOptions}{\void}
+\docparam{parent}{The parent window for the colour selection dialog}
-Gets the additional options for the print command (e.g. specific printer). The default is nothing.
+\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
-\membersection{::wxGetPrinterOrientation}
+\wxheading{Include files}
-\func{int}{wxGetPrinterOrientation}{\void}
+<wx/colordlg.h>
-Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
-\membersection{::wxGetPrinterPreviewCommand}
+\func{size\_t}{wxGetMultipleChoices}{\\
+ \param{wxArrayInt\& }{selections},\\
+ \param{const wxString\& }{message},\\
+ \param{const wxString\& }{caption},\\
+ \param{const wxArrayString\& }{aChoices},\\
+ \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1},\\
+ \param{bool}{ centre = TRUE},\\
+ \param{int }{width=150}, \param{int }{height=200}}
-\func{wxString}{wxGetPrinterPreviewCommand}{\void}
+\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}}
-Gets the command used to view a PostScript file. The default depends on the platform.
+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.
-\membersection{::wxGetPrinterScaling}
+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}.
-\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
+If {\it centre} is TRUE, the message text (which may include new line
+characters) is centred; if FALSE, the message is left-justified.
-Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
+\wxheading{Include files}
+
+<wx/choicdlg.h>
+
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}, and no {\tt selections} parameter; the function
+returns an array containing the user selections.}
-\membersection{::wxGetPrinterTranslation}
+\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
-\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
+\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}}
-Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+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.
-\membersection{::wxSetPrinterCommand}
+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.
-\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
+Dialog is centered on its {\it parent} unless an explicit position is given in
+{\it pos}.
-Sets the printer command used to print a file. The default is {\tt lpr}.
+\wxheading{Include files}
-\membersection{::wxSetPrinterFile}
+<wx/textdlg.h>
-\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
+\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
-Sets the PostScript output filename.
+\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
+ \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}}
-\membersection{::wxSetPrinterMode}
+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.
-\func{void}{wxSetPrinterMode}{\param{int }{mode}}
+\wxheading{Include files}
-Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
-The default is PS\_PREVIEW.
+<wx/textdlg.h>
-\membersection{::wxSetPrinterOptions}
+\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
-\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
+\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}}
-Sets the additional options for the print command (e.g. specific printer). The default is nothing.
+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.
-\membersection{::wxSetPrinterOrientation}
+If {\it centre} is TRUE, the message text (which may include new line characters)
+is centred; if FALSE, the message is left-justified.
-\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
+\wxheading{Include files}
-Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+<wx/textdlg.h>
-\membersection{::wxSetPrinterPreviewCommand}
+\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
-\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
+\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}}
-Sets the command used to view a PostScript file. The default depends on the platform.
+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.
-\membersection{::wxSetPrinterScaling}
+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.
-\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
+If Cancel is pressed, -1 is returned.
-Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
+{\it choices} is an array of {\it n} strings for the listbox.
-\membersection{::wxSetPrinterTranslation}
+If {\it centre} is TRUE, the message text (which may include new line characters)
+is centred; if FALSE, the message is left-justified.
-\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
+\wxheading{Include files}
-Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+<wx/choicdlg.h>
-\section{Clipboard functions}\label{clipsboard}
+\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
-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.
+\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}}
-\wxheading{Include files}
+\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}}
-<wx/clipbrd.h>
+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.
-\membersection{::wxClipboardOpen}
+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}.
-\func{bool}{wxClipboardOpen}{\void}
+If {\it centre} is TRUE, the message text (which may include new line
+characters) is centred; if FALSE, the message is left-justified.
-Returns TRUE if this application has already opened the clipboard.
+\wxheading{Include files}
-\membersection{::wxCloseClipboard}
+<wx/choicdlg.h>
-\func{bool}{wxCloseClipboard}{\void}
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
-Closes the clipboard to allow other applications to use it.
+\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
-\membersection{::wxEmptyClipboard}
+\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}{wxEmptyClipboard}{\void}
+\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}}
-Empties the clipboard.
+As {\bf wxGetSingleChoice} but returns the index representing the selected
+string. If the user pressed cancel, -1 is returned.
-\membersection{::wxEnumClipboardFormats}
+\wxheading{Include files}
-\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
+<wx/choicdlg.h>
-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.
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
-{\it dataFormat} specifies a known format. If this parameter is zero,
-the function returns the first format in the list.
+\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
-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.
+\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}}
-Before it enumerates the formats function, an application must open the clipboard by using the
-wxOpenClipboard function.
+\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}}
-\membersection{::wxGetClipboardData}
+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}!
-\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
+\wxheading{Include files}
-Gets data from the clipboard.
+<wx/choicdlg.h>
-{\it dataFormat} may be one of:
+\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.}
-\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}
+\membersection{::wxIsBusy}\label{wxisbusy}
-The clipboard must have previously been opened for this call to succeed.
+\func{bool}{wxIsBusy}{\void}
-\membersection{::wxGetClipboardFormatName}
+Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
+\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
-\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
+See also \helpref{wxBusyCursor}{wxbusycursor}.
-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{Include files}
-\membersection{::wxIsClipboardFormatAvailable}
+<wx/utils.h>
-\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
+\membersection{::wxMessageBox}\label{wxmessagebox}
-Returns TRUE if the given data format is available on the clipboard.
+\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{::wxOpenClipboard}
+General purpose message dialog. {\it style} may be a bit list of the
+following identifiers:
-\func{bool}{wxOpenClipboard}{\void}
+\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}
-Opens the clipboard for passing data to it or getting data from it.
+The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
-\membersection{::wxRegisterClipboardFormat}
+For example:
-\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
+\begin{verbatim}
+ ...
+ int answer = wxMessageBox("Quit program?", "Confirm",
+ wxYES_NO | wxCANCEL, main_frame);
+ if (answer == wxYES)
+ delete main_frame;
+ ...
+\end{verbatim}
-Registers the clipboard data format name and returns an identifier.
+{\it message} may contain newline characters, in which case the
+message will be split into separate lines, to cater for large messages.
-\membersection{::wxSetClipboardData}
+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}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
+\wxheading{Include files}
-Passes data to the clipboard.
+<wx/msgdlg.h>
-{\it dataFormat} may be one of:
+\membersection{::wxShowTip}\label{wxshowtip}
-\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}
+\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
+ \param{wxTipProvider *}{tipProvider},
+ \param{bool }{showAtStartup = TRUE}}
-The clipboard must have previously been opened for this call to succeed.
+This function shows a "startup tip" to the user.
-\section{Miscellaneous functions}\label{miscellany}
+\docparam{parent}{The parent window for the modal dialog}
-\membersection{::wxDROP\_ICON}\label{wxdropicon}
+\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{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
+\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.}
-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.
+\wxheading{See also}
-This macro should be used with
-\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}.
+\helpref{Tips overview}{tipsoverview}
\wxheading{Include files}
-<wx/dnd.h>
-
-\membersection{::wxNewId}
+<wx/tipdlg.h>
-\func{long}{wxNewId}{\void}
+\section{GDI functions}\label{gdifunctions}
-Generates an integer identifier unique to this run of the program.
+The following are relevant to the GDI (Graphics Device Interface).
\wxheading{Include files}
-<wx/utils.h>
+<wx/gdicmn.h>
-\membersection{::wxRegisterId}
+\membersection{wxBITMAP}\label{wxbitmapmacro}
-\func{void}{wxRegisterId}{\param{long}{ id}}
+\func{}{wxBITMAP}{bitmapName}
-Ensures that ids subsequently generated by {\bf NewId} do not clash with
-the given {\bf id}.
+This macro loads a bitmap from either application resources (on the platforms
+for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
+avoid using {\tt \#ifdef}s when creating bitmaps.
+
+\wxheading{See also}
+
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxICON}{wxiconmacro}
\wxheading{Include files}
-<wx/utils.h>
+<wx/gdicmn.h>
-\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
+\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect}
-\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
+\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
+\param{int *}{width}, \param{int *}{height}}
-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{wxRect}{wxGetClientDisplayRect}{\void}
-See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+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.
-\wxheading{Include files}
+\membersection{::wxColourDisplay}\label{wxcolourdisplay}
-<wx/utils.h>
+\func{bool}{wxColourDisplay}{\void}
-\membersection{::wxBell}
+Returns TRUE if the display is colour, FALSE otherwise.
-\func{void}{wxBell}{\void}
+\membersection{::wxDisplayDepth}\label{wxdisplaydepth}
-Ring the system bell.
+\func{int}{wxDisplayDepth}{\void}
-\wxheading{Include files}
+Returns the depth of the display (a value of 1 denotes a monochrome display).
-<wx/utils.h>
+\membersection{::wxDisplaySize}\label{wxdisplaysize}
-\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
+\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
-\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
+\func{wxSize}{wxGetDisplaySize}{\void}
-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.
+Returns the display size in pixels.
-\membersection{::wxDDECleanUp}\label{wxddecleanup}
+\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm}
-\func{void}{wxDDECleanUp}{\void}
+\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
-Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
-called by the application.
+\func{wxSize}{wxGetDisplaySizeMM}{\void}
-See also \helpref{wxDDEInitialize}{wxddeinitialize}.
+Returns the display size in millimeters.
-\wxheading{Include files}
+\membersection{::wxDROP\_ICON}\label{wxdropicon}
-<wx/dde.h>
+\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
-\membersection{::wxDDEInitialize}\label{wxddeinitialize}
+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.
-\func{void}{wxDDEInitialize}{\void}
+This macro should be used with
+\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}.
-Initializes the DDE system. May be called multiple times without harm.
+\wxheading{Include files}
-This no longer needs to be called by the application: it will be called
-by wxWindows if necessary.
+<wx/dnd.h>
-See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
-\helpref{wxDDECleanUp}{wxddecleanup}.
+\membersection{wxICON}\label{wxiconmacro}
-\wxheading{Include files}
+\func{}{wxICON}{iconName}
-<wx/dde.h>
+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.
-\membersection{::wxDebugMsg}\label{wxdebugmsg}
+\wxheading{See also}
-\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxBITMAP}{wxbitmapmacro}
-{\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogdebug} instead!}
+\wxheading{Include files}
-Display a debugging message; under Windows, this will appear on the
-debugger command window, and under Unix, it will be written to standard
-error.
+<wx/gdicmn.h>
-The syntax is identical to {\bf printf}: pass a format string and a
-variable list of arguments.
+\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
-{\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.
+\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
+ \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+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.
-\wxheading{Include files}
+In addition to adding the placeable metafile header, this function adds
+the equivalent of the following code to the start of the metafile data:
-<wx/utils.h>
+\begin{verbatim}
+ SetMapMode(dc, MM_ANISOTROPIC);
+ SetWindowOrg(dc, minX, minY);
+ SetWindowExt(dc, maxX - minX, maxY - minY);
+\end{verbatim}
-\membersection{::wxDisplaySize}
+This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
-\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
+Placeable metafiles may be imported by many Windows applications, and can be
+used in RTF (Rich Text Format) files.
-Gets the physical size of the display in pixels.
+{\it scale} allows the specification of scale for the metafile.
-\wxheading{Include files}
+This function is only available under Windows.
-<wx/gdicmn.h>
+\membersection{::wxSetCursor}\label{wxsetcursor}
-\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
+\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
-\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
+Globally sets the cursor; only has an effect in Windows and GTK.
+See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
-This function enables or disables all top level windows. It is used by
-\helpref{::wxSafeYield}{wxsafeyield}.
+\section{Printer settings}\label{printersettings}
-\wxheading{Include files}
+These routines are obsolete and should no longer be used!
-<wx/utils.h>
+The following functions are used to control PostScript printing. Under
+Windows, PostScript output can only be sent to a file.
-\membersection{::wxEntry}\label{wxentry}
+\wxheading{Include files}
-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.
+<wx/dcps.h>
-\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
- \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
+\membersection{::wxGetPrinterCommand}\label{wxgetprintercommand}
-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.
+\func{wxString}{wxGetPrinterCommand}{\void}
-\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
- \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
+Gets the printer command used to print a file. The default is {\tt lpr}.
-wxWindows initialization under Windows (for applications constructed as a DLL).
+\membersection{::wxGetPrinterFile}\label{wxgetprinterfile}
-\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
+\func{wxString}{wxGetPrinterFile}{\void}
-wxWindows initialization under Unix.
+Gets the PostScript output filename.
-\wxheading{Remarks}
+\membersection{::wxGetPrinterMode}\label{wxgetprintermode}
-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{int}{wxGetPrinterMode}{\void}
-\begin{verbatim}
-int CTheApp::ExitInstance()
-{
- // OnExit isn't called by CleanUp so must be called explicitly.
- wxTheApp->OnExit();
- wxApp::CleanUp();
+Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
+The default is PS\_PREVIEW.
- return CWinApp::ExitInstance();
-}
-\end{verbatim}
+\membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions}
-\wxheading{Include files}
+\func{wxString}{wxGetPrinterOptions}{\void}
-<wx/app.h>
+Gets the additional options for the print command (e.g. specific printer). The default is nothing.
-\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
+\membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation}
-\func{void}{wxEndBusyCursor}{\void}
+\func{int}{wxGetPrinterOrientation}{\void}
-Changes the cursor back to the original cursor, for all windows in the application.
-Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
+Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
-See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+\membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand}
-\wxheading{Include files}
+\func{wxString}{wxGetPrinterPreviewCommand}{\void}
-<wx/utils.h>
+Gets the command used to view a PostScript file. The default depends on the platform.
-\membersection{::wxError}\label{wxerror}
+\membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling}
-\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
+\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
-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}.
+Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
-\wxheading{Include files}
+\membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation}
-<wx/utils.h>
+\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
-\membersection{::wxExecute}\label{wxexecute}
+Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
-\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\membersection{::wxSetPrinterCommand}\label{wxsetprintercommand}
-\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
-\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
+Sets the printer command used to print a file. The default is {\tt lpr}.
-\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}}
+\membersection{::wxSetPrinterFile}\label{wxsetprinterfile}
-Executes another program in Unix or Windows.
+\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
-The first form takes a command string, such as {\tt "emacs file.txt"}.
+Sets the PostScript output filename.
-The second form takes an array of values: a command, any number of
-arguments, terminated by NULL.
+\membersection{::wxSetPrinterMode}\label{wxsetprintermode}
-The semantics of the third and fourth versions is different from the first two
-and is described in more details below.
+\func{void}{wxSetPrinterMode}{\param{int }{mode}}
-If {\it sync} is FALSE (the default), flow of control immediately returns.
-If TRUE, the current application waits until the other program has terminated.
+Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
+The default is PS\_PREVIEW.
-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{::wxSetPrinterOptions}\label{wxsetprinteroptions}
-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.
+\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
-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.
+Sets the additional options for the print command (e.g. specific printer). The default is nothing.
-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{::wxSetPrinterOrientation}\label{wxsetprinterorientation}
-See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
-\helpref{Exec sample}{sampleexec}.
+\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}\label{wxsetprinterpreviewcommand}
-\membersection{::wxExit}\label{wxexit}
+\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
-\func{void}{wxExit}{\void}
+Sets the command used to view a PostScript file. The default depends on the platform.
-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}.
+\membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling}
-\wxheading{Include files}
+\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
-<wx/app.h>
+Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
-\membersection{::wxFatalError}\label{wxfatalerror}
+\membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation}
-\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
+\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
-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}.
+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/utils.h>
+<wx/clipbrd.h>
-\membersection{::wxFindMenuItemId}
+\membersection{::wxClipboardOpen}\label{wxclipboardopen}
-\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
+\func{bool}{wxClipboardOpen}{\void}
-Find a menu item identifier associated with the given frame's menu bar.
+Returns TRUE if this application has already opened the clipboard.
-\wxheading{Include files}
+\membersection{::wxCloseClipboard}\label{wxcloseclipboard}
-<wx/utils.h>
+\func{bool}{wxCloseClipboard}{\void}
-\membersection{::wxFindWindowByLabel}\label{wxfindwindowbylabel}
+Closes the clipboard to allow other applications to use it.
-\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
+\membersection{::wxEmptyClipboard}\label{wxemptyclipboard}
-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.
+\func{bool}{wxEmptyClipboard}{\void}
-\wxheading{Include files}
+Empties the clipboard.
-<wx/utils.h>
+\membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats}
-\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
+\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
-\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
+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.
-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.
+{\it dataFormat} specifies a known format. If this parameter is zero,
+the function returns the first format in the list.
-If no such named window is found, {\bf wxFindWindowByLabel} is called.
+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.
-\wxheading{Include files}
+Before it enumerates the formats function, an application must open the clipboard by using the
+wxOpenClipboard function.
-<wx/utils.h>
+\membersection{::wxGetClipboardData}\label{wxgetclipboarddata}
-\membersection{::wxFindWindowAtPoint}\label{wxfindwindowatpoint}
+\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
-\func{wxWindow *}{wxFindWindowAtPoint}{\param{const wxPoint\& }{pt}}
+Gets data from the clipboard.
-Find the deepest window at the given mouse position in screen coordinates,
-returning the window if found, or NULL if not.
+{\it dataFormat} may be one of:
-\membersection{::wxFindWindowAtPointer}\label{wxfindwindowatpointer}
+\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}
-\func{wxWindow *}{wxFindWindowAtPointer}{\param{wxPoint\& }{pt}}
+The clipboard must have previously been opened for this call to succeed.
-Find the deepest window at the mouse pointer position, returning the window
-and current pointer position in screen coordinates.
+\membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname}
-\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
+\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
-\func{wxWindow *}{wxGetActiveWindow}{\void}
+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.
-Gets the currently active window (Windows only).
+\membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable}
-\wxheading{Include files}
+\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
-<wx/windows.h>
+Returns TRUE if the given data format is available on the clipboard.
-\membersection{::wxGetDisplayName}\label{wxgetdisplayname}
+\membersection{::wxOpenClipboard}\label{wxopenclipboard}
-\func{wxString}{wxGetDisplayName}{\void}
+\func{bool}{wxOpenClipboard}{\void}
-Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
+Opens the clipboard for passing data to it or getting data from it.
-\wxheading{Include files}
+\membersection{::wxRegisterClipboardFormat}\label{wxregisterclipboardformat}
-<wx/utils.h>
+\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
-\membersection{::wxGetHomeDir}\label{wxgethomedir}
+Registers the clipboard data format name and returns an identifier.
-\func{wxString}{wxGetHomeDir}{\void}
+\membersection{::wxSetClipboardData}\label{wxsetclipboarddata}
-Return the (current) user's home directory.
+\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
-\wxheading{See also}
+Passes data to the clipboard.
-\helpref{wxGetUserHome}{wxgetuserhome}
+{\it dataFormat} may be one of:
-\wxheading{Include files}
+\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}
-<wx/utils.h>
+The clipboard must have previously been opened for this call to succeed.
-\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
+\section{Miscellaneous functions}\label{miscellany}
-\func{long}{wxGetFreeMemory}{\void}
+\membersection{::wxNewId}\label{wxnewid}
-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.
+\func{long}{wxNewId}{\void}
+
+Generates an integer identifier unique to this run of the program.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxGetMousePosition}\label{wxgetmouseposition}
+\membersection{::wxRegisterId}\label{wxregisterid}
-\func{wxPoint}{wxGetMousePosition}{\void}
+\func{void}{wxRegisterId}{\param{long}{ id}}
-Returns the mouse position in screen coordinates.
+Ensures that ids subsequently generated by {\bf NewId} do not clash with
+the given {\bf id}.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxGetOsDescription}\label{wxgetosdescription}
-
-\func{wxString}{wxGetOsDescription}{\void}
+\membersection{::wxDDECleanUp}\label{wxddecleanup}
-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}.
+\func{void}{wxDDECleanUp}{\void}
-\wxheading{See also}
+Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
+called by the application.
-\helpref{::wxGetOsVersion}{wxgetosversion}
+See also \helpref{wxDDEInitialize}{wxddeinitialize}.
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxGetOsVersion}\label{wxgetosversion}
+<wx/dde.h>
-\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
+\membersection{::wxDDEInitialize}\label{wxddeinitialize}
-Gets operating system version information.
+\func{void}{wxDDEInitialize}{\void}
-\begin{twocollist}\itemsep=0pt
-\twocolitemruled{Platform}{Return types}
-\twocolitem{Macintosh}{Return value is wxMACINTOSH.}
-\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}
+Initializes the DDE system. May be called multiple times without harm.
-\wxheading{See also}
+This no longer needs to be called by the application: it will be called
+by wxWindows if necessary.
-\helpref{::wxGetOsDescription}{wxgetosdescription}
+See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
+\helpref{wxDDECleanUp}{wxddecleanup}.
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxGetResource}\label{wxgetresource}
+<wx/dde.h>
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
+\membersection{::wxDisplaySize}\label{wxdisplaysize}
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{float *}{value}, \param{const wxString\& }{file = NULL}}
+\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{long *}{value}, \param{const wxString\& }{file = NULL}}
+Gets the physical size of the display in pixels.
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{int *}{value}, \param{const wxString\& }{file = NULL}}
+\wxheading{Include files}
-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.
+<wx/gdicmn.h>
-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.
+\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
-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.
+\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
-See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
+This function enables or disables all top level windows. It is used by
+\helpref{::wxSafeYield}{wxsafeyield}.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxGetUserId}
+\membersection{::wxFindMenuItemId}\label{wxfindmenuitemid}
-\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
+\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
-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''.
+Find a menu item identifier associated with the given frame's menu bar.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxGetUserHome}\label{wxgetuserhome}
+\membersection{::wxFindWindowByLabel}\label{wxfindwindowbylabel}
-\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
+\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
-Returns the home directory for the given user. If the username is empty
-(default value), this function behaves like
-\helpref{wxGetHomeDir}{wxgethomedir}.
+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{::wxGetUserName}
+\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
+
+\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
-\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
+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.
-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''.
+If no such named window is found, {\bf wxFindWindowByLabel} is called.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions}
-
-\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = TRUE}}
+\membersection{::wxFindWindowAtPoint}\label{wxfindwindowatpoint}
-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.
+\func{wxWindow *}{wxFindWindowAtPoint}{\param{const wxPoint\& }{pt}}
-\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
+Find the deepest window at the given mouse position in screen coordinates,
+returning the window if found, or NULL if not.
-\func{void}{wxInitAllImageHandlers}{\void}
+\membersection{::wxFindWindowAtPointer}\label{wxfindwindowatpointer}
-Initializes all available image handlers. For a list of available handlers,
-see \helpref{wxImage}{wximage}.
+\func{wxWindow *}{wxFindWindowAtPointer}{\param{wxPoint\& }{pt}}
-\wxheading{See also}
+Find the deepest window at the mouse pointer position, returning the window
+and current pointer position in screen coordinates.
-\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
+\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
-\wxheading{Include files}
+\func{wxWindow *}{wxGetActiveWindow}{\void}
-<wx/image.h>
+Gets the currently active window (Windows only).
-\membersection{::wxInitialize}\label{wxinitialize}
+\wxheading{Include files}
-\func{bool}{wxInitialize}{\void}
+<wx/windows.h>
-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{::wxGetDisplayName}\label{wxgetdisplayname}
-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{wxString}{wxGetDisplayName}{\void}
-This function may be called several times but
-\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
-call to this function.
+Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
\wxheading{Include files}
-<wx/app.h>
-
-\membersection{::wxIsBusy}\label{wxisbusy}
+<wx/utils.h>
-\func{bool}{wxIsBusy}{\void}
+\membersection{::wxGetMousePosition}\label{wxgetmouseposition}
-Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
-\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
+\func{wxPoint}{wxGetMousePosition}{\void}
-See also \helpref{wxBusyCursor}{wxbusycursor}.
+Returns the mouse position in screen coordinates.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxKill}\label{wxkill}
+\membersection{::wxGetResource}\label{wxgetresource}
-\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}}
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
-Equivalent to the Unix kill function: send the given signal {\it sig} to the
-process with PID {\it pid}. The valud signal values are
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{float *}{value}, \param{const wxString\& }{file = NULL}}
-\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{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{long *}{value}, \param{const wxString\& }{file = NULL}}
-{\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.
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{int *}{value}, \param{const wxString\& }{file = NULL}}
-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:
+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.
-\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}
+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.
-\wxheading{See also}
+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.
-\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
-\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
-\helpref{Exec sample}{sampleexec}
+See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxNow}\label{wxnow}
-
-\func{wxString}{wxNow}{\void}
-
-Returns a string representing the current date and time.
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
\membersection{::wxPostDelete}\label{wxpostdelete}
\func{void}{wxPostDelete}{\param{wxObject *}{object}}
<wx/app.h>
-\membersection{::wxSafeYield}\label{wxsafeyield}
-
-\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
-
-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.
-
-Returns the result of the call to \helpref{::wxYield}{wxyield}.
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
\membersection{::wxSetDisplayName}\label{wxsetdisplayname}
\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
<wx/utils.h>
-\membersection{::wxShell}\label{wxshell}
-
-\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
-
-Executes a command in an interactive shell window. If no command is
-specified, then just the shell is spawned.
-
-See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
-\membersection{::wxSleep}\label{wxsleep}
-
-\func{void}{wxSleep}{\param{int}{ secs}}
-
-Sleeps for the specified number of seconds.
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
-\membersection{::wxStripMenuCodes}
+\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).
<wx/utils.h>
-\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{::wxToUpper}\label{wxtoupper}
-
-\func{char}{wxToUpper}{\param{char }{ch}}
-
-Converts the character to upper case. This is implemented as a macro for efficiency.
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
-\membersection{::wxTrace}\label{wxtrace}
-
-\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
-
-Takes printf-style variable argument syntax. Output
-is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
-
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
-\wxheading{Include files}
-
-<wx/memory.h>
-
-\membersection{::wxTraceLevel}\label{wxtracelevel}
-
-\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
-
-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 is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
-\wxheading{Include files}
-
-<wx/memory.h>
-
-\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{::wxUninitialize}\label{wxuninitialize}
-
-\func{void}{wxUninitialize}{\void}
-
-This function is for use in console (wxBase) programs only. It must be called
-once for each previous successful call to \helpref{wxInitialize}{wxinitialize}.
-
-\wxheading{Include files}
-
-<wx/app.h>
-
-\membersection{::wxUsleep}\label{wxusleep}
-
-\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.
-
-\wxheading{Include files}
-
-<wx/utils.h>
-
\membersection{::wxWriteResource}\label{wxwriteresource}
\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
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>
-
-\membersection{::wxYield}\label{wxyield}
-
-\func{bool}{wxYield}{\void}
-
-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 on systems with
-cooperative multitasking, such as Windows 3.1 other processes will not respond.
-
-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: see \helpref{::wxSafeYield}{wxsafeyield} for a better
-function.
-
-Note that wxYield will not flush the message logs. This is intentional as
-calling wxYield is usually done to quickly update the screen and popping up a
-message box dialog may be undesirable. If you do wish to flush the log
-messages immediately (otherwise it will be done during the next idle loop
-iteration), call \helpref{wxLog::FlushActive}{wxlogflushactive}.
-
-\wxheading{Include files}
-
-<wx/app.h> or <wx/utils.h>
-
-\membersection{::wxWakeUpIdle}\label{wxwakeupidle}
+\rtfsp{\bf wxFlushResources} is called automatically on exit, when
+all updated resource databases are written to their files.
-\func{void}{wxWakeUpIdle}{\void}
+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.
-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}.
+See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
\wxheading{Include files}
-<wx/app.h>
+<wx/utils.h>
-\section{Macros}\label{macros}
+\section{Byte order macros}\label{macros}
-These macros are defined in wxWindows.
+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{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
-This macro will swap the bytes of the {\it value} variable from little
-endian to big endian or vice versa.
+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}
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 (Intel i386) format.
+data in little-endian (for example Intel i386) format.
\membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
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.
+data in big-endian format.
+
+\section{RTTI functions}\label{macros}
+
+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}
<wx/object.h>
-\membersection{DECLARE\_ABSTRACT\_CLASS}
+\membersection{DECLARE\_ABSTRACT\_CLASS}\label{declareabstractclass}
\func{}{DECLARE\_ABSTRACT\_CLASS}{className}
<wx/app.h>
-\membersection{DECLARE\_CLASS}
+\membersection{DECLARE\_CLASS}\label{declareclass}
\func{}{DECLARE\_CLASS}{className}
<wx/object.h>
-\membersection{DECLARE\_DYNAMIC\_CLASS}
+\membersection{DECLARE\_DYNAMIC\_CLASS}\label{declaredynamicclass}
\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
<wx/object.h>
-\membersection{IMPLEMENT\_ABSTRACT\_CLASS}
+\membersection{IMPLEMENT\_ABSTRACT\_CLASS}\label{implementabstractclass}
\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
<wx/object.h>
-\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}
+\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}\label{implementabstractclass2}
\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
<wx/app.h>
-\membersection{IMPLEMENT\_CLASS}
+\membersection{IMPLEMENT\_CLASS}\label{implementclass}
\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
<wx/object.h>
-\membersection{IMPLEMENT\_CLASS2}
+\membersection{IMPLEMENT\_CLASS2}\label{implementclass2}
\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
<wx/object.h>
-\membersection{IMPLEMENT\_DYNAMIC\_CLASS}
+\membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass}
\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
<wx/object.h>
-\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}
+\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2}
\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
<wx/object.h>
-\membersection{wxBITMAP}\label{wxbitmapmacro}
-
-\func{}{wxBITMAP}{bitmapName}
-
-This macro loads a bitmap from either application resources (on the platforms
-for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
-avoid using {\tt \#ifdef}s when creating bitmaps.
-
-\wxheading{See also}
-
-\helpref{Bitmaps and icons overview}{wxbitmapoverview},
-\helpref{wxICON}{wxiconmacro}
-
-\wxheading{Include files}
-
-<wx/gdicmn.h>
-
\membersection{wxConstCast}\label{wxconstcast}
\func{classname *}{wxConstCast}{ptr, classname}
\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}
\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
+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.
\helpref{wxDynamicCast}{wxdynamiccast}
-\membersection{wxICON}\label{wxiconmacro}
-
-\func{}{wxICON}{iconName}
-
-This macro loads an icon from either application resources (on the platforms
-for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
-avoid using {\tt \#ifdef}s when creating icons.
-
-\wxheading{See also}
-
-\helpref{Bitmaps and icons overview}{wxbitmapoverview},
-\helpref{wxBITMAP}{wxbitmapmacro}
-
-\wxheading{Include files}
-
-<wx/gdicmn.h>
-
\membersection{wxStaticCast}\label{wxstaticcast}
\func{classname *}{wxStaticCast}{ptr, classname}
\helpref{wxDynamicCast}{wxdynamiccast}\\
\helpref{wxConstCast}{wxconstcast}
-\membersection{WXTRACE}\label{trace}
-
-\wxheading{Include files}
-
-<wx/object.h>
-
-\func{}{WXTRACE}{formatString, ...}
-
-Calls wxTrace with 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}.
-
-\wxheading{Include files}
-
-<wx/memory.h>
-
-\membersection{WXTRACELEVEL}\label{tracelevel}
+\section{Resource functions}\label{resourcefuncs}
-\func{}{WXTRACELEVEL}{level, formatString, ...}
-
-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.
-
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
-
-\wxheading{Include files}
-
-<wx/memory.h>
-
-\section{wxWindows resource functions}\label{resourcefuncs}
-
-\overview{wxWindows resource system}{resourceformats}
+\overview{Resource functions}{resourceformats}
This section details functions for manipulating wxWindows (.WXR) resource
files and loading user interface elements from resources.
\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}
+\membersection{::wxResourceClear}\label{wxresourceclear}
\func{void}{wxResourceClear}{\void}
Clears the wxWindows resource table.
-\membersection{::wxResourceCreateBitmap}
+\membersection{::wxResourceCreateBitmap}\label{wxresourcecreatebitmap}
\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
wxBitmap *bitmap = wxResourceCreateBitmap("project_resource");
\end{verbatim}
-\membersection{::wxResourceCreateIcon}
+\membersection{::wxResourceCreateIcon}\label{wxresourcecreateicon}
\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
wxIcon *icon = wxResourceCreateIcon("project_resource");
\end{verbatim}
-\membersection{::wxResourceCreateMenuBar}
+\membersection{::wxResourceCreateMenuBar}\label{wxresourcecreatemenubar}
\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
\end{verbatim}
-\membersection{::wxResourceGetIdentifier}
+\membersection{::wxResourceGetIdentifier}\label{wxresourcegetidentifier}
\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
Each of the contained resources will declare a new C++ variable, and each
of these variables should be passed to wxResourceParseData.
-\membersection{::wxResourceParseFile}
+\membersection{::wxResourceParseFile}\label{wxresourceparsefile}
\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
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.
-\membersection{::wxResourceRegisterIconData}
+\membersection{::wxResourceRegisterIconData}\label{wxresourceregistericondata}
Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
<wx/log.h>
+\membersection{::wxDebugMsg}\label{wxdebugmsg}
+
+\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
+
+{\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogdebug} instead!}
+
+Display a debugging message; under Windows, this will appear on the
+debugger command window, and under Unix, it will be written to standard
+error.
+
+The syntax is identical to {\bf printf}: pass a format string and a
+variable list of arguments.
+
+{\bf Tip:} under Windows, if your application crashes before the
+message appears in the debugging window, put a wxYield call after
+each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
+(at least for Watcom C++): preformat your messages and use OutputDebugString
+instead.
+
+This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxError}\label{wxerror}
+
+\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
+
+This function is now obsolete, please use \helpref{wxLogError}{wxlogerror}
+instead.
+
+Displays {\it msg} and continues. This writes to standard error under
+Unix, and pops up a message box under Windows. Used for internal
+wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxFatalError}\label{wxfatalerror}
+
+\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
+
+This function is now obsolete, please use
+\helpref{wxLogFatalError}{wxlogfatalerror} instead.
+
+Displays {\it msg} and exits. This writes to standard error under Unix,
+and pops up a message box under Windows. Used for fatal internal
+wxWindows errors. See also \helpref{wxError}{wxerror}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
\membersection{::wxLogError}\label{wxlogerror}
\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
\helpref{wxSysErrorCode}{wxsyserrorcode},
\helpref{wxLogSysError}{wxlogsyserror}
+\membersection{WXTRACE}\label{trace}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+\func{}{WXTRACE}{formatString, ...}
+
+Calls wxTrace with 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}.
+
+\wxheading{Include files}
+
+<wx/memory.h>
+
+\membersection{WXTRACELEVEL}\label{tracelevel}
+
+\func{}{WXTRACELEVEL}{level, formatString, ...}
+
+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.
+
+This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
+\wxheading{Include files}
+
+<wx/memory.h>
+
+\membersection{::wxTrace}\label{wxtrace}
+
+\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
+
+Takes printf-style variable argument syntax. Output
+is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
+
+This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
+\wxheading{Include files}
+
+<wx/memory.h>
+
+\membersection{::wxTraceLevel}\label{wxtracelevel}
+
+\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
+
+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 is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+
+\wxheading{Include files}
+
+<wx/memory.h>
+
\section{Time functions}\label{timefunctions}
The functions in this section deal with getting the current time and
<wx/timer.h>
+\membersection{::wxNow}\label{wxnow}
+
+\func{wxString}{wxNow}{\void}
+
+Returns a string representing the current date and time.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+\membersection{::wxSleep}\label{wxsleep}
+
+\func{void}{wxSleep}{\param{int}{ secs}}
+
+Sleeps for the specified number of seconds.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
\membersection{::wxStartTimer}\label{wxstarttimer}
\func{void}{wxStartTimer}{\void}
<wx/timer.h>
+\membersection{::wxUsleep}\label{wxusleep}
+
+\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.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
\section{Debugging macros and functions}\label{debugmacros}
Useful macros and functions for error checking and defensive programming. ASSERTs are only
\helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called
instead of wxFAIL() if the {\it condition} is false.
+\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>
+
\section{Environment access functions}\label{environfunctions}
The functions in this section allow to access (get) or change value of
Returns {\tt TRUE} on success.
-
projects / wxWidgets.git / blobdiff