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