X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f7bd26981f1c8d46d3909e3de90df081de4df33b..5e51fb4ca59f3094a13d471f3209c922bbd0bc46:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index 15c982dbe2..68aa665cae 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -1,726 +1,3664 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% 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}\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{copystring}{copystring}\\ +\helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\ +\helpref{DECLARE\_APP}{declareapp}\\ +\helpref{DECLARE\_CLASS}{declareclass}\\ +\helpref{DECLARE\_DYNAMIC\_CLASS}{declaredynamicclass}\\ +\helpref{IMPLEMENT\_ABSTRACT\_CLASS2}{implementabstractclass2}\\ +\helpref{IMPLEMENT\_ABSTRACT\_CLASS}{implementabstractclass}\\ +\helpref{IMPLEMENT\_APP}{implementapp}\\ +\helpref{IMPLEMENT\_CLASS2}{implementclass2}\\ +\helpref{IMPLEMENT\_CLASS}{implementclass}\\ +\helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\ +\helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\ +\helpref{wxASSERT}{wxassert}\\ +\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\ +\helpref{wxASSERT\_MSG}{wxassertmsg}\\ +\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\_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{wxDirExists}{functionwxdirexists}\\ +\helpref{wxDirSelector}{wxdirselector}\\ +\helpref{wxDisplayDepth}{wxdisplaydepth}\\ +\helpref{wxDisplaySize}{wxdisplaysize}\\ +\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\ +\helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\ +\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\ +\helpref{wxDynamicCast}{wxdynamiccast}\\ +\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}\\ +\helpref{wxEmptyClipboard}{wxemptyclipboard}\\ +\helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\ +\helpref{wxEndBusyCursor}{wxendbusycursor}\\ +\helpref{wxENTER\_CRIT\_SECT}{wxentercritsect}\\ +\helpref{wxEntry}{wxentry}\\ +\helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\ +\helpref{wxError}{wxerror}\\ +\helpref{wxExecute}{wxexecute}\\ +\helpref{wxExit}{wxexit}\\ +\helpref{wxEXPLICIT}{wxexplicit}\\ +\helpref{wxFAIL\_MSG}{wxfailmsg}\\ +\helpref{wxFAIL}{wxfail}\\ +\helpref{wxFatalError}{wxfatalerror}\\ +\helpref{wxFileExists}{functionwxfileexists}\\ +\helpref{wxFileModificationTime}{wxfilemodificationtime}\\ +\helpref{wxFileNameFromPath}{wxfilenamefrompath}\\ +\helpref{wxFileSelector}{wxfileselector}\\ +\helpref{wxFindFirstFile}{wxfindfirstfile}\\ +\helpref{wxFindMenuItemId}{wxfindmenuitemid}\\ +\helpref{wxFindNextFile}{wxfindnextfile}\\ +\helpref{wxFindWindowAtPointer}{wxfindwindowatpointer}\\ +\helpref{wxFindWindowAtPoint}{wxfindwindowatpoint}\\ +\helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\ +\helpref{wxFindWindowByName}{wxfindwindowbyname}\\ +\helpref{wxFinite}{wxfinite}\\ +\helpref{wxGetActiveWindow}{wxgetactivewindow}\\ +\helpref{wxGetApp}{wxgetapp}\\ +\helpref{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{wxGetElapsedTime}{wxgetelapsedtime}\\ +\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{wxGetMultipleChoice}{wxgetmultiplechoice}\\ +\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{wxGetResource}{wxgetresource}\\ +\helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\ +\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\ +\helpref{wxGetSingleChoice}{wxgetsinglechoice}\\ +\helpref{wxGetTempFileName}{wxgettempfilename}\\ +\helpref{wxGetTextFromUser}{wxgettextfromuser}\\ +\helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\ +\helpref{wxGetTranslation}{wxgettranslation}\\ +\helpref{wxGetUTCTime}{wxgetutctime}\\ +\helpref{wxGetUserHome}{wxgetuserhome}\\ +\helpref{wxGetUserId}{wxgetuserid}\\ +\helpref{wxGetUserName}{wxgetusername}\\ +\helpref{wxGetWorkingDirectory}{wxgetworkingdirectory}\\ +\helpref{wxGetenv}{wxgetenvmacro}\\ +\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\ +\helpref{wxICON}{wxiconmacro}\\ +\helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\ +\helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\ +\helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\ +\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}\\ +\helpref{wxInitialize}{wxinitialize}\\ +\helpref{wxIsAbsolutePath}{wxisabsolutepath}\\ +\helpref{wxIsBusy}{wxisbusy}\\ +\helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\ +\helpref{wxIsDebuggerRunning}{wxisdebuggerrunning}\\ +\helpref{wxIsEmpty}{wxisempty}\\ +\helpref{wxIsMainThread}{wxismainthread}\\ +\helpref{wxIsNaN}{wxisnan}\\ +\helpref{wxIsWild}{wxiswild}\\ +\helpref{wxKill}{wxkill}\\ +\helpref{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{wxSplitPath}{wxsplitfunction}\\ +\helpref{wxStartTimer}{wxstarttimer}\\ +\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{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{wxWriteResource}{wxwriteresource}\\ +\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} +\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} -See also \helpref{wxPathList}{wxpathlist}. +For example, the values or these constants for wxWidgets 2.1.15 are 2, 1 and +15. -\membersection{::wxDirExists} +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. -\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} +The subrelease number is only used for the sources in between official releases +and so normally is not useful. -Returns TRUE if the directory exists. +\wxheading{Include files} -\membersection{::wxDos2UnixFilename} + or -\func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}} -Converts a DOS to a UNIX filename by replacing backslashes with forward -slashes. +\membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion} -\membersection{::wxFileExists} +\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}} -\func{bool}{wxFileExists}{\param{const wxString\& }{filename}} +Returns $1$ if the compiler being used to compile the code is GNU C++ +compiler (g++) version major.minor.release or greater. Otherwise, and also if +the compiler is not GNU C++ at all, returns $0$. -Returns TRUE if the file exists. -\membersection{::wxFileNameFromPath} +\membersection{wxCHECK\_VERSION}\label{wxcheckversion} -\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} +\func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}} -Returns a temporary pointer to the filename for a full path. -Copy this pointer for long-term use. +This is a macro which evaluates to true if the current wxWidgets version is at +least major.minor.release. -\membersection{::wxFindFirstFile}\label{wxfindfirstfile} +For example, to test if the program is compiled with wxWidgets 2.2 or higher, +the following can be done: -\func{wxString}{wxFindFirstFile}{\param{const wxString\& }{spec}, \param{int}{ flags = 0}} +\begin{verbatim} + wxString s; +#if wxCHECK_VERSION(2, 2, 0) + if ( s.StartsWith("foo") ) +#else // replacement code for old version + if ( strncmp(s, "foo", 3) == 0 ) +#endif + { + ... + } +\end{verbatim} -This function does directory searching; returns the first file -that matches the path {\it spec}, or NULL. Use \helpref{wxFindNextFile}{wxfindnextfile} to -get the next matching file. -{\it spec} may contain wildcards. +\membersection{wxCHECK\_VERSION\_FULL}\label{wxcheckversionfull} -{\it flags} is reserved for future use. +\func{bool}{wxCHECK\_VERSION\_FULL}{\param{}{major, minor, release, subrel}} -The returned filename is a pointer to static memory so should -not be freed. +Same as \helpref{wxCHECK\_VERSION}{wxcheckversion} but also checks that +\texttt{wxSUBRELEASE\_NUMBER} is at least \arg{subrel}. -For example: -\begin{verbatim} - wxString f = wxFindFirstFile("/home/project/*.*"); - while (f) - { - ... - f = wxFindNextFile(); - } -\end{verbatim} +\membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion} -\membersection{::wxFindNextFile}\label{wxfindnextfile} +\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}} -\func{wxString}{wxFindFirstFile}{\void} +Returns $1$ if the version of w32api headers used is major.minor.release or +greater. Otherwise, and also if we are not compiling with mingw32/cygwin under +Win32 at all, returns $0$. -Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. -\membersection{::wxIsAbsolutePath} -\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} +\section{Application initialization and termination}\label{appinifunctions} -Returns TRUE if the argument is an absolute filename, i.e. with a slash -or drive name at the beginning. +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{::wxPathOnly} -\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} +\membersection{::wxEntry}\label{wxentry} -Returns a temporary pointer to the directory part of the filename. Copy this -pointer for long-term use. +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{::wxUnix2DosFilename} +\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, + \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = true}} -\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}} +wxWidgets initialization under Windows (non-DLL). If {\it enterLoop} is false, the +function will return immediately after calling wxApp::OnInit. Otherwise, the wxWidgets +message loop will be entered. -Converts a UNIX to a DOS filename by replacing forward -slashes with backslashes. +\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, + \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}} -\membersection{::wxConcatFiles} +wxWidgets initialization under Windows (for applications constructed as a DLL). -\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, -\param{const wxString\& }{file3}} +\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}} -Concatenates {\it file1} and {\it file2} to {\it file3}, returning -TRUE if successful. +wxWidgets initialization under Unix. -\membersection{::wxCopyFile} +\wxheading{Remarks} -\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} +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: -Copies {\it file1} to {\it file2}, returning TRUE if successful. +\begin{verbatim} +int CTheApp::ExitInstance() +{ + // OnExit isn't called by CleanUp so must be called explicitly. + wxTheApp->OnExit(); + wxApp::CleanUp(); -\membersection{::wxGetHostName}\label{wxgethostname} + return CWinApp::ExitInstance(); +} +\end{verbatim} -\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int }{sz}} +\wxheading{Include files} -Copies the current host machine's name into the supplied buffer. + -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} +\membersection{::wxGetApp}\label{wxgetapp} -\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}} +\func{wxAppDerivedClass\&}{wxGetApp}{\void} -Copies the user's email address into the supplied buffer, by -concatenating the values returned by \helpref{wxGetHostName}{wxgethostname}\rtfsp -and \helpref{wxGetUserId}{wxgetuserid}. +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}. -Returns TRUE if successful, FALSE otherwise. +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. -\membersection{::wxGetUserId}\label{wxgetuserid} -\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int }{sz}} +\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions} -Copies the current user id into the supplied buffer. +\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = true}} -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. +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 successful, FALSE otherwise. -\membersection{::wxGetUserName}\label{wxgetusername} +\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers} -\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int }{sz}} +\func{void}{wxInitAllImageHandlers}{\void} -Copies the current user name into the supplied buffer. +Initializes all available image handlers. For a list of available handlers, +see \helpref{wxImage}{wximage}. -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. +\wxheading{See also} -Returns TRUE if successful, FALSE otherwise. +\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler} -\membersection{::wxGetWorkingDirectory} +\wxheading{Include files} -\func{wxString}{wxGetWorkingDirectory}{\param{const wxString\& }{buf=NULL}, \param{int }{sz=1000}} + -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{::wxInitialize}\label{wxinitialize} -\membersection{::wxGetTempFileName} +\func{bool}{wxInitialize}{\void} -\func{wxString}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{const wxString\& }{buf=NULL}} +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. -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}. +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. -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. +This function may be called several times but +\helpref{wxUninitialize}{wxuninitialize} must be called for each successful +call to this function. -It is the application's responsibility to create and delete the file. +\wxheading{Include files} -\membersection{::wxIsWild}\label{wxiswild} + -\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} -Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. +\membersection{::wxSafeYield}\label{wxsafeyield} -\membersection{::wxMatchWild}\label{wxmatchwild} +\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}, \param{bool}{ + onlyIfNeeded = false}} -\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} +This function is similar to wxYield, except that it disables the user input to +all program windows before calling wxYield and re-enables it again +afterwards. If {\it win} is not NULL, this window will remain enabled, +allowing the implementation of some limited user interaction. -Returns 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}. +Returns the result of the call to \helpref{::wxYield}{wxyield}. -\membersection{::wxMkdir} +\wxheading{Include files} -\func{bool}{wxMkdir}{\param{const wxString\& }{dir}} + -Makes the directory {\it dir}, returning TRUE if successful. -\membersection{::wxRemoveFile} +\membersection{::wxUninitialize}\label{wxuninitialize} -\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} +\func{void}{wxUninitialize}{\void} -Removes {\it file}, returning TRUE if successful. +This function is for use in console (wxBase) programs only. It must be called +once for each previous successful call to \helpref{wxInitialize}{wxinitialize}. -\membersection{::wxRenameFile} +\wxheading{Include files} -\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} + -Renames {\it file1} to {\it file2}, returning TRUE if successful. -\membersection{::wxRmdir} +\membersection{::wxYield}\label{wxyield} -\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}} +\func{bool}{wxYield}{\void} -Removes the directory {\it dir}, returning TRUE if successful. Does not work under VMS. +Calls \helpref{wxApp::Yield}{wxappyield}. -The {\it flags} parameter is reserved for future use. +This function is kept only for backwards compatibility. Please use +the \helpref{wxApp::Yield}{wxappyield} method instead in any new code. -\membersection{::wxSetWorkingDirectory} +\wxheading{Include files} -\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}} + or -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. -\section{String functions} +\membersection{::wxWakeUpIdle}\label{wxwakeupidle} -\membersection{::copystring} +\func{void}{wxWakeUpIdle}{\void} -\func{char*}{copystring}{\param{const char* }{s}} +This functions wakes up the (internal and platform dependent) idle system, i.e. it +will force the system to send an idle event even if the system currently {\it is} + idle and thus would not send any idle event until after some other event would get +sent. This is also useful for sending events between two threads and is used by +the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and +\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}. -Makes a copy of the string {\it s} using the C++ new operator, so it can be -deleted with the {\it delete} operator. +\wxheading{Include files} -\membersection{::wxStringMatch} + -\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\ - \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}} -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{::wxStringEq}\label{wxstringeq} +\section{Process control functions}\label{processfunctions} -\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}} +The functions in this section are used to launch or terminate the other +processes. -A macro defined as: -\begin{verbatim} -#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) -\end{verbatim} +\membersection{::wxExecute}\label{wxexecute} -\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream} +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} -\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}} +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteCommand}} -Copies the given file to {\it stream}. Useful when converting an old application to -use streams (within the document/view framework, for example). +\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}} -Use of this function requires the file wx\_doc.h to be included. +\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteArgs}} -\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile} +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{int }{flags = 0}} -\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}} +\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.} -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). +\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}, \param{int }{flags = 0}} -Use of this function requires the file wx\_doc.h to be included. +\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.} -\section{Dialog functions}\label{dialogfunctions} +Executes another program in Unix or Windows. -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 first form takes a command string, such as {\tt "emacs file.txt"}. -\membersection{::wxFileSelector}\label{wxfileselector} +The second form takes an array of values: a command, any number of +arguments, terminated by NULL. -\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}} +The semantics of the third and fourth versions is different from the first two +and is described in more details below. + +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. -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. +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. -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. +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). -Under Windows (only), the wildcard may be a specification for multiple -types of file with a description for each, such as: +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. -\begin{verbatim} - "BMP files (*.bmp) | *.bmp | GIF files (*.gif) | *.gif" -\end{verbatim} +{\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. -The application must check for a NULL return value (the user pressed -Cancel). For example: +\wxheading{See also} -\begin{verbatim} -const wxString\& s = wxFileSelector("Choose a file to open"); -if (s) -{ - ... -} -\end{verbatim} +\helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, \helpref{Exec sample}{sampleexec}. -Remember that the returned pointer is temporary and should be copied -if other wxWindows calls will be made before the value is to be used. +\wxheading{Parameters} -\membersection{::wxGetTextFromUser}\label{wxgettextfromuser} +\docparam{command}{The command to execute and any parameters to pass to it as a +single string.} -\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\ - \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\ - \param{int}{ x = -1}, \param{int}{ y = -1}, \param{bool}{ centre = TRUE}} +\docparam{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.} -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 NULL. +\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}} -\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice} +\wxheading{Include files} -\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ - \param{int }{nsel}, \param{int *}{selection}, - \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ - \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}} + -Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection -listbox. The user may choose one or more item(s) and press OK or Cancel. -The number of initially selected choices, and array of the selected indices, -are passed in; this array will contain the user selections on exit, with -the function returning the number of selections. {\it selection} must be -as big as the number of choices, in case all are selected. +\membersection{::wxExit}\label{wxexit} -If Cancel is pressed, -1 is returned. +\func{void}{wxExit}{\void} -{\it choices} is an array of {\it n} strings for the listbox. +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}. -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{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 NULL. +\membersection{::wxKill}\label{wxkill} -{\it choices} is an array of {\it n} strings for the listbox. +\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}, \param{int }{flags = 0}} -If {\it centre} is TRUE, the message text (which may include new line characters) -is centred; if FALSE, the message is left-justified. +Equivalent to the Unix kill function: send the given signal {\it sig} to the +process with PID {\it pid}. The valid signal values are -\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex} +\begin{verbatim} +enum wxSignal +{ + wxSIGNONE = 0, // verify if the process exists under Unix + wxSIGHUP, + wxSIGINT, + wxSIGQUIT, + wxSIGILL, + wxSIGTRAP, + wxSIGABRT, + wxSIGEMT, + wxSIGFPE, + wxSIGKILL, // forcefully kill, dangerous! + wxSIGBUS, + wxSIGSEGV, + wxSIGSYS, + wxSIGPIPE, + wxSIGALRM, + wxSIGTERM // terminate the process gently +}; +\end{verbatim} -\func{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}} +{\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. -As {\bf wxGetSingleChoice} but returns the index representing the selected string. -If the user pressed cancel, -1 is returned. +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: -\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata} +\begin{verbatim} +enum wxKillError +{ + wxKILL_OK, // no error + wxKILL_BAD_SIGNAL, // no such signal + wxKILL_ACCESS_DENIED, // permission denied + wxKILL_NO_PROCESS, // no such process + wxKILL_ERROR // another, unspecified error +}; +\end{verbatim} -\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}} +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. -As {\bf wxGetSingleChoice} but takes an array of client data pointers -corresponding to the strings, and returns one of these pointers. +\wxheading{See also} -\membersection{::wxMessageBox}\label{wxmessagebox} +\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp +\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp +\helpref{Exec sample}{sampleexec} -\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}} +\wxheading{Include files} -General purpose message dialog. {\it style} may be a bit list of the -following identifiers: + -\begin{twocollist}\itemsep=0pt -\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with -wxCANCEL.} -\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with -wxYES\_NO or wxOK.} -\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.} -\twocolitem{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} -The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. +\membersection{::wxGetProcessId}\label{wxgetprocessid} -For example: +\func{unsigned long}{wxGetProcessId}{\void} -\begin{verbatim} - ... - int answer = wxMessageBox("Quit program?", "Confirm", - wxYES_NO | wxCANCEL, main_frame); - if (answer == wxYES) - delete main_frame; - ... -\end{verbatim} +Returns the number uniquely identifying the current process in the system. -{\it message} may contain newline characters, in which case the -message will be split into separate lines, to cater for large messages. +If an error occurs, $0$ is returned. -Under Windows, the native MessageBox function is used unless wxCENTRE -is specified in the style, in which case a generic function is used. -This is because the native MessageBox function cannot centre text. -The symbols are not shown when the generic function is used. +\wxheading{Include files} -\section{GDI functions}\label{gdifunctions} + -The following are relevant to the GDI (Graphics Device Interface). -\membersection{::wxColourDisplay} +\membersection{::wxShell}\label{wxshell} -\func{bool}{wxColourDisplay}{\void} +\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} -Returns TRUE if the display is colour, FALSE otherwise. +Executes a command in an interactive shell window. If no command is +specified, then just the shell is spawned. -\membersection{::wxDisplayDepth} +See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}. -\func{int}{wxDisplayDepth}{\void} +\wxheading{Include files} -Returns the depth of the display (a value of 1 denotes a monochrome display). + -\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}} +\membersection{::wxShutdown}\label{wxshutdown} -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. +\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}} -In addition to adding the placeable metafile header, this function adds -the equivalent of the following code to the start of the metafile data: +This function shuts down or reboots the computer depending on the value of the +{\it flags}. Please notice that doing this requires the corresponding access +rights (superuser under Unix, {\tt SE\_SHUTDOWN} privelege under Windows NT) +and that this function is only implemented under Unix and Win32. -\begin{verbatim} - SetMapMode(dc, MM_ANISOTROPIC); - SetWindowOrg(dc, minX, minY); - SetWindowExt(dc, maxX - minX, maxY - minY); -\end{verbatim} +\wxheading{Parameters} -This simulates the MM\_TEXT mapping mode, which wxWindows assumes. +\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}} -Placeable metafiles may be imported by many Windows applications, and can be -used in RTF (Rich Text Format) files. +\wxheading{Returns} -{\it scale} allows the specification of scale for the metafile. +\true on success, \false if an error occurred. -This function is only available under Windows. +\wxheading{Include files} -\membersection{::wxSetCursor}\label{wxsetcursor} + -\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}} -Globally sets the cursor; only has an effect in MS Windows. -See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}. -\section{Printer settings}\label{printersettings} +\section{Thread functions}\label{threadfunctions} -The following functions are used to control PostScript printing. Under -Windows, PostScript output can only be sent to a file. +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$). -\membersection{::wxGetPrinterCommand} +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. -\func{wxString}{wxGetPrinterCommand}{\void} +\wxheading{Include files} -Gets the printer command used to print a file. The default is {\tt lpr}. + -\membersection{::wxGetPrinterFile} +\wxheading{See also} -\func{wxString}{wxGetPrinterFile}{\void} +\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview} -Gets the PostScript output filename. -\membersection{::wxGetPrinterMode} -\func{int}{wxGetPrinterMode}{\void} +\membersection{wxCRIT\_SECT\_DECLARE}\label{wxcritsectdeclare} -Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). -The default is PS\_PREVIEW. +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} -\membersection{::wxGetPrinterOptions} +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{wxString}{wxGetPrinterOptions}{\void} -Gets the additional options for the print command (e.g. specific printer). The default is nothing. -\membersection{::wxGetPrinterOrientation} +\membersection{wxCRIT\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember} -\func{int}{wxGetPrinterOrientation}{\void} +\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}} -Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. +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{::wxGetPrinterPreviewCommand} -\func{wxString}{wxGetPrinterPreviewCommand}{\void} -Gets the command used to view a PostScript file. The default depends on the platform. +\membersection{wxCRIT\_SECT\_LOCKER}\label{wxcritsectlocker} -\membersection{::wxGetPrinterScaling} +\func{}{wxCRIT\_SECT\_LOCKER}{\param{}{name}, \param{}{cs}} -\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}} +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 scaling factor for PostScript output. The default is 1.0, 1.0. -\membersection{::wxGetPrinterTranslation} -\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}} +\membersection{wxCRITICAL\_SECTION}\label{wxcriticalsectionmacro} -Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. +\func{}{wxCRITICAL\_SECTION}{\param{}{name}} -\membersection{::wxSetPrinterCommand} +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}{wxSetPrinterCommand}{\param{const wxString\& }{command}} +\begin{verbatim} +int IncCount() +{ + static int s_counter = 0; -Sets the printer command used to print a file. The default is {\tt lpr}. + wxCRITICAL_SECTION(counter); -\membersection{::wxSetPrinterFile} + return ++s_counter; +} +\end{verbatim} -\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}} +(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). -Sets the PostScript output filename. -\membersection{::wxSetPrinterMode} -\func{void}{wxSetPrinterMode}{\param{int }{mode}} +\membersection{wxENTER\_CRIT\_SECT}\label{wxentercritsect} -Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER). -The default is PS\_PREVIEW. +\func{}{wxENTER\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} -\membersection{::wxSetPrinterOptions} +This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. -\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} +\membersection{::wxIsMainThread}\label{wxismainthread} -\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}} +\func{bool}{wxIsMainThread}{\void} -Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT. +Returns \true if this thread is the main one. Always returns \true if +{\tt wxUSE\_THREADS} is $0$. -\membersection{::wxSetPrinterPreviewCommand} -\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}} -Sets the command used to view a PostScript file. The default depends on the platform. +\membersection{wxLEAVE\_CRIT\_SECT}\label{wxleavecritsect} -\membersection{::wxSetPrinterScaling} +\func{}{wxLEAVE\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}} -\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}} +This macro is equivalent to \helpref{cs.Leave()}{wxcriticalsectionleave} if +{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. -Sets the scaling factor for PostScript output. The default is 1.0, 1.0. -\membersection{::wxSetPrinterTranslation} -\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}} +\membersection{::wxMutexGuiEnter}\label{wxmutexguienter} -Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. +\func{void}{wxMutexGuiEnter}{\void} -\section{Clipboard functions}\label{clipsboard} +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}. -These clipboard functions are implemented for Windows only. +Typically, these functions are used like this: -\membersection{::wxClipboardOpen} +\begin{verbatim} +void MyThread::Foo(void) +{ + // before doing any GUI calls we must ensure that this thread is the only + // one doing it! -\func{bool}{wxClipboardOpen}{\void} + wxMutexGuiEnter(); -Returns TRUE if this application has already opened the clipboard. + // Call GUI here: + my_window->DrawSomething(); -\membersection{::wxCloseClipboard} + wxMutexGuiLeave(); +} +\end{verbatim} -\func{bool}{wxCloseClipboard}{\void} +Note that under GTK, no creation of top-level windows is allowed in any +thread but the main one. -Closes the clipboard to allow other applications to use it. +This function is only defined on platforms which support preemptive +threads. -\membersection{::wxEmptyClipboard} -\func{bool}{wxEmptyClipboard}{\void} +\membersection{::wxMutexGuiLeave}\label{wxmutexguileave} -Empties the clipboard. +\func{void}{wxMutexGuiLeave}{\void} -\membersection{::wxEnumClipboardFormats} +See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}. -\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}} +This function is only defined on platforms which support preemptive +threads. -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. +\section{File functions}\label{filefunctions} -Before it enumerates the formats function, an application must open the clipboard by using the -wxOpenClipboard function. +\wxheading{Include files} -\membersection{::wxGetClipboardData} + -\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}} +\wxheading{See also} -Gets data from the clipboard. +\helpref{wxPathList}{wxpathlist}\\ +\helpref{wxDir}{wxdir}\\ +\helpref{wxFile}{wxfile}\\ +\helpref{wxFileName}{wxfilename} -{\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. +\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename} + +\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}} + +Converts a DOS to a Unix filename by replacing backslashes with forward +slashes. + + +\membersection{::wxFileExists}\label{functionwxfileexists} + +\func{bool}{wxFileExists}{\param{const wxString\& }{filename}} + +Returns true if the file exists and is a plain file. + + +\membersection{::wxFileModificationTime}\label{wxfilemodificationtime} + +\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}} + +Returns time of last modification of given file. + +The return value is $0$ if an error occured (e.g. file not found). + + +\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath} + +\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} + +\func{char *}{wxFileNameFromPath}{\param{char *}{path}} + +{\bf NB:} This function is obsolete, please use +\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. + +Returns the filename for a full path. The second form returns a pointer to +temporary storage that should not be deallocated. + + +\membersection{::wxFindFirstFile}\label{wxfindfirstfile} + +\func{wxString}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}} + +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 "..". + +\wxheading{Warning} + +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. + +{\it spec} may contain wildcards. + +{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either. + +For example: + +\begin{verbatim} + wxString f = wxFindFirstFile("/home/project/*.*"); + while ( !f.empty() ) + { + ... + f = wxFindNextFile(); + } +\end{verbatim} + + +\membersection{::wxFindNextFile}\label{wxfindnextfile} + +\func{wxString}{wxFindNextFile}{\void} + +Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}. + +See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example. + + +\membersection{::wxGetDiskSpace}\label{wxgetdiskspace} + +\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}} + +This function returns the total number of bytes and number of free bytes on +the disk containing the directory {\it path} (it should exist). Both +{\it total} and {\it free} parameters may be {\tt NULL} if the corresponding +information is not needed. + +\wxheading{Returns} + +\true on success, \false if an error occurred (for example, the +directory doesn't exist). + +\wxheading{Portability} + +This function is implemented for Win32, +Mac OS and generic Unix provided the system has {\tt statfs()} function. + +This function first appeared in wxWidgets 2.3.2. + + +\membersection{::wxGetFileKind}\label{wxgetfilekind} + +\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{::wxGetOSDirectory}\label{wxgetosdirectory} + +\func{wxString}{wxGetOSDirectory}{\void} + +Returns the Windows directory under Windows; on other platforms returns the empty string. + + +\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath} + +\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}} + +Returns true if the argument is an absolute filename, i.e. with a slash +or drive name at the beginning. + + +\membersection{::wxDirExists}\label{functionwxdirexists} + +\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}} + +Returns true if the path exists. + + +\membersection{::wxPathOnly}\label{wxpathonly} + +\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} + +Returns the directory part of the filename. + + +\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename} + +\func{void}{wxUnix2DosFilename}{\param{wxChar *}{s}} + +This function is deprecated, use \helpref{wxFileName}{wxfilename} instead. + +Converts a Unix to a DOS filename by replacing forward +slashes with backslashes. + + +\membersection{wxCHANGE\_UMASK}\label{wxchangeumask} + +\func{}{wxCHANGE\_UMASK}{\param{int }{mask}} + +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. + +Under other platforms this macro expands to nothing. + + +\membersection{::wxConcatFiles}\label{wxconcatfiles} + +\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, +\param{const wxString\& }{file3}} + +Concatenates {\it file1} and {\it file2} to {\it file3}, returning +true if successful. + + +\membersection{::wxCopyFile}\label{wxcopyfile} + +\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}} + +Copies {\it file1} to {\it file2}, returning true if successful. If +{\it overwrite} parameter is true (default), the destination file is overwritten +if it exists, but if {\it overwrite} is false, the functions fails in this +case. + + +\membersection{::wxGetCwd}\label{wxgetcwd} + +\func{wxString}{wxGetCwd}{\void} + +Returns a string containing the current (or working) directory. + + +\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory} + +\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}} + +{\bf NB:} This function is deprecated: 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 {\emph must} delete +yourself) if the buffer is NULL. + +{\it sz} is the size of the buffer if supplied. + + +\membersection{::wxGetTempFileName}\label{wxgettempfilename} + +\func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}} + +\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}} + +%% 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. + +{\bf NB:} These functions are obsolete, please use\rtfsp +\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp +instead. + + +\membersection{::wxIsWild}\label{wxiswild} + +\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}} + +Returns true if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}. + + +\membersection{::wxMatchWild}\label{wxmatchwild} + +\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}} + +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{::wxMkdir}\label{wxmkdir} + +\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}} + +Makes the directory \arg{dir}, returning true if successful. + +{\it perm} is the access mask for the directory for the systems on which it is +supported (Unix) and doesn't have effect for the other ones. + + +\membersection{::wxParseCommonDialogsFilter}\label{wxparsecommondialogsfilter} + +\func{int}{wxParseCommonDialogsFilter}{\param{const wxString\& }{wildCard}, \param{wxArrayString\& }{descriptions}, \param{wxArrayString\& }{filters}} + +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} + +\membersection{::wxRemoveFile}\label{wxremovefile} + +\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}} + +Removes \arg{file}, returning true if successful. + + +\membersection{::wxRenameFile}\label{wxrenamefile} + +\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}} + +Renames \arg{file1} to \arg{file2}, returning true if successful. + + +\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. + + +\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{::wxSplitPath}\label{wxsplitfunction} + +\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}} + +{\bf NB:} This function is obsolete, please use +\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead. + +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{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} + +Gets operating system version information. + +\begin{twocollist}\itemsep=0pt +\twocolitemruled{Platform}{Return types} +\twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X. + +Both {\it major} and {\it minor} have to be looked at as hexadecimal numbers. So System 10.2.4 returns 0x10, resp 16 for {\it major} and 0x24, resp 36 for {\it minor}. } +\twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. } +\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.} +\twocolitem{OS/2}{Return value is wxOS2\_PM.} +\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.} +\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}.} +\twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.} +\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.} +\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.} +\twocolitem{Windows PocketPC}{Return value is wxWINDOWS\_POCKETPC, version is returned in {\it major} and {\it minor}.} +\twocolitem{Windows Smartphone}{Return value is wxWINDOWS\_SMARTPHONE, version is returned in {\it major} and {\it minor}.} +\twocolitem{Windows CE (non-specific)}{Return value is wxWINDOWS\_CE, version is returned in {\it major} and {\it minor}.} +\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.} +\end{twocollist} + +\wxheading{See also} + +\helpref{::wxGetOsDescription}{wxgetosdescription} + +\wxheading{Include files} + + + + +\membersection{::wxGetUserHome}\label{wxgetuserhome} + +\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}} + +Returns the home directory for the given user. If the username is empty +(default value), this function behaves like +\helpref{wxGetHomeDir}{wxgethomedir}. + +\wxheading{Include files} + + + + +\membersection{::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{::copystring}\label{copystring} + +\func{char *}{copystring}{\param{const char *}{s}} + +Makes a copy of the string {\it s} using the C++ new operator, so it can be +deleted with the {\it delete} operator. + +This function is deprecated, use \helpref{wxString}{wxstring} class instead. + + +\membersection{::wxGetTranslation}\label{wxgettranslation} + +\func{const char *}{wxGetTranslation}{\param{const char * }{str}} + +\func{const char *}{wxGetTranslation}{\param{const char * }{str}, \param{const char * }{strPlural}, \param{size\_t }{n}} + +This function returns the translation of string {\it str} in the current +\helpref{locale}{wxlocale}. If the string is not found in any of the loaded +message catalogs (see \helpref{internationalization overview}{internationalization}), the +original string is returned. In debug build, an error message is logged -- this +should help to find the strings which were not yet translated. As this function +is used very often, an alternative (and also common in Unix world) syntax is +provided: the \helpref{\_()}{underscore} macro is defined to do the same thing +as wxGetTranslation. + +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 (except in Unicode build where it is equivalent to +\helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT +with the same string which would be really unreadable). + +However it does have a purpose and it is to mark the literal strings for the +extraction into the message catalog created by {\tt xgettext} program. Usually +this is achieved using \helpref{\_()}{underscore} but that macro not only marks +the string for extraction but also expands into 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 wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") }; +... +// use weekdays[n] as usual +\end{verbatim} + +the code wouldn't compile because the function calls are forbidden in the array +initializer. So instead you should do + +\begin{verbatim} +static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") }; +... +// use wxGetTranslation(weekdays[n]) +\end{verbatim} + +here. + +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. + +\wxheading{See also} + +\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv} + + + +\membersection{\_}\label{underscore} + +\func{const wxChar *}{\_}{\param{const char *}{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 wxChar *}{wxPLURAL}{\param{const char *}{sing}, \param{const char *}{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{::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. + +\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 wxOPEN, +wxSAVE, wxOVERWRITE\_PROMPT or wxFILE\_MUST\_EXIST. Note that wxMULTIPLE +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{::wxGetColourFromUser}\label{wxgetcolourfromuser} + +\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}} + +Shows the colour selection dialog and returns the colour selected by user or +invalid colour (use \helpref{wxColour::Ok}{wxcolourok} to test whether a colour +is valid) if the dialog was cancelled. + +\wxheading{Parameters} + +\docparam{parent}{The parent window for the colour selection dialog} + +\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.} + +\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::Ok}{wxfontok} to test whether a font +is valid) if the dialog was cancelled. + +\wxheading{Parameters} + +\docparam{parent}{The parent window for the font selection dialog} + +\docparam{fontInit}{If given, this will be the font initially selected in the dialog.} + +\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{::wxGetMultipleChoice}\label{wxgetmultiplechoice} + +\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\ + \param{int }{nsel}, \param{int *}{selection}, + \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\ + \param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}} + +Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection +listbox. The user may choose one or more item(s) and press OK or Cancel. + +The number of initially selected choices, and array of the selected indices, +are passed in; this array will contain the user selections on exit, with +the function returning the number of selections. {\it selection} must be +as big as the number of choices, in case all are selected. + +If Cancel is pressed, -1 is returned. + +{\it choices} is an array of {\it n} strings for the listbox. + +If {\it centre} is true, the message text (which may include new line characters) +is centred; if false, the message is left-justified. + +\wxheading{Include files} + + + + +\membersection{::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{::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 or NaN (not a number), +returns 0 otherwise. + + +\membersection{wxIsNaN}\label{wxisnan} + +\func{bool}{wxIsNaN}{\param{double }{x}} + +Returns a non-zero value if {\it x} is NaN (not a number), returns 0 +otherwise. + + + + +\section{GDI functions}\label{gdifunctions} + +The following are relevant to the GDI (Graphics Device Interface). + +\wxheading{Include files} + + + + +\membersection{wxBITMAP}\label{wxbitmapmacro} + +\func{}{wxBITMAP}{bitmapName} + +This macro loads a bitmap from either application resources (on the platforms +for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to +avoid using {\tt \#ifdef}s when creating bitmaps. + +\wxheading{See also} + +\helpref{Bitmaps and icons overview}{wxbitmapoverview}, +\helpref{wxICON}{wxiconmacro} + +\wxheading{Include files} + + + + +\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect} + +\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y}, +\param{int *}{width}, \param{int *}{height}} + +\func{wxRect}{wxGetClientDisplayRect}{\void} + +Returns the dimensions of the work area on the display. On Windows +this means the area not covered by the taskbar, etc. Other platforms +are currently defaulting to the whole display until a way is found to +provide this info for all window managers, etc. + + +\membersection{::wxColourDisplay}\label{wxcolourdisplay} + +\func{bool}{wxColourDisplay}{\void} + +Returns true if the display is colour, false otherwise. + + +\membersection{::wxDisplayDepth}\label{wxdisplaydepth} + +\func{int}{wxDisplayDepth}{\void} + +Returns the depth of the display (a value of 1 denotes a monochrome display). + + +\membersection{::wxDisplaySize}\label{wxdisplaysize} + +\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} + +\func{wxSize}{wxGetDisplaySize}{\void} + +Returns the display size in pixels. + + +\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm} + +\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}} + +\func{wxSize}{wxGetDisplaySizeMM}{\void} + +Returns the display size in millimeters. + + +\membersection{::wxDROP\_ICON}\label{wxdropicon} + +\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}} + +This macro creates either a cursor (MSW) or an icon (elsewhere) with the given +name. Under MSW, the cursor is loaded from the resource file and the icon is +loaded from XPM file under other platforms. + +This macro should be used with +\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}. + +\wxheading{Include files} + + + + +\membersection{wxICON}\label{wxiconmacro} + +\func{}{wxICON}{iconName} + +This macro loads an icon from either application resources (on the platforms +for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to +avoid using {\tt \#ifdef}s when creating icons. + +\wxheading{See also} + +\helpref{Bitmaps and icons overview}{wxbitmapoverview}, +\helpref{wxBITMAP}{wxbitmapmacro} + +\wxheading{Include files} + + + + +\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable} + +\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY}, + \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}} + +Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc}) +makes it into a placeable metafile by prepending a header containing the given +bounding box. The bounding box may be obtained from a device context after drawing +into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. + +In addition to adding the placeable metafile header, this function adds +the equivalent of the following code to the start of the metafile data: + +\begin{verbatim} + SetMapMode(dc, MM_ANISOTROPIC); + SetWindowOrg(dc, minX, minY); + SetWindowExt(dc, maxX - minX, maxY - minY); +\end{verbatim} + +This simulates the wxMM\_TEXT mapping mode, which 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. +The clipboard must have previously been opened for this call to succeed. + + +\section{Miscellaneous functions}\label{miscellany} + + +\membersection{wxCONCAT}\label{wxconcat} + +\func{}{wxCONCAT}{\param{}{x}, \param{}{y}} + +This macro returns the concatenation of two tokens \arg{x} and \arg{y}. + + +\membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction} + +\func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}} + +When loading a function from a DLL you always have to cast the returned +{\tt void *} pointer to the correct type and, even more annoyingly, you have to +repeat this type twice if you want to declare and define a function pointer all +in one line + +This macro makes this slightly less painful by allowing you to specify the +type only once, as the first parameter, and creating a variable of this type +named after the function but with {\tt pfn} prefix and initialized with the +function \arg{name} from the \helpref{wxDynamicLibrary}{wxdynamiclibrary} +\arg{dynlib}. + +\wxheading{Parameters} + +\docparam{type}{the type of the function} + +\docparam{name}{the name of the function to load, not a string (without quotes, +it is quoted automatically by the macro)} + +\docparam{dynlib}{the library to load the function from} + + + +\membersection{wxEXPLICIT}\label{wxexplicit} + +{\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if +the compiler supports it or nothing otherwise. Thus, it can be used even in the +code which might have to be compiled with an old compiler without support for +this language feature but still take advantage of it when it is available. + + +\membersection{::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} + +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{::wxGetActiveWindow}\label{wxgetactivewindow} + +\func{wxWindow *}{wxGetActiveWindow}{\void} + +Gets the currently active window (Windows only). + +\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. + +\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. + +\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 coordinants, 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{::wxGetResource}\label{wxgetresource} + +\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{float *}{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{long *}{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{int *}{value}, \param{const wxString\& }{file = NULL}} + +Gets a resource value from the resource database (for example, WIN.INI, or +.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used, +otherwise the specified file is used. + +Under X, if an application class (wxApp::GetClassName) has been defined, +it is appended to the string /usr/lib/X11/app-defaults/ to try to find +an applications default file when merging all resource databases. + +The reason for passing the result in an argument is that it +can be convenient to define a default value, which gets overridden +if the value exists in the resource file. It saves a separate +test for that resource's existence, and it also allows +the overloading of the function for different types. + +See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}. + +\wxheading{Include files} + + + + +\membersection{::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; +usefull for getting labels without accelerator char code like for toolbar tooltip or +under 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). + +Returns \true if the application was successfully launched. + +\wxheading{Include files} + + + + +\membersection{::wxLoadUserResource}\label{wxloaduserresource} + +\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} + +Loads a user-defined Windows resource as a string. If the resource is found, the function creates +a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned. + +The resource must be defined in the {\tt .rc} file using the following syntax: + +\begin{verbatim} +myResource TEXT file.ext +\end{verbatim} + +where {\tt file.ext} is a file that the resource compiler can find. + +This function is available under Windows only. + +\wxheading{Include files} + + + + +\membersection{::wxPostDelete}\label{wxpostdelete} + +\func{void}{wxPostDelete}{\param{wxObject *}{object}} + +Tells the system to delete the specified object when +all other events have been processed. In some environments, it is +necessary to use this instead of deleting a frame directly with the +delete operator, because some GUIs will still send events to a deleted window. + +Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead. + +\wxheading{Include files} + + + + +\membersection{::wxPostEvent}\label{wxpostevent} + +\func{void}{wxPostEvent}{\param{wxEvtHandler *}{dest}, \param{wxEvent\& }{event}} + +In a GUI application, this function posts {\it event} to the specified {\it dest} +object using \helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}. +Otherwise, it dispatches {\it event} immediately using +\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}. +See the respective documentation for details (and caveats). + +\wxheading{Include files} + + + + +\membersection{::wxSetDisplayName}\label{wxsetdisplayname} + +\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}} + +Under X only, sets the current display name. This is the X host and display name such +as ``colonsay:0.0", and the function indicates which display should be used for creating +windows from this point on. Setting the display within an application allows multiple +displays to be used. + +See also \helpref{wxGetDisplayName}{wxgetdisplayname}. + +\wxheading{Include files} + + + + +\membersection{::wxStripMenuCodes}\label{wxstripmenucodes} + +\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}} + +\func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}} + +{\bf NB:} This function is obsolete, please use +\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead. + +Strips any menu codes from {\it in} and places the result +in {\it out} (or returns the new string, in the first form). + +Menu codes include \& (mark the next character with an underline +as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows). + +\wxheading{Include files} + + + + +\membersection{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{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{::wxWriteResource}\label{wxwriteresource} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{float }{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{long }{value}, \param{const wxString\& }{file = NULL}} + +\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, + \param{int }{value}, \param{const wxString\& }{file = NULL}} + +Writes a resource value into the resource database (for example, WIN.INI, or +.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used, +otherwise the specified file is used. + +Under X, the resource databases are cached until the internal function +\rtfsp{\bf wxFlushResources} is called automatically on exit, when +all updated resource databases are written to their files. + +Note that it is considered bad manners to write to the .Xdefaults +file under Unix, although the WIN.INI file is fair game under Windows. + +See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}. + +\wxheading{Include files} + + + + +\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. + + + +\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} -\membersection{::wxGetClipboardFormatName} +\wxheading{Include files} -\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} +\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}\label{implementabstractclass2} -\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}} +\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2} -Returns TRUE if the given data format is available on the clipboard. +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. -\membersection{::wxOpenClipboard} +\wxheading{Include files} -\func{bool}{wxOpenClipboard}{\void} + -Opens the clipboard for passing data to it or getting data from it. -\membersection{::wxRegisterClipboardFormat} +\membersection{IMPLEMENT\_APP}\label{implementapp} -\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}} +\func{}{IMPLEMENT\_APP}{className} -Registers the clipboard data format name and returns an identifier. +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 -\membersection{::wxSetClipboardData} +Old form: -\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}} +\begin{verbatim} + MyApp myApp; +\end{verbatim} -Passes data to the clipboard. +New form: -{\it dataFormat} may be one of: +\begin{verbatim} + IMPLEMENT_APP(MyApp) +\end{verbatim} -\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} +See also \helpref{DECLARE\_APP}{declareapp}. -The clipboard must have previously been opened for this call to succeed. +\wxheading{Include files} -\section{Miscellaneous functions}\label{miscellany} + -\membersection{::NewId} -\func{long}{NewId}{\void} +\membersection{IMPLEMENT\_CLASS}\label{implementclass} -Generates an integer identifier unique to this run of the program. +\func{}{IMPLEMENT\_CLASS}{className, baseClassName} -\membersection{::RegisterId} +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. -\func{void}{RegisterId}{\param{long}{ id}} +\wxheading{Include files} -Ensures that ids subsequently generated by {\bf NewId} do not clash with -the given {\bf id}. + -\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} -\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}} +\membersection{IMPLEMENT\_CLASS2}\label{implementclass2} -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{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2} + +Used in a C++ implementation file to complete the declaration of a +class that has run-time type information and two base classes. The +same as IMPLEMENT\_ABSTRACT\_CLASS2. -See also \helpref{wxIsBusy}{wxisbusy}. +\wxheading{Include files} -\membersection{::wxBell} + -\func{void}{wxBell}{\void} -Ring the system bell. +\membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass} + +\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName} + +Used in a C++ implementation file to complete the declaration of +a class that has run-time type information, and whose instances +can be created dynamically. + +Example: -\membersection{::wxCleanUp}\label{wxcleanup} +\begin{verbatim} +IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) + +wxFrame::wxFrame(void) +{ +... +} +\end{verbatim} + +\wxheading{Include files} + + + + +\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2} + +\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2} + +Used in a C++ implementation file to complete the declaration of +a class that has run-time type information, and whose instances +can be created dynamically. Use this for classes derived from two +base classes. + +\wxheading{Include files} + + + + +\membersection{wxConstCast}\label{wxconstcast} + +\func{classname *}{wxConstCast}{ptr, classname} -\func{void}{wxCleanUp}{\void} +This macro expands into {\tt const\_cast(ptr)} if the compiler +supports {\it const\_cast} or into an old, C-style cast, otherwise. + +\wxheading{See also} + +\helpref{wx\_const\_cast}{wxconstcastraw}\\ +\helpref{wxDynamicCast}{wxdynamiccast}\\ +\helpref{wxStaticCast}{wxstaticcast} -Normally, wxWindows will call this cleanup function for you. However, if -you call \helpref{wxEntry}{wxentry} in order to initialize wxWindows -manually, then you should also call wxCleanUp before terminating wxWindows, -if wxWindows does not get a chance to do it. \membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject} @@ -729,834 +3667,916 @@ if wxWindows does not get a chance to do it. 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{::wxDebugMsg} + +\membersection{WXDEBUG\_NEW}\label{debugnew} + +\func{}{WXDEBUG\_NEW}{arg} + +This is defined in debug mode to be call the redefined new operator +with filename and line number arguments. The definition is: + +\begin{verbatim} +#define WXDEBUG_NEW new(__FILE__,__LINE__) +\end{verbatim} + +In non-debug mode, this is defined as the normal new operator. + +\wxheading{Include files} + + + + +\membersection{wxDynamicCast}\label{wxdynamiccast} + +\func{classname *}{wxDynamicCast}{ptr, classname} + +This macro returns the pointer {\it ptr} cast to the type {\it classname *} if +the pointer is of this type (the check is done during the run-time) or +{\tt NULL} otherwise. Usage of this macro is preferred over obsoleted +wxObject::IsKindOf() function. + +The {\it ptr} argument may be {\tt NULL}, in which case {\tt NULL} will be +returned. + +Example: + +\begin{verbatim} + wxWindow *win = wxWindow::FindFocus(); + wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); + if ( text ) + { + // a text control has the focus... + } + else + { + // no window has the focus or it is not a text control + } +\end{verbatim} + +\wxheading{See also} + +\helpref{RTTI overview}{runtimeclassoverview}\\ +\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\ +\helpref{wxConstCast}{wxconstcast}\\ +\helpref{wxStaticCast}{wxstaticcast} + + +\membersection{wxDynamicCastThis}\label{wxdynamiccastthis} + +\func{classname *}{wxDynamicCastThis}{classname} + +This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the +latter provokes spurious compilation warnings from some compilers (because it +tests whether {\tt this} pointer is non {\tt NULL} which is always true), so +this macro should be used to avoid them. + +\wxheading{See also} + +\helpref{wxDynamicCast}{wxdynamiccast} + + +\membersection{wxStaticCast}\label{wxstaticcast} + +\func{classname *}{wxStaticCast}{ptr, classname} + +This macro checks that the cast is valid in debug mode (an assert failure will +result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the +result of executing an equivalent of {\tt static\_cast(ptr)}. + +\wxheading{See also} + +\helpref{wx\_static\_cast}{wxstaticcastraw}\\ +\helpref{wxDynamicCast}{wxdynamiccast}\\ +\helpref{wxConstCast}{wxconstcast} + + +\membersection{wx\_const\_cast}\label{wxconstcastraw} + +\func{T}{wx\_const\_cast}{T, x} + +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{See also} + +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ +\helpref{wx\_static\_cast}{wxstaticcastraw} + + +\membersection{wx\_reinterpret\_cast}\label{wxreinterpretcastraw} + +\func{T}{wx\_reinterpret\_cast}{T, x} + +Same as \texttt{reinterpret\_cast(x)} if the compiler supports reinterpret cast or +\texttt{(T)x} for old compilers. + +\wxheading{See also} + +\helpref{wx\_const\_cast}{wxconstcastraw},\\ +\helpref{wx\_static\_cast}{wxstaticcastraw} + + +\membersection{wx\_static\_cast}\label{wxstaticcastraw} + +\func{T}{wx\_static\_cast}{T, x} + +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} + +\helpref{wx\_const\_cast}{wxconstcastraw},\\ +\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\ +\helpref{wx\_truncate\_cast}{wxtruncatecast} + + +\membersection{wx\_truncate\_cast}\label{wxtruncatecast} + +\func{T}{wx\_truncate\_cast}{T, x} + +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. + +\wxheading{See also} + +\helpref{wx\_static\_cast}{wxstaticcastraw} + + +\section{Log functions}\label{logfunctions} + +These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for +further information. The functions use (implicitly) the currently active log +target, so their descriptions here may not apply if the log target is not the +standard one (installed by wxWidgets in the beginning of the program). + +\wxheading{Include files} + + + + +\membersection{::wxDebugMsg}\label{wxdebugmsg} \func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}} +{\bf NB:} This function is now obsolete, replaced by \helpref{Log +functions}{logfunctions} and \helpref{wxLogDebug}{wxlogdebug} in particular. + Display a debugging message; under Windows, this will appear on the -debugger command window, and under UNIX, it will be written to standard +debugger command window, and under Unix, it will be written to standard error. The syntax is identical to {\bf printf}: pass a format string and a variable list of arguments. -Note that under Windows, you can see the debugging messages without a -debugger if you have the DBWIN debug log application that comes with -Microsoft C++. - {\bf Tip:} under Windows, if your application crashes before the message appears in the debugging window, put a wxYield call after each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s (at least for Watcom C++): preformat your messages and use OutputDebugString instead. -\membersection{::wxDisplaySize} +\wxheading{Include files} -\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}} + -Gets the physical size of the display in pixels. -\membersection{::wxEntry}\label{wxentry} +\membersection{::wxError}\label{wxerror} -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. See also \helpref{wxCleanUp}{wxcleanup}. +\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Internal Error"}} -\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}} +{\bf NB:} This function is now obsolete, please use \helpref{wxLogError}{wxlogerror} +instead. -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. +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}. -\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance}, - \param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}} +\wxheading{Include files} -wxWindows initialization under Windows (for applications constructed as a DLL). + -\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}} -wxWindows initialization under UNIX. +\membersection{::wxFatalError}\label{wxfatalerror} -\membersection{::wxError}\label{wxerror} +\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWidgets Fatal Error"}} -\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}} +{\bf NB:} This function is now obsolete, please use +\helpref{wxLogFatalError}{wxlogfatalerror} instead. -Displays {\it msg} and continues. This writes to standard error under -UNIX, and pops up a message box under Windows. Used for internal -wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}. +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}. -\membersection{::wxEndBusyCursor}\label{wxendbusycursor} +\wxheading{Include files} -\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}. +\membersection{::wxLogError}\label{wxlogerror} -\membersection{::wxExecute}\label{wxexecute} +\func{void}{wxLogError}{\param{const char *}{formatString}, \param{...}{}} -\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} +\func{void}{wxVLogError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -\func{long}{wxExecute}{\param{const wxString\& *}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}} +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. -Executes another program in UNIX or Windows. -The first form takes a command string, such as {\tt "emacs file.txt"}. +\membersection{::wxLogFatalError}\label{wxlogfatalerror} -The second form takes an array of values: a command, any number of -arguments, terminated by NULL. +\func{void}{wxLogFatalError}{\param{const char *}{formatString}, \param{...}{}} -If {\it sync} is FALSE (the default), flow of control immediately returns. -If TRUE, the current application waits until the other program has terminated. +\func{void}{wxVLogFatalError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -If execution is asynchronous, the return value is the process id, -otherwise it is a status value. A zero value indicates that the command could not -be executed. +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. -If callback isn't NULL and if execution is asynchronous, -\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when -the process finishes. -See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}. +\membersection{::wxLogWarning}\label{wxlogwarning} -\membersection{::wxExit}\label{wxexit} +\func{void}{wxLogWarning}{\param{const char *}{formatString}, \param{...}{}} -\func{void}{wxExit}{\void} +\func{void}{wxVLogWarning}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -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}. +For warnings - they are also normally shown to the user, but don't interrupt +the program work. -\membersection{::wxFatalError}\label{wxfatalerror} -\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}} +\membersection{::wxLogMessage}\label{wxlogmessage} -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}. +\func{void}{wxLogMessage}{\param{const char *}{formatString}, \param{...}{}} -\membersection{::wxFindMenuItemId} +\func{void}{wxVLogMessage}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}} +For all normal, informational messages. They also appear in a message box by +default (but it can be changed). -Find a menu item identifier associated with the given frame's menu bar. +\membersection{::wxLogVerbose}\label{wxlogverbose} -\membersection{::wxFindWindowByLabel} +\func{void}{wxLogVerbose}{\param{const char *}{formatString}, \param{...}{}} -\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}} +\func{void}{wxVLogVerbose}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -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. +For verbose output. Normally, it is suppressed, but +might be activated if the user wishes to know more details about the program +progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}). -\membersection{::wxFindWindowByName}\label{wxfindwindowbyname} -\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}} +\membersection{::wxLogStatus}\label{wxlogstatus} -Find a window by its name (as given in a window constructor or {\bf Create} function call). -If {\it parent} is NULL, the search will start from all top-level -frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. -The search is recursive in both cases. +\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{...}{}} -If no such named window is found, {\bf wxFindWindowByLabel} is called. +\func{void}{wxVLogStatus}{\param{wxFrame *}{frame}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} -\membersection{::wxGetActiveWindow}\label{wxgetactivewindow} +\func{void}{wxLogStatus}{\param{const char *}{formatString}, \param{...}{}} -\func{wxWindow *}{wxGetActiveWindow}{\void} +\func{void}{wxVLogStatus}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -Gets the currently active window (Windows only). +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). -\membersection{::wxGetDisplayName}\label{wxgetdisplayname} +If the target frame doesn't have a statusbar, the message will be lost. -\func{wxString}{wxGetDisplayName}{\void} -Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}. +\membersection{::wxLogSysError}\label{wxlogsyserror} -\membersection{::wxGetHomeDir} +\func{void}{wxLogSysError}{\param{const char *}{formatString}, \param{...}{}} -\func{wxString}{wxGetHomeDir}{\param{const wxString\& }{buf}} +\func{void}{wxVLogSysError}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -Fills the buffer with a string representing the user's home directory (UNIX only). +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. -\membersection{::wxGetHostName} +\wxheading{See also} -\func{bool}{wxGetHostName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} +\helpref{wxSysErrorCode}{wxsyserrorcode}, +\helpref{wxSysErrorMsg}{wxsyserrormsg} -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''. -\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime} +\membersection{::wxLogDebug}\label{wxlogdebug} -\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = TRUE}} +\func{void}{wxLogDebug}{\param{const char *}{formatString}, \param{...}{}} -Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}. +\func{void}{wxVLogDebug}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -If {\it resetTimer} is TRUE (the default), the timer is reset to zero -by this call. +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). -See also \helpref{wxTimer}{wxtimer}. -\membersection{::wxGetFreeMemory} +\membersection{::wxLogTrace}\label{wxlogtrace} -\func{long}{wxGetFreeMemory}{\void} +\func{void}{wxLogTrace}{\param{const char *}{formatString}, \param{...}{}} -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. +\func{void}{wxVLogTrace}{\param{const char *}{formatString}, \param{va\_list }{argPtr}} -\membersection{::wxGetMousePosition} +\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}} -\func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}} +\func{void}{wxVLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} -Returns the mouse position in screen coordinates. +\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}} + +\func{void}{wxVLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{va\_list }{argPtr}} + +As {\bf wxLogDebug}, trace functions only do something in debug build and +expand to nothing in the release one. The reason for making +it a separate function from it is that usually there are a lot of trace +messages, so it might make sense to separate them from other debug messages. + +The trace messages also usually can be separated into different categories and +the second and third versions of this function only log the message if the +{\it mask} which it has is currently enabled in \helpref{wxLog}{wxlog}. This +allows to selectively trace only some operations and not others by changing +the value of the trace mask (possible during the run-time). + +For the second function (taking a string mask), the message is logged only if +the mask has been previously enabled by the call to +\helpref{AddTraceMask}{wxlogaddtracemask} 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} + +{\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). + +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. + +\begin{itemize}\itemsep=0pt +\item wxTraceMemAlloc: trace memory allocation (new/delete) +\item wxTraceMessages: trace window messages/X callbacks +\item wxTraceResAlloc: trace GDI resource allocation +\item wxTraceRefCount: trace various ref counting operations +\item wxTraceOleCalls: trace OLE method calls (Win32 only) +\end{itemize} + + +\membersection{::wxSafeShowMessage}\label{wxsafeshowmessage} + +\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}} + +This function shows a message to the user in a safe way and should be safe to +call even before the application has been initialized or if it is currently in +some other strange state (for example, about to crash). Under Windows this +function shows a message box using a native dialog instead of +\helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere +it simply prints the message to the standard output using the title as prefix. + +\wxheading{Parameters} + +\docparam{title}{The title of the message box shown to the user or the prefix +of the message string} + +\docparam{text}{The text to show to the user} + +\wxheading{See also} + +\helpref{wxLogFatalError}{wxlogfatalerror} + +\wxheading{Include files} + + + + +\membersection{::wxSysErrorCode}\label{wxsyserrorcode} + +\func{unsigned long}{wxSysErrorCode}{\void} + +Returns the error code from the last system call. This function uses +{\tt errno} on Unix platforms and {\tt GetLastError} under Win32. + +\wxheading{See also} + +\helpref{wxSysErrorMsg}{wxsyserrormsg}, +\helpref{wxLogSysError}{wxlogsyserror} + + +\membersection{::wxSysErrorMsg}\label{wxsyserrormsg} + +\func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}} + +Returns the error message corresponding to the given system error code. If +{\it errCode} is $0$ (default), the last error code (as returned by +\helpref{wxSysErrorCode}{wxsyserrorcode}) is used. + +\wxheading{See also} + +\helpref{wxSysErrorCode}{wxsyserrorcode}, +\helpref{wxLogSysError}{wxlogsyserror} + + +\membersection{WXTRACE}\label{trace} -\membersection{::wxGetOsVersion} +\wxheading{Include files} -\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}} + -Gets operating system version information. +\func{}{WXTRACE}{formatString, ...} -\begin{twocollist}\itemsep=0pt -\twocolitemruled{Platform}{Return tyes} -\twocolitem{Macintosh}{Return value is wxMACINTOSH.} -\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} +{\bf NB:} This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -\membersection{::wxGetResource}\label{wxgetresource} +Calls wxTrace with printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}} +\wxheading{Include files} -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{float *}{value}, \param{const wxString\& }{file = NULL}} + -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{long *}{value}, \param{const wxString\& }{file = NULL}} -\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{int *}{value}, \param{const wxString\& }{file = NULL}} +\membersection{WXTRACELEVEL}\label{tracelevel} -Gets a resource value from the resource database (for example, WIN.INI, or -.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used, -otherwise the specified file is used. +\func{}{WXTRACELEVEL}{level, formatString, ...} -Under X, if an application class (wxApp::wx\_class) 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. +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -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. +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. -See also \helpref{wxWriteResource}{wxwriteresource}. +\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{::wxTrace}\label{wxtrace} -\membersection{::wxGetUserName} +\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} -\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}} +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -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''. +Takes printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). -\membersection{::wxKill}\label{wxkill} +\wxheading{Include files} -\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}} + -Under UNIX (the only supported platform), equivalent to the UNIX kill function. -Returns 0 on success, -1 on failure. -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. +\membersection{::wxTraceLevel}\label{wxtracelevel} -\membersection{::wxInitClipboard}\label{wxinitclipboard} +\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} -\func{void}{wxInitClipboard}{\void} +{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}. -Initializes the generic clipboard system by creating an instance of -the class \helpref{wxClipboard}{wxclipboard}. +Takes printf-style variable argument syntax. Output +is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +The first argument should be the level at which this information is appropriate. +It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than +this value. -\membersection{::wxIPCCleanUp}\label{wxipccleanup} +\wxheading{Include files} -\func{void}{wxIPCCleanUp}{\void} + -Call this when your application is terminating, if you have -called \helpref{wxIPCInitialize}{wxipcinitialize}. -\membersection{::wxIPCInitialize}\label{wxipcinitialize} -\func{void}{wxIPCInitialize}{\void} +\section{Time functions}\label{timefunctions} -Initializes for interprocess communication operation. May -be called multiple times without harm. +The functions in this section deal with getting the current time and +starting/stopping the global timers. Please note that the timer functions are +deprecated because they work with one global timer only and +\helpref{wxTimer}{wxtimer} and/or \helpref{wxStopWatch}{wxstopwatch} classes +should be used instead. For retrieving the current time, you may also use +\helpref{wxDateTime::Now}{wxdatetimenow} or +\helpref{wxDateTime::UNow}{wxdatetimeunow} methods. -See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection} -and the relevant section of the user manual. -\membersection{::wxIsBusy}\label{wxisbusy} +\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime} -\func{bool}{wxIsBusy}{\void} +\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = true}} -Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp -\helpref{wxEndBusyCursor}{wxendbusycursor} calls. +Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}. -\membersection{::wxLoadUserResource}\label{wxloaduserresource} +If {\it resetTimer} is true (the default), the timer is reset to zero +by this call. -\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}} +See also \helpref{wxTimer}{wxtimer}. -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. +\wxheading{Include files} -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. +\membersection{::wxGetLocalTime}\label{wxgetlocaltime} -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}. +\func{long}{wxGetLocalTime}{\void} -This function is available under Windows only. +Returns the number of seconds since local time 00:00:00 Jan 1st 1970. -\membersection{::wxNow}\label{wxnow} +\wxheading{See also} -\func{wxString}{wxNow}{\void} +\helpref{wxDateTime::Now}{wxdatetimenow} -Returns a string representing the current date and time. +\wxheading{Include files} -\membersection{::wxPostDelete}\label{wxpostdelete} + -\func{void}{wxPostDelete}{\param{wxObject *}{object}} -Under X, 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 X will still send events to the window. +\membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis} -Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead. +\func{wxLongLong}{wxGetLocalTimeMillis}{\void} -\membersection{::wxSetDisplayName}\label{wxsetdisplayname} +Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. -\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}} +\wxheading{See also} -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. +\helpref{wxDateTime::Now}{wxdatetimenow},\\ +\helpref{wxLongLong}{wxlonglong} -See also \helpref{wxGetDisplayName}{wxgetdisplayname}. +\wxheading{Include files} -\membersection{::wxShell}\label{wxshell} + -\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}} -Executes a command in an interactive shell window. If no command is -specified, then just the shell is spawned. +\membersection{::wxGetUTCTime}\label{wxgetutctime} -See also \helpref{wxExecute}{wxexecute}. +\func{long}{wxGetUTCTime}{\void} -\membersection{::wxSleep} +Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. -\func{void}{wxSleep}{\param{int}{ secs}} +\wxheading{See also} -Under X, sleeps for the specified number of seconds. +\helpref{wxDateTime::Now}{wxdatetimenow} -\membersection{::wxStripMenuCodes} +\wxheading{Include files} -\func{void}{wxStripMenuCodes}{\param{const wxString\& }{in}, \param{const wxString\& }{out}} + -Strips any menu codes from {\it in} and places the result -in {\it out}. Menu codes include \& (mark the next character with an underline -as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows). -\membersection{::wxStartTimer}\label{wxstarttimer} +\membersection{::wxMicroSleep}\label{wxmicrosleep} -\func{void}{wxStartTimer}{\void} +\func{void}{wxMicroSleep}{\param{unsigned long}{ microseconds}} -Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time. +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$). -See also \helpref{wxTimer}{wxtimer}. +\wxheading{Include files} -\membersection{::wxToLower}\label{wxtolower} + -\func{char}{wxToLower}{\param{char }{ch}} -Converts the character to lower case. This is implemented as a macro for efficiency. +\membersection{::wxMilliSleep}\label{wxmillisleep} -\membersection{::wxToUpper}\label{wxtoupper} +\func{void}{wxMilliSleep}{\param{unsigned long}{ milliseconds}} -\func{char}{wxToUpper}{\param{char }{ch}} +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. -Converts the character to upper case. This is implemented as a macro for efficiency. +\wxheading{Include files} -\membersection{::wxTrace}\label{wxtrace} + -\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}} -Takes printf-style variable argument syntax. Output -is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +\membersection{::wxNow}\label{wxnow} -\membersection{::wxTraceLevel}\label{wxtracelevel} +\func{wxString}{wxNow}{\void} -\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}} +Returns a string representing the current date and time. -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{::wxWriteResource}\label{wxwriteresource} + -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}} -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{float }{value}, \param{const wxString\& }{file = NULL}} +\membersection{::wxSleep}\label{wxsleep} -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{long }{value}, \param{const wxString\& }{file = NULL}} +\func{void}{wxSleep}{\param{int}{ secs}} -\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry}, - \param{int }{value}, \param{const wxString\& }{file = NULL}} +Sleeps for the specified number of seconds. -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. +\wxheading{Include files} -Under X, the resource databases are cached until the internal function -\rtfsp{\bf wxFlushResources} is called automatically on exit, when -all updated resource databases are written to their files. + -Note that it is considered bad manners to write to the .Xdefaults -file under UNIX, although the WIN.INI file is fair game under Windows. -See also \helpref{wxGetResource}{wxgetresource}. +\membersection{::wxStartTimer}\label{wxstarttimer} -\membersection{::wxYield} +\func{void}{wxStartTimer}{\void} -\func{bool}{wxYield}{\void} +Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time. -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. +See also \helpref{wxTimer}{wxtimer}. -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. +\wxheading{Include files} -\section{Macros}\label{macros} + -These macros are defined in wxWindows. -\membersection{CLASSINFO}\label{classinfo} +\membersection{::wxUsleep}\label{wxusleep} -\func{wxClassInfo *}{CLASSINFO}{className} +\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}} -Returns a pointer to the wxClassInfo object associated with this class. +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. -\membersection{WXDEBUG\_NEW}\label{debugnew} -\func{}{WXDEBUG\_NEW}{arg} -This is defined in debug mode to be call the redefined new operator -with filename and line number arguments. The definition is: +\section{Debugging macros and functions}\label{debugmacros} -\begin{verbatim} -#define WXDEBUG_NEW new(__FILE__,__LINE__) -\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. -In non-debug mode, this is defined as the normal new operator. +\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{::wxOnAssert}\label{wxonassert} -Example: +\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{func}, \param{const char *}{cond}, \param{const char *}{msg = NULL}} -\begin{verbatim} -class wxCommand: public wxObject -{ - DECLARE_ABSTRACT_CLASS(wxCommand) +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. - private: - ... - public: - ... -}; -\end{verbatim} +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{DECLARE\_APP}\label{declareapp} -\func{}{DECLARE\_APP}{className} +\membersection{wxASSERT}\label{wxassert} -This is used in headers to create a forward declaration of the wxGetApp function implemented -by IMPLEMENT\_APP. It creates the declaration {\tt className\& wxGetApp(void)}. +\func{}{wxASSERT}{\param{}{condition}} -Example: +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. -\begin{verbatim} - DECLARE_APP(MyApp) -\end{verbatim} +Please note that the condition in wxASSERT() should have no side effects +because it will not be executed in release mode at all. -\membersection{DECLARE\_CLASS} +\wxheading{See also} -\func{}{DECLARE\_CLASS}{className} +\helpref{wxASSERT\_MSG}{wxassertmsg},\\ +\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} -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. -\membersection{DECLARE\_DYNAMIC\_CLASS} +\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize} -\func{}{DECLARE\_DYNAMIC\_CLASS}{className} +\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}} -Used inside a class declaration to declare that the objects of this class should be dynamically -createable from run-time type information. +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. -Example: +You may use it like this, for example: \begin{verbatim} -class wxFrame: public wxWindow -{ - DECLARE_DYNAMIC_CLASS(wxFrame) + // we rely on the int being able to hold values up to 2^32 + wxASSERT_MIN_BITSIZE(int, 32); - private: - const wxString\& frameTitle; - public: - ... -}; + // can't work with the platforms using UTF-8 for wchar_t + wxASSERT_MIN_BITSIZE(wchar_t, 16); \end{verbatim} -\membersection{IMPLEMENT\_ABSTRACT\_CLASS} - -\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName} - -Used in a C++ implementation file to complete the declaration of -a class that has run-time type information. The same as IMPLEMENT\_CLASS. -Example: +\membersection{wxASSERT\_MSG}\label{wxassertmsg} -\begin{verbatim} -IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) +\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}} -wxCommand::wxCommand(void) -{ -... -} -\end{verbatim} +Assert macro with message. An error message will be generated if the condition is false. -\membersection{IMPLEMENT\_ABSTRACT\_CLASS2} +\wxheading{See also} -\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2} +\helpref{wxASSERT}{wxassert},\\ +\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert} -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. -\membersection{IMPLEMENT\_APP}\label{implementapp} +\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert} -\func{}{IMPLEMENT\_APP}{className} +\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}} -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 +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. -Old form: +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. -\begin{verbatim} - MyApp myApp; -\end{verbatim} +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. -New form: +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. -\begin{verbatim} - IMPLEMENT_APP(MyApp) -\end{verbatim} +\wxheading{See also} -See also \helpref{DECLARE\_APP}{declareapp}. +\helpref{wxASSERT\_MSG}{wxassertmsg},\\ +\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize} -\membersection{IMPLEMENT\_CLASS} -\func{}{IMPLEMENT\_CLASS}{className, baseClassName} +\membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2} -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. +\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}} -\membersection{IMPLEMENT\_CLASS2} +This macro is identical to \helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2} +except that it allows you to specify a unique {\it name} for the struct +internally defined by this macro to avoid getting the compilation errors +described \helpref{above}{wxcompiletimeassert}. -\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2} -Used in a C++ implementation file to complete the declaration of a -class that has run-time type information and two base classes. The -same as IMPLEMENT\_ABSTRACT\_CLASS2. +\membersection{wxFAIL}\label{wxfail} -\membersection{IMPLEMENT\_DYNAMIC\_CLASS} +\func{}{wxFAIL}{\void} -\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName} +Will always generate an assert error if this code is reached (in debug mode). -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. +See also: \helpref{wxFAIL\_MSG}{wxfailmsg} -Example: -\begin{verbatim} -IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) +\membersection{wxFAIL\_MSG}\label{wxfailmsg} -wxFrame::wxFrame(void) -{ -... -} -\end{verbatim} +\func{}{wxFAIL\_MSG}{\param{}{msg}} -\membersection{IMPLEMENT\_DYNAMIC\_CLASS2} +Will always generate an assert error with specified message if this code is reached (in debug mode). -\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2} +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. -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{See also} -\membersection{WXTRACE}\label{trace} +\helpref{wxFAIL}{wxfail} -\func{}{WXTRACE}{formatString, ...} -Calls wxTrace with printf-style variable argument syntax. Output -is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}). +\membersection{wxCHECK}\label{wxcheck} -\membersection{WXTRACELEVEL}\label{tracelevel} +\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}} -\func{}{WXTRACELEVEL}{level, formatString, ...} +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. -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. -\section{wxWindows resource functions}\label{resourcefuncs} +\membersection{wxCHECK\_MSG}\label{wxcheckmsg} -\overview{wxWindows resource system}{resourceformats} +\func{}{wxCHECK\_MSG}{\param{}{condition}, \param{}{retValue}, \param{}{msg}} -This section details functions for manipulating wxWindows (.WXR) resource -files and loading user interface elements from resources. +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. -\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.} +This macro may be only used in non void functions, see also +\helpref{wxCHECK\_RET}{wxcheckret}. -\helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.} -See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for -loading from resource data. +\membersection{wxCHECK\_RET}\label{wxcheckret} -\membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier} +\func{}{wxCHECK\_RET}{\param{}{condition}, \param{}{msg}} -\func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}} +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. -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. +This macro should be used in void functions instead of +\helpref{wxCHECK\_MSG}{wxcheckmsg}. -\membersection{::wxResourceClear} -\func{void}{wxResourceClear}{\void} +\membersection{wxCHECK2}\label{wxcheck2} -Clears the wxWindows resource table. +\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}} -\membersection{::wxResourceCreateBitmap} +Checks that the condition is true and \helpref{wxFAIL}{wxfail} and execute +{\it operation} if it is not. This is a generalisation of +\helpref{wxCHECK}{wxcheck} and may be used when something else than just +returning from the function must be done when the {\it condition} is false. -\func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}} +This check is done even in release mode. -Creates a new bitmap from a file, static data, or Windows resource, given a valid -wxWindows bitmap resource identifier. For example, if the .WXR file contains -the following: -\begin{verbatim} -static const wxString\& aiai_resource = "bitmap(name = 'aiai_resource',\ - bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\ - bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X'])."; -\end{verbatim} +\membersection{wxCHECK2\_MSG}\label{wxcheck2msg} -then this function can be called as follows: +\func{}{wxCHECK2}{\param{}{condition}, \param{}{operation}, \param{}{msg}} -\begin{verbatim} - wxBitmap *bitmap = wxResourceCreateBitmap("aiai_resource"); -\end{verbatim} +This is the same as \helpref{wxCHECK2}{wxcheck2}, but +\helpref{wxFAIL\_MSG}{wxfailmsg} with the specified {\it msg} is called +instead of wxFAIL() if the {\it condition} is false. -\membersection{::wxResourceCreateIcon} -\func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}} +\membersection{::wxTrap}\label{wxtrap} -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: +\func{void}{wxTrap}{\void} -\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} +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. -then this function can be called as follows: +In release mode this function does nothing. -\begin{verbatim} - wxIcon *icon = wxResourceCreateIcon("aiai_resource"); -\end{verbatim} +\wxheading{Include files} -\membersection{::wxResourceCreateMenuBar} + -\func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}} -Creates a new menu bar given a valid wxWindows menubar resource -identifier. For example, if the .WXR file contains the following: -\begin{verbatim} -static const wxString\& menuBar11 = "menu(name = 'menuBar11',\ - menu = \ - [\ - ['&File', 1, '', \ - ['&Open File', 2, 'Open a file'],\ - ['&Save File', 3, 'Save a file'],\ - [],\ - ['E&xit', 4, 'Exit program']\ - ],\ - ['&Help', 5, '', \ - ['&About', 6, 'About this program']\ - ]\ - ])."; -\end{verbatim} +\membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning} -then this function can be called as follows: +\func{bool}{wxIsDebuggerRunning}{\void} -\begin{verbatim} - wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11"); -\end{verbatim} +Returns \true if the program is running under debugger, \false otherwise. +Please note that this function is currently only implemented for Win32 and Mac +builds using CodeWarrior and always returns \false elsewhere. -\membersection{::wxResourceGetIdentifier} -\func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}} -Used for retrieving the integer value associated with an identifier. -A zero value indicates that the identifier was not found. -See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}. +\section{Environment access functions}\label{environfunctions} -\membersection{::wxResourceParseData}\label{wxresourcedata} +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). -\func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} +% TODO add some stuff about env var inheriting but not propagating upwards (VZ) -Parses a string containing one or more wxWindows resource objects. If -the resource objects are global static data that are included into the -C++ program, then this function must be called for each variable -containing the resource data, to make it known to wxWindows. +\wxheading{Include files} -{\it resource} should contain data in the following form: + -\begin{verbatim} -dialog(name = 'dialog1', - style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE', - title = 'Test dialog box', - x = 312, y = 234, width = 400, height = 300, - modal = 0, - control = [wxGroupBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262, - [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]], - control = [wxMultiText, 'Multitext', 'wxVERTICAL_LABEL', 'multitext3', - 156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.', - [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0], - [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]). -\end{verbatim} -This function will typically be used after including a {\tt .wxr} file into -a C++ program as follows: +\membersection{wxGetenv}\label{wxgetenvmacro} -\begin{verbatim} -#include "dialog1.wxr" -\end{verbatim} +\func{wxChar *}{wxGetEnv}{\param{const wxString\&}{ var}} -Each of the contained resources will declare a new C++ variable, and each -of these variables should be passed to wxResourceParseData. +This is a macro defined as {\tt getenv()} or its wide char version in Unicode +mode. -\membersection{::wxResourceParseFile} +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{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}} -Parses a file containing one or more wxWindows resource objects -in C++-compatible syntax. Use this function to dynamically load -wxWindows resource data. +\membersection{wxGetEnv}\label{wxgetenv} -\membersection{::wxResourceParseString}\label{wxresourceparsestring} +\func{bool}{wxGetEnv}{\param{const wxString\&}{ var}, \param{wxString *}{value}} -\func{bool}{wxResourceParseString}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}} +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. -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. +Returns \true if the variable exists, \false otherwise. -{\it resource} should contain data with the following form: -\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} +\membersection{wxSetEnv}\label{wxsetenv} -This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to -load an entire {\tt .wxr file} into a string. +\func{bool}{wxSetEnv}{\param{const wxString\&}{ var}, \param{const wxChar *}{value}} -\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata} +Sets the value of the environment variable {\it var} (adding it if necessary) +to {\it value}. -\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width}, -\param{int }{height}, \param{wxResourceTable *}{table = NULL}} +Returns \true on success. -\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& *}{xpm\_data}} -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{wxUnsetEnv}\label{wxunsetenv} -\membersection{::wxResourceRegisterIconData} +\func{bool}{wxUnsetEnv}{\param{const wxString\&}{ var}} -Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}. +Removes the variable {\it var} from the environment. +\helpref{wxGetEnv}{wxgetenv} will return {\tt NULL} after the call to this +function. +Returns \true on success.