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