X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/585037876a5ae832c13d1dd5bad54e4000ec51b9..a75124d0da255513e83d2e62f963dd849829466b:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index 191f4c59f5..f8c78e68aa 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -1,2055 +1,5027 @@ -\chapter{Functions}\label{functions} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: function.tex +%% Purpose: Functions and macros +%% Author: wxWidgets Team +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) wxWidgets Team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\chapter{Functions and macros}\label{functions} \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% \setfooter{\thepage}{}{}{}{}{\thepage} -The functions defined in wxWindows are described here. +The functions and macros defined in wxWidgets 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}\label{functionsalphabetically} + +\helpref{CLASSINFO}{classinfo}\\ +\helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\ +\helpref{DECLARE\_APP}{declareapp}\\ +\helpref{DECLARE\_CLASS}{declareclass}\\ +\helpref{DECLARE\_DYNAMIC\_CLASS}{declaredynamicclass}\\ +\helpref{IMPLEMENT\_ABSTRACT\_CLASS2}{implementabstractclass2}\\ +\helpref{IMPLEMENT\_ABSTRACT\_CLASS}{implementabstractclass}\\ +\helpref{IMPLEMENT\_APP}{implementapp}\\ +\helpref{IMPLEMENT\_CLASS2}{implementclass2}\\ +\helpref{IMPLEMENT\_CLASS}{implementclass}\\ +\helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\ +\helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\ +\helpref{wxAboutBox}{wxaboutbox}\\ +\helpref{wxASSERT}{wxassert}\\ +\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\ +\helpref{wxASSERT\_MSG}{wxassertmsg}\\ +\helpref{wxAtomicDec}{wxatomicdec}\\ +\helpref{wxAtomicInc}{wxatomicinc}\\ +\helpref{wxBase64Decode}{wxbase64decode}\\ +\helpref{wxBase64Encode}{wxbase64encode}\\ +\helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\ +\helpref{wxBell}{wxbell}\\ +\helpref{wxBITMAP}{wxbitmapmacro}\\ +\helpref{wxCHANGE\_UMASK}{wxchangeumask}\\ +\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\_SUNCC\_VERSION}{wxchecksunccversion}\\ +\helpref{wxCHECK\_VERSION}{wxcheckversion}\\ +\helpref{wxCHECK\_VERSION\_FULL}{wxcheckversionfull}\\ +\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{wxCONCAT}{wxconcat}\\ +\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{WXDEBUG\_NEW}{debugnew}\\ +\helpref{wxDEPRECATED}{wxdeprecated}\\ +\helpref{wxDEPRECATED\_BUT\_USED\_INTERNALLY}{wxdeprecatedbutusedinternally}\\ +\helpref{wxDEPRECATED\_INLINE}{wxdeprecatedinline}\\ +\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{wxEntryStart}{wxentrystart}\\ +\helpref{wxEntryCleanup}{wxentrycleanup}\\ +\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{wxGenericAboutBox}{wxgenericaboutbox}\\ +\helpref{wxGetActiveWindow}{wxgetactivewindow}\\ +\helpref{wxGetApp}{wxgetapp}\\ +\helpref{wxGetBatteryState}{wxgetbatterystate}\\ +\helpref{wxGetClipboardData}{wxgetclipboarddata}\\ +\helpref{wxGetClipboardFormatName}{wxgetclipboardformatname}\\ +\helpref{wxGetColourFromUser}{wxgetcolourfromuser}\\ +\helpref{wxGetCwd}{wxgetcwd}\\ +\helpref{wxGetDiskSpace}{wxgetdiskspace}\\ +\helpref{wxGetDisplayName}{wxgetdisplayname}\\ +\helpref{wxGetDisplaySize}{wxdisplaysize}\\ +\helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\ +\helpref{wxGetEmailAddress}{wxgetemailaddress}\\ +\helpref{wxGetEnv}{wxgetenv}\\ +\helpref{wxGetFileKind}{wxgetfilekind}\\ +\helpref{wxGetFontFromUser}{wxgetfontfromuser}\\ +\helpref{wxGetFreeMemory}{wxgetfreememory}\\ +\helpref{wxGetFullHostName}{wxgetfullhostname}\\ +\helpref{wxGetHomeDir}{wxgethomedir}\\ +\helpref{wxGetHostName}{wxgethostname}\\ +\helpref{wxGetKeyState}{wxgetkeystate}\\ +\helpref{wxGetLocalTimeMillis}{wxgetlocaltimemillis}\\ +\helpref{wxGetLocalTime}{wxgetlocaltime}\\ +\helpref{wxGetMousePosition}{wxgetmouseposition}\\ +\helpref{wxGetMouseState}{wxgetmousestate}\\ +\helpref{wxGetMultipleChoices}{wxgetmultiplechoices}\\ +\helpref{wxGetNumberFromUser}{wxgetnumberfromuser}\\ +\helpref{wxGetOSDirectory}{wxgetosdirectory}\\ +\helpref{wxGetOsDescription}{wxgetosdescription}\\ +\helpref{wxGetOsVersion}{wxgetosversion}\\ +\helpref{wxGetPasswordFromUser}{wxgetpasswordfromuser}\\ +\helpref{wxGetPowerType}{wxgetpowertype}\\ +\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{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{wxInfoMessageBox}{wxinfomessagebox}\\ +\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{wxIsPlatformLittleEndian}{wxisplatformlittleendian}\\ +\helpref{wxIsPlatform64Bit}{wxisplatform64bit}\\ +\helpref{wxIsWild}{wxiswild}\\ +\helpref{wxJoin}{wxjoin}\\ +\helpref{wxKill}{wxkill}\\ +\helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser}\\ +\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{wxMilliSleep}{wxmillisleep}\\ +\helpref{wxMicroSleep}{wxmicrosleep}\\ +\helpref{wxMkdir}{wxmkdir}\\ +\helpref{wxMutexGuiEnter}{wxmutexguienter}\\ +\helpref{wxMutexGuiLeave}{wxmutexguileave}\\ +\helpref{wxNewId}{wxnewid}\\ +\helpref{wxNow}{wxnow}\\ +\helpref{wxOnAssert}{wxonassert}\\ +\helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}\\ +\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}\\ +\helpref{wxOpenClipboard}{wxopenclipboard}\\ +\helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\ +\helpref{wxPathOnly}{wxpathonly}\\ +\helpref{wxPLURAL}{wxplural}\\ +\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{wxSplit}{wxsplit}\\ +\helpref{wxSplitPath}{wxsplitfunction}\\ +\helpref{wxStaticCast}{wxstaticcast}\\ +\helpref{wxStrcmp}{wxstrcmp}\\ +\helpref{wxStricmp}{wxstricmp}\\ +\helpref{wxStringEq}{wxstringeq}\\ +\helpref{wxStringMatch}{wxstringmatch}\\ +\helpref{wxStringTokenize}{wxstringtokenize}\\ +\helpref{wxStripMenuCodes}{wxstripmenucodes}\\ +\helpref{wxStrlen}{wxstrlen}\\ +\helpref{wxSTRINGIZE}{wxstringize}\\ +\helpref{wxSTRINGIZE\_T}{wxstringizet}\\ +\helpref{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{wxsuppressgccprivatedtorwarning}\\ +\helpref{wxSysErrorCode}{wxsyserrorcode}\\ +\helpref{wxSysErrorMsg}{wxsyserrormsg}\\ +\helpref{wxT}{wxt}\\ +\helpref{wxTrace}{wxtrace}\\ +\helpref{WXTRACE}{trace}\\ +\helpref{wxTraceLevel}{wxtracelevel}\\ +\helpref{WXTRACELEVEL}{tracelevel}\\ +\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{wxVaCopy}{wxvacopy}\\ +\helpref{wxVsnprintf}{wxvsnprintf}\\ +\helpref{wxWakeUpIdle}{wxwakeupidle}\\ +\helpref{wxYield}{wxyield}\\ +\helpref{wx\_const\_cast}{wxconstcastraw}\\ +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\ +\helpref{wx\_static\_cast}{wxstaticcastraw}\\ +\helpref{wx\_truncate\_cast}{wxtruncatecast}\\ +\helpref{\_}{underscore}\\ +\helpref{\_T}{underscoret} +\helpref{\_\_WXFUNCTION\_\_}{wxfunction} + + + +\section{Version macros}\label{versionfunctions} + +The following constants are defined in wxWidgets: -\section{File functions}\label{filefunctions} - -\wxheading{Include files} - - - -\wxheading{See also} - -\helpref{wxPathList}{wxpathlist} - -\membersection{::wxDirExists} +\begin{itemize}\itemsep=0pt +\item {\tt wxMAJOR\_VERSION} is the major version of wxWidgets +\item {\tt wxMINOR\_VERSION} is the minor version of wxWidgets +\item {\tt wxRELEASE\_NUMBER} is the release number +\item {\tt wxSUBRELEASE\_NUMBER} is the subrelease number which is $0$ for all +official releases +\end{itemize} -\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} +For example, the values or these constants for wxWidgets 2.1.15 are 2, 1 and +15. -Returns TRUE if the directory exists. +Additionally, {\tt wxVERSION\_STRING} is a user-readable string containing +the full wxWidgets 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 +wxWidgets 2.2. -\membersection{::wxDos2UnixFilename} +The subrelease number is only used for the sources in between official releases +and so normally is not useful. -\func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}} +\wxheading{Include files} -Converts a DOS to a Unix filename by replacing backslashes with forward -slashes. + or -\membersection{::wxFileExists} -\func{bool}{wxFileExists}{\param{const wxString\& }{filename}} +\membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion} -Returns TRUE if the file exists. +\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor}} -\membersection{::wxFileNameFromPath} +Returns $1$ if the compiler being used to compile the code is GNU C++ +compiler (g++) version major.minor or greater. Otherwise, and also if +the compiler is not GNU C++ at all, returns $0$. -\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} -\func{char*}{wxFileNameFromPath}{\param{char* }{path}} +\membersection{wxCHECK\_SUNCC\_VERSION}\label{wxchecksunccversion} -Returns the filename for a full path. The second form returns a pointer to -temporary storage that should not be deallocated. +\func{bool}{wxCHECK\_SUNCC\_VERSION}{\param{}{major, minor}} -\membersection{::wxFindFirstFile}\label{wxfindfirstfile} +Returns $1$ if the compiler being used to compile the code is Sun CC Pro +compiler and its version is at least \texttt{major.minor}. Otherwise returns +$0$. -\func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}} -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. +\membersection{wxCHECK\_VERSION}\label{wxcheckversion} -{\it spec} may contain wildcards. +\func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}} -{\it flags} is reserved for future use. +This is a macro which evaluates to true if the current wxWidgets version is at +least major.minor.release. -For example: +For example, to test if the program is compiled with wxWidgets 2.2 or higher, +the following can be done: \begin{verbatim} - wxString f = wxFindFirstFile("/home/project/*.*"); - while ( !f.IsEmpty() ) - { - ... - f = wxFindNextFile(); - } + 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} -\membersection{::wxFindNextFile}\label{wxfindnextfile} -\func{wxString}{wxFindFirstFile}{\void} +\membersection{wxCHECK\_VERSION\_FULL}\label{wxcheckversionfull} -Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. +\func{bool}{wxCHECK\_VERSION\_FULL}{\param{}{major, minor, release, subrel}} -\membersection{::wxGetOSDirectory}\label{wxgetosdirectory} +Same as \helpref{wxCHECK\_VERSION}{wxcheckversion} but also checks that +\texttt{wxSUBRELEASE\_NUMBER} is at least \arg{subrel}. -\func{wxString}{wxGetOSDirectory}{\void} -Returns the Windows directory under Windows; on other platforms returns the empty string. +\membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion} -\membersection{::wxIsAbsolutePath} +\func{bool}{wxCHECK\_W32API\_VERSION}{\param{}{major, minor, release}} -\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} +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 TRUE if the argument is an absolute filename, i.e. with a slash -or drive name at the beginning. -\membersection{::wxPathOnly} -\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} +\section{Application initialization and termination}\label{appinifunctions} -Returns the directory part of the filename. +The functions in this section are used on application startup/shutdown and also +to control the behaviour of the main event loop of the GUI programs. -\membersection{::wxUnix2DosFilename} -\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}} +\membersection{::wxEntry}\label{wxentry} -Converts a Unix to a DOS filename by replacing forward -slashes with backslashes. +This initializes wxWidgets in a platform-dependent way. Use this if you are not +using the default wxWidgets entry code (e.g. main or WinMain). For example, you +can initialize wxWidgets from an Microsoft Foundation Classes application using +this function. -\membersection{::wxConcatFiles} +The following overload of wxEntry is available under all platforms: -\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, -\param{const wxString\& }{file3}} +\func{int}{wxEntry}{\param{int\&}{ argc}, \param{wxChar **}{argv}} -Concatenates {\it file1} and {\it file2} to {\it file3}, returning -TRUE if successful. +Under MS Windows, an additional overload suitable for calling from +\texttt{WinMain} is available: -\membersection{::wxCopyFile} +\func{int}{wxEntry}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}} -\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} +(notice that under Windows CE platform, and only there, the type of +\arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in +Unicode build). -Copies {\it file1} to {\it file2}, returning TRUE if successful. +\wxheading{See also} -\membersection{::wxGetCwd}\label{wxgetcwd} +\helpref{wxEntryStart}{wxentrystart} -\func{wxString}{wxGetCwd}{\void} +\wxheading{Remarks} -Returns a string containing the current (or working) directory. +To clean up wxWidgets, call wxApp::OnExit followed by the static function +wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWidgets: -\membersection{::wxGetHostName}\label{wxgethostname} +\begin{verbatim} +int CTheApp::ExitInstance() +{ + // OnExit isn't called by CleanUp so must be called explicitly. + wxTheApp->OnExit(); + wxApp::CleanUp(); -\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int }{sz}} + return CWinApp::ExitInstance(); +} +\end{verbatim} -Copies the current host machine's name into the supplied buffer. +\wxheading{Include files} -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. + -Returns TRUE if successful, FALSE otherwise. -\membersection{::wxGetEmailAddress}\label{wxgetemailaddress} -\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}} +\membersection{::wxEntryCleanup}\label{wxentrycleanup} -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{void}{wxEntryCleanup}{\void} -Returns TRUE if successful, FALSE otherwise. +Free resources allocated by a successful call to \helpref{wxEntryStart}{wxentrystart}. -\membersection{::wxGetUserId}\label{wxgetuserid} +\wxheading{Include files} -\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int }{sz}} + -Copies the current user id into the supplied buffer. -Under Windows or NT, this function first looks in the environment -variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp -in the {\bf wxWindows} section of the WIN.INI file is tried. +\membersection{::wxEntryStart}\label{wxentrystart} -Returns TRUE if successful, FALSE otherwise. +\func{bool}{wxEntryStart}{\param{int\&}{ argc}, \param{wxChar **}{argv}} -\membersection{::wxGetUserName}\label{wxgetusername} +This function can be used to perform the initialization of wxWidgets if you +can't use the default initialization code for any reason. -\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int }{sz}} +If the function returns \true, the initialization was successful and the global +\helpref{wxApp}{wxapp} object \texttt{wxTheApp} has been created. Moreover, +\helpref{wxEntryCleanup}{wxentrycleanup} must be called afterwards. If the +function returns \false, a catastrophic initialization error occured and (at +least the GUI part of) the library can't be used at all. -Copies the current user name into the supplied buffer. +Notice that parameters \arg{argc} and \arg{argv} may be modified by this +function. -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. +An additional overload of wxEntryStart() is provided under MSW only: it is +meant to be called with the parameters passed to \texttt{WinMain()}. -Returns TRUE if successful, FALSE otherwise. +\func{bool}{wxEntryStart}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}} -\membersection{::wxGetWorkingDirectory} +(notice that under Windows CE platform, and only there, the type of +\arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in +Unicode build). -\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}} +\wxheading{Include files} -This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead. + -Copies the current working directory into the buffer if supplied, or -copies the working directory into new storage (which you must delete yourself) -if the buffer is NULL. -{\it sz} is the size of the buffer if supplied. +\membersection{::wxGetApp}\label{wxgetapp} -\membersection{::wxGetTempFileName} +\func{wxAppDerivedClass\&}{wxGetApp}{\void} -\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}} +This function doesn't exist in wxWidgets 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}. -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}. +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. -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. +\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions} -\membersection{::wxIsWild}\label{wxiswild} +\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = true}} -\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} +If {\it doIt} is true, the fatal exceptions (also known as general protection +faults under Windows or segmentation violations in the Unix world) will be +caught and passed to \helpref{wxApp::OnFatalException}{wxapponfatalexception}. +By default, i.e. before this function is called, they will be handled in the +normal way which usually just means that the application will be terminated. +Calling wxHandleFatalExceptions() with {\it doIt} equal to false will restore +this default behaviour. -Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. +Notice that this function is only available if +\texttt{wxUSE\_ON\_FATAL\_EXCEPTION} is $1$ and under Windows platform this +requires a compiler with support for SEH (structured exception handling) which +currently means only Microsoft Visual C++ or a recent Borland C++ version. -\membersection{::wxMatchWild}\label{wxmatchwild} -\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} +\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers} -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}{wxInitAllImageHandlers}{\void} -\membersection{::wxMkdir} +Initializes all available image handlers. For a list of available handlers, +see \helpref{wxImage}{wximage}. -\func{bool}{wxMkdir}{\param{const wxString\& }{dir}} +\wxheading{See also} -Makes the directory {\it dir}, returning TRUE if successful. +\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler} -\membersection{::wxRemoveFile} +\wxheading{Include files} -\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} + -Removes {\it file}, returning TRUE if successful. -\membersection{::wxRenameFile} +\membersection{::wxInitialize}\label{wxinitialize} -\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} +\func{bool}{wxInitialize}{\void} -Renames {\it file1} to {\it file2}, returning TRUE if successful. +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 wxWidgets functions. -\membersection{::wxRmdir} +If the function returns \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}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}} +This function may be called several times but +\helpref{wxUninitialize}{wxuninitialize} must be called for each successful +call to this function. -Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS. +\wxheading{Include files} -The {\it flags} parameter is reserved for future use. + -\membersection{::wxSetWorkingDirectory} -\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}} +\membersection{::wxSafeYield}\label{wxsafeyield} -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. +\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}, \param{bool}{ + onlyIfNeeded = false}} -\membersection{::wxSplitPath}\label{wxsplitfunction} +This function is similar to wxYield, except that it disables the user input to +all program windows before calling wxYield and re-enables it again +afterwards. If {\it win} is not NULL, this window will remain enabled, +allowing the implementation of some limited user interaction. -\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{const wxString *}{ path}, \param{const wxString *}{ name}, \param{const wxString *}{ ext}} +Returns the result of the call to \helpref{::wxYield}{wxyield}. -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. +\wxheading{Include files} -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). + -On entry, {\it fullname} should be non NULL (it may be empty though). -On return, {\it path} contains the file path (without the trailing separator), {\it name} -contains the file name and {\it ext} contains the file extension without leading dot. All -three of them may be empty if the corresponding component is. The old contents of the -strings pointed to by these parameters will be overwritten in any case (if the pointers -are not NULL). +\membersection{::wxUninitialize}\label{wxuninitialize} -\section{String functions} +\func{void}{wxUninitialize}{\void} -\membersection{::copystring} +This function is for use in console (wxBase) programs only. It must be called +once for each previous successful call to \helpref{wxInitialize}{wxinitialize}. -\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{::wxYield}\label{wxyield} -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{bool}{wxYield}{\void} -\membersection{::wxStringEq}\label{wxstringeq} +Calls \helpref{wxApp::Yield}{wxappyield}. -\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} +This function is kept only for backwards compatibility. Please use +the \helpref{wxApp::Yield}{wxappyield} method instead in any new code. -A macro defined as: +\wxheading{Include files} -\begin{verbatim} -#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) -\end{verbatim} + or -\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream} -\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}} +\membersection{::wxWakeUpIdle}\label{wxwakeupidle} -Copies the given file to {\it stream}. Useful when converting an old application to -use streams (within the document/view framework, for example). +\func{void}{wxWakeUpIdle}{\void} -Use of this function requires the file wx\_doc.h to be included. +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}. -\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile} +\wxheading{Include files} -\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}} + -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). -Use of this function requires the file wx\_doc.h to be included. -\section{Dialog functions}\label{dialogfunctions} +\section{Process control functions}\label{processfunctions} -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. +The functions in this section are used to launch or terminate the other +processes. -\membersection{::wxFileSelector}\label{wxfileselector} -\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = NULL},\\ - \param{const wxString\& }{default\_filename = NULL}, \param{const wxString\& }{default\_extension = NULL},\\ - \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\ - \param{int}{ x = -1}, \param{int}{ y = -1}} +\membersection{::wxExecute}\label{wxexecute} -Pops up a file selector box. In Windows, this is the common file selector -dialog. In X, this is a file selector box with somewhat less functionality. -The path and filename are distinct elements of a full file pathname. -If path is NULL, the current directory will be used. If filename is NULL, -no default filename will be supplied. The wildcard determines what files -are displayed in the file selector, and file extension supplies a type -extension for the required filename. Flags may be a combination of wxOPEN, -wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, or 0. They are only significant -at present in Windows. +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} -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. +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteCommand}} -Under Windows (only), the wildcard may be a specification for multiple -types of file with a description for each, such as: +\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} -\begin{verbatim} - "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif" -\end{verbatim} +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteArgs}} -The application must check for a NULL return value (the user pressed -Cancel). For example: +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{int }{flags = 0}} -\begin{verbatim} -const wxString\& s = wxFileSelector("Choose a file to open"); -if (s) -{ - ... -} -\end{verbatim} +\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.} -\wxheading{Include files} +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}, \param{int }{flags = 0}} - +\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.} -\membersection{::wxGetTextFromUser}\label{wxgettextfromuser} +Executes another program in Unix or Windows. -\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}} +The first form takes a command string, such as {\tt "emacs file.txt"}. -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. +The second form takes an array of values: a command, any number of +arguments, terminated by NULL. -If {\it centre} is TRUE, the message text (which may include new line characters) -is centred; if FALSE, the message is left-justified. +The semantics of the third and fourth versions is different from the first two +and is described in more details below. -\wxheading{Include files} +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. - +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}. Because of this, by +default this function disables all application windows to avoid unexpected +reentrancies which could result from the users interaction with the program +while the child process is running. If you are sure that it is safe to not +disable the program windows, you may pass \texttt{wxEXEC\_NODISABLE} flag to +prevent this automatic disabling from happening. + +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} passing wxKILL\_CHILDREN will +kill this process as well as all of its children (except those which have +started their own session). + +The {\tt wxEXEC\_NOEVENTS} flag prevents processing of any events from taking +place while the child process is running. It should be only used for very +short-lived processes as otherwise the application windows risk becoming +unresponsive from the users point of view. As this flag only makes sense with +{\tt wxEXEC\_SYNC}, {\tt wxEXEC\_BLOCK} equal to the sum of both of these flags +is provided as a convenience. + +Finally, you may use the third overloaded version of this function to execute +a process (always synchronously, the contents of \arg{flags} is or'd with +\texttt{wxEXEC\_SYNC}) and capture its output in the array \arg{output}. The +fourth version adds the possibility to additionally capture the messages from +standard error output in the \arg{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. -\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice} +\wxheading{See also} -\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}} +\helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, \helpref{Exec sample}{sampleexec}. -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. +\wxheading{Parameters} -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. +\docparam{command}{The command to execute and any parameters to pass to it as a +single string.} -If Cancel is pressed, -1 is returned. +\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.} -{\it choices} is an array of {\it n} strings for the listbox. +\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},\rtfsp +{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}} -If {\it centre} is TRUE, the message text (which may include new line characters) -is centred; if FALSE, the message is left-justified. +\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}} \wxheading{Include files} - - -\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{::wxExit}\label{wxexit} -{\it choices} is an array of {\it n} strings for the listbox. +\func{void}{wxExit}{\void} -If {\it centre} is TRUE, the message text (which may include new line characters) -is centred; if FALSE, the message is left-justified. +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}. \wxheading{Include files} - - -\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex} - -\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} - +\membersection{::wxJoin}\label{wxjoin} -\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata} +\func{wxString}{wxJoin}{\param{const wxArrayString\&}{ arr}, \param{const wxChar}{ sep}, \param{const wxChar}{ escape = '$\backslash$'}} -\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}} +Concatenate all lines of the given \helpref{wxArrayString}{wxarraystring} object using the separator \arg{sep} and returns +the result as a \helpref{wxString}{wxstring}. -As {\bf wxGetSingleChoice} but takes an array of client data pointers -corresponding to the strings, and returns one of these pointers. +If the \arg{escape} character is non-\NULL, then it's used as prefix for each occurrence of \arg{sep} +in the strings contained in \arg{arr} before joining them which is necessary +in order to be able to recover the original array contents from the string +later using \helpref{wxSplit}{wxsplit}. \wxheading{Include files} - + -\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{::wxKill}\label{wxkill} + +\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}, \param{int }{flags = 0}} -General purpose message dialog. {\it style} may be a bit list of the -following identifiers: +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{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} +\begin{verbatim} +enum wxSignal +{ + wxSIGNONE = 0, // verify if the process exists under Unix + wxSIGHUP, + wxSIGINT, + wxSIGQUIT, + wxSIGILL, + wxSIGTRAP, + wxSIGABRT, + wxSIGEMT, + wxSIGFPE, + wxSIGKILL, // forcefully kill, dangerous! + wxSIGBUS, + wxSIGSEGV, + wxSIGSYS, + wxSIGPIPE, + wxSIGALRM, + wxSIGTERM // terminate the process gently +}; +\end{verbatim} -The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. +{\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. -For example: +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: \begin{verbatim} - ... - int answer = wxMessageBox("Quit program?", "Confirm", - wxYES_NO | wxCANCEL, main_frame); - if (answer == wxYES) - delete main_frame; - ... +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} -{\it message} may contain newline characters, in which case the -message will be split into separate lines, to cater for large messages. +The {\it flags} parameter can be wxKILL\_NOCHILDREN (the default), +or wxKILL\_CHILDREN, in which case the child processes of this +process will be killed too. Note that under Unix, for wxKILL\_CHILDREN +to work you should have created the process by passing wxEXEC\_MAKE\_GROUP\_LEADER +to wxExecute. -Under Windows, the native MessageBox function is used unless wxCENTRE -is specified in the style, in which case a generic function is used. -This is because the native MessageBox function cannot centre text. -The symbols are not shown when the generic function is used. +\wxheading{See also} + +\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp +\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp +\helpref{Exec sample}{sampleexec} \wxheading{Include files} - + -\section{GDI functions}\label{gdifunctions} -The following are relevant to the GDI (Graphics Device Interface). +\membersection{::wxGetProcessId}\label{wxgetprocessid} -\wxheading{Include files} +\func{unsigned long}{wxGetProcessId}{\void} - +Returns the number uniquely identifying the current process in the system. -\membersection{::wxColourDisplay} +If an error occurs, $0$ is returned. -\func{bool}{wxColourDisplay}{\void} +\wxheading{Include files} -Returns TRUE if the display is colour, FALSE otherwise. + -\membersection{::wxDisplayDepth} -\func{int}{wxDisplayDepth}{\void} +\membersection{::wxShell}\label{wxshell} -Returns the depth of the display (a value of 1 denotes a monochrome display). +\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} -\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable} +Executes a command in an interactive shell window. If no command is +specified, then just the shell is spawned. -\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY}, - \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}} +See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}. -Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc}) -makes it into a placeable metafile by prepending a header containing the given -bounding box. The bounding box may be obtained from a device context after drawing -into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. +\wxheading{Include files} -In addition to adding the placeable metafile header, this function adds -the equivalent of the following code to the start of the metafile data: + -\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{::wxShutdown}\label{wxshutdown} -Placeable metafiles may be imported by many Windows applications, and can be -used in RTF (Rich Text Format) files. +\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}} -{\it scale} allows the specification of scale for the metafile. +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} privilege under Windows NT) +and that this function is only implemented under Unix and Win32. -This function is only available under Windows. +\wxheading{Parameters} -\membersection{::wxSetCursor}\label{wxsetcursor} +\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}} -\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}} +\wxheading{Returns} -Globally sets the cursor; only has an effect in MS Windows. -See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. +\true on success, \false if an error occurred. -\section{Printer settings}\label{printersettings} +\wxheading{Include files} -The following functions are used to control PostScript printing. Under -Windows, PostScript output can only be sent to a file. + + + + +\section{Thread functions}\label{threadfunctions} + +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$). + +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. \wxheading{Include files} - + -\membersection{::wxGetPrinterCommand} +\wxheading{See also} -\func{wxString}{wxGetPrinterCommand}{\void} +\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview} -Gets the printer command used to print a file. The default is {\tt lpr}. -\membersection{::wxGetPrinterFile} -\func{wxString}{wxGetPrinterFile}{\void} +\membersection{wxCRIT\_SECT\_DECLARE}\label{wxcritsectdeclare} -Gets the PostScript output filename. +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} -\membersection{::wxGetPrinterMode} +This macro declares a (static) critical section object named {\it cs} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. -\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} +\membersection{wxCRIT\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember} -\func{wxString}{wxGetPrinterOptions}{\void} +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} -Gets the additional options for the print command (e.g. specific printer). The default is nothing. +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. -\membersection{::wxGetPrinterOrientation} -\func{int}{wxGetPrinterOrientation}{\void} -Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. +\membersection{wxCRIT\_SECT\_LOCKER}\label{wxcritsectlocker} -\membersection{::wxGetPrinterPreviewCommand} +\func{}{wxCRIT\_SECT\_LOCKER}{\param{}{name}, \param{}{cs}} -\func{wxString}{wxGetPrinterPreviewCommand}{\void} +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$. -Gets the command used to view a PostScript file. The default depends on the platform. -\membersection{::wxGetPrinterScaling} -\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}} +\membersection{wxCRITICAL\_SECTION}\label{wxcriticalsectionmacro} -Gets the scaling factor for PostScript output. The default is 1.0, 1.0. +\func{}{wxCRITICAL\_SECTION}{\param{}{name}} -\membersection{::wxGetPrinterTranslation} +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: -\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}} +\begin{verbatim} +int IncCount() +{ + static int s_counter = 0; -Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. + wxCRITICAL_SECTION(counter); + + return ++s_counter; +} +\end{verbatim} -\membersection{::wxSetPrinterCommand} +(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). -\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}} -Sets the printer command used to print a file. The default is {\tt lpr}. -\membersection{::wxSetPrinterFile} +\membersection{wxENTER\_CRIT\_SECT}\label{wxentercritsect} -\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}} +\func{}{wxENTER\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} -Sets the PostScript output filename. +This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. -\membersection{::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{::wxIsMainThread}\label{wxismainthread} -\membersection{::wxSetPrinterOptions} +\func{bool}{wxIsMainThread}{\void} -\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}} +Returns \true if this thread is the main one. Always returns \true if +{\tt wxUSE\_THREADS} is $0$. -Sets the additional options for the print command (e.g. specific printer). The default is nothing. -\membersection{::wxSetPrinterOrientation} -\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}} +\membersection{wxLEAVE\_CRIT\_SECT}\label{wxleavecritsect} -Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. +\func{}{wxLEAVE\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} -\membersection{::wxSetPrinterPreviewCommand} +This macro is equivalent to \helpref{cs.Leave()}{wxcriticalsectionleave} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. -\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}} -Sets the command used to view a PostScript file. The default depends on the platform. -\membersection{::wxSetPrinterScaling} +\membersection{::wxMutexGuiEnter}\label{wxmutexguienter} -\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}} +\func{void}{wxMutexGuiEnter}{\void} -Sets the scaling factor for PostScript output. The default is 1.0, 1.0. +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}. -\membersection{::wxSetPrinterTranslation} +Typically, these functions are used like this: -\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}} +\begin{verbatim} +void MyThread::Foo(void) +{ + // before doing any GUI calls we must ensure that this thread is the only + // one doing it! -Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. + wxMutexGuiEnter(); -\section{Clipboard functions}\label{clipsboard} + // Call GUI here: + my_window->DrawSomething(); + + wxMutexGuiLeave(); +} +\end{verbatim} + +Note that under GTK, no creation of top-level windows is allowed in any +thread but the main one. + +This function is only defined on platforms which support preemptive +threads. + + +\membersection{::wxMutexGuiLeave}\label{wxmutexguileave} + +\func{void}{wxMutexGuiLeave}{\void} + +See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}. + +This function is only defined on platforms which support preemptive +threads. -These clipboard functions are implemented for Windows only. + + +\section{File functions}\label{filefunctions} \wxheading{Include files} - + -\membersection{::wxClipboardOpen} +\wxheading{See also} -\func{bool}{wxClipboardOpen}{\void} +\helpref{wxPathList}{wxpathlist}\\ +\helpref{wxDir}{wxdir}\\ +\helpref{wxFile}{wxfile}\\ +\helpref{wxFileName}{wxfilename} -Returns TRUE if this application has already opened the clipboard. -\membersection{::wxCloseClipboard} +\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename} -\func{bool}{wxCloseClipboard}{\void} +\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}} -Closes the clipboard to allow other applications to use it. +Converts a DOS to a Unix filename by replacing backslashes with forward +slashes. -\membersection{::wxEmptyClipboard} -\func{bool}{wxEmptyClipboard}{\void} +\membersection{::wxFileExists}\label{functionwxfileexists} -Empties the clipboard. +\func{bool}{wxFileExists}{\param{const wxString\& }{filename}} -\membersection{::wxEnumClipboardFormats} +Returns true if the file exists and is a plain file. -\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. +\membersection{::wxFileModificationTime}\label{wxfilemodificationtime} -{\it dataFormat} specifies a known format. If this parameter is zero, -the function returns the first format in the list. +\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}} -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. +Returns time of last modification of given file. -Before it enumerates the formats function, an application must open the clipboard by using the -wxOpenClipboard function. +The function returns \texttt{(time\_t)}$-1$ if an error occurred (e.g. file not +found). -\membersection{::wxGetClipboardData} -\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}} +\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath} -Gets data from the clipboard. +\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} -{\it dataFormat} may be one of: +\func{char *}{wxFileNameFromPath}{\param{char *}{path}} -\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} +{\bf NB:} This function is obsolete, please use +\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. -The clipboard must have previously been opened for this call to succeed. +Returns the filename for a full path. The second form returns a pointer to +temporary storage that should not be deallocated. -\membersection{::wxGetClipboardFormatName} -\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}} +\membersection{::wxFindFirstFile}\label{wxfindfirstfile} -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. +\func{wxString}{wxFindFirstFile}{\param{const wxString\& }{spec}, \param{int}{ flags = 0}} -\membersection{::wxIsClipboardFormatAvailable} +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{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}} +\wxheading{Warning} -Returns TRUE if the given data format is available on the clipboard. +As of wx 2.5.2, these functions are not thread-safe! (they use static variables). You probably want to use \helpref{wxDir::GetFirst}{wxdirgetfirst} or \helpref{wxDirTraverser}{wxdirtraverser} instead. -\membersection{::wxOpenClipboard} +{\it spec} may contain wildcards. -\func{bool}{wxOpenClipboard}{\void} +{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either. -Opens the clipboard for passing data to it or getting data from it. +For example: -\membersection{::wxRegisterClipboardFormat} +\begin{verbatim} + wxString f = wxFindFirstFile("/home/project/*.*"); + while ( !f.empty() ) + { + ... + f = wxFindNextFile(); + } +\end{verbatim} -\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}} -Registers the clipboard data format name and returns an identifier. +\membersection{::wxFindNextFile}\label{wxfindnextfile} -\membersection{::wxSetClipboardData} +\func{wxString}{wxFindNextFile}{\void} -\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}} +Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. -Passes data to the clipboard. +See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example. -{\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} +\membersection{::wxGetDiskSpace}\label{wxgetdiskspace} -The clipboard must have previously been opened for this call to succeed. +\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}} -\section{Miscellaneous functions}\label{miscellany} +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. -\membersection{::wxNewId} +\wxheading{Returns} -\func{long}{wxNewId}{\void} +\true on success, \false if an error occurred (for example, the +directory doesn't exist). -Generates an integer identifier unique to this run of the program. +\wxheading{Portability} -\wxheading{Include files} +The generic Unix implementation depends on the system having +the \texttt{statfs()} or \texttt{statvfs()} function. - +This function first appeared in wxWidgets 2.3.2. -\membersection{::wxRegisterId} -\func{void}{wxRegisterId}{\param{long}{ id}} +\membersection{::wxGetFileKind}\label{wxgetfilekind} -Ensures that ids subsequently generated by {\bf NewId} do not clash with -the given {\bf id}. +\func{wxFileKind}{wxGetFileKind}{\param{int }{fd}} + +\func{wxFileKind}{wxGetFileKind}{\param{FILE *}{fp}} + +Returns the type of an open file. Possible return values are: + +\begin{verbatim} +enum wxFileKind +{ + wxFILE_KIND_UNKNOWN, + wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets + wxFILE_KIND_TERMINAL, // a tty + wxFILE_KIND_PIPE // a pipe +}; + +\end{verbatim} \wxheading{Include files} - + -\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} -\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}} +\membersection{::wxGetOSDirectory}\label{wxgetosdirectory} -Changes the cursor to the given cursor for all windows in the application. -Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back -to its previous state. These two calls can be nested, and a counter -ensures that only the outer calls take effect. +\func{wxString}{wxGetOSDirectory}{\void} -See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. +Returns the Windows directory under Windows; on other platforms returns the empty string. -\wxheading{Include files} - +\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath} -\membersection{::wxBell} +\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} -\func{void}{wxBell}{\void} +Returns true if the argument is an absolute filename, i.e. with a slash +or drive name at the beginning. -Ring the system bell. -\wxheading{Include files} +\membersection{::wxDirExists}\label{functionwxdirexists} - +\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} -\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject} +Returns true if \arg{dirname} exists and is a directory. -\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{::wxPathOnly}\label{wxpathonly} -\membersection{::wxDDECleanUp}\label{wxddecleanup} +\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} -\func{void}{wxDDECleanUp}{\void} +Returns the directory part of the filename. -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}. +\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename} -\wxheading{Include files} +\func{void}{wxUnix2DosFilename}{\param{wxChar *}{s}} - +This function is deprecated, use \helpref{wxFileName}{wxfilename} instead. -\membersection{::wxDDEInitialize}\label{wxddeinitialize} +Converts a Unix to a DOS filename by replacing forward +slashes with backslashes. -\func{void}{wxDDEInitialize}{\void} -Initializes the DDE system. May be called multiple times without harm. +\membersection{wxCHANGE\_UMASK}\label{wxchangeumask} -This no longer needs to be called by the application: it will be called -by wxWindows if necessary. +\func{}{wxCHANGE\_UMASK}{\param{int }{mask}} -See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection}, -\helpref{wxDDECleanUp}{wxddecleanup}. +Under Unix this macro changes the current process umask to the given value, +unless it is equal to $-1$ in which case nothing is done, and restores it to +the original value on scope exit. It works by declaring a variable which sets +umask to \arg{mask} in its constructor and restores it in its destructor. -\wxheading{Include files} +Under other platforms this macro expands to nothing. - -\membersection{::wxDebugMsg}\label{wxdebugmsg} +\membersection{::wxConcatFiles}\label{wxconcatfiles} -\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}} +\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, +\param{const wxString\& }{file3}} -Display a debugging message; under Windows, this will appear on the -debugger command window, and under Unix, it will be written to standard -error. +Concatenates {\it file1} and {\it file2} to {\it file3}, returning +true if successful. -The syntax is identical to {\bf printf}: pass a format string and a -variable list of arguments. -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++. +\membersection{::wxCopyFile}\label{wxcopyfile} -{\bf Tip:} under Windows, if your application crashes before the -message appears in the debugging window, put a wxYield call after -each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s -(at least for Watcom C++): preformat your messages and use OutputDebugString -instead. +\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}} -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +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. -\wxheading{Include files} +This function supports resources forks under Mac OS. - -\membersection{::wxDisplaySize} +\membersection{::wxGetCwd}\label{wxgetcwd} -\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} +\func{wxString}{wxGetCwd}{\void} -Gets the physical size of the display in pixels. +Returns a string containing the current (or working) directory. -\wxheading{Include files} - +\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory} -\membersection{::wxEntry}\label{wxentry} +\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}} -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. +{\bf NB:} This function is deprecated: use \helpref{wxGetCwd}{wxgetcwd} instead. -\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}} +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. -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. +{\it sz} is the size of the buffer if supplied. -\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}} -wxWindows initialization under Windows (for applications constructed as a DLL). +\membersection{::wxGetTempFileName}\label{wxgettempfilename} -\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}} +\func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}} -wxWindows initialization under Unix. +\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}} -\wxheading{Remarks} +%% 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. -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: +{\bf NB:} These functions are obsolete, please use\rtfsp +\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp +instead. -\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} +\membersection{::wxIsWild}\label{wxiswild} -\wxheading{Include files} +\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} - +Returns true if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. -\membersection{::wxError}\label{wxerror} -\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}} +\membersection{::wxMatchWild}\label{wxmatchwild} -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}. +\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} -\wxheading{Include files} +Returns true if the \arg{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{::wxEndBusyCursor}\label{wxendbusycursor} +\membersection{::wxMkdir}\label{wxmkdir} -\func{void}{wxEndBusyCursor}{\void} +\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}} -Changes the cursor back to the original cursor, for all windows in the application. -Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}. +Makes the directory \arg{dir}, returning true if successful. -See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. +{\it perm} is the access mask for the directory for the systems on which it is +supported (Unix) and doesn't have any effect on the other ones. -\wxheading{Include files} - +\membersection{::wxParseCommonDialogsFilter}\label{wxparsecommondialogsfilter} -\membersection{::wxExecute}\label{wxexecute} +\func{int}{wxParseCommonDialogsFilter}{\param{const wxString\& }{wildCard}, \param{wxArrayString\& }{descriptions}, \param{wxArrayString\& }{filters}} -\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} +Parses the \arg{wildCard}, returning the number of filters. +Returns 0 if none or if there's a problem. +The arrays will contain an equal number of items found before the error. +On platforms where native dialogs handle only one filter per entry, +entries in arrays are automatically adjusted. +\arg{wildCard} is in the form: +\begin{verbatim} + "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" +\end{verbatim} -\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} +\membersection{::wxRemoveFile}\label{wxremovefile} -Executes another program in Unix or Windows. +\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} -The first form takes a command string, such as {\tt "emacs file.txt"}. +Removes \arg{file}, returning true if successful. -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{::wxRenameFile}\label{wxrenamefile} -In the case of synchronous execution, the return value is trhe exit code of -the process (which terminates by the moment the function returns) and will be -$-1$ if the process couldn't be started and typically 0 if the process -terminated successfully. +\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}} -For asynchronous execution, however, the return value is the process id and -zero value indicates that the command could not be executed. +Renames \arg{file1} to \arg{file2}, returning true if successful. + +If \arg{overwrite} parameter is true (default), the destination file is +overwritten if it exists, but if \arg{overwrite} is false, the functions fails +in this case. + + +\membersection{::wxRmdir}\label{wxrmdir} + +\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}} + +Removes the directory {\it dir}, returning true if successful. Does not work under VMS. + +The {\it flags} parameter is reserved for future use. + +Please notice that there is also a wxRmDir() function which simply wraps the +standard POSIX rmdir() function and so return an integer error code instead of +a boolean value (but otherwise is currently identical to wxRmdir), don't +confuse these two functions. + + +\membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory} + +\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}} + +Sets the current working directory, returning true if the operation succeeded. +Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification. + + +\membersection{::wxSplit}\label{wxsplit} + +\func{wxArrayString}{wxSplit}{\param{const wxString\&}{ str}, \param{const wxChar}{ sep}, \param{const wxChar}{ escape = '\\'}} + +Splits the given \helpref{wxString}{wxstring} object using the separator \arg{sep} and returns the +result as a \helpref{wxArrayString}{wxarraystring}. + +If the \arg{escape} character is non-\NULL, then the occurrences of \arg{sep} immediately prefixed +with \arg{escape} are not considered as separators. + +Note that empty tokens will be generated if there are two or more adjacent separators. + +\wxheading{See also} + +\helpref{wxJoin}{wxjoin} + +\wxheading{Include files} + + + + +\membersection{::wxSplitPath}\label{wxsplitfunction} + +\func{void}{wxSplitPath}{\param{const wxString\&}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}} + +{\bf NB:} This function is obsolete, please use +\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. + +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. + +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). + +On entry, {\it fullname} should be non-NULL (it may be empty though). + +On return, {\it path} contains the file path (without the trailing separator), {\it name} +contains the file name and {\it ext} contains the file extension without leading dot. All +three of them may be empty if the corresponding component is. The old contents of the +strings pointed to by these parameters will be overwritten in any case (if the pointers +are not NULL). + + +\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream} + +\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}} + +Copies the given file to {\it stream}. Useful when converting an old application to +use streams (within the document/view framework, for example). + +\wxheading{Include files} + + + + +\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile} + +\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}} + +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} + + + + + +\section{Network, user and OS functions}\label{networkfunctions} + +The functions in this section are used to retrieve information about the +current computer and/or user characteristics. + + +\membersection{::wxGetEmailAddress}\label{wxgetemailaddress} + +\func{wxString}{wxGetEmailAddress}{\void} + +\func{bool}{wxGetEmailAddress}{\param{char * }{buf}, \param{int }{sz}} + +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{::wxGetFreeMemory}\label{wxgetfreememory} + +\func{wxMemorySize}{wxGetFreeMemory}{\void} + +Returns the amount of free memory in bytes under environments which +support it, and -1 if not supported or failed to perform measurement. + +\wxheading{Include files} + + + + +\membersection{::wxGetFullHostName}\label{wxgetfullhostname} + +\func{wxString}{wxGetFullHostName}{\void} + +Returns the FQDN (fully qualified domain host name) or an empty string on +error. + +\wxheading{See also} + +\helpref{wxGetHostName}{wxgethostname} + +\wxheading{Include files} + + + + +\membersection{::wxGetHomeDir}\label{wxgethomedir} + +\func{wxString}{wxGetHomeDir}{\void} + +Return the (current) user's home directory. + +\wxheading{See also} + +\helpref{wxGetUserHome}{wxgetuserhome}\\ +\helpref{wxStandardPaths}{wxstandardpaths} + +\wxheading{Include files} + + + + +\membersection{::wxGetHostName}\label{wxgethostname} + +\func{wxString}{wxGetHostName}{\void} + +\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. + +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 wxWidgets} section of the WIN.INI file is tried. + +The first variant of this function returns the hostname if successful or an +empty string otherwise. The second (deprecated) function returns true +if successful, false otherwise. + +\wxheading{See also} + +\helpref{wxGetFullHostName}{wxgetfullhostname} + +\wxheading{Include files} + + + + +\membersection{::wxGetOsDescription}\label{wxgetosdescription} + +\func{wxString}{wxGetOsDescription}{\void} + +Returns the string containing the description of the current platform in a +user-readable form. For example, this function may return strings like +{\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}. + +\wxheading{See also} + +\helpref{::wxGetOsVersion}{wxgetosversion} + +\wxheading{Include files} + + + + +\membersection{::wxGetOsVersion}\label{wxgetosversion} + +\func{wxOperatingSystemId}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} + +Gets the version and the operating system ID for currently running OS. +See \helpref{wxPlatformInfo}{wxplatforminfo} for more details about wxOperatingSystemId. + +\wxheading{See also} + +\helpref{::wxGetOsDescription}{wxgetosdescription}, +\helpref{wxPlatformInfo}{wxplatforminfo} + +\wxheading{Include files} + + + + +\membersection{::wxIsPlatformLittleEndian}\label{wxisplatformlittleendian} + +\func{bool}{wxIsPlatformLittleEndian}{\void} + +Returns \true if the current platform is little endian (instead of big endian). +The check is performed at run-time. + +\wxheading{See also} + +\helpref{Byte order macros}{byteordermacros} + +\wxheading{Include files} + + + + +\membersection{::wxIsPlatform64Bit}\label{wxisplatform64bit} + +\func{bool}{wxIsPlatform64Bit}{\void} + +Returns \true if the operating system the program is running under is 64 bit. +The check is performed at run-time and may differ from the value available at +compile-time (at compile-time you can just check if {\tt sizeof(void*)==8}) +since the program could be running in emulation mode or in a mixed 32/64 bit system +(bi-architecture operating system). + +Very important: this function is not 100\% reliable on some systems given the fact +that there isn't always a standard way to do a reliable check on the OS architecture. + +\wxheading{Include files} + + + + +\membersection{::wxGetUserHome}\label{wxgetuserhome} + +\func{wxString}{wxGetUserHome}{\param{const wxString\& }{user = ""}} + +Returns the home directory for the given user. If the \arg{user} is empty +(default value), this function behaves like +\helpref{wxGetHomeDir}{wxgethomedir} i.e. returns the current user home +directory. + +If the home directory couldn't be determined, an empty string is returned. + +\wxheading{Include files} + + + + +\membersection{::wxGetUserId}\label{wxgetuserid} + +\func{wxString}{wxGetUserId}{\void} + +\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}} + +This function returns the "user id" also known as "login name" under Unix i.e. +something like "jsmith". It uniquely identifies the current user (on this system). + +Under Windows or NT, this function first looks in the environment +variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp +in the {\bf wxWidgets} section of the WIN.INI file is tried. + +The first variant of this function returns the login name if successful or an +empty string otherwise. The second (deprecated) function returns true +if successful, false otherwise. + +\wxheading{See also} + +\helpref{wxGetUserName}{wxgetusername} + +\wxheading{Include files} + + + + +\membersection{::wxGetUserName}\label{wxgetusername} + +\func{wxString}{wxGetUserName}{\void} + +\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}} + +This function returns the full user name (something like "Mr. John Smith"). + +Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp +in the {\bf wxWidgets} section of the WIN.INI file. If PenWindows +is running, the entry {\bf Current} in the section {\bf User} of +the PENWIN.INI file is used. + +The first variant of this function returns the user name if successful or an +empty string otherwise. The second (deprecated) function returns \true +if successful, \false otherwise. + +\wxheading{See also} + +\helpref{wxGetUserId}{wxgetuserid} + +\wxheading{Include files} + + + + + +\section{String functions}\label{stringfunctions} + +\membersection{::wxGetTranslation}\label{wxgettranslation} + +\func{const wxString\& }{wxGetTranslation}{\param{const wxString\& }{str}, + \param{const wxString\& }{domain = wxEmptyString}} + +\func{const wxString\& }{wxGetTranslation}{\param{const wxString\& }{str}, \param{const wxString\& }{strPlural}, \param{size\_t }{n}, + \param{const wxString\& }{domain = wxEmptyString}} + +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. If +{\it domain} is specified then only that domain/catalog is searched +for a matching string. As this function +is used very often, an alternative (and also common in Unix world) syntax is +provided: the \helpref{\_()}{underscore} macro is defined to do the same thing +as wxGetTranslation. + +The second form is used when retrieving translation of string that has +different singular and plural form in English or different plural forms in some +other language. It takes two extra arguments: as above, \arg{str} +parameter must contain the singular form of the string to be converted and +is used as the key for the search in the catalog. The \arg{strPlural} parameter +is the plural form (in English). The parameter \arg{n} is used to determine the +plural form. If no message catalog is found \arg{str} is returned if `n == 1', +otherwise \arg{strPlural}. + +See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} +for additional information on plural forms handling. For a shorter alternative +see the \helpref{wxPLURAL()}{wxplural} macro. + +Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}. + +Note that this function is not suitable for literal strings in Unicode +builds, since the literal strings must be enclosed into +\helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them +unrecognised by \texttt{xgettext}, and so they are not extracted to the message +catalog. Instead, use the \helpref{\_()}{underscore} and +\helpref{wxPLURAL}{wxplural} macro for all literal strings. + + +\membersection{::wxIsEmpty}\label{wxisempty} + +\func{bool}{wxIsEmpty}{\param{const char *}{ p}} + +Returns \true if the pointer is either {\tt NULL} or points to an empty +string, \false otherwise. + + +\membersection{::wxStrcmp}\label{wxstrcmp} + +\func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}} + +Returns a negative value, 0, or positive value if {\it p1} is less than, equal +to or greater than {\it p2}. The comparison is case-sensitive. + +This function complements the standard C function {\it stricmp()} which performs +case-insensitive comparison. + + +\membersection{::wxStricmp}\label{wxstricmp} + +\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}} + +Returns a negative value, 0, or positive value if {\it p1} is less than, equal +to or greater than {\it p2}. The comparison is case-insensitive. + +This function complements the standard C function {\it strcmp()} which performs +case-sensitive comparison. + + +\membersection{::wxStringEq}\label{wxstringeq} + +\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} + +{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead. + +A macro defined as: + +\begin{verbatim} +#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) +\end{verbatim} + + +\membersection{::wxStringMatch}\label{wxstringmatch} + +\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\ + \param{bool}{ subString = true}, \param{bool}{ exact = false}} + +{\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead. + +Returns \true if the substring {\it s1} is found within {\it s2}, +ignoring case if {\it exact} is false. If {\it subString} is \false, +no substring matching is done. + + +\membersection{::wxStringTokenize}\label{wxstringtokenize} + +\func{wxArrayString}{wxStringTokenize}{\param{const wxString\& }{str},\\ + \param{const wxString\& }{delims = wxDEFAULT\_DELIMITERS},\\ + \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}} + +This is a convenience function wrapping +\helpref{wxStringTokenizer}{wxstringtokenizer} which simply returns all tokens +found in the given \arg{str} in an array. + +Please see +\helpref{wxStringTokenizer::wxStringTokenizer}{wxstringtokenizerwxstringtokenizer} +for the description of the other parameters. + + +\membersection{::wxStrlen}\label{wxstrlen} + +\func{size\_t}{wxStrlen}{\param{const char *}{ p}} + +This is a safe version of standard function {\it strlen()}: it does exactly the +same thing (i.e. returns the length of the string) except that it returns 0 if +{\it p} is the {\tt NULL} pointer. + + +\membersection{::wxSnprintf}\label{wxsnprintf} + +\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}} + +This function replaces the dangerous standard function {\tt sprintf()} and is +like {\tt snprintf()} available on some platforms. The only difference with +sprintf() is that an additional argument - buffer size - is taken and the +buffer is never overflowed. + +Returns the number of characters copied to the buffer or -1 if there is not +enough space. + +\wxheading{See also} + +\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf} + + +\membersection{wxT}\label{wxt} + +\func{wxChar}{wxT}{\param{char }{ch}} + +\func{const wxChar *}{wxT}{\param{const char *}{s}} + +wxT() is a macro which can be used with character and string literals (in other +words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in +Unicode build configuration. Please see the +\helpref{Unicode overview}{unicode} for more information. + +This macro is simply returns the value passed to it without changes in ASCII +build. In fact, its definition is: +\begin{verbatim} +#ifdef UNICODE +#define wxT(x) L ## x +#else // !Unicode +#define wxT(x) x +#endif +\end{verbatim} + + +\membersection{wxTRANSLATE}\label{wxtranslate} + +\func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}} + +This macro doesn't do anything in the program code -- it simply expands to the +value of its argument. + +However it does have a purpose which is to mark the literal strings for the +extraction into the message catalog created by {\tt xgettext} program. Usually +this is achieved using \helpref{\_()}{underscore} but that macro not only marks +the string for extraction but also expands into a +\helpref{wxGetTranslation}{wxgettranslation} function call which means that it +cannot be used in some situations, notably for static array +initialization. + +Here is an example which should make it more clear: suppose that you have a +static array of strings containing the weekday names and which have to be +translated (note that it is a bad example, really, as +\helpref{wxDateTime}{wxdatetime} already can be used to get the localized week +day names already). If you write + +\begin{verbatim} +static const char * 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 char * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") }; +... +// use wxGetTranslation(weekdays[n]) +\end{verbatim} + +here. + +Note that although the code {\bf would} compile if you simply omit +wxTRANSLATE() in the above, it wouldn't work as expected because there would be +no translations for the weekday names in the program message catalog and +wxGetTranslation wouldn't find them. + + +\membersection{::wxVsnprintf}\label{wxvsnprintf} + +\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}} + +The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list } +argument instead of arbitrary number of parameters. + +Note that if \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is set to 1, then this function supports +positional arguments (see \helpref{wxString::Printf}{wxstringprintf} for more information). +However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, wxVfprintf, +wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional parameters +even when \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is 1. + +\wxheading{See also} + +\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv} + + + +\membersection{\_}\label{underscore} + +\func{const wxString\&}{\_}{\param{const wxString\&}{s}} + +This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation} +function, so it marks the message for the extraction by {\tt xgettext} just as +\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of +the string for the current locale during execution. + +Don't confuse this macro with \helpref{\_T()}{underscoret}! + + +\membersection{wxPLURAL}\label{wxplural} + +\func{const wxString\&}{wxPLURAL}{\param{const wxString\&}{sing}, \param{const wxString\&}{plur}, \param{size\_t}{n}} + +This macro is identical to \helpref{\_()}{underscore} but for the plural variant +of \helpref{wxGetTranslation}{wxgettranslation}. + + +\membersection{\_T}\label{underscoret} + +\func{wxChar}{\_T}{\param{char }{ch}} + +\func{const wxChar *}{\_T}{\param{const wxChar }{ch}} + +This macro is exactly the same as \helpref{wxT}{wxt} and is defined in +wxWidgets simply because it may be more intuitive for Windows programmers as +the standard Win32 headers also define it (as well as yet another name for the +same macro which is {\tt \_TEXT()}). + +Don't confuse this macro with \helpref{\_()}{underscore}! + + + +\section{Dialog functions}\label{dialogfunctions} + +Below are a number of convenience functions for getting input from the +user or displaying messages. Note that in these functions the last three +parameters are optional. However, it is recommended to pass a parent frame +parameter, or (in MS Windows or Motif) the wrong window frame may be brought to +the front when the dialog box is popped up. + + +\membersection{::wxAboutBox}\label{wxaboutbox} + +\func{void}{wxAboutBox}{\param{const wxAboutDialogInfo\& }{info}} + +This function shows the standard about dialog containing the information +specified in \arg{info}. If the current platform has a native about dialog +which is capable of showing all the fields in \arg{info}, the native dialog is +used, otherwise the function falls back to the generic wxWidgets version of the +dialog, i.e. does the same thing as \helpref{wxGenericAboutBox()}{wxgenericaboutbox}. + +Here is an example of how this function may be used: +\begin{verbatim} +void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event)) +{ + wxAboutDialogInfo info; + info.SetName(_("My Program")); + info.SetVersion(_("1.2.3 Beta")); + info.SetDescription(_("This program does something great.")); + info.SetCopyright(_T("(C) 2007 Me ")); + + wxAboutBox(info); +} +\end{verbatim} + +Please see the \helpref{dialogs sample}{sampledialogs} for more examples of +using this function and \helpref{wxAboutDialogInfo}{wxaboutdialoginfo} for the +description of the information which can be shown in the about dialog. + +\wxheading{Include files} + + + + +\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{::wxBell}\label{wxbell} + +\func{void}{wxBell}{\void} + +Ring the system bell. + +Note that this function is categorized as a GUI one and so is not thread-safe. + +\wxheading{Include files} + + + + +\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider} + +\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename}, + \param{size\_t }{currentTip}} + +This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be +used with \helpref{wxShowTip}{wxshowtip}. + +\docparam{filename}{The name of the file containing the tips, one per line} +\docparam{currentTip}{The index of the first tip to show - normally this index +is remembered between the 2 program runs.} + +\wxheading{See also} + +\helpref{Tips overview}{tipsoverview} + +\wxheading{Include files} + + + + +\membersection{::wxDirSelector}\label{wxdirselector} + +\func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\ + \param{const wxString\& }{default\_path = ""},\\ + \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\ + \param{wxWindow *}{parent = NULL}} + +Pops up a directory selector dialog. The arguments have the same meaning as +those of wxDirDialog::wxDirDialog(). The message is displayed at the top, +and the default\_path, if specified, is set as the initial selection. + +The application must check for an empty return value (if the user pressed +Cancel). For example: + +\begin{verbatim} +const wxString& dir = wxDirSelector("Choose a folder"); +if ( !dir.empty() ) +{ + ... +} +\end{verbatim} + +\wxheading{Include files} + + + + +\membersection{::wxFileSelector}\label{wxfileselector} + +\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\ + \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\ + \param{const wxString\& }{wildcard = "*.*"}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\ + \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 wxFD\_OPEN, +wxFD\_SAVE, wxFD\_OVERWRITE\_PROMPT or wxFD\_FILE\_MUST\_EXIST. Note that wxFD\_MULTIPLE +can only be used with \helpref{wxFileDialog}{wxfiledialog} and not here as this +function only returns a single file name. + +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{::wxEndBusyCursor}\label{wxendbusycursor} + +\func{void}{wxEndBusyCursor}{\void} + +Changes the cursor back to the original cursor, for all windows in the application. +Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}. + +See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. + +\wxheading{Include files} + + + + +\membersection{::wxGenericAboutBox}\label{wxgenericaboutbox} + +\func{void}{wxGenericAboutBox}{\param{const wxAboutDialogInfo\& }{info}} + +This function does the same thing as \helpref{wxAboutBox}{wxaboutbox} except +that it always uses the generic wxWidgets version of the dialog instead of the +native one. This is mainly useful if you need to customize the dialog by e.g. +adding custom controls to it (customizing the native dialog is not currently +supported). + +See the \helpref{dialogs sample}{sampledialogs} for an example of about dialog +customization. + +\wxheading{See also} + +\helpref{wxAboutDialogInfo}{wxaboutdialoginfo} + +\wxheading{Include files} + +\\ + + + +\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser} + +\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}, \param{wxColourData *}{data = \NULL}} + +Shows the colour selection dialog and returns the colour selected by user or +invalid colour (use \helpref{wxColour:IsOk}{wxcolourisok} to test whether a colour +is valid) if the dialog was cancelled. + +\wxheading{Parameters} + +\docparam{parent}{The parent window for the colour selection dialog} + +\docparam{colInit}{If given, this will be the colour initially selected in the dialog.} + +\docparam{caption}{If given, this will be used for the dialog caption.} + +\docparam{data}{Optional object storing additional colour dialog settings, such +as custom colours. If none is provided the same settings as the last time are +used.} + +\wxheading{Include files} + + + + +\membersection{::wxGetFontFromUser}\label{wxgetfontfromuser} + +\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}, \param{const wxString\& }{caption = wxEmptyString}} + +Shows the font selection dialog and returns the font selected by user or +invalid font (use \helpref{wxFont:IsOk}{wxfontisok} 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.} + +\docparam{caption}{If given, this will be used for the dialog caption.} + +\wxheading{Include files} + + + + + +\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices} + +\func{size\_t}{wxGetMultipleChoices}{\\ + \param{wxArrayInt\& }{selections},\\ + \param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{const wxArrayString\& }{aChoices},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} + +\func{size\_t}{wxGetMultipleChoices}{\\ + \param{wxArrayInt\& }{selections},\\ + \param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{int}{ n}, \param{const wxString\& }{choices[]},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} + +Pops up a dialog box containing a message, OK/Cancel buttons and a +multiple-selection listbox. The user may choose an arbitrary (including 0) +number of items in the listbox whose indices will be returned in +{\it selection} array. The initial contents of this array will be used to +select the items when the dialog is shown. + +You may pass the list of strings to choose from either using {\it choices} +which is an array of {\it n} strings for the listbox or by using a single +{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}. + +If {\it centre} is true, the message text (which may include new line +characters) is centred; if false, the message is left-justified. + +\wxheading{Include files} + + + +\perlnote{In wxPerl there is just an array reference in place of {\tt n} +and {\tt choices}, and no {\tt selections} parameter; the function +returns an array containing the user selections.} + + +\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser} + +\func{long}{wxGetNumberFromUser}{ + \param{const wxString\& }{message}, + \param{const wxString\& }{prompt}, + \param{const wxString\& }{caption}, + \param{long }{value}, + \param{long }{min = 0}, + \param{long }{max = 100}, + \param{wxWindow *}{parent = NULL}, + \param{const wxPoint\& }{pos = wxDefaultPosition}} + +Shows a dialog asking the user for numeric input. The dialogs title is set to +{\it caption}, it contains a (possibly) multiline {\it message} above the +single line {\it prompt} and the zone for entering the number. + +The number entered must be in the range {\it min}..{\it max} (both of which +should be positive) and {\it value} is the initial value of it. If the user +enters an invalid value or cancels the dialog, the function will return -1. + +Dialog is centered on its {\it parent} unless an explicit position is given in +{\it pos}. + +\wxheading{Include files} + + + + +\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser} + +\func{wxString}{wxGetPasswordFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ + \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}} + +Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered +in the dialog is not shown on screen but replaced with stars. This is intended +to be used for entering passwords as the function name implies. + +\wxheading{Include files} + + + + +\membersection{::wxGetTextFromUser}\label{wxgettextfromuser} + +\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ + \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}} + +Pop up a dialog box with title set to {\it caption}, {\it message}, and a +\rtfsp{\it default\_value}. The user may type in text and press OK to return this text, +or press Cancel to return the empty string. + +If {\it centre} is true, the message text (which may include new line characters) +is centred; if false, the message is left-justified. + +\wxheading{Include files} + + + + +\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice} + +\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{const wxArrayString\& }{aChoices},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} + +\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\ + \param{const wxString\& }{caption},\\ + \param{int}{ n}, \param{const wxString\& }{choices[]},\\ + \param{wxWindow *}{parent = NULL},\\ + \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true},\\ + \param{int }{width=150}, \param{int }{height=200}} + +Pops up a dialog box containing a message, OK/Cancel buttons and a +single-selection listbox. The user may choose an item and press OK to return a +string or Cancel to return the empty string. Use +\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex} if empty string is a +valid choice and if you want to be able to detect pressing Cancel reliably. + +You may pass the list of strings to choose from either using {\it choices} +which is an array of {\it n} strings for the listbox or by using a single +{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}. + +If {\it centre} is true, the message text (which may include new line +characters) is centred; if false, the message is left-justified. + +\wxheading{Include files} + + + +\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{::wxInfoMessageBox}\label{wxinfomessagebox} + +\func{void}{wxInfoMessageBox}{\param{wxWindow (}{parent = \NULL}} + +Shows a message box with the information about the wxWidgets build used, +including its version, most important build parameters and the version of the +underlying GUI toolkit. This is mainly used for diagnostic purposes and can be +invoked by Ctrl-Alt-middle clicking on any wxWindow which doesn't otherwise +handle this event. + +\newsince{2.9.0} + +\wxheading{Include files} + + + + +\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 only 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}\label{mathfunctions} + +\wxheading{Include files} + + + + +\membersection{wxFinite}\label{wxfinite} + +\func{int}{wxFinite}{\param{double }{x}} + +Returns a non-zero value if {\it x} is neither infinite nor 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 wxWidgets assumes. + +Placeable metafiles may be imported by many Windows applications, and can be +used in RTF (Rich Text Format) files. + +{\it scale} allows the specification of scale for the metafile. + +This function is only available under Windows. + + +\membersection{::wxSetCursor}\label{wxsetcursor} + +\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}} + +Globally sets the cursor; only has an effect in Windows and GTK. +See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. + + + +\section{Printer settings}\label{printersettings} + +{\bf NB:} These routines are obsolete and should no longer be used! + +The following functions are used to control PostScript printing. Under +Windows, PostScript output can only be sent to a file. + +\wxheading{Include files} + + + + +\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 and macros}\label{miscellany} + + +\membersection{wxBase64Decode}\label{wxbase64decode} + +\func{size\_t}{wxBase64Decode}{\param{void *}{dst}, \param{size\_t }{dstLen}, +\param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN}, +\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict}, +\param{size\_t }{*posErr = \NULL}} + +\func{wxMemoryBuffer}{wxBase64Decode}{\\ +\param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN},\\ +\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\ +\param{size\_t }{*posErr = \NULL}} + +\func{wxMemoryBuffer}{wxBase64Decode}{\\ +\param{const wxString\& }{src},\\ +\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\ +\param{size\_t }{*posErr = \NULL}} + +These function decode a Base64-encoded string. The first version is a raw +decoding function and decodes the data into the provided buffer \arg{dst} of +the given size \arg{dstLen}. An error is returned if the buffer is not large +enough -- that is not at least \helpref{wxBase64DecodedSize(srcLen)}{wxbase64decodedsize} +bytes. The second version allocates memory internally and returns it as +\helpref{wxMemoryBuffer}{wxmemorybuffer} and is recommended for normal use. + +The first version returns the number of bytes written to the buffer or the +necessary buffer size if \arg{dst} was \NULL or \texttt{wxCONV\_FAILED} on +error, e.g. if the output buffer is too small or invalid characters were +encountered in the input string. The second version returns a buffer with the +base64 decoded binary equivalent of the input string. In neither case is the +buffer NUL-terminated. + +\wxheading{Parameters} + +\docparam{dst}{Pointer to output buffer, may be \NULL to just compute the +necessary buffer size.} + +\docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is +\NULL.} + +\docparam{src}{The input string, must not be \NULL. For the version using +wxString, the input string should contain only ASCII characters.} + +\docparam{srcLen}{The length of the input string or special value +\texttt{wxNO\_LEN} if the string is \NUL-terminated and the length should be +computed by this function itself.} + +\docparam{mode}{This parameter specifies the function behaviour when invalid +characters are encountered in input. By default, any such character stops the +decoding with error. If the mode is wxBase64DecodeMode\_SkipWS, then the white +space characters are silently skipped instead. And if it is +wxBase64DecodeMode\_Relaxed, then all invalid characters are skipped.} + +\docparam{posErr}{If this pointer is non-\NULL and an error occurs during +decoding, it is filled with the index of the invalid character.} + +\wxheading{Include files} + + + + +\membersection{wxBase64DecodedSize}\label{wxbase64decodedsize} + +\func{size\_t}{wxBase64DecodedSize}{\param{size\_t }{srcLen}} + +Returns the size of the buffer necessary to contain the data encoded in a +base64 string of length \arg{srcLen}. This can be useful for allocating a +buffer to be passed to \helpref{wxBase64Decode}{wxbase64decode}. + + +\membersection{wxBase64Encode}\label{wxbase64encode} + +\func{size\_t}{wxBase64Encode}{\param{char *}{dst}, \param{size\_t }{dstLen}, +\param{const void *}{src}, \param{size\_t }{srcLen}} + +\func{wxString}{wxBase64Encode}{\param{const void *}{src}, \param{size\_t }{srcLen}} + +\func{wxString}{wxBase64Encode}{\param{const wxMemoryBuffer\& }{buf}} + +These functions encode the given data using base64. The first of them is the +raw encoding function writing the output string into provided buffer while the +other ones return the output as wxString. There is no error return for these +functions except for the first one which returns \texttt{wxCONV\_FAILED} if the +output buffer is too small. To allocate the buffer of the correct size, use +\helpref{wxBase64EncodedSize}{wxbase64encodedsize} or call this function with +\arg{dst} set to \NULL -- it will then return the necessary buffer size. + +\wxheading{Parameters} + +\docparam{dst}{The output buffer, may be \NULL to retrieve the needed buffer +size.} + +\docparam{dstLen}{The output buffer size, ignored if \arg{dst} is \NULL.} + +\docparam{src}{The input buffer, must not be \NULL.} + +\docparam{srcLen}{The length of the input data.} + +\wxheading{Include files} + + + + +\membersection{wxBase64EncodedSize}\label{wxbase64encodedsize} + +\func{size\_t}{wxBase64EncodedSize}{\param{size\_t }{len}} + +Returns the length of the string with base64 representation of a buffer of +specified size \arg{len}. This can be useful for allocating the buffer passed +to \helpref{wxBase64Encode}{wxbase64encode}. + + +\membersection{wxCONCAT}\label{wxconcat} + +\func{}{wxCONCAT}{\param{}{x}, \param{}{y}} + +This macro returns the concatenation of two tokens \arg{x} and \arg{y}. + + +\membersection{wxDECLARE\_APP}\label{wxdeclareapp} + +\func{}{wxDECLARE\_APP}{className} + +This is used in headers to create a forward declaration of the +\helpref{wxGetApp}{wxgetapp} function implemented by +\helpref{wxIMPLEMENT\_APP}{wximplementapp}. It creates the declaration +{\tt className\& wxGetApp(void)}. + +Example: + +\begin{verbatim} + wxDECLARE_APP(MyApp) +\end{verbatim} + +\wxheading{Include files} + + + + +\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{wxDEPRECATED}\label{wxdeprecated} + +This macro can be used around a function declaration to generate warnings +indicating that this function is deprecated (i.e. obsolete and planned to be +removed in the future) when it is used. Only Visual C++ 7 and higher and g++ +compilers currently support this functionality. + +Example of use: +\begin{verbatim} + // old function, use wxString version instead + wxDEPRECATED( void wxGetSomething(char *buf, size_t len) ); + + // ... + wxString wxGetSomething(); +\end{verbatim} + + +\membersection{wxDEPRECATED\_BUT\_USED\_INTERNALLY}\label{wxdeprecatedbutusedinternally} + +This is a special version of \helpref{wxDEPRECATED}{wxdeprecated} macro which +only does something when the deprecated function is used from the code outside +wxWidgets itself but doesn't generate warnings when it is used from wxWidgets. +It is used with the virtual functions which are called by the library itself -- +even if such function is deprecated the library still has to call it to ensure +that the existing code overriding it continues to work, but the use of this +macro ensures that a deprecation warning will be generated if this function is +used from the user code or, in case of Visual C++, even when it is simply +overridden. + + +\membersection{wxDEPRECATED\_INLINE}\label{wxdeprecatedinline} + +\func{}{wxDEPRECATED\_INLINE}{\param{}{func}, \param{}{body}} + +This macro is similar to \helpref{wxDEPRECATED}{wxdeprecated} but can be used +to not only declare the function \arg{func} as deprecated but to also provide +its (inline) implementation \arg{body}. + +It can be used as following: +\begin{verbatim} + class wxFoo + { + public: + // OldMethod() is deprecated, use NewMethod() instead + void NewMethod(); + wxDEPRECATED_INLINE( void OldMethod(), NewMethod() ); + }; +\end{verbatim} + +\membersection{wxEXPLICIT}\label{wxexplicit} + +{\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if +the compiler supports it or nothing otherwise. Thus, it can be used even in the +code which might have to be compiled with an old compiler without support for +this language feature but still take advantage of it when it is available. + + + +\membersection{::wxGetKeyState}\label{wxgetkeystate} + +\func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}} + +For normal keys, returns \true if the specified key is currently down. + +For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns +\true if the key is toggled such that its LED indicator is lit. There is +currently no way to test whether togglable keys are up or down. + +Even though there are virtual key codes defined for mouse buttons, they +cannot be used with this function currently. + +\wxheading{Include files} + + + + +\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} + +This function is deprecated as the ids generated by it can conflict with the +ids defined by the user code, use \texttt{wxID\_ANY} to assign ids which are +guaranteed to not conflict with the user-defined ids for the controls and menu +items you create instead of using this function. + + +Generates an integer identifier unique to this run of the program. + +\wxheading{Include files} + + + + +\membersection{wxON\_BLOCK\_EXIT}\label{wxonblockexit} + +\func{}{wxON\_BLOCK\_EXIT0}{\param{}{func}} + +\func{}{wxON\_BLOCK\_EXIT1}{\param{}{func}, \param{}{p1}} + +\func{}{wxON\_BLOCK\_EXIT2}{\param{}{func}, \param{}{p1}, \param{}{p2}} + +This family of macros allows to ensure that the global function \arg{func} +with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is +executed on scope exit, whether due to a normal function return or because an +exception has been thrown. A typical example of its usage: +\begin{verbatim} + void *buf = malloc(size); + wxON_BLOCK_EXIT1(free, buf); +\end{verbatim} + +Please see the original article by Andrei Alexandrescu and Petru Marginean +published in December 2000 issue of \emph{C/C++ Users Journal} for more +details. + +\wxheading{Include files} + + + +\wxheading{See also} + +\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj} + + +\membersection{wxON\_BLOCK\_EXIT\_OBJ}\label{wxonblockexitobj} + +\func{}{wxON\_BLOCK\_EXIT\_OBJ0}{\param{}{obj}, \param{}{method}} + +\func{}{wxON\_BLOCK\_EXIT\_OBJ1}{\param{}{obj}, \param{}{method}, \param{}{p1}} + +\func{}{wxON\_BLOCK\_EXIT\_OBJ2}{\param{}{obj}, \param{}{method}, \param{}{p1}, \param{}{p2}} + +This family of macros is similar to \helpref{wxON\_BLOCK\_EXIT}{wxonblockexit} +but calls a method of the given object instead of a free function. + +\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 wxWidgets exits, to clean up the DDE system. This no longer needs to be +called by the application. + +See also \helpref{wxDDEInitialize}{wxddeinitialize}. + +\wxheading{Include files} + + + + +\membersection{::wxDDEInitialize}\label{wxddeinitialize} + +\func{void}{wxDDEInitialize}{\void} + +Initializes the DDE system. May be called multiple times without harm. + +This no longer needs to be called by the application: it will be called +by wxWidgets if necessary. + +See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},\rtfsp +\helpref{wxDDECleanUp}{wxddecleanup}. + +\wxheading{Include files} + + + + +\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows} + +\func{void}{wxEnableTopLevelWindows}{\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{wxFromString}\label{wxfromstring} + +\func{bool}{wxFromString}{\param{const wxString\& }{str}, + \param{wxColour* }{col}} + +\func{bool}{wxFromString}{\param{const wxString\& }{str}, + \param{wxFont* }{col}} + +Converts string to the type of the second argument. Returns \true on success. +See also: \helpref{wxToString}{wxtostring}. + + +\membersection{::wxGetActiveWindow}\label{wxgetactivewindow} + +\func{wxWindow *}{wxGetActiveWindow}{\void} + +Gets the currently active window (implemented for MSW and GTK only currently, +always returns \NULL in the other ports). + +\wxheading{Include files} + + + + +\membersection{::wxGetBatteryState}\label{wxgetbatterystate} + +\func{wxBatteryState}{wxGetBatteryState}{\void} + +Returns battery state as one of \texttt{wxBATTERY\_NORMAL\_STATE}, +\texttt{wxBATTERY\_LOW\_STATE}, \texttt{wxBATTERY\_CRITICAL\_STATE}, +\texttt{wxBATTERY\_SHUTDOWN\_STATE} or \texttt{wxBATTERY\_UNKNOWN\_STATE}. +\texttt{wxBATTERY\_UNKNOWN\_STATE} is also the default on platforms where +this feature is not implemented (currently everywhere but MS Windows). + +\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{::wxGetPowerType}\label{wxgetpowertype} + +\func{wxPowerType}{wxGetPowerType}{\void} + +Returns the type of power source as one of \texttt{wxPOWER\_SOCKET}, +\texttt{wxPOWER\_BATTERY} or \texttt{wxPOWER\_UNKNOWN}. +\texttt{wxPOWER\_UNKNOWN} is also the default on platforms where this +feature is not implemented (currently everywhere but MS Windows). + +\wxheading{Include files} + + + + +\membersection{::wxGetMousePosition}\label{wxgetmouseposition} + +\func{wxPoint}{wxGetMousePosition}{\void} + +Returns the mouse position in screen coordinates. + +\wxheading{Include files} + + + + +\membersection{::wxGetMouseState}\label{wxgetmousestate} + +\func{wxMouseState}{wxGetMouseState}{\void} + +Returns the current state of the mouse. Returns a wxMouseState +instance that contains the current position of the mouse pointer in +screen coordinates, as well as boolean values indicating the up/down +status of the mouse buttons and the modifier keys. + +\wxheading{Include files} + + + +wxMouseState has the following interface: + +\begin{verbatim} +class wxMouseState +{ +public: + wxMouseState(); + + wxCoord GetX(); + wxCoord GetY(); + + bool LeftDown(); + bool MiddleDown(); + bool RightDown(); + + bool ControlDown(); + bool ShiftDown(); + bool AltDown(); + bool MetaDown(); + bool CmdDown(); + + void SetX(wxCoord x); + void SetY(wxCoord y); + + void SetLeftDown(bool down); + void SetMiddleDown(bool down); + void SetRightDown(bool down); + + void SetControlDown(bool down); + void SetShiftDown(bool down); + void SetAltDown(bool down); + void SetMetaDown(bool down); +}; +\end{verbatim} + + + +\membersection{::wxGetStockLabel}\label{wxgetstocklabel} + +\func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{const wxString\& }{accelerator = wxEmptyString}} + +Returns label that should be used for given {\it id} element. + +\wxheading{Parameters} + +\docparam{id}{given id of the \helpref{wxMenuItem}{wxmenuitem}, \helpref{wxButton}{wxbutton}, \helpref{wxToolBar}{wxtoolbar} tool, etc.} + +\docparam{withCodes}{if false then strip accelerator code from the label; +useful for getting labels without accelerator char code like for toolbar tooltip or +on platforms without traditional keyboard like smartphones} + +\docparam{accelerator}{optional accelerator string automatically added to label; useful +for building labels for \helpref{wxMenuItem}{wxmenuitem}} + +\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{::wxLaunchDefaultBrowser}\label{wxlaunchdefaultbrowser} + +\func{bool}{wxLaunchDefaultBrowser}{\param{const wxString\& }{url}, \param{int }{flags = $0$}} + +Open the \arg{url} in user's default browser. If \arg{flags} parameter contains +\texttt{wxBROWSER\_NEW\_WINDOW} flag, a new window is opened for the URL +(currently this is only supported under Windows). The \arg{url} may also be a +local file path (with or without \texttt{file://} prefix), if it doesn't +correspond to an existing file and the URL has no scheme \texttt{http://} is +prepended to it by default. + +Returns \true if the application was successfully launched. + +Note that for some configurations of the running user, the application which +is launched to open the given URL may be URL-dependent (e.g. a browser may be used for +local URLs while another one may be used for remote URLs). + +\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\& }{str}, \param{int }{flags = wxStrip\_All}} + +Strips any menu codes from \arg{str} and returns the result. + +By default, the functions strips both the mnemonics character (\texttt{'\&'}) +which is used to indicate a keyboard shortkey, and the accelerators, which are +used only in the menu items and are separated from the main text by the +\texttt{$\backslash$t} (TAB) character. By using \arg{flags} of +\texttt{wxStrip\_Mnemonics} or \texttt{wxStrip\_Accel} to strip only the former +or the latter part, respectively. + +Notice that in most cases +\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} or +\helpref{wxControl::GetLabelText}{wxcontrolgetlabeltext} can be used instead. + +\wxheading{Include files} + + + + +\membersection{wxSTRINGIZE}\label{wxstringize} + +\func{}{wxSTRINGIZE}{\param{}{x}} + +Returns the string representation of the given symbol which can be either a +literal or a macro (hence the advantage of using this macro instead of the +standard preprocessor \texttt{\#} operator which doesn't work with macros). + +Notice that this macro always produces a \texttt{char} string, use +\helpref{wxSTRINGIZE\_T}{wxstringizet} to build a wide string Unicode build. + +\wxheading{See also} + +\helpref{wxCONCAT}{wxconcat} + + +\membersection{wxSTRINGIZE\_T}\label{wxstringizet} + +\func{}{wxSTRINGIZE\_T}{\param{}{x}} + +Returns the string representation of the given symbol as either an ASCII or +Unicode string, depending on the current build. This is the Unicode-friendly +equivalent of \helpref{wxSTRINGIZE}{wxstringize}. + + +\membersection{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}\label{wxsuppressgccprivatedtorwarning} + +\func{}{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{\param{}{name}} + +GNU C++ compiler gives a warning for any class whose destructor is private +unless it has a friend. This warning may sometimes be useful but it doesn't +make sense for reference counted class which always delete themselves (hence +destructor should be private) but don't necessarily have any friends, so this +macro is provided to disable the warning in such case. The \arg{name} parameter +should be the name of the class but is only used to construct a unique friend +class name internally. Example of using the macro: + +\begin{verbatim} + class RefCounted + { + public: + RefCounted() { m_nRef = 1; } + void IncRef() { m_nRef++ ; } + void DecRef() { if ( !--m_nRef ) delete this; } + + private: + ~RefCounted() { } + + wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted) + }; +\end{verbatim} + +Notice that there should be no semicolon after this macro. + + +\membersection{wxToString}\label{wxtostring} + +\func{wxString}{wxToString}{\param{const wxColour\& }{col}} + +\func{wxString}{wxToString}{\param{const wxFont\& }{col}} + +Converts its argument to string. +See also: \helpref{wxFromString}{wxfromstring}. + + +\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{wxVaCopy}\label{wxvacopy} + +\func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{ argptrSrc}} + +This macro is the same as the standard C99 \texttt{va\_copy} for the compilers +which support it or its replacement for those that don't. It must be used to +preserve the value of a \texttt{va\_list} object if you need to use it after +passing it to another function because it can be modified by the latter. + +As with \texttt{va\_start}, each call to \texttt{wxVaCopy} must have a matching +\texttt{va\_end}. + + + +\membersection{\_\_WXFUNCTION\_\_}\label{wxfunction} + +\func{}{\_\_WXFUNCTION\_\_}{\void} + +This macro expands to the name of the current function if the compiler supports +any of \texttt{\_\_FUNCTION\_\_}, \texttt{\_\_func\_\_} or equivalent variables +or macros or to \NULL if none of them is available. + + + +\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. + + +\membersection{wxFORCE\_LINK\_THIS\_MODULE}\label{wxforcelinkthismodule} + +\func{}{wxFORCE\_LINK\_THIS\_MODULE}{moduleName} + +This macro can be used in conjunction with the +\helpref{wxFORCE\_LINK\_MODULE}{wxforcelinkmodule} macro to force +the linker to include in its output a specific object file. + +In particular, you should use this macro in the source file which you want +to force for inclusion. The \tt{moduleName} needs to be a name not already +in use in other \tt{wxFORCE\_LINK\_THIS\_MODULE} macros, but is not required +to be e.g. the same name of the source file (even if it's a good choice). + +\wxheading{Include files} + + + + +\membersection{wxFORCE\_LINK\_MODULE}\label{wxforcelinkmodule} + +\func{}{wxFORCE\_LINK\_MODULE}{moduleName} + +This macro can be used in conjunction with the +\helpref{wxFORCE\_LINK\_THIS\_MODULE}{wxforcelinkthismodule} macro to force +the linker to include in its output a specific object file. + +In particular, you should use this macro in a source file which you know +for sure is linked in the output (e.g. the source file containing the "main()" +of your app). The \tt{moduleName} is the name of the module you want to forcefully link +(i.e. the name you used in the relative \helpref{wxFORCE\_LINK\_THIS\_MODULE}{wxforcelinkthismodule} macro. + +\wxheading{Include files} + + + + +\membersection{wxIMPLEMENT\_APP}\label{wximplementapp} + +\func{}{wxIMPLEMENT\_APP}{className} + +This is used in the application class implementation file to make the application class +known to wxWidgets for dynamic construction. You use this as: + +\begin{verbatim} + wxIMPLEMENT_APP(MyApp) +\end{verbatim} + +See also \helpref{wxDECLARE\_APP}{wxdeclareapp}. + +\wxheading{Include files} + + + + +\section{RTTI functions}\label{rttimacros} + +wxWidgets uses its own RTTI ("run-time type identification") system which +predates the current standard C++ RTTI and so is kept for backwards +compatibility reasons but also because it allows some things which the +standard RTTI doesn't directly support (such as creating a class from its +name). + +The standard C++ RTTI can be used in the user code without any problems and in +general you shouldn't need to use the functions and the macros in this section +unless you are thinking of modifying or adding any wxWidgets classes. + +\wxheading{See also} + +\helpref{RTTI overview}{runtimeclassoverview} + + +\membersection{CLASSINFO}\label{classinfo} + +\func{wxClassInfo *}{CLASSINFO}{className} + +Returns a pointer to the wxClassInfo object associated with this class. + +\wxheading{Include files} + + + + +\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 make the class known to wxWidgets RTTI +system and also declare that the objects of this class should be dynamically +creatable from run-time type information. Notice that this implies that the +class should have a default constructor, if this is not the case consider using +\helpref{DECLARE\_CLASS}{declareclass}. + +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 +wxWidgets for dynamic construction. You use this instead of + +Old form: + +\begin{verbatim} + MyApp myApp; +\end{verbatim} + +New form: + +\begin{verbatim} + IMPLEMENT_APP(MyApp) +\end{verbatim} + +See also \helpref{DECLARE\_APP}{declareapp}. + +\wxheading{Include files} + + + + +\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} -If callback isn't NULL and if execution is asynchronous (note that callback -parameter can not be non NULL for synchronous execution), -\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when -the process finishes. +\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2} -See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}. +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{::wxExit}\label{wxexit} + -\func{void}{wxExit}{\void} -Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}. -Should only be used in an emergency: normally the top-level frame -should be deleted (after deleting all other frames) to terminate the -application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}. +\membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass} -\wxheading{Include files} +\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. -\membersection{::wxFatalError}\label{wxfatalerror} +Example: -\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}} +\begin{verbatim} +IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) -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}. +wxFrame::wxFrame(void) +{ +... +} +\end{verbatim} \wxheading{Include files} - + -\membersection{::wxFindMenuItemId} -\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}} +\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2} -Find a menu item identifier associated with the given frame's menu bar. +\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{::wxFindWindowByLabel} -\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}} +\membersection{wxConstCast}\label{wxconstcast} -Find a window by its label. Depending on the type of window, the label may be a window title -or panel item label. If {\it parent} is NULL, the search will start from all top-level -frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. -The search is recursive in both cases. +\func{classname *}{wxConstCast}{ptr, classname} -\wxheading{Include files} +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} -\membersection{::wxFindWindowByName}\label{wxfindwindowbyname} +\helpref{wx\_const\_cast}{wxconstcastraw}\\ +\helpref{wxDynamicCast}{wxdynamiccast}\\ +\helpref{wxStaticCast}{wxstaticcast} -\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}} -Find a window by its name (as given in a window constructor or {\bf Create} function call). -If {\it parent} is NULL, the search will start from all top-level -frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. -The search is recursive in both cases. +\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject} -If no such named window is found, {\bf wxFindWindowByLabel} is called. +\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}} -\wxheading{Include files} +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{::wxGetActiveWindow}\label{wxgetactivewindow} +\membersection{WXDEBUG\_NEW}\label{debugnew} -\func{wxWindow *}{wxGetActiveWindow}{\void} +\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} -Gets the currently active window (Windows only). +In non-debug mode, this is defined as the normal new operator. \wxheading{Include files} - + -\membersection{::wxGetDisplayName}\label{wxgetdisplayname} -\func{wxString}{wxGetDisplayName}{\void} +\membersection{wxDynamicCast}\label{wxdynamiccast} -Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}. +\func{classname *}{wxDynamicCast}{ptr, classname} -\wxheading{Include files} +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. -\membersection{::wxGetHomeDir} +Example: -\func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}} +\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} -Fills the buffer with a string representing the user's home directory (Unix only). +\wxheading{See also} -\wxheading{Include files} +\helpref{RTTI overview}{runtimeclassoverview}\\ +\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\ +\helpref{wxConstCast}{wxconstcast}\\ +\helpref{wxStaticCast}{wxstaticcast} - -\membersection{::wxGetHostName} +\membersection{wxDynamicCastThis}\label{wxdynamiccastthis} -\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} +\func{classname *}{wxDynamicCastThis}{classname} -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''. +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{Include files} +\wxheading{See also} - +\helpref{wxDynamicCast}{wxdynamiccast} -\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime} -\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}} +\membersection{wxStaticCast}\label{wxstaticcast} -Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}. +\func{classname *}{wxStaticCast}{ptr, classname} -If {\it resetTimer} is TRUE (the default), the timer is reset to zero -by this call. +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)}. -See also \helpref{wxTimer}{wxtimer}. +\wxheading{See also} -\wxheading{Include files} +\helpref{wx\_static\_cast}{wxstaticcastraw}\\ +\helpref{wxDynamicCast}{wxdynamiccast}\\ +\helpref{wxConstCast}{wxconstcast} - -\membersection{::wxGetFreeMemory}\label{wxgetfreememory} +\membersection{wx\_const\_cast}\label{wxconstcastraw} -\func{long}{wxGetFreeMemory}{\void} +\func{T}{wx\_const\_cast}{T, x} -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. +Same as \texttt{const\_cast(x)} if the compiler supports const cast or +\texttt{(T)x} for old compilers. Unlike \helpref{wxConstCast}{wxconstcast}, +the cast it to the type \arg{T} and not to \texttt{T *} and also the order of +arguments is the same as for the standard cast. -\wxheading{Include files} +\wxheading{See also} - +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ +\helpref{wx\_static\_cast}{wxstaticcastraw} -\membersection{::wxGetMousePosition} -\func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}} +\membersection{wx\_reinterpret\_cast}\label{wxreinterpretcastraw} -Returns the mouse position in screen coordinates. +\func{T}{wx\_reinterpret\_cast}{T, x} -\wxheading{Include files} +Same as \texttt{reinterpret\_cast(x)} if the compiler supports reinterpret cast or +\texttt{(T)x} for old compilers. - +\wxheading{See also} -\membersection{::wxGetOsVersion} +\helpref{wx\_const\_cast}{wxconstcastraw},\\ +\helpref{wx\_static\_cast}{wxstaticcastraw} -\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} -Gets operating system version information. +\membersection{wx\_static\_cast}\label{wxstaticcastraw} -\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} +\func{T}{wx\_static\_cast}{T, x} -\wxheading{Include files} +Same as \texttt{static\_cast(x)} if the compiler supports static cast or +\texttt{(T)x} for old compilers. Unlike \helpref{wxStaticCast}{wxstaticcast}, +there are no checks being done and the meaning of the macro arguments is exactly +the same as for the standard static cast, i.e. \arg{T} is the full type name and +star is not appended to it. - +\wxheading{See also} -\membersection{::wxGetResource}\label{wxgetresource} +\helpref{wx\_const\_cast}{wxconstcastraw},\\ +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ +\helpref{wx\_truncate\_cast}{wxtruncatecast} -\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}} +\membersection{wx\_truncate\_cast}\label{wxtruncatecast} -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{long *}{value}, \param{const wxString\& }{file = NULL}} +\func{T}{wx\_truncate\_cast}{T, x} -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{int *}{value}, \param{const wxString\& }{file = NULL}} +This case doesn't correspond to any standard cast but exists solely to make +casts which possibly result in a truncation of an integer value more readable. -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. +\wxheading{See also} -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. +\helpref{wx\_static\_cast}{wxstaticcastraw} -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}. +\section{Log functions}\label{logfunctions} -\wxheading{Include files} +These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for +further information. The functions use (implicitly) the currently active log +target, so their descriptions here may not apply if the log target is not the +standard one (installed by wxWidgets in the beginning of the program). - +\wxheading{Include files} -\membersection{::wxGetUserId} + -\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} -Copies the user's login identity (such as ``jacs'') into the buffer {\it -buf}, of maximum size {\it bufSize}, returning TRUE if successful. -Under Windows, this returns ``user''. +\membersection{::wxDebugMsg}\label{wxdebugmsg} -\wxheading{Include files} +\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. -\membersection{::wxGetUserName} +Display a debugging message; under Windows, this will appear on the +debugger command window, and under Unix, it will be written to standard +error. -\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} +The syntax is identical to {\bf printf}: pass a format string and a +variable list of arguments. -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 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{::wxKill}\label{wxkill} -\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}} +\membersection{::wxError}\label{wxerror} + +\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Internal Error"}} -Under Unix (the only supported platform), equivalent to the Unix kill function. -Returns 0 on success, -1 on failure. +{\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror} +instead. -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. +Displays {\it msg} and continues. This writes to standard error under +Unix, and pops up a message box under Windows. Used for internal +wxWidgets errors. See also \helpref{wxFatalError}{wxfatalerror}. \wxheading{Include files} -\membersection{::wxIsBusy}\label{wxisbusy} -\func{bool}{wxIsBusy}{\void} +\membersection{::wxFatalError}\label{wxfatalerror} -Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp -\helpref{wxEndBusyCursor}{wxendbusycursor} calls. +\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Fatal Error"}} -See also \helpref{wxBusyCursor}{wxbusycursor}. +{\bf NB:} This function is now obsolete, please use +\helpref{wxLogFatalError}{wxlogfatalerror} instead. + +Displays {\it msg} and exits. This writes to standard error under Unix, +and pops up a message box under Windows. Used for fatal internal +wxWidgets errors. See also \helpref{wxError}{wxerror}. \wxheading{Include files} -\membersection{::wxLoadUserResource}\label{wxloaduserresource} -\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} +\membersection{::wxLogError}\label{wxlogerror} -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{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}} -The resource must be defined in the {\tt .rc} file using the following syntax: +\func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -\begin{verbatim} -myResource TEXT file.ext -\end{verbatim} +The functions to use for error messages, i.e. the messages that must be shown +to the user. The default processing is to pop up a message box to inform the +user about it. -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{::wxLogFatalError}\label{wxlogfatalerror} -This function is available under Windows only. +\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}} -\wxheading{Include files} +\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{::wxNow}\label{wxnow} -\func{wxString}{wxNow}{\void} +\membersection{::wxLogWarning}\label{wxlogwarning} -Returns a string representing the current date and time. +\func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}} -\wxheading{Include files} +\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{::wxPostDelete}\label{wxpostdelete} -\func{void}{wxPostDelete}{\param{wxObject *}{object}} +\membersection{::wxLogMessage}\label{wxlogmessage} -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{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}} -Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead. +\func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -\wxheading{Include files} +For all normal, informational messages. They also appear in a message box by +default (but it can be changed). - +\membersection{::wxLogVerbose}\label{wxlogverbose} -\membersection{::wxSetDisplayName}\label{wxsetdisplayname} +\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}} -\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}} +\func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -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. +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}). -See also \helpref{wxGetDisplayName}{wxgetdisplayname}. -\wxheading{Include files} +\membersection{::wxLogStatus}\label{wxlogstatus} - +\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}} -\membersection{::wxShell}\label{wxshell} +\func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} -\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} +\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}} -Executes a command in an interactive shell window. If no command is -specified, then just the shell is spawned. +\func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -See also \helpref{wxExecute}{wxexecute}. +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). -\wxheading{Include files} +If the target frame doesn't have a statusbar, the message will be lost. - -\membersection{::wxSleep}\label{wxsleep} +\membersection{::wxLogSysError}\label{wxlogsyserror} -\func{void}{wxSleep}{\param{int}{ secs}} +\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}} -Sleeps for the specified number of seconds. +\func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -\wxheading{Include files} +Mostly used by wxWidgets itself, but might be handy for logging errors after +system call (API function) failure. It logs the specified message text as well +as the last system error code ({\it errno} or {\it ::GetLastError()} depending +on the platform) and the corresponding error message. The second form +of this function takes the error code explicitly as the first argument. - +\wxheading{See also} -\membersection{::wxStripMenuCodes} +\helpref{wxSysErrorCode}{wxsyserrorcode}, +\helpref{wxSysErrorMsg}{wxsyserrormsg} -\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}} -\func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}} +\membersection{::wxLogDebug}\label{wxlogdebug} -Strips any menu codes from {\it in} and places the result -in {\it out} (or returns the new string, in the first form). +\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}} -Menu codes include \& (mark the next character with an underline -as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows). +\func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -\wxheading{Include files} +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{::wxStartTimer}\label{wxstarttimer} +\membersection{::wxLogTrace}\label{wxlogtrace} -\func{void}{wxStartTimer}{\void} +\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}} -Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time. +\func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -See also \helpref{wxTimer}{wxtimer}. +\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}} -\wxheading{Include files} +\func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} - +\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}} -\membersection{::wxToLower}\label{wxtolower} +\func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} -\func{char}{wxToLower}{\param{char }{ch}} +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. -Converts the character to lower case. This is implemented as a macro for efficiency. +The trace messages also usually can be separated into different categories and +the second and third versions of this function only log the message if the +{\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This +allows to selectively trace only some operations and not others by changing +the value of the trace mask (possible during the run-time). -\wxheading{Include files} +For the second function (taking a string mask), the message is logged only if +the mask has been previously enabled by the call to +\helpref{AddTraceMask}{wxlogaddtracemask} or by setting +\helpref{{\tt WXTRACE} environment variable}{envvars}. +The predefined string trace masks +used by wxWidgets are: - +\begin{itemize}\itemsep=0pt +\item wxTRACE\_MemAlloc: trace memory allocation (new/delete) +\item wxTRACE\_Messages: trace window messages/X callbacks +\item wxTRACE\_ResAlloc: trace GDI resource allocation +\item wxTRACE\_RefCount: trace various ref counting operations +\item wxTRACE\_OleCalls: trace OLE method calls (Win32 only) +\end{itemize} -\membersection{::wxToUpper}\label{wxtoupper} +{\bf Caveats:} since both the mask and the format string are strings, +this might lead to function signature confusion in some cases: +if you intend to call the format string only version of wxLogTrace, +then add a \%s format string parameter and then supply a second string parameter for that \%s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function. +In this case you'll unfortunately have to avoid having two leading +string parameters, e.g. by adding a bogus integer (with its \%d format string). -\func{char}{wxToUpper}{\param{char }{ch}} +The third version of the function only logs the message if all the bits +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. -Converts the character to upper case. This is implemented as a macro for efficiency. +\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} -\wxheading{Include files} - +\membersection{::wxSafeShowMessage}\label{wxsafeshowmessage} -\membersection{::wxTrace}\label{wxtrace} +\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}} -\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} +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. -Takes printf-style variable argument syntax. Output -is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +\wxheading{Parameters} -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +\docparam{title}{The title of the message box shown to the user or the prefix +of the message string} -\wxheading{Include files} +\docparam{text}{The text to show to the user} - +\wxheading{See also} -\membersection{::wxTraceLevel}\label{wxtracelevel} +\helpref{wxLogFatalError}{wxlogfatalerror} -\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} +\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. + -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -\wxheading{Include files} +\membersection{::wxSysErrorCode}\label{wxsyserrorcode} - +\func{unsigned long}{wxSysErrorCode}{\void} -\membersection{::wxWriteResource}\label{wxwriteresource} +Returns the error code from the last system call. This function uses +{\tt errno} on Unix platforms and {\tt GetLastError} under Win32. -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}} +\wxheading{See also} -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{float }{value}, \param{const wxString\& }{file = NULL}} +\helpref{wxSysErrorMsg}{wxsyserrormsg}, +\helpref{wxLogSysError}{wxlogsyserror} -\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}} +\membersection{::wxSysErrorMsg}\label{wxsyserrormsg} -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. +\func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}} -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. +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. -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. +\wxheading{See also} -See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}. +\helpref{wxSysErrorCode}{wxsyserrorcode}, +\helpref{wxLogSysError}{wxlogsyserror} -\wxheading{Include files} - +\membersection{WXTRACE}\label{trace} -\membersection{::wxYield}\label{wxyield} +\wxheading{Include files} -\func{bool}{wxYield}{\void} + + +\func{}{WXTRACE}{formatString, ...} -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. +{\bf NB:} This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -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. +Calls wxTrace with printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). \wxheading{Include files} - + -\section{Macros}\label{macros} -These macros are defined in wxWindows. +\membersection{WXTRACELEVEL}\label{tracelevel} -\membersection{CLASSINFO}\label{classinfo} +\func{}{WXTRACELEVEL}{level, formatString, ...} -\func{wxClassInfo *}{CLASSINFO}{className} +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -Returns a pointer to the wxClassInfo object associated with this class. +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{WXDEBUG\_NEW}\label{debugnew} -\func{}{WXDEBUG\_NEW}{arg} +\membersection{::wxTrace}\label{wxtrace} -This is defined in debug mode to be call the redefined new operator -with filename and line number arguments. The definition is: +\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} -\begin{verbatim} -#define WXDEBUG_NEW new(__FILE__,__LINE__) -\end{verbatim} +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -In non-debug mode, this is defined as the normal new operator. +Takes printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). \wxheading{Include files} - - -\membersection{DECLARE\_ABSTRACT\_CLASS} + -\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. +\membersection{::wxTraceLevel}\label{wxtracelevel} -Example: +\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} -\begin{verbatim} -class wxCommand: public wxObject -{ - DECLARE_ABSTRACT_CLASS(wxCommand) +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. - private: - ... - public: - ... -}; -\end{verbatim} +Takes printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +The first argument should be the level at which this information is appropriate. +It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than +this value. \wxheading{Include files} - + -\membersection{DECLARE\_APP}\label{declareapp} -\func{}{DECLARE\_APP}{className} -This is used in headers to create a forward declaration of the wxGetApp function implemented -by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}. +\section{Time functions}\label{timefunctions} -Example: +The functions in this section deal with getting the current time and sleeping +for the specified time interval. -\begin{verbatim} - DECLARE_APP(MyApp) -\end{verbatim} -\wxheading{Include files} +\membersection{::wxGetLocalTime}\label{wxgetlocaltime} - +\func{long}{wxGetLocalTime}{\void} -\membersection{DECLARE\_CLASS} +Returns the number of seconds since local time 00:00:00 Jan 1st 1970. -\func{}{DECLARE\_CLASS}{className} +\wxheading{See also} -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. +\helpref{wxDateTime::Now}{wxdatetimenow} \wxheading{Include files} - + -\membersection{DECLARE\_DYNAMIC\_CLASS} -\func{}{DECLARE\_DYNAMIC\_CLASS}{className} +\membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis} -Used inside a class declaration to declare that the objects of this class should be dynamically -createable from run-time type information. +\func{wxLongLong}{wxGetLocalTimeMillis}{\void} -Example: +Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. -\begin{verbatim} -class wxFrame: public wxWindow -{ - DECLARE_DYNAMIC_CLASS(wxFrame) +\wxheading{See also} - private: - const wxString\& frameTitle; - public: - ... -}; -\end{verbatim} +\helpref{wxDateTime::Now}{wxdatetimenow},\\ +\helpref{wxLongLong}{wxlonglong} \wxheading{Include files} - + -\membersection{IMPLEMENT\_ABSTRACT\_CLASS} -\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName} +\membersection{::wxGetUTCTime}\label{wxgetutctime} -Used in a C++ implementation file to complete the declaration of -a class that has run-time type information. The same as IMPLEMENT\_CLASS. +\func{long}{wxGetUTCTime}{\void} -Example: +Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. -\begin{verbatim} -IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) +\wxheading{See also} -wxCommand::wxCommand(void) -{ -... -} -\end{verbatim} +\helpref{wxDateTime::Now}{wxdatetimenow} \wxheading{Include files} - + -\membersection{IMPLEMENT\_ABSTRACT\_CLASS2} -\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2} +\membersection{::wxMicroSleep}\label{wxmicrosleep} -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. +\func{void}{wxMicroSleep}{\param{unsigned long}{ microseconds}} + +Sleeps for the specified number of microseconds. The microsecond resolution may +not, in fact, be available on all platforms (currently only Unix platforms with +nanosleep(2) may provide it) in which case this is the same as +\helpref{wxMilliSleep}{wxmillisleep}(\arg{microseconds}$/1000$). \wxheading{Include files} - + -\membersection{IMPLEMENT\_APP}\label{implementapp} -\func{}{IMPLEMENT\_APP}{className} +\membersection{::wxMilliSleep}\label{wxmillisleep} -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{void}{wxMilliSleep}{\param{unsigned long}{ milliseconds}} -Old form: +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. -\begin{verbatim} - MyApp myApp; -\end{verbatim} +\wxheading{Include files} -New form: + -\begin{verbatim} - IMPLEMENT_APP(MyApp) -\end{verbatim} -See also \helpref{DECLARE\_APP}{declareapp}. +\membersection{::wxNow}\label{wxnow} -\wxheading{Include files} +\func{wxString}{wxNow}{\void} - +Returns a string representing the current date and time. -\membersection{IMPLEMENT\_CLASS} +\wxheading{Include files} -\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{::wxSleep}\label{wxsleep} - +\func{void}{wxSleep}{\param{int}{ secs}} -\membersection{IMPLEMENT\_CLASS2} +Sleeps for the specified number of seconds. -\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2} +\wxheading{Include files} -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{::wxUsleep}\label{wxusleep} -\membersection{IMPLEMENT\_DYNAMIC\_CLASS} +\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}} -\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName} +This function is deprecated because its name is misleading: notice that the +argument is in milliseconds, not microseconds. Please use either +\helpref{wxMilliSleep}{wxmillisleep} or \helpref{wxMicroSleep}{wxmicrosleep} +depending on the resolution you need. -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) +\section{Debugging macros and functions}\label{debugmacros} -wxFrame::wxFrame(void) -{ -... -} -\end{verbatim} +Useful macros and functions for error checking and defensive programming. +wxWidgets defines three families of the assert-like macros: +the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined +(in other words, in the debug build) but disappear completely in the release +build. On the other hand, the wxCHECK macros stay event in release builds but a +check failure doesn't generate any user-visible effects then. Finally, the +compile time assertions don't happen during the run-time but result in the +compilation error messages if the condition they check fail. \wxheading{Include files} - + -\membersection{IMPLEMENT\_DYNAMIC\_CLASS2} -\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2} +\membersection{::wxOnAssert}\label{wxonassert} -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}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{func}, \param{const char *}{cond}, \param{const char *}{msg = NULL}} -\wxheading{Include files} +This function is called whenever one of debugging macros fails (i.e. condition +is false in an assertion). It is only defined in the debug mode, in release +builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything. - +To override the default behaviour in the debug builds which is to show the user +a dialog asking whether he wants to abort the program, continue or continue +ignoring any subsequent assert failures, you may override +\helpref{wxApp::OnAssertFailure}{wxapponassertfailure} which is called by this function if +the global application object exists. -\membersection{WXTRACE}\label{trace} -\func{}{WXTRACE}{formatString, ...} +\membersection{wxASSERT}\label{wxassert} -Calls wxTrace with printf-style variable argument syntax. Output -is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +\func{}{wxASSERT}{\param{}{condition}} -This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +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. -\wxheading{Include files} +Please note that the condition in wxASSERT() should have no side effects +because it will not be executed in release mode at all. - +\wxheading{See also} -\membersection{WXTRACELEVEL}\label{tracelevel} +\helpref{wxASSERT\_MSG}{wxassertmsg},\\ +\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} -\func{}{WXTRACELEVEL}{level, formatString, ...} -Calls wxTraceLevel with printf-style variable argument syntax. Output -is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). -The first argument should be the level at which this information is appropriate. -It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than -this value. +\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize} -This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. +\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}} -\wxheading{Include files} +This macro results in a +\helpref{compile time assertion failure}{wxcompiletimeassert} if the size +of the given type {\it type} is less than {\it size} bits. - +You may use it like this, for example: -\section{wxWindows resource functions}\label{resourcefuncs} +\begin{verbatim} + // we rely on the int being able to hold values up to 2^32 + wxASSERT_MIN_BITSIZE(int, 32); -\overview{wxWindows resource system}{resourceformats} + // can't work with the platforms using UTF-8 for wchar_t + wxASSERT_MIN_BITSIZE(wchar_t, 16); +\end{verbatim} -This section details functions for manipulating wxWindows (.WXR) resource -files and loading user interface elements from resources. -\normalbox{Please note that this use of the word `resource' is different from that used when talking -about initialisation file resource reading and writing, using such functions -as wxWriteResource and wxGetResource. It's just an unfortunate clash of terminology.} +\membersection{wxASSERT\_MSG}\label{wxassertmsg} -\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.} +\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} -See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for -loading from resource data. +Assert macro with message. An error message will be generated if the condition is false. -{\bf Warning:} this needs updating for wxWindows 2. +\wxheading{See also} -\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier} +\helpref{wxASSERT}{wxassert},\\ +\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} -\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}} -Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp -\verb$#$defining a name to an integer). Unlikely to be used by an application except -perhaps for implementing resource functionality for interpreted languages. +\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert} -\membersection{::wxResourceClear} +\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}} -\func{void}{wxResourceClear}{\void} +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. -Clears the wxWindows resource table. +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. -\membersection{::wxResourceCreateBitmap} +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. -\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}} +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. -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{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize} -then this function can be called as follows: -\begin{verbatim} - wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource"); -\end{verbatim} +\membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2} -\membersection{::wxResourceCreateIcon} +\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}} -\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}} +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}. -Creates a new icon from a file, static data, or Windows resource, given a valid -wxWindows icon resource identifier. For example, if the .WXR file contains -the following: -\begin{verbatim} -static const wxString\& aiai_resource = "icon(name = 'aiai_resource',\ - icon = ['aiai', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\ - icon = ['aiai', wxBITMAP_TYPE_XBM_DATA, 'X'])."; -\end{verbatim} +\membersection{wxFAIL}\label{wxfail} -then this function can be called as follows: +\func{}{wxFAIL}{\void} -\begin{verbatim} - wxIcon *icon = wxResourceCreateIcon("aiai_resource"); -\end{verbatim} +Will always generate an assert error if this code is reached (in debug mode). -\membersection{::wxResourceCreateMenuBar} +See also: \helpref{wxFAIL\_MSG}{wxfailmsg} -\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}} -Creates a new menu bar given a valid wxWindows menubar resource -identifier. For example, if the .WXR file contains the following: +\membersection{wxFAIL\_MSG}\label{wxfailmsg} -\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} +\func{}{wxFAIL\_MSG}{\param{}{msg}} -then this function can be called as follows: +Will always generate an assert error with specified message if this code is reached (in debug mode). -\begin{verbatim} - wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11"); -\end{verbatim} +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. +\wxheading{See also} -\membersection{::wxResourceGetIdentifier} +\helpref{wxFAIL}{wxfail} -\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}} -Used for retrieving the integer value associated with an identifier. -A zero value indicates that the identifier was not found. +\membersection{wxCHECK}\label{wxcheck} -See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}. +\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} -\membersection{::wxResourceParseData}\label{wxresourcedata} +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. -\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} -Parses a string containing one or more wxWindows resource objects. If -the resource objects are global static data that are included into the -C++ program, then this function must be called for each variable -containing the resource data, to make it known to wxWindows. +\membersection{wxCHECK\_MSG}\label{wxcheckmsg} -{\it resource} should contain data in the following form: +\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}} -\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} +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. -This function will typically be used after including a {\tt .wxr} file into -a C++ program as follows: +This macro may be only used in non-void functions, see also +\helpref{wxCHECK\_RET}{wxcheckret}. -\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{wxCHECK\_RET}\label{wxcheckret} -\membersection{::wxResourceParseFile} +\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}} -\func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}} +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. -Parses a file containing one or more wxWindows resource objects -in C++-compatible syntax. Use this function to dynamically load -wxWindows resource data. +This macro should be used in void functions instead of +\helpref{wxCHECK\_MSG}{wxcheckmsg}. -\membersection{::wxResourceParseString}\label{wxresourceparsestring} -\func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} +\membersection{wxCHECK2}\label{wxcheck2} -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. +\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}} -{\it resource} should contain data with the following form: +Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute +{\it operation} if it is not. This is a generalisation of +\helpref{wxCHECK}{wxcheck} and may be used when something else than just +returning from the function must be done when the {\it condition} is false. -\begin{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} +This check is done even in release mode. -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{wxCHECK2\_MSG}\label{wxcheck2msg} -\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width}, -\param{int }{height}, \param{wxResourceTable *}{table = NULL}} +\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}} -\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}} +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. -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{::wxTrap}\label{wxtrap} -Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}. +\func{void}{wxTrap}{\void} -\section{Log functions}\label{logfunctions} +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. -These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for -further information. +In release mode this function does nothing. \wxheading{Include files} - + -\membersection{::wxLogError}\label{wxlogerror} -\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}} -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. +\membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning} -\membersection{::wxLogFatalError}\label{wxlogfatalerror} +\func{bool}{wxIsDebuggerRunning}{\void} -\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}} +Returns \true if the program is running under debugger, \false otherwise. -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. +Please note that this function is currently only implemented for Win32 and Mac +builds using CodeWarrior and always returns \false elsewhere. -\membersection{::wxLogWarning}\label{wxlogwarning} -\func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}} -For warnings - they are also normally shown to the -user, but don't interrupt the program work. -\membersection{::wxLogMessage}\label{wxlogmessage} +\section{Environment access functions}\label{environfunctions} -\func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}} +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). -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. +% TODO add some stuff about env var inheriting but not propagating upwards (VZ) -\membersection{::wxLogVerbose}\label{wxlogverbose} +\wxheading{Include files} -\func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}} + -For verbose output. Normally, it's suppressed, but -might be activated if the user wishes to know more details about the program -progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}). -\membersection{::wxLogStatus}\label{wxlogstatus} +\membersection{wxGetenv}\label{wxgetenvmacro} -\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}} +\func{wxChar *}{wxGetEnv}{\param{const wxString\&}{ var}} -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. +This is a macro defined as {\tt getenv()} or its wide char version in Unicode +mode. -\membersection{::wxLogSysError}\label{wxlogsyserror} +Note that under Win32 it may not return correct value for the variables set +with \helpref{wxSetEnv}{wxsetenv}, use \helpref{wxGetEnv}{wxgetenv} function +instead. -\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{wxGetEnv}\label{wxgetenv} -\membersection{::wxLogDebug}\label{wxlogdebug} +\func{bool}{wxGetEnv}{\param{const wxString\&}{ var}, \param{wxString *}{value}} -\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}} +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. -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 \true if the variable exists, \false otherwise. -\membersection{::wxLogTrace}\label{wxlogtrace} -\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}} +\membersection{wxSetEnv}\label{wxsetenv} -\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char*}{ formatString}, \param{...}{}} +\func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxString\& }{value}} -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: +Sets the value of the environment variable {\it var} (adding it if necessary) +to {\it value}. -\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} +Returns \true on success. -\section{Debugging macros and functions}\label{debugmacros} +\wxheading{See also} -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. +\helpref{wxUnsetEnv}{wxunsetenv} -\wxheading{Include files} - +\membersection{wxUnsetEnv}\label{wxunsetenv} -\membersection{::wxOnAssert}\label{wxonassert} +\func{bool}{wxUnsetEnv}{\param{const wxString\&}{ var}} -\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}} +Removes the variable {\it var} from the environment. +\helpref{wxGetEnv}{wxgetenv} will return {\tt NULL} after the call to this +function. -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. +Returns \true on success. -\membersection{wxASSERT}\label{wxassert} +\wxheading{See also} -\func{}{wxASSERT}{\param{}{condition}} +\helpref{wxSetEnv}{wxsetenv} -Assert macro. An error message will be generated if the condition is FALSE. -\membersection{wxASSERT\_MSG}\label{wxassertmsg} +\section{Atomic operations}\label{atomicoperations} -\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} +When using multi-threaded applications, it is often required to access or +modify memory which is shared between threads. Atomic integer and pointer +operations are an efficient way to handle this issue (another, less efficient, +way is to use a \helpref{mutex}{wxmutex} or \helpref{critical +section}{wxcriticalsection}). A native implementation exists for Windows, +Linux, Solaris and Mac OS X, for other OS, a +\helpref{wxCriticalSection}{wxcriticalsection} is used to protect the data. -Assert macro with message. An error message will be generated if the condition is FALSE. +One particular application is reference counting (used by so-called smart +pointers). -\membersection{wxFAIL}\label{wxfail} +You should define your variable with the type wxAtomicInt in order to apply +atomic operations to it. -\func{}{wxFAIL}{\param{}{condition}} +\wxheading{Include files} -Will always generate an assert error if this code is reached (in debug mode). + -\membersection{wxFAIL\_MSG}\label{wxfailmsg} +\membersection{::wxAtomicInc}\label{wxatomicinc} -\func{}{wxFAIL\_MSG}{\param{}{condition}, \param{}{msg}} +\func{void}{wxAtomicInc}{\param{wxAtomicInt\& }{value}} -Will always generate an assert error with specified message if this code is reached (in debug mode). +This function increments \arg{value} in an atomic manner. -\membersection{wxCHECK}\label{wxcheck} -\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} +\membersection{::wxAtomicDec}\label{wxatomicdec} -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. +\func{wxInt32}{wxAtomicDec}{\param{wxAtomicInt\& }{value}} -\membersection{wxCHECK\_MSG}\label{wxcheckmsg} +This function decrements \arg{value} in an atomic manner. -\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}} +Returns 0 if \arg{value} is 0 after decrementation or any non-zero value (not +necessarily equal to the value of the variable) otherwise. -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.