X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/43bb369911099ab875c4239356fcea43ee6a486d..21f60945831a6edad0f2101b6053a2c8213d5296:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index a3bc04a831..7b2f4c1d31 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -2,2119 +2,4150 @@ \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{ngettext}{ngettext}\\ +\helpref{wxCONCAT}{wxconcat}\\ +\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{wxCHECK}{wxcheck}\\ +\helpref{wxCHECK2\_MSG}{wxcheck2msg}\\ +\helpref{wxCHECK2}{wxcheck2}\\ +\helpref{wxCHECK\_GCC\_VERSION}{wxcheckgccversion}\\ +\helpref{wxCHECK\_MSG}{wxcheckmsg}\\ +\helpref{wxCHECK\_RET}{wxcheckret}\\ +\helpref{wxCHECK\_VERSION}{wxcheckversion}\\ +\helpref{wxCHECK\_W32API\_VERSION}{wxcheckw32apiversion}\\ +\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{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}\\ +\helpref{wxCRIT\_SECT\_DECLARE\_MEMBER}{wxcritsectdeclaremember}\\ +\helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}\\ +\helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro}\\ % wxcs already taken! +\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{wxDYNLIB\_FUNCTION}{wxdynlibfunction}\\ +\helpref{wxEmptyClipboard}{wxemptyclipboard}\\ +\helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\ +\helpref{wxEndBusyCursor}{wxendbusycursor}\\ +\helpref{wxENTER\_CRIT\_SECT}{wxentercritsect}\\ +\helpref{wxEntry}{wxentry}\\ +\helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\ +\helpref{wxError}{wxerror}\\ +\helpref{wxExecute}{wxexecute}\\ +\helpref{wxExit}{wxexit}\\ +\helpref{wxEXPLICIT}{wxexplicit}\\ +\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{wxFinite}{wxfinite}\\ +\helpref{wxGetActiveWindow}{wxgetactivewindow}\\ +\helpref{wxGetApp}{wxgetapp}\\ +\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{wxGetProcessId}{wxgetprocessid}\\ +\helpref{wxGetResource}{wxgetresource}\\ +\helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\ +\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\ +\helpref{wxGetSingleChoice}{wxgetsinglechoice}\\ +\helpref{wxGetTempFileName}{wxgettempfilename}\\ +\helpref{wxGetTextFromUser}{wxgettextfromuser}\\ +\helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\ +\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{wxIsDebuggerRunning}{wxisdebuggerrunning}\\ +\helpref{wxIsEmpty}{wxisempty}\\ +\helpref{wxIsMainThread}{wxismainthread}\\ +\helpref{wxIsNaN}{wxisnan}\\ +\helpref{wxIsWild}{wxiswild}\\ +\helpref{wxKill}{wxkill}\\ +\helpref{wxLEAVE\_CRIT\_SECT}{wxleavecritsect}\\ +\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{wxLL}{wxll}\\ +\helpref{wxLongLongFmtSpec}{wxlonglongfmtspec}\\ +\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{wxRmdir}{wxrmdir}\\ +\helpref{wxSafeShowMessage}{wxsafeshowmessage}\\ +\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{wxShutdown}{wxshutdown}\\ +\helpref{wxSleep}{wxsleep}\\ +\helpref{wxSnprintf}{wxsnprintf}\\ +\helpref{wxSplitPath}{wxsplitfunction}\\ +\helpref{wxStartTimer}{wxstarttimer}\\ +\helpref{wxStaticCast}{wxstaticcast}\\ +\helpref{wxStrcmp}{wxstrcmp}\\ +\helpref{wxStricmp}{wxstricmp}\\ +\helpref{wxStringEq}{wxstringeq}\\ +\helpref{wxStringMatch}{wxstringmatch}\\ +\helpref{wxStripMenuCodes}{wxstripmenucodes}\\ +\helpref{wxStrlen}{wxstrlen}\\ +\helpref{wxSysErrorCode}{wxsyserrorcode}\\ +\helpref{wxSysErrorMsg}{wxsyserrormsg}\\ +\helpref{wxT}{wxt}\\ +\helpref{wxToLower}{wxtolower}\\ +\helpref{wxToUpper}{wxtoupper}\\ +\helpref{wxTraceLevel}{wxtracelevel}\\ +\helpref{wxTrace}{wxtrace}\\ +\helpref{wxTransferFileToStream}{wxtransferfiletostream}\\ +\helpref{wxTransferStreamToFile}{wxtransferstreamtofile}\\ +\helpref{wxTrap}{wxtrap}\\ +\helpref{wxULL}{wxull}\\ +\helpref{wxUninitialize}{wxuninitialize}\\ +\helpref{wxUnix2DosFilename}{wxunix2dosfilename}\\ +\helpref{wxUnsetEnv}{wxunsetenv}\\ +\helpref{wxUsleep}{wxusleep}\\ +\helpref{wxVsnprintf}{wxvsnprintf}\\ +\helpref{wxWakeUpIdle}{wxwakeupidle}\\ +\helpref{wxWriteResource}{wxwriteresource}\\ +\helpref{wxYield}{wxyield}\\ +\helpref{\_}{underscore}\\ +\helpref{\_T}{underscoret} + + + +\section{Version macros}\label{versionfunctions} + +The following constants are defined in wxWindows: -\section{File functions}\label{filefunctions} +\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} + +For example, the values or these constants for wxWindows 2.1.15 are 2, 1 and +15. + +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. \wxheading{Include files} - + or -\wxheading{See also} -\helpref{wxPathList}{wxpathlist} +\membersection{wxCHECK\_VERSION}\label{wxcheckversion} -\membersection{::wxDirExists} +\func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}} -\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} +This is a macro which evaluates to true if the current wxWindows version is at +least major.minor.release. -Returns TRUE if the directory exists. +For example, to test if the program is compiled with wxWindows 2.2 or higher, +the following can be done: -\membersection{::wxDos2UnixFilename} +\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{void}{Dos2UnixFilename}{\param{const wxString\& }{s}} -Converts a DOS to a Unix filename by replacing backslashes with forward -slashes. +\membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion} -\membersection{::wxFileExists} +\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}} -\func{bool}{wxFileExists}{\param{const wxString\& }{filename}} +Returns $1$ if the compiler being used to compile the code is GNU C++ +compiler (g++) version major.minor.release or greater. Otherwise, and also if +the compiler is not GNU C++ at all, returns $0$. -Returns TRUE if the file exists. -\membersection{::wxFileNameFromPath} +\membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion} -\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} +\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}} -\func{char*}{wxFileNameFromPath}{\param{char* }{path}} +Returns $1$ if the version of w32api headers used is major.minor.release or +greater. Otherwise, and also if we are not compiling with mingw32/cygwin under +Win32 at all, returns $0$. -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} -\func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}} +\section{Application initialization and termination}\label{appinifunctions} -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. +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. -{\it spec} may contain wildcards. -{\it flags} is reserved for future use. +\membersection{::wxEntry}\label{wxentry} -For example: +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. -\begin{verbatim} - wxString f = wxFindFirstFile("/home/project/*.*"); - while ( !f.IsEmpty() ) - { - ... - f = wxFindNextFile(); - } -\end{verbatim} +\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, + \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = true}} -\membersection{::wxFindNextFile}\label{wxfindnextfile} +wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is false, the +function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows +message loop will be entered. -\func{wxString}{wxFindFirstFile}{\void} +\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, + \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}} -Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. +wxWindows initialization under Windows (for applications constructed as a DLL). -\membersection{::wxGetOSDirectory}\label{wxgetosdirectory} +\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}} -\func{wxString}{wxGetOSDirectory}{\void} +wxWindows initialization under Unix. -Returns the Windows directory under Windows; on other platforms returns the empty string. +\wxheading{Remarks} -\membersection{::wxIsAbsolutePath} +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{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} +\begin{verbatim} +int CTheApp::ExitInstance() +{ + // OnExit isn't called by CleanUp so must be called explicitly. + wxTheApp->OnExit(); + wxApp::CleanUp(); -Returns TRUE if the argument is an absolute filename, i.e. with a slash -or drive name at the beginning. + return CWinApp::ExitInstance(); +} +\end{verbatim} -\membersection{::wxPathOnly} +\wxheading{Include files} -\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} + -Returns the directory part of the filename. -\membersection{::wxUnix2DosFilename} -\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}} +\membersection{::wxGetApp}\label{wxgetapp} -Converts a Unix to a DOS filename by replacing forward -slashes with backslashes. +\func{wxAppDerivedClass\&}{wxGetApp}{\void} -\membersection{::wxConcatFiles} +This function doesn't exist in wxWindows but it is created by using +the \helpref{IMPLEMENT\_APP}{implementapp} macro. Thus, before using it +anywhere but in the same module where this macro is used, you must make it +available using \helpref{DECLARE\_APP}{declareapp}. -\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, -\param{const wxString\& }{file3}} +The advantage of using this function compared to directly using the global +wxTheApp pointer is that the latter is of type {\tt wxApp *} and so wouldn't +allow you to access the functions specific to your application class but not +present in wxApp while wxGetApp() returns the object of the right type. -Concatenates {\it file1} and {\it file2} to {\it file3}, returning -TRUE if successful. -\membersection{::wxCopyFile} +\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions} -\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} +\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = true}} -Copies {\it file1} to {\it file2}, returning TRUE if successful. +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. -\membersection{::wxGetCwd}\label{wxgetcwd} -\func{wxString}{wxGetCwd}{\void} +\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers} -Returns a string containing the current (or working) directory. +\func{void}{wxInitAllImageHandlers}{\void} -\membersection{::wxGetHostName}\label{wxgethostname} +Initializes all available image handlers. For a list of available handlers, +see \helpref{wxImage}{wximage}. -\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int }{sz}} +\wxheading{See also} -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. +\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler} -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. +\wxheading{Include files} -Returns TRUE if successful, FALSE otherwise. + -\membersection{::wxGetEmailAddress}\label{wxgetemailaddress} -\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}} +\membersection{::wxInitialize}\label{wxinitialize} -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}{wxInitialize}{\void} -Returns TRUE if successful, FALSE otherwise. +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{::wxGetUserId}\label{wxgetuserid} +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}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int }{sz}} +This function may be called several times but +\helpref{wxUninitialize}{wxuninitialize} must be called for each successful +call to this function. -Copies the current user id into the supplied buffer. +\wxheading{Include files} -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. + -Returns TRUE if successful, FALSE otherwise. -\membersection{::wxGetUserName}\label{wxgetusername} +\membersection{::wxSafeYield}\label{wxsafeyield} -\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int }{sz}} +\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}, \param{bool}{ + onlyIfNeeded = false}} -Copies the current user name into the supplied buffer. +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. -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. +Returns the result of the call to \helpref{::wxYield}{wxyield}. -Returns TRUE if successful, FALSE otherwise. +\wxheading{Include files} -\membersection{::wxGetWorkingDirectory} + -\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}} -This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead. +\membersection{::wxUninitialize}\label{wxuninitialize} -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{void}{wxUninitialize}{\void} -{\it sz} is the size of the buffer if supplied. +This function is for use in console (wxBase) programs only. It must be called +once for each previous successful call to \helpref{wxInitialize}{wxinitialize}. -\membersection{::wxGetTempFileName} +\wxheading{Include files} -\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}} + -Makes a temporary filename based on {\it prefix}, opens and closes the file, -and places the name in {\it buf}. If {\it buf} is NULL, new store -is allocated for the temporary filename using {\it new}. -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. +\membersection{::wxYield}\label{wxyield} -It is the application's responsibility to create and delete the file. +\func{bool}{wxYield}{\void} -\membersection{::wxIsWild}\label{wxiswild} +Calls \helpref{wxApp::Yield}{wxappyield}. -\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} +This function is kept only for backwards compatibility. Please use +the \helpref{wxApp::Yield}{wxappyield} method instead in any new code. -Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. +\wxheading{Include files} -\membersection{::wxMatchWild}\label{wxmatchwild} + or -\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} -Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it -dot\_special}\/ is TRUE, filenames beginning with a dot are not matched -with wildcard characters. See \helpref{wxIsWild}{wxiswild}. +\membersection{::wxWakeUpIdle}\label{wxwakeupidle} -\membersection{::wxMkdir} +\func{void}{wxWakeUpIdle}{\void} -\func{bool}{wxMkdir}{\param{const wxString\& }{dir}} +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}. -Makes the directory {\it dir}, returning TRUE if successful. +\wxheading{Include files} -\membersection{::wxRemoveFile} + -\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} -Removes {\it file}, returning TRUE if successful. -\membersection{::wxRenameFile} +\section{Process control functions}\label{processfunctions} -\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} +The functions in this section are used to launch or terminate the other +processes. -Renames {\it file1} to {\it file2}, returning TRUE if successful. -\membersection{::wxRmdir} +\membersection{::wxExecute}\label{wxexecute} -\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}} +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} -Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS. +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteCommand}} -The {\it flags} parameter is reserved for future use. +\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} -\membersection{::wxSetWorkingDirectory} +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteArgs}} -\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}} +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}} -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. +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdout} and it +only takes the {\tt command} argument, +and returns a 2-element list {\tt ( status, output )}, where {\tt output} is +an array reference.} -\membersection{::wxSplitPath}\label{wxsplitfunction} +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}} -\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{const wxString *}{ path}, \param{const wxString *}{ name}, \param{const wxString *}{ ext}} +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdoutStderr} +and it 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.} -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. +Executes another program in Unix or Windows. -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). +The first form takes a command string, such as {\tt "emacs file.txt"}. -On entry, {\it fullname} should be non NULL (it may be empty though). +The second form takes an array of values: a command, any number of +arguments, terminated by NULL. -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). +The semantics of the third and fourth versions is different from the first two +and is described in more details below. -\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream} +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. -\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}} +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}. -Copies the given file to {\it stream}. Useful when converting an old application to -use streams (within the document/view framework, for example). +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 indicates 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. + +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). + +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. + +{\bf NB:} Currently wxExecute() can only be used from the main thread, calling +this function from another thread will result in an assert failure in debug +build and won't work. -Use of this function requires the file wx\_doc.h to be included. +\wxheading{See also} -\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile} +\helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, \helpref{Exec sample}{sampleexec}. -\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}} +\wxheading{Parameters} -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). +\docparam{command}{The command to execute and any parameters to pass to it as a +single string.} -Use of this function requires the file wx\_doc.h to be included. +\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.} -\section{String functions} +\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC}, +{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}} -\membersection{::copystring} +\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}} -\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} -\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\ - \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}} +\membersection{::wxExit}\label{wxexit} -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. +\func{void}{wxExit}{\void} -\membersection{::wxStringEq}\label{wxstringeq} +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}. -\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} +\wxheading{Include files} -A macro defined as: + + + +\membersection{::wxKill}\label{wxkill} + +\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}} + +Equivalent to the Unix kill function: send the given signal {\it sig} to the +process with PID {\it pid}. The valid signal values are \begin{verbatim} -#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) +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} -\membersection{::IsEmpty}\label{isempty} +{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning +under both Unix and Windows but all the other signals are equivalent to +{\tt wxSIGTERM} under Windows. -\func{bool}{IsEmpty}{\param{const char *}{ p}} +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: -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. +\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} -\membersection{::Stricmp}\label{stricmp} +\wxheading{See also} -\func{int}{Stricmp}{\param{const char *}{p1}, \param{const char *}{p2}} +\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp +\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp +\helpref{Exec sample}{sampleexec} -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. +\wxheading{Include files} -This function complements the standard C function {\it strcmp()} which performs -case-sensitive comparison. + -\membersection{::Strlen}\label{strlen} -\func{size\_t}{Strlen}{\param{const char *}{ p}} +\membersection{::wxGetProcessId}\label{wxgetprocessid} -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. +\func{unsigned long}{wxGetProcessId}{\void} -\membersection{::wxGetTranslation}\label{wxgettranslation} +Returns the number uniquely identifying the current process in the system. -\func{const char *}{wxGetTranslation}{\param{const char * }{str}} +If an error occurs, $0$ is returned. -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{Include files} -\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{::wxFileSelector}\label{wxfileselector} +\membersection{::wxShell}\label{wxshell} -\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}} +\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} -Pops up a file selector box. In Windows, this is the common file selector -dialog. In X, this is a file selector box with somewhat less 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, or 0. They are only significant -at present in Windows. +Executes a command in an interactive shell window. If no command is +specified, then just the shell is spawned. -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. +See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}. -Under Windows (only), the wildcard may be a specification for multiple -types of file with a description for each, such as: +\wxheading{Include files} -\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} +\membersection{::wxShutdown}\label{wxshutdown} -\wxheading{Include files} +\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}} - +This function shuts down or reboots the computer depending on the value of the +{\it flags}. Please notice that doing this requires the corresponding access +rights (superuser under Unix, {\tt SE\_SHUTDOWN} privelege under Windows NT) +and that this function is only implemented under Unix and Win32. -\membersection{::wxGetTextFromUser}\label{wxgettextfromuser} +\wxheading{Parameters} -\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}} +\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}} -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. +\wxheading{Returns} -If {\it centre} is TRUE, the message text (which may include new line characters) -is centred; if FALSE, the message is left-justified. +{\tt true} on success, {\tt false} if an error occured. \wxheading{Include files} - + -\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice} -\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ - \param{int }{nsel}, \param{int *}{selection}, - \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ - \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} -Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection -listbox. The user may choose one or more item(s) and press OK or Cancel. +\section{Thread functions}\label{threadfunctions} -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. +The functions and macros here mainly exist to make it writing the code which +may be compiled in multi thread build ({\tt wxUSE\_THREADS} $= 1$) as well as +in single thread configuration ({\tt wxUSE\_THREADS} $= 0$). -If Cancel is pressed, -1 is returned. +For example, a static variable must be protected against simultaneous access by +multiple threads in the former configuration but in the latter the extra +overhead of using the critical section is not needed. To solve this problem, +the \helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro} macro may be used +to create and use the critical section only when needed. -{\it choices} is an array of {\it n} strings for the listbox. +\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} +\wxheading{See also} - +\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview} -\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice} -\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ - \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ - \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} -Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection -listbox. The user may choose an item and press OK to return a string or -Cancel to return the empty string. +\membersection{wxCRIT\_SECT\_DECLARE}\label{wxcritsectdeclare} -{\it choices} is an array of {\it n} strings for the listbox. +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} -If {\it centre} is TRUE, the message text (which may include new line characters) -is centred; if FALSE, the message is left-justified. +This macro declares a (static) critical section object named {\it cs} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. -\wxheading{Include files} - -\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex} +\membersection{wxCRIT\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember} -\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}} +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} -As {\bf wxGetSingleChoice} but returns the index representing the selected string. -If the user pressed cancel, -1 is returned. +This macro declares a critical section object named {\it cs} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. As it doesn't +include the {\tt static} keyword (unlike +\helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}), it can be used to declare +a class or struct member which explains its name. -\wxheading{Include files} - - -\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata} -\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ - \param{const wxString\& }{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\ - \param{int}{ y = -1}, \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} +\membersection{wxCRIT\_SECT\_LOCKER}\label{wxcritsectlocker} -As {\bf wxGetSingleChoice} but takes an array of client data pointers -corresponding to the strings, and returns one of these pointers. +\func{}{wxCRIT\_SECT\_LOCKER}{\param{}{name}, \param{}{cs}} -\wxheading{Include files} +This macro creates a \helpref{critical section lock}{wxcriticalsectionlocker} +object named {\it name} and associated with the critical section {\it cs} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. - -\membersection{::wxMessageBox}\label{wxmessagebox} -\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{wxCRITICAL\_SECTION}\label{wxcriticalsectionmacro} -General purpose message dialog. {\it style} may be a bit list of the -following identifiers: +\func{}{wxCRITICAL\_SECTION}{\param{}{name}} -\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} +This macro combines \helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare} and +\helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}: it creates a static critical +section object and also the lock object associated with it. Because of this, it +can be only used inside a function, not at global scope. For example: -The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. +\begin{verbatim} +int IncCount() +{ + static int s_counter = 0; -For example: + wxCRITICAL_SECTION(counter); -\begin{verbatim} - ... - int answer = wxMessageBox("Quit program?", "Confirm", - wxYES_NO | wxCANCEL, main_frame); - if (answer == wxYES) - delete main_frame; - ... + return ++s_counter; +} \end{verbatim} -{\it message} may contain newline characters, in which case the -message will be split into separate lines, to cater for large messages. - -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. +(note that we suppose that the function is called the first time from the main +thread so that the critical section object is initialized correctly by the time +other threads start calling it, if this is not the case this approach can +{\bf not} be used and the critical section must be made a global instead). -\wxheading{Include files} - -\section{GDI functions}\label{gdifunctions} +\membersection{wxENTER\_CRIT\_SECT}\label{wxentercritsect} -The following are relevant to the GDI (Graphics Device Interface). +\func{}{wxENTER\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} -\wxheading{Include files} +This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. - -\membersection{::wxColourDisplay} -\func{bool}{wxColourDisplay}{\void} +\membersection{::wxIsMainThread}\label{wxismainthread} -Returns TRUE if the display is colour, FALSE otherwise. +\func{bool}{wxIsMainThread}{\void} -\membersection{::wxDisplayDepth} +Returns {\tt true} if this thread is the main one. Always returns {\tt true} if +{\tt wxUSE\_THREADS} is $0$. -\func{int}{wxDisplayDepth}{\void} -Returns the depth of the display (a value of 1 denotes a monochrome display). -\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable} +\membersection{wxLEAVE\_CRIT\_SECT}\label{wxleavecritsect} -\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY}, - \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}} +\func{}{wxLEAVE\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} -Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc}) -makes it into a placeable metafile by prepending a header containing the given -bounding box. The bounding box may be obtained from a device context after drawing -into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. +This macro is equivalent to \helpref{cs.Leave()}{wxcriticalsectionleave} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. -In addition to adding the placeable metafile header, this function adds -the equivalent of the following code to the start of the metafile data: -\begin{verbatim} - SetMapMode(dc, MM_ANISOTROPIC); - SetWindowOrg(dc, minX, minY); - SetWindowExt(dc, maxX - minX, maxY - minY); -\end{verbatim} -This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes. +\membersection{::wxMutexGuiEnter}\label{wxmutexguienter} -Placeable metafiles may be imported by many Windows applications, and can be -used in RTF (Rich Text Format) files. +\func{void}{wxMutexGuiEnter}{\void} -{\it scale} allows the specification of scale for the metafile. +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}. -This function is only available under Windows. +Typically, these functions are used like this: -\membersection{::wxSetCursor}\label{wxsetcursor} +\begin{verbatim} +void MyThread::Foo(void) +{ + // before doing any GUI calls we must ensure that this thread is the only + // one doing it! -\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}} + wxMutexGuiEnter(); -Globally sets the cursor; only has an effect in MS Windows. -See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. + // Call GUI here: + my_window->DrawSomething(); -\section{Printer settings}\label{printersettings} + wxMutexGuiLeave(); +} +\end{verbatim} -The following functions are used to control PostScript printing. Under -Windows, PostScript output can only be sent to a file. +Note that under GTK, no creation of top-level windows is allowed in any +thread but the main one. -\wxheading{Include files} +This function is only defined on platforms which support preemptive +threads. - -\membersection{::wxGetPrinterCommand} +\membersection{::wxMutexGuiLeave}\label{wxmutexguileave} -\func{wxString}{wxGetPrinterCommand}{\void} +\func{void}{wxMutexGuiLeave}{\void} -Gets the printer command used to print a file. The default is {\tt lpr}. +See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}. -\membersection{::wxGetPrinterFile} +This function is only defined on platforms which support preemptive +threads. -\func{wxString}{wxGetPrinterFile}{\void} -Gets the PostScript output filename. -\membersection{::wxGetPrinterMode} +\section{File functions}\label{filefunctions} -\func{int}{wxGetPrinterMode}{\void} +\wxheading{Include files} -Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). -The default is PS\_PREVIEW. + -\membersection{::wxGetPrinterOptions} +\wxheading{See also} -\func{wxString}{wxGetPrinterOptions}{\void} +\helpref{wxPathList}{wxpathlist}\\ +\helpref{wxDir}{wxdir}\\ +\helpref{wxFile}{wxfile}\\ +\helpref{wxFileName}{wxfilename} -Gets the additional options for the print command (e.g. specific printer). The default is nothing. -\membersection{::wxGetPrinterOrientation} +\membersection{::wxDirExists}\label{functionwxdirexists} -\func{int}{wxGetPrinterOrientation}{\void} +\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} -Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. +Returns true if the directory exists. -\membersection{::wxGetPrinterPreviewCommand} -\func{wxString}{wxGetPrinterPreviewCommand}{\void} +\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename} -Gets the command used to view a PostScript file. The default depends on the platform. +\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}} -\membersection{::wxGetPrinterScaling} +Converts a DOS to a Unix filename by replacing backslashes with forward +slashes. -\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}} -Gets the scaling factor for PostScript output. The default is 1.0, 1.0. +\membersection{::wxFileExists}\label{functionwxfileexists} -\membersection{::wxGetPrinterTranslation} +\func{bool}{wxFileExists}{\param{const wxString\& }{filename}} -\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}} +Returns true if the file exists and is a plain file. -Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. -\membersection{::wxSetPrinterCommand} +\membersection{::wxFileModificationTime}\label{wxfilemodificationtime} -\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}} +\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}} -Sets the printer command used to print a file. The default is {\tt lpr}. +Returns time of last modification of given file. -\membersection{::wxSetPrinterFile} -\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}} +\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath} -Sets the PostScript output filename. +\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} -\membersection{::wxSetPrinterMode} +\func{char *}{wxFileNameFromPath}{\param{char *}{path}} -\func{void}{wxSetPrinterMode}{\param{int }{mode}} +{\bf NB:} This function is obsolete, please use +\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. -Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). -The default is PS\_PREVIEW. +Returns the filename for a full path. The second form returns a pointer to +temporary storage that should not be deallocated. -\membersection{::wxSetPrinterOptions} -\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}} +\membersection{::wxFindFirstFile}\label{wxfindfirstfile} -Sets the additional options for the print command (e.g. specific printer). The default is nothing. +\func{wxString}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}} -\membersection{::wxSetPrinterOrientation} +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 "..". -\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}} +{\it spec} may contain wildcards. -Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. +{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either. -\membersection{::wxSetPrinterPreviewCommand} +For example: -\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}} +\begin{verbatim} + wxString f = wxFindFirstFile("/home/project/*.*"); + while ( !f.IsEmpty() ) + { + ... + f = wxFindNextFile(); + } +\end{verbatim} -Sets the command used to view a PostScript file. The default depends on the platform. -\membersection{::wxSetPrinterScaling} +\membersection{::wxFindNextFile}\label{wxfindnextfile} -\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}} +\func{wxString}{wxFindNextFile}{\void} -Sets the scaling factor for PostScript output. The default is 1.0, 1.0. +Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. -\membersection{::wxSetPrinterTranslation} +See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example. -\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}} -Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. +\membersection{::wxGetDiskSpace}\label{wxgetdiskspace} -\section{Clipboard functions}\label{clipsboard} +\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}} -These clipboard functions are implemented for Windows only. +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. -\wxheading{Include files} +\wxheading{Returns} - +{\tt true} on success, {\tt false} if an error occured (for example, the +directory doesn't exist). -\membersection{::wxClipboardOpen} +\wxheading{Portability} -\func{bool}{wxClipboardOpen}{\void} +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. -Returns TRUE if this application has already opened the clipboard. +This function first appeared in wxWindows 2.3.2. -\membersection{::wxCloseClipboard} -\func{bool}{wxCloseClipboard}{\void} +\membersection{::wxGetOSDirectory}\label{wxgetosdirectory} -Closes the clipboard to allow other applications to use it. +\func{wxString}{wxGetOSDirectory}{\void} -\membersection{::wxEmptyClipboard} +Returns the Windows directory under Windows; on other platforms returns the empty string. -\func{bool}{wxEmptyClipboard}{\void} -Empties the clipboard. +\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath} -\membersection{::wxEnumClipboardFormats} +\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} -\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}} +Returns true if the argument is an absolute filename, i.e. with a slash +or drive name at the beginning. -Enumerates the formats found in a list of available formats that belong -to the clipboard. Each call to this function specifies a known -available format; the function returns the format that appears next in -the list. -{\it dataFormat} specifies a known format. If this parameter is zero, -the function returns the first format in the list. +\membersection{::wxPathOnly}\label{wxpathonly} -The return value specifies the next known clipboard data format if the -function is successful. It is zero if the {\it dataFormat} parameter specifies -the last format in the list of available formats, or if the clipboard -is not open. +\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} -Before it enumerates the formats function, an application must open the clipboard by using the -wxOpenClipboard function. +Returns the directory part of the filename. -\membersection{::wxGetClipboardData} -\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}} +\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename} -Gets data from the clipboard. +\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}} -{\it dataFormat} may be one of: +Converts a Unix to a DOS filename by replacing forward +slashes with backslashes. -\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{::wxConcatFiles}\label{wxconcatfiles} -\membersection{::wxGetClipboardFormatName} +\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, +\param{const wxString\& }{file3}} -\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}} +Concatenates {\it file1} and {\it file2} to {\it file3}, returning +true if successful. -Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum -length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format. -\membersection{::wxIsClipboardFormatAvailable} +\membersection{::wxCopyFile}\label{wxcopyfile} -\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}} +\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}} -Returns TRUE if the given data format is available on the clipboard. +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 fails in this +case. -\membersection{::wxOpenClipboard} -\func{bool}{wxOpenClipboard}{\void} +\membersection{::wxGetCwd}\label{wxgetcwd} -Opens the clipboard for passing data to it or getting data from it. +\func{wxString}{wxGetCwd}{\void} -\membersection{::wxRegisterClipboardFormat} +Returns a string containing the current (or working) directory. -\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}} -Registers the clipboard data format name and returns an identifier. +\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory} -\membersection{::wxSetClipboardData} +\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}} -\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}} +{\bf NB:} This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead. -Passes data to the clipboard. +Copies the current working directory into the buffer if supplied, or +copies the working directory into new storage (which you {\emph must} delete +yourself) if the buffer is NULL. -{\it dataFormat} may be one of: +{\it sz} is the size of the buffer if supplied. -\begin{itemize}\itemsep=0pt -\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string. -\item wxCF\_BITMAP: {\it data} is a wxBitmap. -\item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap). -\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions. -\end{itemize} -The clipboard must have previously been opened for this call to succeed. +\membersection{::wxGetTempFileName}\label{wxgettempfilename} -\section{Miscellaneous functions}\label{miscellany} +\func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}} -\membersection{::wxNewId} +\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}} -\func{long}{wxNewId}{\void} +%% 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. -Generates an integer identifier unique to this run of the program. +{\bf NB:} These functions are obsolete, please use\rtfsp +\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp +instead. -\wxheading{Include files} - +\membersection{::wxIsWild}\label{wxiswild} -\membersection{::wxRegisterId} +\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} -\func{void}{wxRegisterId}{\param{long}{ id}} +Returns true if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. -Ensures that ids subsequently generated by {\bf NewId} do not clash with -the given {\bf id}. -\wxheading{Include files} +\membersection{::wxMatchWild}\label{wxmatchwild} - +\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} -\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} +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}. -\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. +\membersection{::wxMkdir}\label{wxmkdir} -See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. +\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}} -\wxheading{Include files} +Makes the directory {\it dir}, returning true if successful. - +{\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. -\membersection{::wxBell} -\func{void}{wxBell}{\void} +\membersection{::wxRemoveFile}\label{wxremovefile} -Ring the system bell. +\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} -\wxheading{Include files} +Removes {\it file}, returning true if successful. - -\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject} +\membersection{::wxRenameFile}\label{wxrenamefile} -\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}} +\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} -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. +Renames {\it file1} to {\it file2}, returning true if successful. -\membersection{::wxDDECleanUp}\label{wxddecleanup} -\func{void}{wxDDECleanUp}{\void} +\membersection{::wxRmdir}\label{wxrmdir} -Called when wxWindows exits, to clean up the DDE system. This no longer needs to be -called by the application. +\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}} -See also helpref{wxDDEInitialize}{wxddeinitialize}. +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{::wxDDEInitialize}\label{wxddeinitialize} +\membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory} -\func{void}{wxDDEInitialize}{\void} +\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}} -Initializes the DDE system. May be called multiple times without harm. +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. -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}. +\membersection{::wxSplitPath}\label{wxsplitfunction} -\wxheading{Include files} +\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}} - +{\bf NB:} This function is obsolete, please use +\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. -\membersection{::wxDebugMsg}\label{wxdebugmsg} +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. -\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}} +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). -Display a debugging message; under Windows, this will appear on the -debugger command window, and under Unix, it will be written to standard -error. +On entry, {\it fullname} should be non-NULL (it may be empty though). -The syntax is identical to {\bf printf}: pass a format string and a -variable list of arguments. +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). -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{::wxTransferFileToStream}\label{wxtransferfiletostream} + +\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}} -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +Copies the given file to {\it stream}. Useful when converting an old application to +use streams (within the document/view framework, for example). \wxheading{Include files} - + -\membersection{::wxDisplaySize} -\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} +\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile} -Gets the physical size of the display in pixels. +\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}} -\wxheading{Include files} +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} -\membersection{::wxEntry}\label{wxentry} + -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{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}} -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. +\section{Network, user and OS functions}\label{networkfunctions} -\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}} +The functions in this section are used to retrieve information about the +current computer and/or user characteristics. -wxWindows initialization under Windows (for applications constructed as a DLL). -\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}} +\membersection{::wxGetFreeMemory}\label{wxgetfreememory} -wxWindows initialization under Unix. +\func{long}{wxGetFreeMemory}{\void} -\wxheading{Remarks} +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. -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: +\wxheading{Include files} -\begin{verbatim} -int CTheApp::ExitInstance() -{ - // OnExit isn't called by CleanUp so must be called explicitly. - wxTheApp->OnExit(); - wxApp::CleanUp(); + - return CWinApp::ExitInstance(); -} -\end{verbatim} -\wxheading{Include files} +\membersection{::wxGetFullHostName}\label{wxgetfullhostname} - +\func{wxString}{wxGetFullHostName}{\void} -\membersection{::wxError}\label{wxerror} +Returns the FQDN (fully qualified domain host name) or an empty string on +error. -\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}} +\wxheading{See also} -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}. +\helpref{wxGetHostName}{wxgethostname} \wxheading{Include files} -\membersection{::wxEndBusyCursor}\label{wxendbusycursor} -\func{void}{wxEndBusyCursor}{\void} +\membersection{::wxGetEmailAddress}\label{wxgetemailaddress} -Changes the cursor back to the original cursor, for all windows in the application. -Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}. +\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}} -See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. +Copies the user's email address into the supplied buffer, by +concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp +and \helpref{wxGetUserId}{wxgetuserid}. + +Returns true if successful, false otherwise. \wxheading{Include files} -\membersection{::wxExecute}\label{wxexecute} - -\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} - -\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} - -Executes another program in Unix or Windows. - -The first form takes a command string, such as {\tt "emacs file.txt"}. - -The second form takes an array of values: a command, any number of -arguments, terminated by NULL. -If {\it sync} is FALSE (the default), flow of control immediately returns. -If TRUE, the current application waits until the other program has terminated. +\membersection{::wxGetHomeDir}\label{wxgethomedir} -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. +\func{wxString}{wxGetHomeDir}{\void} -For asynchronous execution, however, the return value is the process id and -zero value indicates that the command could not be executed. +Return the (current) user's home directory. -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. +\wxheading{See also} -See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}. +\helpref{wxGetUserHome}{wxgetuserhome} \wxheading{Include files} -\membersection{::wxExit}\label{wxexit} -\func{void}{wxExit}{\void} +\membersection{::wxGetHostName}\label{wxgethostname} -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}. +\func{wxString}{wxGetHostName}{\void} -\wxheading{Include files} +\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}} - +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. -\membersection{::wxFatalError}\label{wxfatalerror} +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. -\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}} +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. -Displays {\it msg} and exits. This writes to standard error under Unix, -and pops up a message box under Windows. Used for fatal internal -wxWindows errors. See also \helpref{wxError}{wxerror}. +\wxheading{See also} + +\helpref{wxGetFullHostName}{wxgetfullhostname} \wxheading{Include files} -\membersection{::wxFindMenuItemId} -\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}} +\membersection{::wxGetUserId}\label{wxgetuserid} -Find a menu item identifier associated with the given frame's menu bar. +\func{wxString}{wxGetUserId}{\void} -\wxheading{Include files} +\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}} - +This function returns the "user id" also known as "login name" under Unix i.e. +something like "jsmith". It uniquely identifies the current user (on this system). -\membersection{::wxFindWindowByLabel} +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. -\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}} +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. -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{See also} + +\helpref{wxGetUserName}{wxgetusername} \wxheading{Include files} -\membersection{::wxFindWindowByName}\label{wxfindwindowbyname} -\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}} +\membersection{::wxGetOsDescription}\label{wxgetosdescription} -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}{wxGetOsDescription}{\void} -If no such named window is found, {\bf wxFindWindowByLabel} is called. +Returns the string containing the description of the current platform in a +user-readable form. For example, this function may return strings like +{\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}. + +\wxheading{See also} + +\helpref{::wxGetOsVersion}{wxgetosversion} \wxheading{Include files} -\membersection{::wxGetActiveWindow}\label{wxgetactivewindow} -\func{wxWindow *}{wxGetActiveWindow}{\void} +\membersection{::wxGetOsVersion}\label{wxgetosversion} -Gets the currently active window (Windows only). +\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} -\wxheading{Include files} +Gets operating system version information. - +\begin{twocollist}\itemsep=0pt +\twocolitemruled{Platform}{Return types} +\twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X. -\membersection{::wxGetDisplayName}\label{wxgetdisplayname} +Both {\it major} and {\it minor} have to be looked at as hexadecimal numbers. So System 10.2.4 returns 0x10, resp 16 for {\it major} and 0x24, resp 36 for {\it minor}. } +\twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. } +\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.} +\twocolitem{OS/2}{Return value is wxOS2\_PM.} +\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.} +\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}} +\twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.} +\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.} +\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.} +\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.} +\end{twocollist} -\func{wxString}{wxGetDisplayName}{\void} +\wxheading{See also} -Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}. +\helpref{::wxGetOsDescription}{wxgetosdescription} \wxheading{Include files} -\membersection{::wxGetHomeDir} -\func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}} +\membersection{::wxGetUserHome}\label{wxgetuserhome} -Fills the buffer with a string representing the user's home directory (Unix only). +\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}} + +Returns the home directory for the given user. If the username is empty +(default value), this function behaves like +\helpref{wxGetHomeDir}{wxgethomedir}. \wxheading{Include files} -\membersection{::wxGetHostName} -\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} +\membersection{::wxGetUserName}\label{wxgetusername} + +\func{wxString}{wxGetUserName}{\void} + +\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}} + +This function returns the full user name (something like "Mr. John Smith"). + +Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp +in the {\bf wxWindows} section of the WIN.INI file. If PenWindows +is running, the entry {\bf Current} in the section {\bf User} of +the PENWIN.INI file is used. -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''. +The first variant of this function returns the user name if successful or an +empty string otherwise. The second (deprecated) function returns {\tt true} +if successful, {\tt false} otherwise. + +\wxheading{See also} + +\helpref{wxGetUserId}{wxgetuserid} \wxheading{Include files} -\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime} -\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}} -Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}. +\section{String functions} -If {\it resetTimer} is TRUE (the default), the timer is reset to zero -by this call. -See also \helpref{wxTimer}{wxtimer}. +\membersection{::copystring}\label{copystring} -\wxheading{Include files} +\func{char *}{copystring}{\param{const char *}{s}} - +Makes a copy of the string {\it s} using the C++ new operator, so it can be +deleted with the {\it delete} operator. -\membersection{::wxGetFreeMemory}\label{wxgetfreememory} +This function is deprecated, use \helpref{wxString}{wxstring} class instead. -\func{long}{wxGetFreeMemory}{\void} -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. +\membersection{ngettext}\label{ngettext} -\wxheading{Include files} +\func{const wxChar *}{ngettext}{\param{const char *}{str}, \param{const char *}{strPlural}, \param{size\_t }{n}} - +This macro expands into a call to plural form version of +\helpref{wxGetTranslation}{wxgettranslation} +function, so it marks the message for the extraction by {\tt xgettext} just as +\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of +the string for the current locale during execution, either singular or plural +form depending on the value of \arg{n}. -\membersection{::wxGetMousePosition} +\wxheading{See also} -\func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}} +\helpref{\_}{underscore} -Returns the mouse position in screen coordinates. -\wxheading{Include files} +\membersection{::wxGetTranslation}\label{wxgettranslation} - +\func{const char *}{wxGetTranslation}{\param{const char * }{str}} -\membersection{::wxGetOsVersion} +\func{const char *}{wxGetTranslation}{\param{const char * }{str}, \param{const char * }{strPlural}, \param{size\_t }{n}} -\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} +This function returns the translation of string {\it str} in the current +\helpref{locale}{wxlocale}. If the string is not found in any of the loaded +message catalogs (see \helpref{internationalization overview}{internationalization}), the +original string is returned. In debug build, an error message is logged -- this +should help to find the strings which were not yet translated. As this function +is used very often, an alternative (and also common in Unix world) syntax is +provided: the \helpref{\_()}{underscore} macro is defined to do the same thing +as wxGetTranslation. -Gets operating system version information. +The second form is used when retrieving translation of string that has +different singular and plural form in English or different plural forms in some +other language. It takes two extra arguments: \arg{str} +parameter must contain the singular form of the string to be converted. +It is also used as the key for the search in the catalog. +The \arg{strPlural} parameter is the plural form (in English). +The parameter \arg{n} is used to determine the plural form. If no +message catalog is found \arg{str} is returned if `n == 1', +otherwise \arg{strPlural}. The \helpref{ngettext}{ngettext} macro is defined +to do the same thing. +See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} for additional information on plural forms handling. -\begin{twocollist}\itemsep=0pt -\twocolitemruled{Platform}{Return tyes} -\twocolitem{Macintosh}{Return value is wxMACINTOSH.} -\twocolitem{GTK}{Return value is wxGTK, {\it major} is 1, {\it minor} is 0. (for GTK 1.0.X) } -\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.} -\twocolitem{OS/2}{Return value is wxOS2\_PM.} -\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.} -\twocolitem{Windows NT}{Return value is wxWINDOWS\_NT, {\it major} is 3, {\it minor} is 1.} -\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 3, {\it minor} is 1.} -\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.} -\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.} -\end{twocollist} +\membersection{::wxIsEmpty}\label{wxisempty} -\wxheading{Include files} +\func{bool}{wxIsEmpty}{\param{const char *}{ p}} - +Returns {\tt true} if the pointer is either {\tt NULL} or points to an empty +string, {\tt false} otherwise. -\membersection{::wxGetResource}\label{wxgetresource} -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}} +\membersection{::wxStrcmp}\label{wxstrcmp} -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{float *}{value}, \param{const wxString\& }{file = NULL}} +\func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}} -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{long *}{value}, \param{const wxString\& }{file = NULL}} +Returns a negative value, 0, or positive value if {\it p1} is less than, equal +to or greater than {\it p2}. The comparison is case-sensitive. -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{int *}{value}, \param{const wxString\& }{file = NULL}} +This function complements the standard C function {\it stricmp()} which performs +case-insensitive comparison. -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{::wxStricmp}\label{wxstricmp} -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{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}} -See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}. +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. -\wxheading{Include files} +This function complements the standard C function {\it strcmp()} which performs +case-sensitive comparison. - -\membersection{::wxGetUserId} +\membersection{::wxStringMatch}\label{wxstringmatch} -\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} +\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\ + \param{bool}{ subString = true}, \param{bool}{ exact = false}} -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''. +{\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead. -\wxheading{Include files} +Returns {\tt true} if the substring {\it s1} is found within {\it s2}, +ignoring case if {\it exact} is false. If {\it subString} is {\tt false}, +no substring matching is done. - -\membersection{::wxGetUserName} +\membersection{::wxStringEq}\label{wxstringeq} -\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} +\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} -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''. +{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead. -\wxheading{Include files} +A macro defined as: - +\begin{verbatim} +#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) +\end{verbatim} -\membersection{::wxKill}\label{wxkill} -\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}} +\membersection{::wxStrlen}\label{wxstrlen} -Under Unix (the only supported platform), equivalent to the Unix kill function. -Returns 0 on success, -1 on failure. +\func{size\_t}{wxStrlen}{\param{const char *}{ p}} -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. +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. -\wxheading{Include files} - +\membersection{::wxSnprintf}\label{wxsnprintf} -\membersection{::wxIsBusy}\label{wxisbusy} +\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}} -\func{bool}{wxIsBusy}{\void} +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 TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp -\helpref{wxEndBusyCursor}{wxendbusycursor} calls. +Returns the number of characters copied to the buffer or -1 if there is not +enough space. -See also \helpref{wxBusyCursor}{wxbusycursor}. +\wxheading{See also} -\wxheading{Include files} +\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf} - -\membersection{::wxLoadUserResource}\label{wxloaduserresource} +\membersection{wxT}\label{wxt} -\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} +\func{wxChar}{wxT}{\param{char }{ch}} -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{const wxChar *}{wxT}{\param{const char *}{s}} -The resource must be defined in the {\tt .rc} file using the following syntax: +wxT() is a macro which can be used with character and string literals (in other +words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in +Unicode build configuration. Please see the +\helpref{Unicode overview}{unicode} for more information. +This macro is simply returns the value passed to it without changes in ASCII +build. In fact, its definition is: \begin{verbatim} -myResource TEXT file.ext +#ifdef UNICODE +#define wxT(x) L ## x +#else // !Unicode +#define wxT(x) x +#endif \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}. +\membersection{wxTRANSLATE}\label{wxtranslate} -This function is available under Windows only. +\func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}} -\wxheading{Include files} +This macro doesn't do anything in the program code -- it simply expands to the +value of its argument (expand in Unicode build where it is equivalent to +\helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT +with the same string which would be really unreadable). - +However it does have a purpose and it is to mark the literal strings for the +extraction into the message catalog created by {\tt xgettext} program. Usually +this is achieved using \helpref{\_()}{underscore} but that macro not only marks +the string for extraction but also expands into +\helpref{wxGetTranslation}{wxgettranslation} function call which means that it +cannot be used in some situations, notably for the static arrays +initialization. -\membersection{::wxNow}\label{wxnow} +Here is an example which should make it more clear: suppose that you have a +static array of strings containing the weekday names and which have to be +translated (note that it is a bad example, really, as +\helpref{wxDateTime}{wxdatetime} already can be used to get the localized week +day names already). If you write +\begin{verbatim} +static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") }; +... +// use weekdays[n] as usual +\end{verbatim} +the code wouldn't compile because the function calls are forbidden in the array +initializer. So instead you should do +\begin{verbatim} +static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") }; +... +// use wxGetTranslation(weekdays[n]) +\end{verbatim} +here. -\func{wxString}{wxNow}{\void} +Note that although the code {\bf would} compile if you simply omit +wxTRANSLATE() in the above, it wouldn't work as expected because there would be +no translations for the weekday names in the program message catalog and +wxGetTranslation wouldn't find them. -Returns a string representing the current date and time. + + +\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{::wxPostDelete}\label{wxpostdelete} -\func{void}{wxPostDelete}{\param{wxObject *}{object}} +\membersection{::wxToUpper}\label{wxtoupper} -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. +\func{char}{wxToUpper}{\param{char }{ch}} -Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead. +Converts the character to upper case. This is implemented as a macro for efficiency. \wxheading{Include files} -\membersection{::wxSafeYield}{wxsafeyield} -\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}} +\membersection{::wxVsnprintf}\label{wxvsnprintf} -This function is similar to wxYield, except that it disables the user input to -the given window {\it win} or to all program windows if {\it win} is NULL. +\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}} -Returns the result of the call to \helpref{::wxYield}{wxyield}. +The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list } +argument instead of arbitrary number of parameters. -\wxheading{Include files} +\wxheading{See also} - +\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv} -\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. +\membersection{\_}\label{underscore} -See also \helpref{wxGetDisplayName}{wxgetdisplayname}. +\func{const wxChar *}{\_}{\param{const char *}{s}} -\wxheading{Include files} +This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation} +function, so it marks the message for the extraction by {\tt xgettext} just as +\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of +the string for the current locale during execution. - +Don't confuse this macro with \helpref{\_T()}{underscoret}! -\membersection{::wxShell}\label{wxshell} +\wxheading{See also} -\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} +\helpref{ngettext}{ngettext} -Executes a command in an interactive shell window. If no command is -specified, then just the shell is spawned. -See also \helpref{wxExecute}{wxexecute}. + +\membersection{\_T}\label{underscoret} + +\func{wxChar}{\_T}{\param{char }{ch}} + +\func{const wxChar *}{\_T}{\param{const wxChar }{ch}} + +This macro is exactly the same as \helpref{wxT}{wxt} and is defined in +wxWindows simply because it may be more intuitive for Windows programmers as +the standard Win32 headers also define it (as well as yet another name for the +same macro which is {\tt \_TEXT()}). + +Don't confuse this macro with \helpref{\_()}{underscore}! + + + +\section{Dialog functions}\label{dialogfunctions} + +Below are a number of convenience functions for getting input from the +user or displaying messages. Note that in these functions the last three +parameters are optional. However, it is recommended to pass a parent frame +parameter, or (in MS Windows or Motif) the wrong window frame may be brought to +the front when the dialog box is popped up. + + +\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} + +\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}} + +Changes the cursor to the given cursor for all windows in the application. +Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back +to its previous state. These two calls can be nested, and a counter +ensures that only the outer calls take effect. + +See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. \wxheading{Include files} -\membersection{::wxSleep}\label{wxsleep} -\func{void}{wxSleep}{\param{int}{ secs}} +\membersection{::wxBell}\label{wxbell} -Sleeps for the specified number of seconds. +\func{void}{wxBell}{\void} + +Ring the system bell. \wxheading{Include files} -\membersection{::wxStripMenuCodes} -\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}} +\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider} -\func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}} +\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename}, + \param{size\_t }{currentTip}} -Strips any menu codes from {\it in} and places the result -in {\it out} (or returns the new string, in the first form). +This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be +used with \helpref{wxShowTip}{wxshowtip}. -Menu codes include \& (mark the next character with an underline -as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows). +\docparam{filename}{The name of the file containing the tips, one per line} +\docparam{currentTip}{The index of the first tip to show - normally this index +is remembered between the 2 program runs.} + +\wxheading{See also} + +\helpref{Tips overview}{tipsoverview} \wxheading{Include files} - + -\membersection{::wxStartTimer}\label{wxstarttimer} -\func{void}{wxStartTimer}{\void} +\membersection{::wxDirSelector}\label{wxdirselector} -Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time. +\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}} -See also \helpref{wxTimer}{wxtimer}. +Pops up a directory selector dialog. The arguments have the same meaning as +those of wxDirDialog::wxDirDialog(). The message is displayed at the top, +and the default\_path, if specified, is set as the initial selection. + +The application must check for an empty return value (if the user pressed +Cancel). For example: + +\begin{verbatim} +const wxString& dir = wxDirSelector("Choose a folder"); +if ( !dir.empty() ) +{ + ... +} +\end{verbatim} \wxheading{Include files} - + -\membersection{::wxToLower}\label{wxtolower} -\func{char}{wxToLower}{\param{char }{ch}} +\membersection{::wxFileSelector}\label{wxfileselector} -Converts the character to lower case. This is implemented as a macro for efficiency. +\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\ + \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\ + \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = ""},\\ + \param{int}{ x = -1}, \param{int}{ y = -1}} + +Pops up a file selector box. In Windows, this is the common file selector +dialog. In X, this is a file selector box with the same functionality. +The path and filename are distinct elements of a full file pathname. +If path is empty, the current directory will be used. If filename is empty, +no default filename will be supplied. The wildcard determines what files +are displayed in the file selector, and file extension supplies a type +extension for the required filename. Flags may be a combination of wxOPEN, +wxSAVE, wxOVERWRITE\_PROMPT, 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} +wxString filename = wxFileSelector("Choose a file to open"); +if ( !filename.empty() ) +{ + // work with the file + ... +} +//else: cancelled by user +\end{verbatim} \wxheading{Include files} - + -\membersection{::wxToUpper}\label{wxtoupper} -\func{char}{wxToUpper}{\param{char }{ch}} +\membersection{::wxEndBusyCursor}\label{wxendbusycursor} -Converts the character to upper case. This is implemented as a macro for efficiency. +\func{void}{wxEndBusyCursor}{\void} + +Changes the cursor back to the original cursor, for all windows in the application. +Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}. + +See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. \wxheading{Include files} -\membersection{::wxTrace}\label{wxtrace} -\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} +\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser} -Takes printf-style variable argument syntax. Output -is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}} + +Shows the colour selection dialog and returns the colour selected by user or +invalid colour (use \helpref{wxColour::Ok}{wxcolourok} to test whether a colour +is valid) if the dialog was cancelled. + +\wxheading{Parameters} + +\docparam{parent}{The parent window for the colour selection dialog} -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +\docparam{colInit}{If given, this will be the colour initially selected in the dialog.} \wxheading{Include files} - + -\membersection{::wxTraceLevel}\label{wxtracelevel} -\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} +\membersection{::wxGetFontFromUser}\label{wxgetfontfromuser} -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. +\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}} -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +Shows the font selection dialog and returns the font selected by user or +invalid font (use \helpref{wxFont::Ok}{wxfontok} to test whether a font +is valid) if the dialog was cancelled. + +\wxheading{Parameters} + +\docparam{parent}{The parent window for the font selection dialog} + +\docparam{fontInit}{If given, this will be the font initially selected in the dialog.} \wxheading{Include files} - + -\membersection{::wxUsleep}\label{wxusleep} -\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}} -Sleeps for the specified number of milliseconds. Notice that usage of this -function is encouraged instead of calling usleep(3) directly because the -standard usleep() function is not MT safe. +\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices} -\wxheading{Include files} +\func{size\_t}{wxGetMultipleChoices}{\\ + \param{wxArrayInt\& }{selections},\\ + \param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{const wxArrayString\& }{aChoices},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} - +\func{size\_t}{wxGetMultipleChoices}{\\ + \param{wxArrayInt\& }{selections},\\ + \param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{int}{ n}, \param{const wxString\& }{choices[]},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} -\membersection{::wxWriteResource}\label{wxwriteresource} +Pops up a dialog box containing a message, OK/Cancel buttons and a +multiple-selection listbox. The user may choose an arbitrary (including 0) +number of items in the listbox whose indices will be returned in +{\it selection} array. The initial contents of this array will be used to +select the items when the dialog is shown. -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}} +You may pass the list of strings to choose from either using {\it choices} +which is an array of {\it n} strings for the listbox or by using a single +{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}. -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{float }{value}, \param{const wxString\& }{file = NULL}} +If {\it centre} is true, the message text (which may include new line +characters) is centred; if false, the message is left-justified. -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{long }{value}, \param{const wxString\& }{file = NULL}} +\wxheading{Include files} -\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. +\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.} -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. +\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser} -See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}. +\func{long}{wxGetNumberFromUser}{ + \param{const wxString\& }{message}, + \param{const wxString\& }{prompt}, + \param{const wxString\& }{caption}, + \param{long }{value}, + \param{long }{min = 0}, + \param{long }{max = 100}, + \param{wxWindow *}{parent = NULL}, + \param{const wxPoint\& }{pos = wxDefaultPosition}} + +Shows a dialog asking the user for numeric input. The dialogs title is set to +{\it caption}, it contains a (possibly) multiline {\it message} above the +single line {\it prompt} and the zone for entering the number. + +The number entered must be in the range {\it min}..{\it max} (both of which +should be positive) and {\it value} is the initial value of it. If the user +enters an invalid value or cancels the dialog, the function will return -1. + +Dialog is centered on its {\it parent} unless an explicit position is given in +{\it pos}. \wxheading{Include files} - + -\membersection{::wxYield}\label{wxyield} -\func{bool}{wxYield}{\void} +\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser} -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. +\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ + \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}} -Caution should be exercised, however, since yielding may allow the -user to perform actions which are not compatible with the current task. -Disabling menu items or whole menus during processing can avoid unwanted -reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better -function. +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} - + -\section{Macros}\label{macros} -These macros are defined in wxWindows. +\membersection{::wxGetTextFromUser}\label{wxgettextfromuser} -\membersection{CLASSINFO}\label{classinfo} +\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ + \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = true}} -\func{wxClassInfo *}{CLASSINFO}{className} +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. -Returns a pointer to the wxClassInfo object associated with this class. +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{WXDEBUG\_NEW}\label{debugnew} -\func{}{WXDEBUG\_NEW}{arg} +\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice} -This is defined in debug mode to be call the redefined new operator -with filename and line number arguments. The definition is: +\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}} -\begin{verbatim} -#define WXDEBUG_NEW new(__FILE__,__LINE__) -\end{verbatim} +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. -In non-debug mode, this is defined as the normal new operator. +The number of initially selected choices, and array of the selected indices, +are passed in; this array will contain the user selections on exit, with +the function returning the number of selections. {\it selection} must be +as big as the number of choices, in case all are selected. + +If Cancel is pressed, -1 is returned. + +{\it choices} is an array of {\it n} strings for the listbox. + +If {\it centre} is true, the message text (which may include new line characters) +is centred; if false, the message is left-justified. \wxheading{Include files} - + -\membersection{DECLARE\_ABSTRACT\_CLASS} -\func{}{DECLARE\_ABSTRACT\_CLASS}{className} +\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice} -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{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{const wxArrayString\& }{aChoices},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} + +\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{int}{ n}, \param{const wxString\& }{choices[]},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} + +Pops up a dialog box containing a message, OK/Cancel buttons and a +single-selection listbox. The user may choose an item and press OK to return a +string or Cancel to return the empty string. Use +\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex} if empty string is a +valid choice and if you want to be able to detect pressing Cancel reliably. + +You may pass the list of strings to choose from either using {\it choices} +which is an array of {\it n} strings for the listbox or by using a single +{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}. + +If {\it centre} is true, the message text (which may include new line +characters) is centred; if false, the message is left-justified. -Example: +\wxheading{Include files} -\begin{verbatim} -class wxCommand: public wxObject -{ - DECLARE_ABSTRACT_CLASS(wxCommand) + - private: - ... - public: - ... -}; -\end{verbatim} +\perlnote{In wxPerl there is just an array reference in place of {\tt n} +and {\tt choices}.} + + +\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex} + +\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{const wxArrayString\& }{aChoices},\\ + \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} + +\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{int}{ n}, \param{const wxString\& }{choices[]},\\ + \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} + +As {\bf wxGetSingleChoice} but returns the index representing the selected +string. If the user pressed cancel, -1 is returned. + +\wxheading{Include files} + + + +\perlnote{In wxPerl there is just an array reference in place of {\tt n} +and {\tt choices}.} + + +\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata} + +\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{const wxArrayString\& }{aChoices},\\ + \param{const wxString\& }{client\_data[]},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} + +\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{int}{ n}, \param{const wxString\& }{choices[]},\\ + \param{const wxString\& }{client\_data[]},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} + +As {\bf wxGetSingleChoice} but takes an array of client data pointers +corresponding to the strings, and returns one of these pointers or NULL if +Cancel was pressed. The {\it client\_data} array must have the same number of +elements as {\it choices} or {\it aChoices}! + +\wxheading{Include files} + + + +\perlnote{In wxPerl there is just an array reference in place of {\tt n} +and {\tt choices}, and the client data array must have the +same length as the choices array.} + + +\membersection{::wxIsBusy}\label{wxisbusy} + +\func{bool}{wxIsBusy}{\void} + +Returns true if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp +\helpref{wxEndBusyCursor}{wxendbusycursor} calls. + +See also \helpref{wxBusyCursor}{wxbusycursor}. + +\wxheading{Include files} + + + + +\membersection{::wxMessageBox}\label{wxmessagebox} + +\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK},\\ + \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}} + +General purpose message dialog. {\it style} may be a bit list of the +following identifiers: + +\begin{twocollist}\itemsep=0pt +\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with +wxCANCEL.} +\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with +wxYES\_NO or wxOK.} +\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.} +\twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.} +\twocolitem{wxICON\_HAND}{Displays an error symbol.} +\twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.} +\twocolitem{wxICON\_QUESTION}{Displays a question mark symbol.} +\twocolitem{wxICON\_INFORMATION}{Displays an information symbol.} +\end{twocollist} + +The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. + +For example: + +\begin{verbatim} + ... + int answer = wxMessageBox("Quit program?", "Confirm", + wxYES_NO | wxCANCEL, main_frame); + if (answer == wxYES) + main_frame->Close(); + ... +\end{verbatim} + +{\it message} may contain newline characters, in which case the +message will be split into separate lines, to cater for large messages. + +\wxheading{Include files} + + + + +\membersection{::wxShowTip}\label{wxshowtip} + +\func{bool}{wxShowTip}{\param{wxWindow *}{parent}, + \param{wxTipProvider *}{tipProvider}, + \param{bool }{showAtStartup = true}} + +This function shows a "startup tip" to the user. The return value is the +state of the ``Show tips at startup'' checkbox. + +\docparam{parent}{The parent window for the modal dialog} + +\docparam{tipProvider}{An object which is used to get the text of the tips. +It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.} + +\docparam{showAtStartup}{Should be true if startup tips are shown, false +otherwise. This is used as the initial value for "Show tips at startup" +checkbox which is shown in the tips dialog.} + +\wxheading{See also} + +\helpref{Tips overview}{tipsoverview} + +\wxheading{Include files} + + + + + + +\section{Math functions} + +\wxheading{Include files} + + + + +\membersection{wxFinite}\label{wxfinite} + +\func{int}{wxFinite}{\param{double }{x}} + +Returns a non-zero value if {\it x} is neither infinite or NaN (not a number), +returns 0 otherwise. + + +\membersection{wxIsNaN}\label{wxisnan} + +\func{bool}{wxIsNaN}{\param{double }{x}} + +Returns a non-zero value if {\it x} is NaN (not a number), returns 0 +otherwise. + + + + +\section{GDI functions}\label{gdifunctions} + +The following are relevant to the GDI (Graphics Device Interface). + +\wxheading{Include files} + + + + +\membersection{wxBITMAP}\label{wxbitmapmacro} + +\func{}{wxBITMAP}{bitmapName} + +This macro loads a bitmap from either application resources (on the platforms +for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to +avoid using {\tt \#ifdef}s when creating bitmaps. + +\wxheading{See also} + +\helpref{Bitmaps and icons overview}{wxbitmapoverview}, +\helpref{wxICON}{wxiconmacro} + +\wxheading{Include files} + + + + +\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect} + +\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y}, +\param{int *}{width}, \param{int *}{height}} + +\func{wxRect}{wxGetClientDisplayRect}{\void} + +Returns the dimensions of the work area on the display. On Windows +this means the area not covered by the taskbar, etc. Other platforms +are currently defaulting to the whole display until a way is found to +provide this info for all window managers, etc. + + +\membersection{::wxColourDisplay}\label{wxcolourdisplay} + +\func{bool}{wxColourDisplay}{\void} + +Returns true if the display is colour, false otherwise. + + +\membersection{::wxDisplayDepth}\label{wxdisplaydepth} + +\func{int}{wxDisplayDepth}{\void} + +Returns the depth of the display (a value of 1 denotes a monochrome display). + + +\membersection{::wxDisplaySize}\label{wxdisplaysize} + +\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} + +\func{wxSize}{wxGetDisplaySize}{\void} + +Returns the display size in pixels. + + +\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm} + +\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}} + +\func{wxSize}{wxGetDisplaySizeMM}{\void} + +Returns the display size in millimeters. + + +\membersection{::wxDROP\_ICON}\label{wxdropicon} + +\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}} + +This macro creates either a cursor (MSW) or an icon (elsewhere) with the given +name. Under MSW, the cursor is loaded from the resource file and the icon is +loaded from XPM file under other platforms. + +This macro should be used with +\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}. + +\wxheading{Include files} + + + + +\membersection{wxICON}\label{wxiconmacro} + +\func{}{wxICON}{iconName} + +This macro loads an icon from either application resources (on the platforms +for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to +avoid using {\tt \#ifdef}s when creating icons. + +\wxheading{See also} + +\helpref{Bitmaps and icons overview}{wxbitmapoverview}, +\helpref{wxBITMAP}{wxbitmapmacro} + +\wxheading{Include files} + + + + +\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable} + +\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY}, + \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}} + +Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc}) +makes it into a placeable metafile by prepending a header containing the given +bounding box. The bounding box may be obtained from a device context after drawing +into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. + +In addition to adding the placeable metafile header, this function adds +the equivalent of the following code to the start of the metafile data: + +\begin{verbatim} + SetMapMode(dc, MM_ANISOTROPIC); + SetWindowOrg(dc, minX, minY); + SetWindowExt(dc, maxX - minX, maxY - minY); +\end{verbatim} + +This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes. + +Placeable metafiles may be imported by many Windows applications, and can be +used in RTF (Rich Text Format) files. + +{\it scale} allows the specification of scale for the metafile. + +This function is only available under Windows. + + +\membersection{::wxSetCursor}\label{wxsetcursor} + +\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}} + +Globally sets the cursor; only has an effect in Windows and GTK. +See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. + + + +\section{Printer settings}\label{printersettings} + +{\bf NB:} These routines are obsolete and should no longer be used! + +The following functions are used to control PostScript printing. Under +Windows, PostScript output can only be sent to a file. + +\wxheading{Include files} + + + + +\membersection{::wxGetPrinterCommand}\label{wxgetprintercommand} + +\func{wxString}{wxGetPrinterCommand}{\void} + +Gets the printer command used to print a file. The default is {\tt lpr}. + + +\membersection{::wxGetPrinterFile}\label{wxgetprinterfile} + +\func{wxString}{wxGetPrinterFile}{\void} + +Gets the PostScript output filename. + + +\membersection{::wxGetPrinterMode}\label{wxgetprintermode} + +\func{int}{wxGetPrinterMode}{\void} + +Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). +The default is PS\_PREVIEW. + + +\membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions} + +\func{wxString}{wxGetPrinterOptions}{\void} + +Gets the additional options for the print command (e.g. specific printer). The default is nothing. + + +\membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation} + +\func{int}{wxGetPrinterOrientation}{\void} + +Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. + + +\membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand} + +\func{wxString}{wxGetPrinterPreviewCommand}{\void} + +Gets the command used to view a PostScript file. The default depends on the platform. + + +\membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling} + +\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}} + +Gets the scaling factor for PostScript output. The default is 1.0, 1.0. + + +\membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation} + +\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}} + +Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. + + +\membersection{::wxSetPrinterCommand}\label{wxsetprintercommand} + +\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}} + +Sets the printer command used to print a file. The default is {\tt lpr}. + + +\membersection{::wxSetPrinterFile}\label{wxsetprinterfile} + +\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}} + +Sets the PostScript output filename. + + +\membersection{::wxSetPrinterMode}\label{wxsetprintermode} + +\func{void}{wxSetPrinterMode}{\param{int }{mode}} + +Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). +The default is PS\_PREVIEW. + + +\membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions} + +\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}} + +Sets the additional options for the print command (e.g. specific printer). The default is nothing. + + +\membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation} + +\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}} + +Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. + + +\membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand} + +\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}} + +Sets the command used to view a PostScript file. The default depends on the platform. + + +\membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling} + +\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}} + +Sets the scaling factor for PostScript output. The default is 1.0, 1.0. + + +\membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation} + +\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}} + +Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. + + + +\section{Clipboard functions}\label{clipsboard} + +These clipboard functions are implemented for Windows only. The use of these functions +is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard} +class instead. + +\wxheading{Include files} + + + + +\membersection{::wxClipboardOpen}\label{functionwxclipboardopen} + +\func{bool}{wxClipboardOpen}{\void} + +Returns true if this application has already opened the clipboard. + + +\membersection{::wxCloseClipboard}\label{wxcloseclipboard} + +\func{bool}{wxCloseClipboard}{\void} + +Closes the clipboard to allow other applications to use it. + + +\membersection{::wxEmptyClipboard}\label{wxemptyclipboard} + +\func{bool}{wxEmptyClipboard}{\void} + +Empties the clipboard. + + +\membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats} + +\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}} + +Enumerates the formats found in a list of available formats that belong +to the clipboard. Each call to this function specifies a known +available format; the function returns the format that appears next in +the list. + +{\it dataFormat} specifies a known format. If this parameter is zero, +the function returns the first format in the list. + +The return value specifies the next known clipboard data format if the +function is successful. It is zero if the {\it dataFormat} parameter specifies +the last format in the list of available formats, or if the clipboard +is not open. + +Before it enumerates the formats function, an application must open the clipboard by using the +wxOpenClipboard function. + + +\membersection{::wxGetClipboardData}\label{wxgetclipboarddata} + +\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}} + +Gets data from the clipboard. + +{\it dataFormat} may be one of: + +\begin{itemize}\itemsep=0pt +\item wxCF\_TEXT or wxCF\_OEMTEXT: returns a pointer to new memory containing a null-terminated text string. +\item wxCF\_BITMAP: returns a new wxBitmap. +\end{itemize} + +The clipboard must have previously been opened for this call to succeed. + + +\membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname} + +\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}} + +Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum +length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format. + + +\membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable} + +\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}} + +Returns true if the given data format is available on the clipboard. + + +\membersection{::wxOpenClipboard}\label{wxopenclipboard} + +\func{bool}{wxOpenClipboard}{\void} + +Opens the clipboard for passing data to it or getting data from it. + + +\membersection{::wxRegisterClipboardFormat}\label{wxregisterclipboardformat} + +\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}} + +Registers the clipboard data format name and returns an identifier. + + +\membersection{::wxSetClipboardData}\label{wxsetclipboarddata} + +\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}} + +Passes data to the clipboard. + +{\it dataFormat} may be one of: + +\begin{itemize}\itemsep=0pt +\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string. +\item wxCF\_BITMAP: {\it data} is a wxBitmap. +\item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap). +\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions. +\end{itemize} + +The clipboard must have previously been opened for this call to succeed. + + + + +\section{Miscellaneous functions}\label{miscellany} + + +\membersection{wxCONCAT}\label{wxconcat} + +\func{}{wxCONCAT}{\param{}{x}, \param{}{y}} + +This macro returns the concatenation of two tokens \arg{x} and \arg{y}. + + +\membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction} + +\func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}} + +When loading a function from a DLL you always have to cast the returned +\tt{void *} pointer to the correct type and, even more annoyingly, you have to +repeat this type twice if you want to declare and define a function pointer all +in one line + +This macro makes this slightly less painful by allowing you to specify the +type only once, as the first parameter, and creating a variable of this type +named after the function but with {\tt pfn} prefix and initialized with the +function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary} +\arg{dynlib}. + +\wxheading{Parameters} + +\docparam{type}{the type of the function} + +\docparam{name}{the name of the function to load, not a string (without quotes, +it is quoted automatically by the macro)} + +\docparam{dynlib}{the library to load the function from} + + + +\membersection{wxEXPLICIT}\label{wxexplicit} + +{\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if +the compiler supports it or nothing otherwise. Thus, it can be used even in the +code which might have to be compiled with an old compiler without support for +this language feature but still take advantage of it when it is available. + + +\membersection{wxLL}\label{wxll} + +\func{wxLongLong\_t}{wxLL}{\param{}{number}} + +This macro is defined for the platforms with a native 64 bit integer type and +allows to define 64 bit compile time constants: + +\begin{verbatim} + #ifdef wxLongLong_t + wxLongLong_t ll = wxLL(0x1234567890abcdef); + #endif +\end{verbatim} + +\wxheading{Include files} + + + +\wxheading{See also} + +\helpref{wxULL}{wxull}, \helpref{wxLongLong}{wxlonglong} + + +\membersection{wxLongLongFmtSpec}\label{wxlonglongfmtspec} + +This macro is defined to contain the {\tt printf()} format specifier using +which 64 bit integer numbers (i.e. those of type {\tt wxLongLong\_t}) can be +printed. Example of using it: + +\begin{verbatim} + #ifdef wxLongLong_t + wxLongLong_t ll = wxLL(0x1234567890abcdef); + printf("Long long = %" wxLongLongFmtSpec "x\n", ll); + #endif +\end{verbatim} + +\wxheading{See also} + +\helpref{wxLL}{wxll} + +\wxheading{Include files} + + + + +\membersection{::wxNewId}\label{wxnewid} + +\func{long}{wxNewId}{\void} + +Generates an integer identifier unique to this run of the program. + +\wxheading{Include files} + + + + +\membersection{::wxRegisterId}\label{wxregisterid} + +\func{void}{wxRegisterId}{\param{long}{ id}} + +Ensures that ids subsequently generated by {\bf NewId} do not clash with +the given {\bf id}. + +\wxheading{Include files} + + + + +\membersection{::wxDDECleanUp}\label{wxddecleanup} + +\func{void}{wxDDECleanUp}{\void} + +Called when wxWindows exits, to clean up the DDE system. This no longer needs to be +called by the application. + +See also \helpref{wxDDEInitialize}{wxddeinitialize}. + +\wxheading{Include files} + + + + +\membersection{::wxDDEInitialize}\label{wxddeinitialize} + +\func{void}{wxDDEInitialize}{\void} + +Initializes the DDE system. May be called multiple times without harm. + +This no longer needs to be called by the application: it will be called +by wxWindows if necessary. + +See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection}, +\helpref{wxDDECleanUp}{wxddecleanup}. + +\wxheading{Include files} + + + + +\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}} + +{\bf NB:} This function is obsolete, please use +\helpref{wxWindow::FindWindowByLabel}{wxwindowfindwindowbylabel} instead. + +Find a window by its label. Depending on the type of window, the label may be a window title +or panel item label. If {\it parent} is NULL, the search will start from all top-level +frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. +The search is recursive in both cases. + +\wxheading{Include files} + + + + +\membersection{::wxFindWindowByName}\label{wxfindwindowbyname} + +\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}} + +{\bf NB:} This function is obsolete, please use +\helpref{wxWindow::FindWindowByName}{wxwindowfindwindowbyname} instead. + +Find a window by its name (as given in a window constructor or {\bf Create} function call). +If {\it parent} is NULL, the search will start from all top-level +frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. +The search is recursive in both cases. + +If no such named window is found, {\bf wxFindWindowByLabel} is called. + +\wxheading{Include files} + + + + +\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{::wxGetTopLevelParent}\label{wxgettoplevelparent} + +\func{wxWindow *}{wxGetTopLevelParent}{\param{wxWindow }{*win}} + +Returns the first top level parent of the given window, or in other words, the +frame or dialog containing it, or {\tt NULL}. + +\wxheading{Include files} + + + + +\membersection{::wxLoadUserResource}\label{wxloaduserresource} + +\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} + +Loads a user-defined Windows resource as a string. If the resource is found, the function creates +a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned. + +The resource must be defined in the {\tt .rc} file using the following syntax: + +\begin{verbatim} +myResource TEXT file.ext +\end{verbatim} + +where {\tt file.ext} is a file that the resource compiler can find. + +This function is available under Windows only. + +\wxheading{Include files} + + + + +\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}} + +{\bf NB:} This function is obsolete, please use +\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead. + +Strips any menu codes from {\it in} and places the result +in {\it out} (or returns the new string, in the first form). + +Menu codes include \& (mark the next character with an underline +as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows). + +\wxheading{Include files} + + + + +\membersection{wxULL}\label{wxull} + +\func{wxLongLong\_t}{wxULL}{\param{}{number}} + +This macro is defined for the platforms with a native 64 bit integer type and +allows to define unsigned 64 bit compile time constants: + +\begin{verbatim} + #ifdef wxLongLong_t + unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef); + #endif +\end{verbatim} + +\wxheading{Include files} + + + +\wxheading{See also} + +\helpref{wxLL}{wxll}, \helpref{wxLongLong}{wxlonglong} + + +\membersection{::wxWriteResource}\label{wxwriteresource} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{float }{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{long }{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{int }{value}, \param{const wxString\& }{file = NULL}} + +Writes a resource value into the resource database (for example, WIN.INI, or +.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used, +otherwise the specified file is used. + +Under X, the resource databases are cached until the internal function +\rtfsp{\bf wxFlushResources} is called automatically on exit, when +all updated resource databases are written to their files. + +Note that it is considered bad manners to write to the .Xdefaults +file under Unix, although the WIN.INI file is fair game under Windows. + +See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}. + +\wxheading{Include files} + + + + + +\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 +compatibility reasons but also because it allows some things which the +standard RTTI doesn't directly support (such as creating a class from its +name). + +The standard C++ RTTI can be used in the user code without any problems and in +general you shouldn't need to use the functions and the macros in this section +unless you are thinking of modifying or adding any 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 +\helpref{wxGetApp}{wxgetapp} function implemented by +\helpref{IMPLEMENT\_APP}{implementapp}. It creates the declaration +{\tt className\& wxGetApp(void)}. + +Example: + +\begin{verbatim} + DECLARE_APP(MyApp) +\end{verbatim} + +\wxheading{Include files} + + + + +\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: + +\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{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} + +\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}} + +{\bf NB:} This function is now obsolete, replaced by \helpref{Log +functions}{logfunctions} and \helpref{wxLogDebug}{wxlogdebug} in particular. + +Display a debugging message; under Windows, this will appear on the +debugger command window, and under Unix, it will be written to standard +error. + +The syntax is identical to {\bf printf}: pass a format string and a +variable list of arguments. + +{\bf Tip:} under Windows, if your application crashes before the +message appears in the debugging window, put a wxYield call after +each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s +(at least for Watcom C++): preformat your messages and use OutputDebugString +instead. + +\wxheading{Include files} + + + + +\membersection{::wxError}\label{wxerror} + +\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}} + +{\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror} +instead. + +Displays {\it msg} and continues. This writes to standard error under +Unix, and pops up a message box under Windows. Used for internal +wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}. + +\wxheading{Include files} + + + + +\membersection{::wxFatalError}\label{wxfatalerror} + +\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}} + +{\bf NB:} This function is now obsolete, please use +\helpref{wxLogFatalError}{wxlogfatalerror} instead. + +Displays {\it msg} and exits. This writes to standard error under Unix, +and pops up a message box under Windows. Used for fatal internal +wxWindows errors. See also \helpref{wxError}{wxerror}. + +\wxheading{Include files} + + + + +\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{::wxSafeShowMessage}\label{wxsafeshowmessage} + +\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}} + +This function shows a message to the user in a safe way and should be safe to +call even before the application has been initialized or if it is currently in +some other strange state (for example, about to crash). Under Windows this +function shows a message box using a native dialog instead of +\helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere +it simply prints the message to the standard output using the title as prefix. + +\wxheading{Parameters} + +\docparam{title}{The title of the message box shown to the user or the prefix +of the message string} + +\docparam{text}{The text to show to the user} + +\wxheading{See also} + +\helpref{wxLogFatalError}{wxlogfatalerror} + +\wxheading{Include files} + + + + +\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} + + + +\func{}{WXTRACE}{formatString, ...} + +{\bf NB:} This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. + +Calls wxTrace with printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). \wxheading{Include files} - + -\membersection{DECLARE\_APP}\label{declareapp} -\func{}{DECLARE\_APP}{className} +\membersection{WXTRACELEVEL}\label{tracelevel} -This is used in headers to create a forward declaration of the wxGetApp function implemented -by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}. +\func{}{WXTRACELEVEL}{level, formatString, ...} -Example: +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -\begin{verbatim} - DECLARE_APP(MyApp) -\end{verbatim} +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. \wxheading{Include files} - + -\membersection{DECLARE\_CLASS} -\func{}{DECLARE\_CLASS}{className} +\membersection{::wxTrace}\label{wxtrace} -Used inside a class declaration to declare that the class should be -made known to the class hierarchy, but objects of this class cannot be created -dynamically. The same as DECLARE\_ABSTRACT\_CLASS. +\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} -\wxheading{Include files} +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. - +Takes printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). -\membersection{DECLARE\_DYNAMIC\_CLASS} +\wxheading{Include files} -\func{}{DECLARE\_DYNAMIC\_CLASS}{className} + -Used inside a class declaration to declare that the objects of this class should be dynamically -createable from run-time type information. -Example: +\membersection{::wxTraceLevel}\label{wxtracelevel} -\begin{verbatim} -class wxFrame: public wxWindow -{ - DECLARE_DYNAMIC_CLASS(wxFrame) +\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} - private: - const wxString\& frameTitle; - public: - ... -}; -\end{verbatim} +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -\wxheading{Include files} +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. - +\wxheading{Include files} -\membersection{IMPLEMENT\_ABSTRACT\_CLASS} + -\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: +\section{Time functions}\label{timefunctions} -\begin{verbatim} -IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) +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. -wxCommand::wxCommand(void) -{ -... -} -\end{verbatim} -\wxheading{Include files} +\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime} - +\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = true}} -\membersection{IMPLEMENT\_ABSTRACT\_CLASS2} +Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}. -\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2} +If {\it resetTimer} is true (the default), the timer is reset to zero +by this call. -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. +See also \helpref{wxTimer}{wxtimer}. \wxheading{Include files} - + -\membersection{IMPLEMENT\_APP}\label{implementapp} -\func{}{IMPLEMENT\_APP}{className} +\membersection{::wxGetLocalTime}\label{wxgetlocaltime} -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 +\func{long}{wxGetLocalTime}{\void} -Old form: +Returns the number of seconds since local time 00:00:00 Jan 1st 1970. -\begin{verbatim} - MyApp myApp; -\end{verbatim} +\wxheading{See also} -New form: +\helpref{wxDateTime::Now}{wxdatetimenow} -\begin{verbatim} - IMPLEMENT_APP(MyApp) -\end{verbatim} +\wxheading{Include files} -See also \helpref{DECLARE\_APP}{declareapp}. + -\wxheading{Include files} - +\membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis} -\membersection{IMPLEMENT\_CLASS} +\func{wxLongLong}{wxGetLocalTimeMillis}{\void} -\func{}{IMPLEMENT\_CLASS}{className, baseClassName} +Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. -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{See also} + +\helpref{wxDateTime::Now}{wxdatetimenow},\\ +\helpref{wxLongLong}{wxlonglong} \wxheading{Include files} - + -\membersection{IMPLEMENT\_CLASS2} -\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2} +\membersection{::wxGetUTCTime}\label{wxgetutctime} -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. +\func{long}{wxGetUTCTime}{\void} -\wxheading{Include files} +Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. - +\wxheading{See also} -\membersection{IMPLEMENT\_DYNAMIC\_CLASS} +\helpref{wxDateTime::Now}{wxdatetimenow} -\func{}{IMPLEMENT\_DYNAMIC\_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, and whose instances -can be created dynamically. + -Example: -\begin{verbatim} -IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) +\membersection{::wxNow}\label{wxnow} -wxFrame::wxFrame(void) -{ -... -} -\end{verbatim} +\func{wxString}{wxNow}{\void} + +Returns a string representing the current date and time. \wxheading{Include files} - + -\membersection{IMPLEMENT\_DYNAMIC\_CLASS2} -\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2} +\membersection{::wxSleep}\label{wxsleep} -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. +\func{void}{wxSleep}{\param{int}{ secs}} + +Sleeps for the specified number of seconds. \wxheading{Include files} - + -\membersection{WXTRACE}\label{trace} -\func{}{WXTRACE}{formatString, ...} +\membersection{::wxStartTimer}\label{wxstarttimer} -Calls wxTrace with printf-style variable argument syntax. Output -is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +\func{void}{wxStartTimer}{\void} + +Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time. -This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +See also \helpref{wxTimer}{wxtimer}. \wxheading{Include files} - + -\membersection{WXTRACELEVEL}\label{tracelevel} -\func{}{WXTRACELEVEL}{level, formatString, ...} +\membersection{::wxUsleep}\label{wxusleep} -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. +\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}} -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +Sleeps for the specified number of milliseconds. Notice that usage of this +function is encouraged instead of calling usleep(3) directly because the +standard usleep() function is not MT safe. \wxheading{Include files} - + -\section{wxWindows resource functions}\label{resourcefuncs} -\overview{wxWindows resource system}{resourceformats} -This section details functions for manipulating wxWindows (.WXR) resource -files and loading user interface elements from resources. +\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. -\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.} +\wxheading{Include files} -\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. -{\bf Warning:} this needs updating for wxWindows 2. +\membersection{::wxOnAssert}\label{wxonassert} -\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier} +\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{cond}, \param{const char *}{msg = NULL}} -\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}} +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. -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. +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{::wxResourceClear} -\func{void}{wxResourceClear}{\void} +\membersection{wxASSERT}\label{wxassert} -Clears the wxWindows resource table. +\func{}{wxASSERT}{\param{}{condition}} -\membersection{::wxResourceCreateBitmap} +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. -\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}} +Please note that the condition in wxASSERT() should have no side effects +because it will not be executed in release mode at all. -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: +\wxheading{See also} -\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} +\helpref{wxASSERT\_MSG}{wxassertmsg},\\ +\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} -then this function can be called as follows: -\begin{verbatim} - wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource"); -\end{verbatim} +\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize} -\membersection{::wxResourceCreateIcon} +\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}} -\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}} +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. -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: +You may use it like this, for example: \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'])."; + // 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} -then this function can be called as follows: -\begin{verbatim} - wxIcon *icon = wxResourceCreateIcon("aiai_resource"); -\end{verbatim} +\membersection{wxASSERT\_MSG}\label{wxassertmsg} -\membersection{::wxResourceCreateMenuBar} +\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} -\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}} +Assert macro with message. An error message will be generated if the condition is false. -Creates a new menu bar given a valid wxWindows menubar resource -identifier. For example, if the .WXR file contains the following: +\wxheading{See also} -\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} +\helpref{wxASSERT}{wxassert},\\ +\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} -then this function can be called as follows: -\begin{verbatim} - wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11"); -\end{verbatim} +\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert} +\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}} -\membersection{::wxResourceGetIdentifier} +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. -\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}} +This macro is mostly useful for testing the expressions involving 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. -Used for retrieving the integer value associated with an identifier. -A zero value indicates that the identifier was not found. +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. -See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}. +Also note that Microsoft Visual C++ has a bug which results in compiler errors +if you use this macro with ``Program Database For Edit And Continue'' +(\texttt{/ZI}) option, so you shouldn't use it (``Program Database'' +(\texttt{/Zi}) is ok though) for the code making use of this macro. -\membersection{::wxResourceParseData}\label{wxresourcedata} +\wxheading{See also} -\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} +\helpref{wxASSERT\_MSG}{wxassertmsg},\\ +\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize} -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: +\membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2} -\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} +\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}} -This function will typically be used after including a {\tt .wxr} file into -a C++ program as follows: +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}. -\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{wxFAIL}\label{wxfail} + +\func{}{wxFAIL}{\void} + +Will always generate an assert error if this code is reached (in debug mode). -\membersection{::wxResourceParseFile} +See also: \helpref{wxFAIL\_MSG}{wxfailmsg} -\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{wxFAIL\_MSG}\label{wxfailmsg} -\membersection{::wxResourceParseString}\label{wxresourceparsestring} +\func{}{wxFAIL\_MSG}{\param{}{msg}} -\func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} +Will always generate an assert error with specified message if this code is reached (in debug mode). -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. +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. -{\it resource} should contain data with the following form: +\wxheading{See also} -\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]])."; -\end{verbatim} +\helpref{wxFAIL}{wxfail} -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} +\membersection{wxCHECK}\label{wxcheck} -\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width}, -\param{int }{height}, \param{wxResourceTable *}{table = NULL}} +\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} -\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}} +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. -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. -\membersection{::wxResourceRegisterIconData} +\membersection{wxCHECK\_MSG}\label{wxcheckmsg} -Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}. +\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}} -\section{Log functions}\label{logfunctions} +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. -These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for -further information. +This macro may be only used in non void functions, see also +\helpref{wxCHECK\_RET}{wxcheckret}. -\wxheading{Include files} - +\membersection{wxCHECK\_RET}\label{wxcheckret} -\membersection{::wxLogError}\label{wxlogerror} +\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}} -\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}} +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. -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. +This macro should be used in void functions instead of +\helpref{wxCHECK\_MSG}{wxcheckmsg}. -\membersection{::wxLogFatalError}\label{wxlogfatalerror} -\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}} +\membersection{wxCHECK2}\label{wxcheck2} -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{}{wxCHECK2}{\param{}{condition}, \param{}{operation}} -\membersection{::wxLogWarning}\label{wxlogwarning} +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. -\func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}} +This check is done even in release mode. -For warnings - they are also normally shown to the -user, but don't interrupt the program work. -\membersection{::wxLogMessage}\label{wxlogmessage} +\membersection{wxCHECK2\_MSG}\label{wxcheck2msg} -\func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}} +\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}} -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 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. -\membersection{::wxLogVerbose}\label{wxlogverbose} -\func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}} +\membersection{::wxTrap}\label{wxtrap} -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}). +\func{void}{wxTrap}{\void} -\membersection{::wxLogStatus}\label{wxlogstatus} +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. -\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}} +In release mode this function does nothing. -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. +\wxheading{Include files} -\membersection{::wxLogSysError}\label{wxlogsyserror} + -\func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}} -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. -\membersection{::wxLogDebug}\label{wxlogdebug} +\membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning} -\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}} +\func{bool}{wxIsDebuggerRunning}{\void} -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). +Returns {\tt true} if the program is running under debugger, {\tt false} +otherwise. -\membersection{::wxLogTrace}\label{wxlogtrace} +Please note that this function is currently only implemented for Mac builds +using CodeWarrior and always returns {\tt false} elsewhere. -\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}} -\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}} -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: -\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} +\section{Environment access functions}\label{environfunctions} -\section{Debugging macros and functions}\label{debugmacros} +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). -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. +% TODO add some stuff about env var inheriting but not propagating upwards (VZ) \wxheading{Include files} - - -\membersection{::wxOnAssert}\label{wxonassert} + -\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}} -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. +\membersection{wxGetenv}\label{wxgetenvmacro} -\membersection{wxASSERT}\label{wxassert} +\func{wxChar *}{wxGetEnv}{\param{const wxString\&}{ var}} -\func{}{wxASSERT}{\param{}{condition}} +This is a macro defined as {\tt getenv()} or its wide char version in Unicode +mode. -Assert macro. 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{wxASSERT\_MSG}\label{wxassertmsg} -\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} +\membersection{wxGetEnv}\label{wxgetenv} -Assert macro with message. An error message will be generated if the condition is FALSE. +\func{bool}{wxGetEnv}{\param{const wxString\&}{ var}, \param{wxString *}{value}} -\membersection{wxFAIL}\label{wxfail} +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. -\func{}{wxFAIL}{\param{}{condition}} +Returns {\tt true} if the variable exists, {\tt false} otherwise. -Will always generate an assert error if this code is reached (in debug mode). -\membersection{wxFAIL\_MSG}\label{wxfailmsg} +\membersection{wxSetEnv}\label{wxsetenv} -\func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}} +\func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxChar *}{value}} -Will always generate an assert error with specified message if this code is reached (in debug mode). +Sets the value of the environment variable {\it var} (adding it if necessary) +to {\it value}. -\membersection{wxCHECK}\label{wxcheck} +Returns {\tt true} on success. -\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} -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.