+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: function.tex
+%% Purpose: Functions and macros
+%% Author: wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets Team
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\chapter{Functions}\label{functions}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}
-The functions defined in wxWindows are described here.
+The functions and macros defined in wxWidgets are described here: you can
+either look up a function using the alphabetical listing of them or find it in
+the corresponding topic.
+
+\section{Alphabetical functions and macros list}\label{functionsalphabetically}
+
+\helpref{CLASSINFO}{classinfo}\\
+\helpref{copystring}{copystring}\\
+\helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\
+\helpref{DECLARE\_APP}{declareapp}\\
+\helpref{DECLARE\_CLASS}{declareclass}\\
+\helpref{DECLARE\_DYNAMIC\_CLASS}{declaredynamicclass}\\
+\helpref{IMPLEMENT\_ABSTRACT\_CLASS2}{implementabstractclass2}\\
+\helpref{IMPLEMENT\_ABSTRACT\_CLASS}{implementabstractclass}\\
+\helpref{IMPLEMENT\_APP}{implementapp}\\
+\helpref{IMPLEMENT\_CLASS2}{implementclass2}\\
+\helpref{IMPLEMENT\_CLASS}{implementclass}\\
+\helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\
+\helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\
+\helpref{wxAboutBox}{wxaboutbox}\\
+\helpref{wxASSERT}{wxassert}\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\
+\helpref{wxASSERT\_MSG}{wxassertmsg}\\
+\helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\
+\helpref{wxBell}{wxbell}\\
+\helpref{wxBITMAP}{wxbitmapmacro}\\
+\helpref{wxCHANGE\_UMASK}{wxchangeumask}\\
+\helpref{wxCHECK}{wxcheck}\\
+\helpref{wxCHECK2\_MSG}{wxcheck2msg}\\
+\helpref{wxCHECK2}{wxcheck2}\\
+\helpref{wxCHECK\_GCC\_VERSION}{wxcheckgccversion}\\
+\helpref{wxCHECK\_MSG}{wxcheckmsg}\\
+\helpref{wxCHECK\_RET}{wxcheckret}\\
+\helpref{wxCHECK\_VERSION}{wxcheckversion}\\
+\helpref{wxCHECK\_VERSION\_FULL}{wxcheckversionfull}\\
+\helpref{wxCHECK\_W32API\_VERSION}{wxcheckw32apiversion}\\
+\helpref{wxClientDisplayRect}{wxclientdisplayrect}\\
+\helpref{wxClipboardOpen}{functionwxclipboardopen}\\
+\helpref{wxCloseClipboard}{wxcloseclipboard}\\
+\helpref{wxColourDisplay}{wxcolourdisplay}\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\
+\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}\\
+\helpref{wxCONCAT}{wxconcat}\\
+\helpref{wxConcatFiles}{wxconcatfiles}\\
+\helpref{wxConstCast}{wxconstcast}\\
+\helpref{wxCopyFile}{wxcopyfile}\\
+\helpref{wxCreateDynamicObject}{wxcreatedynamicobject}\\
+\helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider}\\
+\helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}\\
+\helpref{wxCRIT\_SECT\_DECLARE\_MEMBER}{wxcritsectdeclaremember}\\
+\helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}\\
+\helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro}\\ % wxcs already taken!
+\helpref{wxDDECleanUp}{wxddecleanup}\\
+\helpref{wxDDEInitialize}{wxddeinitialize}\\
+\helpref{wxDROP\_ICON}{wxdropicon}\\
+\helpref{wxDebugMsg}{wxdebugmsg}\\
+\helpref{WXDEBUG\_NEW}{debugnew}\\
+\helpref{wxDirExists}{functionwxdirexists}\\
+\helpref{wxDirSelector}{wxdirselector}\\
+\helpref{wxDisplayDepth}{wxdisplaydepth}\\
+\helpref{wxDisplaySize}{wxdisplaysize}\\
+\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
+\helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
+\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
+\helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}\\
+\helpref{wxEmptyClipboard}{wxemptyclipboard}\\
+\helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\
+\helpref{wxEndBusyCursor}{wxendbusycursor}\\
+\helpref{wxENTER\_CRIT\_SECT}{wxentercritsect}\\
+\helpref{wxEntry}{wxentry}\\
+\helpref{wxEntryStart}{wxentrystart}\\
+\helpref{wxEntryCleanup}{wxentrycleanup}\\
+\helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\
+\helpref{wxError}{wxerror}\\
+\helpref{wxExecute}{wxexecute}\\
+\helpref{wxExit}{wxexit}\\
+\helpref{wxEXPLICIT}{wxexplicit}\\
+\helpref{wxFAIL\_MSG}{wxfailmsg}\\
+\helpref{wxFAIL}{wxfail}\\
+\helpref{wxFatalError}{wxfatalerror}\\
+\helpref{wxFileExists}{functionwxfileexists}\\
+\helpref{wxFileModificationTime}{wxfilemodificationtime}\\
+\helpref{wxFileNameFromPath}{wxfilenamefrompath}\\
+\helpref{wxFileSelector}{wxfileselector}\\
+\helpref{wxFindFirstFile}{wxfindfirstfile}\\
+\helpref{wxFindMenuItemId}{wxfindmenuitemid}\\
+\helpref{wxFindNextFile}{wxfindnextfile}\\
+\helpref{wxFindWindowAtPointer}{wxfindwindowatpointer}\\
+\helpref{wxFindWindowAtPoint}{wxfindwindowatpoint}\\
+\helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\
+\helpref{wxFindWindowByName}{wxfindwindowbyname}\\
+\helpref{wxFinite}{wxfinite}\\
+\helpref{wxGenericAboutBox}{wxgenericaboutbox}\\
+\helpref{wxGetActiveWindow}{wxgetactivewindow}\\
+\helpref{wxGetApp}{wxgetapp}\\
+\helpref{wxGetBatteryState}{wxgetbatterystate}\\
+\helpref{wxGetClipboardData}{wxgetclipboarddata}\\
+\helpref{wxGetClipboardFormatName}{wxgetclipboardformatname}\\
+\helpref{wxGetColourFromUser}{wxgetcolourfromuser}\\
+\helpref{wxGetCwd}{wxgetcwd}\\
+\helpref{wxGetDiskSpace}{wxgetdiskspace}\\
+\helpref{wxGetDisplayName}{wxgetdisplayname}\\
+\helpref{wxGetDisplaySize}{wxdisplaysize}\\
+\helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\
+\helpref{wxGetElapsedTime}{wxgetelapsedtime}\\
+\helpref{wxGetEmailAddress}{wxgetemailaddress}\\
+\helpref{wxGetEnv}{wxgetenv}\\
+\helpref{wxGetFileKind}{wxgetfilekind}\\
+\helpref{wxGetFontFromUser}{wxgetfontfromuser}\\
+\helpref{wxGetFreeMemory}{wxgetfreememory}\\
+\helpref{wxGetFullHostName}{wxgetfullhostname}\\
+\helpref{wxGetHomeDir}{wxgethomedir}\\
+\helpref{wxGetHostName}{wxgethostname}\\
+\helpref{wxGetKeyState}{wxgetkeystate}\\
+\helpref{wxGetLocalTimeMillis}{wxgetlocaltimemillis}\\
+\helpref{wxGetLocalTime}{wxgetlocaltime}\\
+\helpref{wxGetMousePosition}{wxgetmouseposition}\\
+\helpref{wxGetMouseState}{wxgetmousestate}\\
+\helpref{wxGetMultipleChoices}{wxgetmultiplechoices}\\
+\helpref{wxGetMultipleChoice}{wxgetmultiplechoice}\\
+\helpref{wxGetNumberFromUser}{wxgetnumberfromuser}\\
+\helpref{wxGetOSDirectory}{wxgetosdirectory}\\
+\helpref{wxGetOsDescription}{wxgetosdescription}\\
+\helpref{wxGetOsVersion}{wxgetosversion}\\
+\helpref{wxGetPasswordFromUser}{wxgetpasswordfromuser}\\
+\helpref{wxGetPowerType}{wxgetpowertype}\\
+\helpref{wxGetPrinterCommand}{wxgetprintercommand}\\
+\helpref{wxGetPrinterFile}{wxgetprinterfile}\\
+\helpref{wxGetPrinterMode}{wxgetprintermode}\\
+\helpref{wxGetPrinterOptions}{wxgetprinteroptions}\\
+\helpref{wxGetPrinterOrientation}{wxgetprinterorientation}\\
+\helpref{wxGetPrinterPreviewCommand}{wxgetprinterpreviewcommand}\\
+\helpref{wxGetPrinterScaling}{wxgetprinterscaling}\\
+\helpref{wxGetPrinterTranslation}{wxgetprintertranslation}\\
+\helpref{wxGetProcessId}{wxgetprocessid}\\
+\helpref{wxGetResource}{wxgetresource}\\
+\helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\
+\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\
+\helpref{wxGetSingleChoice}{wxgetsinglechoice}\\
+\helpref{wxGetTempFileName}{wxgettempfilename}\\
+\helpref{wxGetTextFromUser}{wxgettextfromuser}\\
+\helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\
+\helpref{wxGetTranslation}{wxgettranslation}\\
+\helpref{wxGetUTCTime}{wxgetutctime}\\
+\helpref{wxGetUserHome}{wxgetuserhome}\\
+\helpref{wxGetUserId}{wxgetuserid}\\
+\helpref{wxGetUserName}{wxgetusername}\\
+\helpref{wxGetWorkingDirectory}{wxgetworkingdirectory}\\
+\helpref{wxGetenv}{wxgetenvmacro}\\
+\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\
+\helpref{wxICON}{wxiconmacro}\\
+\helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\
+\helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\
+\helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\
+\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}\\
+\helpref{wxInitialize}{wxinitialize}\\
+\helpref{wxIsAbsolutePath}{wxisabsolutepath}\\
+\helpref{wxIsBusy}{wxisbusy}\\
+\helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\
+\helpref{wxIsDebuggerRunning}{wxisdebuggerrunning}\\
+\helpref{wxIsEmpty}{wxisempty}\\
+\helpref{wxIsMainThread}{wxismainthread}\\
+\helpref{wxIsNaN}{wxisnan}\\
+\helpref{wxIsPlatformLittleEndian}{wxisplatformlittleendian}\\
+\helpref{wxIsPlatform64Bit}{wxisplatform64bit}\\
+\helpref{wxIsWild}{wxiswild}\\
+\helpref{wxKill}{wxkill}\\
+\helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser}\\
+\helpref{wxLEAVE\_CRIT\_SECT}{wxleavecritsect}\\
+\helpref{wxLoadUserResource}{wxloaduserresource}\\
+\helpref{wxLogDebug}{wxlogdebug}\\
+\helpref{wxLogError}{wxlogerror}\\
+\helpref{wxLogFatalError}{wxlogfatalerror}\\
+\helpref{wxLogMessage}{wxlogmessage}\\
+\helpref{wxLogStatus}{wxlogstatus}\\
+\helpref{wxLogSysError}{wxlogsyserror}\\
+\helpref{wxLogTrace}{wxlogtrace}\\
+\helpref{wxLogVerbose}{wxlogverbose}\\
+\helpref{wxLogWarning}{wxlogwarning}\\
+\helpref{wxLL}{wxll}\\
+\helpref{wxLongLongFmtSpec}{wxlonglongfmtspec}\\
+\helpref{wxMakeMetafilePlaceable}{wxmakemetafileplaceable}\\
+\helpref{wxMatchWild}{wxmatchwild}\\
+\helpref{wxMessageBox}{wxmessagebox}\\
+\helpref{wxMilliSleep}{wxmillisleep}\\
+\helpref{wxMicroSleep}{wxmicrosleep}\\
+\helpref{wxMkdir}{wxmkdir}\\
+\helpref{wxMutexGuiEnter}{wxmutexguienter}\\
+\helpref{wxMutexGuiLeave}{wxmutexguileave}\\
+\helpref{wxNewId}{wxnewid}\\
+\helpref{wxNow}{wxnow}\\
+\helpref{wxOnAssert}{wxonassert}\\
+\helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}\\
+\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}\\
+\helpref{wxOpenClipboard}{wxopenclipboard}\\
+\helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\
+\helpref{wxPathOnly}{wxpathonly}\\
+\helpref{wxPLURAL}{wxplural}\\
+\helpref{wxPostDelete}{wxpostdelete}\\
+\helpref{wxPostEvent}{wxpostevent}\\
+\helpref{wxRegisterClipboardFormat}{wxregisterclipboardformat}\\
+\helpref{wxRegisterId}{wxregisterid}\\
+\helpref{wxRemoveFile}{wxremovefile}\\
+\helpref{wxRenameFile}{wxrenamefile}\\
+\helpref{wxRmdir}{wxrmdir}\\
+\helpref{wxSafeShowMessage}{wxsafeshowmessage}\\
+\helpref{wxSafeYield}{wxsafeyield}\\
+\helpref{wxSetClipboardData}{wxsetclipboarddata}\\
+\helpref{wxSetCursor}{wxsetcursor}\\
+\helpref{wxSetDisplayName}{wxsetdisplayname}\\
+\helpref{wxSetEnv}{wxsetenv}\\
+\helpref{wxSetPrinterCommand}{wxsetprintercommand}\\
+\helpref{wxSetPrinterFile}{wxsetprinterfile}\\
+\helpref{wxSetPrinterMode}{wxsetprintermode}\\
+\helpref{wxSetPrinterOptions}{wxsetprinteroptions}\\
+\helpref{wxSetPrinterOrientation}{wxsetprinterorientation}\\
+\helpref{wxSetPrinterPreviewCommand}{wxsetprinterpreviewcommand}\\
+\helpref{wxSetPrinterScaling}{wxsetprinterscaling}\\
+\helpref{wxSetPrinterTranslation}{wxsetprintertranslation}\\
+\helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\
+\helpref{wxShell}{wxshell}\\
+\helpref{wxShowTip}{wxshowtip}\\
+\helpref{wxShutdown}{wxshutdown}\\
+\helpref{wxSleep}{wxsleep}\\
+\helpref{wxSnprintf}{wxsnprintf}\\
+\helpref{wxSplitPath}{wxsplitfunction}\\
+\helpref{wxStartTimer}{wxstarttimer}\\
+\helpref{wxStaticCast}{wxstaticcast}\\
+\helpref{wxStrcmp}{wxstrcmp}\\
+\helpref{wxStricmp}{wxstricmp}\\
+\helpref{wxStringEq}{wxstringeq}\\
+\helpref{wxStringMatch}{wxstringmatch}\\
+\helpref{wxStringTokenize}{wxstringtokenize}\\
+\helpref{wxStripMenuCodes}{wxstripmenucodes}\\
+\helpref{wxStrlen}{wxstrlen}\\
+\helpref{wxSTRINGIZE}{wxstringize}\\
+\helpref{wxSTRINGIZE\_T}{wxstringizet}\\
+\helpref{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{wxsuppressgccprivatedtorwarning}\\
+\helpref{wxSysErrorCode}{wxsyserrorcode}\\
+\helpref{wxSysErrorMsg}{wxsyserrormsg}\\
+\helpref{wxT}{wxt}\\
+\helpref{wxTrace}{wxtrace}\\
+\helpref{WXTRACE}{trace}\\
+\helpref{wxTraceLevel}{wxtracelevel}\\
+\helpref{WXTRACELEVEL}{tracelevel}\\
+\helpref{wxTransferFileToStream}{wxtransferfiletostream}\\
+\helpref{wxTransferStreamToFile}{wxtransferstreamtofile}\\
+\helpref{wxTrap}{wxtrap}\\
+\helpref{wxULL}{wxull}\\
+\helpref{wxUninitialize}{wxuninitialize}\\
+\helpref{wxUnix2DosFilename}{wxunix2dosfilename}\\
+\helpref{wxUnsetEnv}{wxunsetenv}\\
+\helpref{wxUsleep}{wxusleep}\\
+\helpref{wxVaCopy}{wxvacopy}\\
+\helpref{wxVsnprintf}{wxvsnprintf}\\
+\helpref{wxWakeUpIdle}{wxwakeupidle}\\
+\helpref{wxWriteResource}{wxwriteresource}\\
+\helpref{wxYield}{wxyield}\\
+\helpref{wx\_const\_cast}{wxconstcastraw}\\
+\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\
+\helpref{wx\_static\_cast}{wxstaticcastraw}\\
+\helpref{wx\_truncate\_cast}{wxtruncatecast}\\
+\helpref{\_}{underscore}\\
+\helpref{\_T}{underscoret}
+\helpref{\_\_WXFUNCTION\_\_}{wxfunction}
+
+
+
+\section{Version macros}\label{versionfunctions}
+
+The following constants are defined in wxWidgets:
-\section{Thread functions}\label{threadfunctions}
+\begin{itemize}\itemsep=0pt
+\item {\tt wxMAJOR\_VERSION} is the major version of wxWidgets
+\item {\tt wxMINOR\_VERSION} is the minor version of wxWidgets
+\item {\tt wxRELEASE\_NUMBER} is the release number
+\item {\tt wxSUBRELEASE\_NUMBER} is the subrelease number which is $0$ for all
+official releases
+\end{itemize}
+
+For example, the values or these constants for wxWidgets 2.1.15 are 2, 1 and
+15.
+
+Additionally, {\tt wxVERSION\_STRING} is a user-readable string containing
+the full wxWidgets version and {\tt wxVERSION\_NUMBER} is a combination of the
+three version numbers above: for 2.1.15, it is 2115 and it is 2200 for
+wxWidgets 2.2.
+
+The subrelease number is only used for the sources in between official releases
+and so normally is not useful.
\wxheading{Include files}
-<wx/thread.h>
+<wx/version.h> or <wx/defs.h>
-\wxheading{See also}
-\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
+\membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion}
-\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
+\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}}
-\func{void}{wxMutexGuiEnter}{\void}
+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$.
-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 wxWidgets version is at
+least major.minor.release.
- // Call GUI here:
- my_window->DrawSomething();
+For example, to test if the program is compiled with wxWidgets 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{wxCHECK\_VERSION\_FULL}\label{wxcheckversionfull}
-\membersection{::wxMutexGuiLeave}\label{wxmutexguileave}
+\func{bool}{wxCHECK\_VERSION\_FULL}{\param{}{major, minor, release, subrel}}
-\func{void}{wxMutexGuiLeave}{\void}
+Same as \helpref{wxCHECK\_VERSION}{wxcheckversion} but also checks that
+\texttt{wxSUBRELEASE\_NUMBER} is at least \arg{subrel}.
-See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
-This function is only defined on platforms which support preemptive
-threads.
+\membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion}
-\section{File functions}\label{filefunctions}
+\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}}
-\wxheading{Include files}
+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$.
-<wx/utils.h>
-\wxheading{See also}
-\helpref{wxPathList}{wxpathlist}, \helpref{wxDir}{wxdir}, \helpref{wxFile}{wxfile}
+\section{Application initialization and termination}\label{appinifunctions}
-\membersection{::wxDirExists}
+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.
-\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
-Returns TRUE if the directory exists.
+\membersection{::wxEntry}\label{wxentry}
-\membersection{::wxDos2UnixFilename}
+This initializes wxWidgets in a platform-dependent way. Use this if you are not
+using the default wxWidgets entry code (e.g. main or WinMain). For example, you
+can initialize wxWidgets from an Microsoft Foundation Classes application using
+this function.
-\func{void}{Dos2UnixFilename}{\param{const wxString\& }{s}}
+The following overload of wxEntry is available under all platforms:
-Converts a DOS to a Unix filename by replacing backslashes with forward
-slashes.
+\func{int}{wxEntry}{\param{int\&}{ argc}, \param{wxChar **}{argv}}
-\membersection{::wxFileExists}
+Under MS Windows, an additional overload suitable for calling from
+\texttt{WinMain} is available:
-\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
+\func{int}{wxEntry}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}}
-Returns TRUE if the file exists. It also returns TRUE if the file is
-a directory.
+(notice that under Windows CE platform, and only there, the type of
+\arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in
+Unicode build).
-\membersection{::wxFileModificationTime}
+\wxheading{See also}
-\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}}
+\helpref{wxEntryStart}{wxentrystart}
-Returns time of last modification of given file.
+\wxheading{Remarks}
+To clean up wxWidgets, call wxApp::OnExit followed by the static function
+wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWidgets:
-\membersection{::wxFileNameFromPath}
+\begin{verbatim}
+int CTheApp::ExitInstance()
+{
+ // OnExit isn't called by CleanUp so must be called explicitly.
+ wxTheApp->OnExit();
+ wxApp::CleanUp();
-\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
+ return CWinApp::ExitInstance();
+}
+\end{verbatim}
-\func{char*}{wxFileNameFromPath}{\param{char* }{path}}
+\wxheading{Include files}
-Returns the filename for a full path. The second form returns a pointer to
-temporary storage that should not be deallocated.
+<wx/app.h>
-\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
-\func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}}
-This function does directory searching; returns the first file
-that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
-get the next matching file. Neither will report the current directory "." or the
-parent directory "..".
+\membersection{::wxEntryCleanup}\label{wxentrycleanup}
-{\it spec} may contain wildcards.
+\func{void}{wxEntryCleanup}{\void}
-{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
+Free resources allocated by a successful call to \helpref{wxEntryStart}{wxentrystart}.
-For example:
+\wxheading{Include files}
-\begin{verbatim}
- wxString f = wxFindFirstFile("/home/project/*.*");
- while ( !f.IsEmpty() )
- {
- ...
- f = wxFindNextFile();
- }
-\end{verbatim}
+<wx/init.h>
-\membersection{::wxFindNextFile}\label{wxfindnextfile}
-\func{wxString}{wxFindNextFile}{\void}
+\membersection{::wxEntryStart}\label{wxentrystart}
-Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
+\func{bool}{wxEntryStart}{\param{int\&}{ argc}, \param{wxChar **}{argv}}
-See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
+This function can be used to perform the initialization of wxWidgets if you
+can't use the default initialization code for any reason.
-\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
+If the function returns \true, the initialization was successful and the global
+\helpref{wxApp}{wxapp} object \texttt{wxTheApp} has been created. Moreover,
+\helpref{wxEntryCleanup}{wxentrycleanup} must be called afterwards. If the
+function returns \false, a catastrophic initialization error occured and (at
+least the GUI part of) the library can't be used at all.
-\func{wxString}{wxGetOSDirectory}{\void}
+Notice that parameters \arg{argc} and \arg{argv} may be modified by this
+function.
-Returns the Windows directory under Windows; on other platforms returns the empty string.
+\wxheading{Include files}
-\membersection{::wxIsAbsolutePath}
+<wx/init.h>
-\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
-Returns TRUE if the argument is an absolute filename, i.e. with a slash
-or drive name at the beginning.
+\membersection{::wxGetApp}\label{wxgetapp}
-\membersection{::wxPathOnly}
+\func{wxAppDerivedClass\&}{wxGetApp}{\void}
-\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
+This function doesn't exist in wxWidgets but it is created by using
+the \helpref{IMPLEMENT\_APP}{implementapp} macro. Thus, before using it
+anywhere but in the same module where this macro is used, you must make it
+available using \helpref{DECLARE\_APP}{declareapp}.
-Returns the directory part of the filename.
+The advantage of using this function compared to directly using the global
+wxTheApp pointer is that the latter is of type {\tt wxApp *} and so wouldn't
+allow you to access the functions specific to your application class but not
+present in wxApp while wxGetApp() returns the object of the right type.
-\membersection{::wxUnix2DosFilename}
-\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
+\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions}
-Converts a Unix to a DOS filename by replacing forward
-slashes with backslashes.
+\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = true}}
-\membersection{::wxConcatFiles}
+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.
-\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
-\param{const wxString\& }{file3}}
-Concatenates {\it file1} and {\it file2} to {\it file3}, returning
-TRUE if successful.
+\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
-\membersection{::wxCopyFile}
+\func{void}{wxInitAllImageHandlers}{\void}
-\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
+Initializes all available image handlers. For a list of available handlers,
+see \helpref{wxImage}{wximage}.
-Copies {\it file1} to {\it file2}, returning TRUE if successful.
+\wxheading{See also}
-\membersection{::wxGetCwd}\label{wxgetcwd}
+\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
-\func{wxString}{wxGetCwd}{\void}
+\wxheading{Include files}
-Returns a string containing the current (or working) directory.
+<wx/image.h>
-\membersection{::wxGetWorkingDirectory}
-\func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
+\membersection{::wxInitialize}\label{wxinitialize}
-This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
+\func{bool}{wxInitialize}{\void}
-Copies the current working directory into the buffer if supplied, or
-copies the working directory into new storage (which you must delete yourself)
-if the buffer is NULL.
+This function is used in wxBase only and only if you don't create
+\helpref{wxApp}{wxapp} object at all. In this case you must call it from your
+{\tt main()} function before calling any other wxWidgets functions.
-{\it sz} is the size of the buffer if supplied.
+If the function returns \false the initialization could not be performed,
+in this case the library cannot be used and
+\helpref{wxUninitialize}{wxuninitialize} shouldn't be called neither.
-\membersection{::wxGetTempFileName}
+This function may be called several times but
+\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
+call to this function.
-\func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}}
+\wxheading{Include files}
-\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
+<wx/app.h>
-Makes a temporary filename based on {\it prefix}, opens and closes the file,
-and places the name in {\it buf}. If {\it buf} is NULL, new store
-is allocated for the temporary filename using {\it new}.
-Under Windows, the filename will include the drive and name of the
-directory allocated for temporary files (usually the contents of the
-TEMP variable). Under Unix, the {\tt /tmp} directory is used.
+\membersection{::wxSafeYield}\label{wxsafeyield}
-It is the application's responsibility to create and delete the file.
+\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}, \param{bool}{
+ onlyIfNeeded = false}}
-\membersection{::wxIsWild}\label{wxiswild}
+This function is similar to wxYield, except that it disables the user input to
+all program windows before calling wxYield and re-enables it again
+afterwards. If {\it win} is not NULL, this window will remain enabled,
+allowing the implementation of some limited user interaction.
-\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
+Returns the result of the call to \helpref{::wxYield}{wxyield}.
-Returns TRUE if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
+\wxheading{Include files}
-\membersection{::wxMatchWild}\label{wxmatchwild}
+<wx/utils.h>
-\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
-Returns TRUE if the {\it pattern}\/ matches the {\it text}\/; if {\it
-dot\_special}\/ is TRUE, filenames beginning with a dot are not matched
-with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
+\membersection{::wxUninitialize}\label{wxuninitialize}
-\membersection{::wxMkdir}
+\func{void}{wxUninitialize}{\void}
-\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
+This function is for use in console (wxBase) programs only. It must be called
+once for each previous successful call to \helpref{wxInitialize}{wxinitialize}.
-Makes the directory {\it dir}, returning TRUE if successful.
+\wxheading{Include files}
-{\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.
+<wx/app.h>
-\membersection{::wxRemoveFile}
-\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
+\membersection{::wxYield}\label{wxyield}
-Removes {\it file}, returning TRUE if successful.
+\func{bool}{wxYield}{\void}
-\membersection{::wxRenameFile}
+Calls \helpref{wxApp::Yield}{wxappyield}.
-\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
+This function is kept only for backwards compatibility. Please use
+the \helpref{wxApp::Yield}{wxappyield} method instead in any new code.
-Renames {\it file1} to {\it file2}, returning TRUE if successful.
+\wxheading{Include files}
-\membersection{::wxRmdir}
+<wx/app.h> or <wx/utils.h>
-\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{::wxWakeUpIdle}\label{wxwakeupidle}
-The {\it flags} parameter is reserved for future use.
+\func{void}{wxWakeUpIdle}{\void}
-\membersection{::wxSetWorkingDirectory}
+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}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
+\wxheading{Include files}
-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.
+<wx/app.h>
-\membersection{::wxSplitPath}\label{wxsplitfunction}
-\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
-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.
+\section{Process control functions}\label{processfunctions}
-wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
-Windows, however it will not consider backslashes as path separators under Unix (where backslash
-is a valid character in a filename).
+The functions in this section are used to launch or terminate the other
+processes.
-On entry, {\it fullname} should be non NULL (it may be empty though).
-On return, {\it path} contains the file path (without the trailing separator), {\it name}
-contains the file name and {\it ext} contains the file extension without leading dot. All
-three of them may be empty if the corresponding component is. The old contents of the
-strings pointed to by these parameters will be overwritten in any case (if the pointers
-are not NULL).
+\membersection{::wxExecute}\label{wxexecute}
-\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
-\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
+\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteCommand}}
-Copies the given file to {\it stream}. Useful when converting an old application to
-use streams (within the document/view framework, for example).
+\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
-Use of this function requires the file wx\_doc.h to be included.
+\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteArgs}}
-\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{int }{flags = 0}}
-\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
+\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdout} and it
+only takes the {\tt command} argument,
+and returns a 2-element list {\tt ( status, output )}, where {\tt output} is
+an array reference.}
-Copies the given stream to the file {\it filename}. Useful when converting an old application to
-use streams (within the document/view framework, for example).
+\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}, \param{int }{flags = 0}}
-Use of this function requires the file wx\_doc.h to be included.
+\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdoutStderr}
+and it only takes the {\tt command} argument,
+and returns a 3-element list {\tt ( status, output, errors )}, where
+{\tt output} and {\tt errors} are array references.}
-\section{Network functions}\label{networkfunctions}
+Executes another program in Unix or Windows.
-\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
+The first form takes a command string, such as {\tt "emacs file.txt"}.
-\func{wxString}{wxGetFullHostName}{\void}
+The second form takes an array of values: a command, any number of
+arguments, terminated by NULL.
-Returns the FQDN (fully qualified domain host name) or an empty string on
-error.
+The semantics of the third and fourth versions is different from the first two
+and is described in more details below.
-\wxheading{See also}
+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.
-\helpref{wxGetHostName}{wxgethostname}
+In the case of synchronous execution, the return value is the exit code of
+the process (which terminates by the moment the function returns) and will be
+$-1$ if the process couldn't be started and typically 0 if the process
+terminated successfully. Also, while waiting for the process to
+terminate, wxExecute will call \helpref{wxYield}{wxyield}. Because of this, by
+default this function disables all application windows to avoid unexpected
+reentrancies which could result from the users interaction with the program
+while the child process is running. If you are sure that it is safe to not
+disable the program windows, you may pass \texttt{wxEXEC\_NODISABLE} flag to
+prevent this automatic disabling from happening.
-\wxheading{Include files}
+For asynchronous execution, however, the return value is the process id and
+zero value indicates that the command could not be executed. As an added
+complication, the return value of $-1$ in this case indicates that we didn't
+launch a new process, but connected to the running one (this can only happen in
+case of using DDE under Windows for command execution). In particular, in this,
+and only this, case the calling code will not get the notification about
+process termination.
+
+If callback isn't NULL and if execution is asynchronous,
+\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
+the process finishes. Specifying this parameter also allows you to redirect the
+standard input and/or output of the process being launched by calling
+\helpref{Redirect}{wxprocessredirect}. If the child process IO is redirected,
+under Windows the process window is not shown by default (this avoids having to
+flush an unnecessary console for the processes which don't create any windows
+anyhow) but a {\tt wxEXEC\_NOHIDE} flag can be used to prevent this from
+happening, i.e. with this flag the child process window will be shown normally.
+
+Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure
+that the new process is a group leader (this will create a new session if
+needed). Calling \helpref{wxKill}{wxkill} passing wxKILL\_CHILDREN will
+kill this process as well as all of its children (except those which have
+started their own session).
-<wx/utils.h>
+Finally, you may use the third overloaded version of this function to execute
+a process (always synchronously, the contents of \arg{flags} is or'd with
+\texttt{wxEXEC\_SYNC}) and capture its output in the array \arg{output}. The
+fourth version adds the possibility to additionally capture the messages from
+standard error output in the \arg{errors} array.
-\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
+{\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.
-\func{bool}{wxGetEmailAddress}{\param{const wxString\& }{buf}, \param{int }{sz}}
+\wxheading{See also}
-Copies the user's email address into the supplied buffer, by
-concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
-and \helpref{wxGetUserId}{wxgetuserid}.
+\helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, \helpref{Exec sample}{sampleexec}.
-Returns TRUE if successful, FALSE otherwise.
+\wxheading{Parameters}
-\wxheading{Include files}
+\docparam{command}{The command to execute and any parameters to pass to it as a
+single string.}
-<wx/utils.h>
+\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.}
-\membersection{::wxGetHostName}\label{wxgethostname}
+\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},\rtfsp
+{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}}
-\func{wxString}{wxGetHostName}{\void}
+\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}}
-\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
+\wxheading{Include files}
-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.
+<wx/utils.h>
-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.
-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{::wxExit}\label{wxexit}
-\wxheading{See also}
+\func{void}{wxExit}{\void}
-\helpref{wxGetFullHostName}{wxgetfullhostname}
+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>
-\section{User identification}\label{useridfunctions}
-\membersection{::wxGetUserId}\label{wxgetuserid}
+\membersection{::wxKill}\label{wxkill}
-\func{wxString}{wxGetUserId}{\void}
+\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}, \param{int }{flags = 0}}
-\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
+Equivalent to the Unix kill function: send the given signal {\it sig} to the
+process with PID {\it pid}. The valid signal values are
-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).
+\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}
-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.
+{\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.
-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.
+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}
+
+The {\it flags} parameter can be wxKILL\_NOCHILDREN (the default),
+or wxKILL\_CHILDREN, in which case the child processes of this
+process will be killed too. Note that under Unix, for wxKILL\_CHILDREN
+to work you should have created the process by passing wxEXEC\_MAKE\_GROUP\_LEADER
+to wxExecute.
\wxheading{See also}
-\helpref{wxGetUserName}{wxgetusername}
+\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
+\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
+\helpref{Exec sample}{sampleexec}
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxGetUserName}\label{wxgetusername}
-
-\func{wxString}{wxGetUserName}{\void}
-
-\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
-
-This function returns the full user name (something like "Mr. John Smith").
-Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
-in the {\bf wxWindows} section of the WIN.INI file. If PenWindows
-is running, the entry {\bf Current} in the section {\bf User} of
-the PENWIN.INI file is used.
+\membersection{::wxGetProcessId}\label{wxgetprocessid}
-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.
+\func{unsigned long}{wxGetProcessId}{\void}
-\wxheading{See also}
+Returns the number uniquely identifying the current process in the system.
-\helpref{wxGetUserId}{wxgetuserid}
+If an error occurs, $0$ is returned.
\wxheading{Include files}
<wx/utils.h>
-\section{String functions}
-\membersection{::copystring}
+\membersection{::wxShell}\label{wxshell}
-\func{char*}{copystring}{\param{const char* }{s}}
+\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
-Makes a copy of the string {\it s} using the C++ new operator, so it can be
-deleted with the {\it delete} operator.
+Executes a command in an interactive shell window. If no command is
+specified, then just the shell is spawned.
-\membersection{::wxStringMatch}
+See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
-\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
- \param{bool}{ subString = TRUE}, \param{bool}{ exact = FALSE}}
-
-Returns TRUE if the substring {\it s1} is found within {\it s2},
-ignoring case if {\it exact} is FALSE. If {\it subString} is FALSE,
-no substring matching is done.
-
-\membersection{::wxStringEq}\label{wxstringeq}
-
-\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
-
-A macro defined as:
+\wxheading{Include files}
-\begin{verbatim}
-#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
-\end{verbatim}
+<wx/utils.h>
-\membersection{::IsEmpty}\label{isempty}
-\func{bool}{IsEmpty}{\param{const char *}{ p}}
+\membersection{::wxShutdown}\label{wxshutdown}
-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.
+\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}}
-\membersection{::Stricmp}\label{stricmp}
+This function shuts down or reboots the computer depending on the value of the
+{\it flags}. Please notice that doing this requires the corresponding access
+rights (superuser under Unix, {\tt SE\_SHUTDOWN} privilege under Windows NT)
+and that this function is only implemented under Unix and Win32.
-\func{int}{Stricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
+\wxheading{Parameters}
-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.
+\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}}
-This function complements the standard C function {\it strcmp()} which performs
-case-sensitive comparison.
+\wxheading{Returns}
-\membersection{::Strlen}\label{strlen}
+\true on success, \false if an error occurred.
-\func{size\_t}{Strlen}{\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 NULL pointer.
+<wx/utils.h>
-\membersection{::wxGetTranslation}\label{wxgettranslation}
-\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
-This function returns the translation of string {\it str} in the current
-\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
-message catalogs (see \helpref{i18n overview}{internationalization}), the
-original string is returned. In debug build, an error message is logged - this
-should help to find the strings which were not yet translated. As this function
-is used very often, an alternative syntax is provided: the \_() macro is
-defined as wxGetTranslation().
+\section{Thread functions}\label{threadfunctions}
-\membersection{::wxSnprintf}\label{wxsnprintf}
+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$).
-\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
+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.
-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.
+\wxheading{Include files}
-Returns the number of characters copied to the buffer or -1 if there is not
-enough space.
+<wx/thread.h>
\wxheading{See also}
-\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
+\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
-\membersection{::wxVsnprintf}\label{wxvsnprintf}
-\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argptr}}
-The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list}
-argument instead of arbitrary number of parameters.
+\membersection{wxCRIT\_SECT\_DECLARE}\label{wxcritsectdeclare}
-\wxheading{See also}
+\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}}
-\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
+This macro declares a (static) critical section object named {\it cs} if
+{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$.
-\section{Dialog functions}\label{dialogfunctions}
-Below are a number of convenience functions for getting input from the
-user or displaying messages. Note that in these functions the last three
-parameters are optional. However, it is recommended to pass a parent frame
-parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
-the front when the dialog box is popped up.
-\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
+\membersection{wxCRIT\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember}
-\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
- \param{size\_t }{currentTip}}
+\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}}
-This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
-used with \helpref{wxShowTip}{wxshowtip}.
+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.
-\docparam{filename}{The name of the file containing the tips, one per line}
-\docparam{currentTip}{The index of the first tip to show - normally this index
-is remembered between the 2 program runs.}
-\wxheading{See also}
-\helpref{Tips overview}{tipsoverview}
+\membersection{wxCRIT\_SECT\_LOCKER}\label{wxcritsectlocker}
-\wxheading{Include files}
+\func{}{wxCRIT\_SECT\_LOCKER}{\param{}{name}, \param{}{cs}}
-<wx/tipdlg.h>
+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{::wxFileSelector}\label{wxfileselector}
-\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
- \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\
- \param{const wxString\& }{wildcard = ``*.*''}, \param{int }{flags = 0}, \param{wxWindow *}{parent = ""},\\
- \param{int}{ x = -1}, \param{int}{ y = -1}}
-Pops up a file selector box. In Windows, this is the common file selector
-dialog. In X, this is a file selector box with the same functionality.
-The path and filename are distinct elements of a full file pathname.
-If path is empty, the current directory will be used. If filename is empty,
-no default filename will be supplied. The wildcard determines what files
-are displayed in the file selector, and file extension supplies a type
-extension for the required filename. Flags may be a combination of wxOPEN,
-wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, wxFILE\_MUST\_EXIST, wxMULTIPLE or 0.
+\membersection{wxCRITICAL\_SECTION}\label{wxcriticalsectionmacro}
-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.
+\func{}{wxCRITICAL\_SECTION}{\param{}{name}}
-The wildcard may be a specification for multiple types of file
-with a description for each, such as:
+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:
\begin{verbatim}
- "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
-\end{verbatim}
+int IncCount()
+{
+ static int s_counter = 0;
-The application must check for an empty return value (the user pressed
-Cancel). For example:
+ wxCRITICAL_SECTION(counter);
-\begin{verbatim}
-const wxString& s = wxFileSelector("Choose a file to open");
-if (s)
-{
- ...
+ return ++s_counter;
}
\end{verbatim}
-\wxheading{Include files}
+(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).
-<wx/filedlg.h>
-\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
-\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}}
+\membersection{wxENTER\_CRIT\_SECT}\label{wxentercritsect}
-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{}{wxENTER\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}}
-\wxheading{Parameters}
+This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if
+{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$.
-\docparam{parent}{The parent window for the colour selection dialog}
-\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
-\wxheading{Include files}
+\membersection{::wxIsMainThread}\label{wxismainthread}
-<wx/colordlg.h>
+\func{bool}{wxIsMainThread}{\void}
-\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
+Returns \true if this thread is the main one. Always returns \true if
+{\tt wxUSE\_THREADS} is $0$.
-\func{long}{wxGetNumberFromUser}{
- \param{const wxString\& }{message},
- \param{const wxString\& }{prompt},
- \param{const wxString\& }{caption},
- \param{long }{value},
- \param{long }{min = 0},
- \param{long }{max = 100},
- \param{wxWindow *}{parent = NULL},
- \param{const wxPoint\& }{pos = wxDefaultPosition}}
-Shows a dialog asking the user for numeric input. The dialogs title is set to
-{\it caption}, it contains a (possibly) multiline {\it message} above the
-single line {\it prompt} and the zone for entering the number.
-The number entered must be in the range {\it min}..{\it max} (both of which
-should be positive) and {\it value} is the initial value of it. If the user
-enters an invalid value or cancels the dialog, the function will return -1.
+\membersection{wxLEAVE\_CRIT\_SECT}\label{wxleavecritsect}
-Dialog is centered on its {\it parent} unless an explicit position is given in
-{\it pos}.
+\func{}{wxLEAVE\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}}
-\wxheading{Include files}
+This macro is equivalent to \helpref{cs.Leave()}{wxcriticalsectionleave} if
+{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$.
-<wx/textdlg.h>
-\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
-\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
- \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL}}
+\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
-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.
+\func{void}{wxMutexGuiEnter}{\void}
-\wxheading{Include files}
+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}.
-<wx/textdlg.h>
+Typically, these functions are used like this:
-\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
+\begin{verbatim}
+void MyThread::Foo(void)
+{
+ // before doing any GUI calls we must ensure that this thread is the only
+ // one doing it!
-\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}}
+ wxMutexGuiEnter();
-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.
+ // Call GUI here:
+ my_window->DrawSomething();
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+ 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/textdlg.h>
+This function is only defined on platforms which support preemptive
+threads.
-\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
-\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
- \param{int }{nsel}, \param{int *}{selection},
- \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
- \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
+\membersection{::wxMutexGuiLeave}\label{wxmutexguileave}
-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.
+\func{void}{wxMutexGuiLeave}{\void}
-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.
+See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
-If Cancel is pressed, -1 is returned.
+This function is only defined on platforms which support preemptive
+threads.
-{\it choices} is an array of {\it n} strings for the listbox.
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+
+\section{File functions}\label{filefunctions}
\wxheading{Include files}
-<wx/choicdlg.h>
+<wx/filefn.h>
-\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
+\wxheading{See also}
-\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}}
+\helpref{wxPathList}{wxpathlist}\\
+\helpref{wxDir}{wxdir}\\
+\helpref{wxFile}{wxfile}\\
+\helpref{wxFileName}{wxfilename}
-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.
-{\it choices} is an array of {\it n} strings for the listbox.
+\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename}
-If {\it centre} is TRUE, the message text (which may include new line characters)
-is centred; if FALSE, the message is left-justified.
+\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}}
-\wxheading{Include files}
+Converts a DOS to a Unix filename by replacing backslashes with forward
+slashes.
-<wx/choicdlg.h>
-\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
+\membersection{::wxFileExists}\label{functionwxfileexists}
-\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
- \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
- \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
+\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
-As {\bf wxGetSingleChoice} but returns the index representing the selected string.
-If the user pressed cancel, -1 is returned.
+Returns true if the file exists and is a plain file.
-\wxheading{Include files}
-<wx/choicdlg.h>
+\membersection{::wxFileModificationTime}\label{wxfilemodificationtime}
-\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
+\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}}
-\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
- \param{const wxString\& }{client\_data[]}, \param{wxWindow *}{parent = NULL}, \param{int}{ x = -1},\\
- \param{int}{ y = -1}, \param{bool}{ centre = TRUE}, \param{int }{width=150}, \param{int }{height=200}}
+Returns time of last modification of given file.
-As {\bf wxGetSingleChoice} but takes an array of client data pointers
-corresponding to the strings, and returns one of these pointers.
+The return value is $0$ if an error occured (e.g. file not found).
-\wxheading{Include files}
-<wx/choicdlg.h>
+\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath}
-\membersection{::wxMessageBox}\label{wxmessagebox}
+\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
-\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}}
+\func{char *}{wxFileNameFromPath}{\param{char *}{path}}
-General purpose message dialog. {\it style} may be a bit list of the
-following identifiers:
+{\bf NB:} This function is obsolete, please use
+\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
-\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}
+Returns the filename for a full path. The second form returns a pointer to
+temporary storage that should not be deallocated.
-The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
-For example:
+\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
-\begin{verbatim}
- ...
- int answer = wxMessageBox("Quit program?", "Confirm",
- wxYES_NO | wxCANCEL, main_frame);
- if (answer == wxYES)
- delete main_frame;
- ...
-\end{verbatim}
+\func{wxString}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}}
-{\it message} may contain newline characters, in which case the
-message will be split into separate lines, to cater for large messages.
+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 "..".
-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{Warning}
-\wxheading{Include files}
+As of wx 2.5.2, these functions are not thread-safe! (they use static variables). You probably want to use \helpref{wxDir::GetFirst}{wxdirgetfirst} or \helpref{wxDirTraverser}{wxdirtraverser} instead.
-<wx/msgdlg.h>
+{\it spec} may contain wildcards.
-\membersection{::wxShowTip}\label{wxshowtip}
+{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
-\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
- \param{wxTipProvider *}{tipProvider},
- \param{bool }{showAtStartup = TRUE}}
+For example:
-This function shows a "startup tip" to the user.
+\begin{verbatim}
+ wxString f = wxFindFirstFile("/home/project/*.*");
+ while ( !f.empty() )
+ {
+ ...
+ f = wxFindNextFile();
+ }
+\end{verbatim}
-\docparam{parent}{The parent window for the modal dialog}
-\docparam{tipProvider}{An object which is used to get the text of the tips.
-It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
+\membersection{::wxFindNextFile}\label{wxfindnextfile}
-\docparam{showAtStartup}{Should be TRUE if startup tips are shown, FALSE
-otherwise. This is used as the initial value for "Show tips at startup"
-checkbox which is shown in the tips dialog.}
+\func{wxString}{wxFindNextFile}{\void}
-\wxheading{See also}
+Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
-\helpref{Tips overview}{tipsoverview}
+See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
-\wxheading{Include files}
-<wx/tipdlg.h>
+\membersection{::wxGetDiskSpace}\label{wxgetdiskspace}
-\section{GDI functions}\label{gdifunctions}
+\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}}
-The following are relevant to the GDI (Graphics Device Interface).
+This function returns the total number of bytes and number of free bytes on
+the disk containing the directory {\it path} (it should exist). Both
+{\it total} and {\it free} parameters may be {\tt NULL} if the corresponding
+information is not needed.
-\wxheading{Include files}
+\wxheading{Returns}
-<wx/gdicmn.h>
+\true on success, \false if an error occurred (for example, the
+directory doesn't exist).
-\membersection{::wxColourDisplay}
+\wxheading{Portability}
-\func{bool}{wxColourDisplay}{\void}
+This function is implemented for Win32,
+Mac OS and generic Unix provided the system has {\tt statfs()} function.
-Returns TRUE if the display is colour, FALSE otherwise.
+This function first appeared in wxWidgets 2.3.2.
-\membersection{::wxDisplayDepth}
-\func{int}{wxDisplayDepth}{\void}
+\membersection{::wxGetFileKind}\label{wxgetfilekind}
-Returns the depth of the display (a value of 1 denotes a monochrome display).
+\func{wxFileKind}{wxGetFileKind}{\param{int }{fd}}
-\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
+\func{wxFileKind}{wxGetFileKind}{\param{FILE *}{fp}}
-\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
- \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
-
-Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
-makes it into a placeable metafile by prepending a header containing the given
-bounding box. The bounding box may be obtained from a device context after drawing
-into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
-
-In addition to adding the placeable metafile header, this function adds
-the equivalent of the following code to the start of the metafile data:
+Returns the type of an open file. Possible return values are:
\begin{verbatim}
- SetMapMode(dc, MM_ANISOTROPIC);
- SetWindowOrg(dc, minX, minY);
- SetWindowExt(dc, maxX - minX, maxY - minY);
-\end{verbatim}
-
-This simulates the wxMM\_TEXT mapping mode, which wxWindows assumes.
-
-Placeable metafiles may be imported by many Windows applications, and can be
-used in RTF (Rich Text Format) files.
-
-{\it scale} allows the specification of scale for the metafile.
+enum wxFileKind
+{
+ wxFILE_KIND_UNKNOWN,
+ wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets
+ wxFILE_KIND_TERMINAL, // a tty
+ wxFILE_KIND_PIPE // a pipe
+};
-This function is only available under Windows.
+\end{verbatim}
-\membersection{::wxSetCursor}\label{wxsetcursor}
+\wxheading{Include files}
-\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
+<wx/filefn.h>
-Globally sets the cursor; only has an effect in Windows and GTK.
-See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
-\section{Printer settings}\label{printersettings}
+\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
-These routines are obsolete and should no longer be used!
+\func{wxString}{wxGetOSDirectory}{\void}
-The following functions are used to control PostScript printing. Under
-Windows, PostScript output can only be sent to a file.
+Returns the Windows directory under Windows; on other platforms returns the empty string.
-\wxheading{Include files}
-<wx/dcps.h>
+\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath}
-\membersection{::wxGetPrinterCommand}
+\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
-\func{wxString}{wxGetPrinterCommand}{\void}
+Returns true if the argument is an absolute filename, i.e. with a slash
+or drive name at the beginning.
-Gets the printer command used to print a file. The default is {\tt lpr}.
-\membersection{::wxGetPrinterFile}
+\membersection{::wxDirExists}\label{functionwxdirexists}
-\func{wxString}{wxGetPrinterFile}{\void}
+\func{bool}{wxDirExists}{\param{const wxChar *}{dirname}}
-Gets the PostScript output filename.
+Returns true if \arg{dirname} exists and is a directory.
-\membersection{::wxGetPrinterMode}
-\func{int}{wxGetPrinterMode}{\void}
+\membersection{::wxPathOnly}\label{wxpathonly}
-Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
-The default is PS\_PREVIEW.
+\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
-\membersection{::wxGetPrinterOptions}
+Returns the directory part of the filename.
-\func{wxString}{wxGetPrinterOptions}{\void}
-Gets the additional options for the print command (e.g. specific printer). The default is nothing.
+\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename}
-\membersection{::wxGetPrinterOrientation}
+\func{void}{wxUnix2DosFilename}{\param{wxChar *}{s}}
-\func{int}{wxGetPrinterOrientation}{\void}
+This function is deprecated, use \helpref{wxFileName}{wxfilename} instead.
-Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+Converts a Unix to a DOS filename by replacing forward
+slashes with backslashes.
-\membersection{::wxGetPrinterPreviewCommand}
-\func{wxString}{wxGetPrinterPreviewCommand}{\void}
+\membersection{wxCHANGE\_UMASK}\label{wxchangeumask}
-Gets the command used to view a PostScript file. The default depends on the platform.
+\func{}{wxCHANGE\_UMASK}{\param{int }{mask}}
-\membersection{::wxGetPrinterScaling}
+Under Unix this macro changes the current process umask to the given value,
+unless it is equal to $-1$ in which case nothing is done, and restores it to
+the original value on scope exit. It works by declaring a variable which sets
+umask to \arg{mask} in its constructor and restores it in its destructor.
-\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
+Under other platforms this macro expands to nothing.
-Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
-\membersection{::wxGetPrinterTranslation}
+\membersection{::wxConcatFiles}\label{wxconcatfiles}
-\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
+\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
+\param{const wxString\& }{file3}}
-Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+Concatenates {\it file1} and {\it file2} to {\it file3}, returning
+true if successful.
-\membersection{::wxSetPrinterCommand}
-\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
+\membersection{::wxCopyFile}\label{wxcopyfile}
-Sets the printer command used to print a file. The default is {\tt lpr}.
+\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}}
-\membersection{::wxSetPrinterFile}
+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.
-\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
-Sets the PostScript output filename.
+\membersection{::wxGetCwd}\label{wxgetcwd}
-\membersection{::wxSetPrinterMode}
+\func{wxString}{wxGetCwd}{\void}
-\func{void}{wxSetPrinterMode}{\param{int }{mode}}
+Returns a string containing the current (or working) directory.
-Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
-The default is PS\_PREVIEW.
-\membersection{::wxSetPrinterOptions}
+\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory}
-\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
+\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}}
-Sets the additional options for the print command (e.g. specific printer). The default is nothing.
+{\bf NB:} This function is deprecated: use \helpref{wxGetCwd}{wxgetcwd} instead.
-\membersection{::wxSetPrinterOrientation}
+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.
-\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
+{\it sz} is the size of the buffer if supplied.
-Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
-\membersection{::wxSetPrinterPreviewCommand}
+\membersection{::wxGetTempFileName}\label{wxgettempfilename}
-\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
+\func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}}
-Sets the command used to view a PostScript file. The default depends on the platform.
+\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
-\membersection{::wxSetPrinterScaling}
+%% 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.
-\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
-Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
+\membersection{::wxIsWild}\label{wxiswild}
-\membersection{::wxSetPrinterTranslation}
+\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
-\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
+Returns true if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
-Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
-\section{Clipboard functions}\label{clipsboard}
+\membersection{::wxMatchWild}\label{wxmatchwild}
-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.
+\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
-\wxheading{Include files}
+Returns true if the \arg{pattern}\/ matches the {\it text}\/; if {\it
+dot\_special}\/ is true, filenames beginning with a dot are not matched
+with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
-<wx/clipbrd.h>
-\membersection{::wxClipboardOpen}
+\membersection{::wxMkdir}\label{wxmkdir}
-\func{bool}{wxClipboardOpen}{\void}
+\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
-Returns TRUE if this application has already opened the clipboard.
+Makes the directory \arg{dir}, returning true if successful.
-\membersection{::wxCloseClipboard}
+{\it perm} is the access mask for the directory for the systems on which it is
+supported (Unix) and doesn't have any effect on the other ones.
-\func{bool}{wxCloseClipboard}{\void}
-Closes the clipboard to allow other applications to use it.
+\membersection{::wxParseCommonDialogsFilter}\label{wxparsecommondialogsfilter}
-\membersection{::wxEmptyClipboard}
+\func{int}{wxParseCommonDialogsFilter}{\param{const wxString\& }{wildCard}, \param{wxArrayString\& }{descriptions}, \param{wxArrayString\& }{filters}}
-\func{bool}{wxEmptyClipboard}{\void}
+Parses the \arg{wildCard}, returning the number of filters.
+Returns 0 if none or if there's a problem.
+The arrays will contain an equal number of items found before the error.
+On platforms where native dialogs handle only one filter per entry,
+entries in arrays are automatically adjusted.
+\arg{wildCard} is in the form:
+\begin{verbatim}
+ "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
+\end{verbatim}
-Empties the clipboard.
+\membersection{::wxRemoveFile}\label{wxremovefile}
-\membersection{::wxEnumClipboardFormats}
+\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
-\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
+Removes \arg{file}, returning true if successful.
-Enumerates the formats found in a list of available formats that belong
-to the clipboard. Each call to this function specifies a known
-available format; the function returns the format that appears next in
-the list.
-{\it dataFormat} specifies a known format. If this parameter is zero,
-the function returns the first format in the list.
+\membersection{::wxRenameFile}\label{wxrenamefile}
-The return value specifies the next known clipboard data format if the
-function is successful. It is zero if the {\it dataFormat} parameter specifies
-the last format in the list of available formats, or if the clipboard
-is not open.
+\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}}
-Before it enumerates the formats function, an application must open the clipboard by using the
-wxOpenClipboard function.
+Renames \arg{file1} to \arg{file2}, returning true if successful.
-\membersection{::wxGetClipboardData}
+If \arg{overwrite} parameter is true (default), the destination file is
+overwritten if it exists, but if \arg{overwrite} is false, the functions fails
+in this case.
-\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
-Gets data from the clipboard.
+\membersection{::wxRmdir}\label{wxrmdir}
-{\it dataFormat} may be one of:
+\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
-\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}
+Removes the directory {\it dir}, returning true if successful. Does not work under VMS.
-The clipboard must have previously been opened for this call to succeed.
+The {\it flags} parameter is reserved for future use.
-\membersection{::wxGetClipboardFormatName}
-\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
+\membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory}
-Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
-length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
+\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
-\membersection{::wxIsClipboardFormatAvailable}
+Sets the current working directory, returning true if the operation succeeded.
+Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
-\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
-Returns TRUE if the given data format is available on the clipboard.
+\membersection{::wxSplitPath}\label{wxsplitfunction}
-\membersection{::wxOpenClipboard}
+\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
-\func{bool}{wxOpenClipboard}{\void}
+{\bf NB:} This function is obsolete, please use
+\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
-Opens the clipboard for passing data to it or getting data from it.
+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{::wxRegisterClipboardFormat}
+wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
+Windows, however it will not consider backslashes as path separators under Unix (where backslash
+is a valid character in a filename).
-\func{int}{wxRegisterClipboardFormat}{\param{const wxString\& }{formatName}}
+On entry, {\it fullname} should be non-NULL (it may be empty though).
-Registers the clipboard data format name and returns an identifier.
+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{::wxSetClipboardData}
-\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
+\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
-Passes data to the clipboard.
+\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
-{\it dataFormat} may be one of:
+Copies the given file to {\it stream}. Useful when converting an old application to
+use streams (within the document/view framework, for example).
-\begin{itemize}\itemsep=0pt
-\item wxCF\_TEXT or wxCF\_OEMTEXT: {\it data} is a null-terminated text string.
-\item wxCF\_BITMAP: {\it data} is a wxBitmap.
-\item wxCF\_DIB: {\it data} is a wxBitmap. The bitmap is converted to a DIB (device independent bitmap).
-\item wxCF\_METAFILE: {\it data} is a wxMetafile. {\it width} and {\it height} are used to give recommended dimensions.
-\end{itemize}
+\wxheading{Include files}
-The clipboard must have previously been opened for this call to succeed.
+<wx/docview.h>
-\section{Miscellaneous functions}\label{miscellany}
-\membersection{::wxNewId}
+\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
-\func{long}{wxNewId}{\void}
+\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
-Generates an integer identifier unique to this run of the program.
+Copies the given stream to the file {\it filename}. Useful when converting an old application to
+use streams (within the document/view framework, for example).
\wxheading{Include files}
-<wx/utils.h>
+<wx/docview.h>
-\membersection{::wxRegisterId}
-\func{void}{wxRegisterId}{\param{long}{ id}}
-Ensures that ids subsequently generated by {\bf NewId} do not clash with
-the given {\bf id}.
+\section{Network, user and OS functions}\label{networkfunctions}
-\wxheading{Include files}
+The functions in this section are used to retrieve information about the
+current computer and/or user characteristics.
-<wx/utils.h>
-\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
+\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
-\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
+\func{wxString}{wxGetEmailAddress}{\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.
+\func{bool}{wxGetEmailAddress}{\param{char * }{buf}, \param{int }{sz}}
-See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+Copies the user's email address into the supplied buffer, by
+concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
+and \helpref{wxGetUserId}{wxgetuserid}.
+
+Returns true if successful, false otherwise.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxBell}
-\func{void}{wxBell}{\void}
+\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
-Ring the system bell.
+\func{wxMemorySize}{wxGetFreeMemory}{\void}
+
+Returns the amount of free memory in bytes under environments which
+support it, and -1 if not supported or failed to perform measurement.
\wxheading{Include files}
<wx/utils.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{::wxGetFullHostName}\label{wxgetfullhostname}
-\membersection{::wxDDECleanUp}\label{wxddecleanup}
+\func{wxString}{wxGetFullHostName}{\void}
-\func{void}{wxDDECleanUp}{\void}
+Returns the FQDN (fully qualified domain host name) or an empty string on
+error.
-Called when wxWindows exits, to clean up the DDE system. This no longer needs to be
-called by the application.
+\wxheading{See also}
-See also \helpref{wxDDEInitialize}{wxddeinitialize}.
+\helpref{wxGetHostName}{wxgethostname}
\wxheading{Include files}
-<wx/dde.h>
+<wx/utils.h>
-\membersection{::wxDDEInitialize}\label{wxddeinitialize}
-\func{void}{wxDDEInitialize}{\void}
+\membersection{::wxGetHomeDir}\label{wxgethomedir}
-Initializes the DDE system. May be called multiple times without harm.
+\func{wxString}{wxGetHomeDir}{\void}
-This no longer needs to be called by the application: it will be called
-by wxWindows if necessary.
+Return the (current) user's home directory.
-See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},
-\helpref{wxDDECleanUp}{wxddecleanup}.
+\wxheading{See also}
+
+\helpref{wxGetUserHome}{wxgetuserhome}\\
+\helpref{wxStandardPaths}{wxstandardpaths}
\wxheading{Include files}
-<wx/dde.h>
+<wx/utils.h>
-\membersection{::wxDebugMsg}\label{wxdebugmsg}
-\func{void}{wxDebugMsg}{\param{const wxString\& }{fmt}, \param{...}{}}
+\membersection{::wxGetHostName}\label{wxgethostname}
-{\bf This function is deprecated, use \helpref{wxLogDebug}{wxlogdebug} instead!}
+\func{wxString}{wxGetHostName}{\void}
-Display a debugging message; under Windows, this will appear on the
-debugger command window, and under Unix, it will be written to standard
-error.
+\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
-The syntax is identical to {\bf printf}: pass a format string and a
-variable list of arguments.
+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.
-{\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.
+Under Windows or NT, this function first looks in the environment
+variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
+in the {\bf wxWidgets} section of the WIN.INI file is tried.
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+The first variant of this function returns the hostname if successful or an
+empty string otherwise. The second (deprecated) function returns true
+if successful, false otherwise.
-\wxheading{Include files}
+\wxheading{See also}
-<wx/utils.h>
+\helpref{wxGetFullHostName}{wxgetfullhostname}
-\membersection{::wxDisplaySize}
+\wxheading{Include files}
-\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
+<wx/utils.h>
-Gets the physical size of the display in pixels.
-\wxheading{Include files}
+\membersection{::wxGetOsDescription}\label{wxgetosdescription}
-<wx/gdicmn.h>
+\func{wxString}{wxGetOsDescription}{\void}
-\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
+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{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = TRUE}}
+\wxheading{See also}
-This function enables or disables all top level windows. It is used by
-\helpref{::wxSafeYield}{wxsafeyield}.
+\helpref{::wxGetOsVersion}{wxgetosversion}
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxEntry}\label{wxentry}
-
-This initializes wxWindows in a platform-dependent way. Use this if you
-are not using the default wxWindows entry code (e.g. main or WinMain). For example,
-you can initialize wxWindows from an Microsoft Foundation Classes application using
-this function.
-
-\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
- \param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = TRUE}}
-wxWindows initialization under Windows (non-DLL). If {\it enterLoop} is FALSE, the
-function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows
-message loop will be entered.
-
-\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{::wxGetOsVersion}\label{wxgetosversion}
-\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
+\func{wxOperatingSystemId}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
-wxWindows initialization under Unix.
+Gets the version and the operating system ID for currently running OS.
+See \helpref{wxPlatformInfo}{wxplatforminfo} for more details about wxOperatingSystemId.
-\wxheading{Remarks}
+\wxheading{See also}
-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:
+\helpref{::wxGetOsDescription}{wxgetosdescription},
+\helpref{wxPlatformInfo}{wxplatforminfo}
-\begin{verbatim}
-int CTheApp::ExitInstance()
-{
- // OnExit isn't called by CleanUp so must be called explicitly.
- wxTheApp->OnExit();
- wxApp::CleanUp();
+\wxheading{Include files}
- return CWinApp::ExitInstance();
-}
-\end{verbatim}
+<wx/utils.h>
-\wxheading{Include files}
-<wx/app.h>
+\membersection{::wxIsPlatformLittleEndian}\label{wxisplatformlittleendian}
-\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
+\func{bool}{wxIsPlatformLittleEndian}{\void}
-\func{void}{wxEndBusyCursor}{\void}
+Returns \true if the current platform is little endian (instead of big endian).
+The check is performed at run-time.
-Changes the cursor back to the original cursor, for all windows in the application.
-Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
+\wxheading{See also}
-See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
+\helpref{Byte order macros}{byteordermacros}
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxError}\label{wxerror}
-\func{void}{wxError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Internal Error"}}
+\membersection{::wxIsPlatform64Bit}\label{wxisplatform64bit}
-Displays {\it msg} and continues. This writes to standard error under
-Unix, and pops up a message box under Windows. Used for internal
-wxWindows errors. See also \helpref{wxFatalError}{wxfatalerror}.
+\func{bool}{wxIsPlatform64Bit}{\void}
+
+Returns \true if the operating system the program is running under is 64 bit.
+The check is performed at run-time and may differ from the value available at
+compile-time (at compile-time you can just check if {\tt sizeof(void*)==8})
+since the program could be running in emulation mode or in a mixed 32/64 bit system
+(bi-architecture operating system).
+
+Very important: this function is not 100\% reliable on some systems given the fact
+that there isn't always a standard way to do a reliable check on the OS architecture.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxExecute}\label{wxexecute}
-\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\membersection{::wxGetUserHome}\label{wxgetuserhome}
-\func{long}{wxExecute}{\param{char **}{argv}, \param{bool }{sync = FALSE}, \param{wxProcess *}{callback = NULL}}
+\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
-\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}}
+Returns the home directory for the given user. If the username is empty
+(default value), this function behaves like
+\helpref{wxGetHomeDir}{wxgethomedir}.
-Executes another program in Unix or Windows.
+\wxheading{Include files}
-The first form takes a command string, such as {\tt "emacs file.txt"}.
+<wx/utils.h>
-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{::wxGetUserId}\label{wxgetuserid}
-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{wxString}{wxGetUserId}{\void}
-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{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
-For asynchronous execution, however, the return value is the process id and
-zero value indicates that the command could not be executed.
+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 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.
+Under Windows or NT, this function first looks in the environment
+variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
+in the {\bf wxWidgets} section of the WIN.INI file is tried.
-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 first variant of this function returns the login name if successful or an
+empty string otherwise. The second (deprecated) function returns true
+if successful, false otherwise.
+
+\wxheading{See also}
-See also \helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess},
-\helpref{Exec sample}{sampleexec}.
+\helpref{wxGetUserName}{wxgetusername}
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxExit}\label{wxexit}
-
-\func{void}{wxExit}{\void}
-
-Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
-Should only be used in an emergency: normally the top-level frame
-should be deleted (after deleting all other frames) to terminate the
-application. See \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} and \helpref{wxApp}{wxapp}.
-
-\wxheading{Include files}
-
-<wx/app.h>
-\membersection{::wxFatalError}\label{wxfatalerror}
+\membersection{::wxGetUserName}\label{wxgetusername}
-\func{void}{wxFatalError}{\param{const wxString\& }{msg}, \param{const wxString\& }{title = "wxWindows Fatal Error"}}
+\func{wxString}{wxGetUserName}{\void}
-Displays {\it msg} and exits. This writes to standard error under Unix,
-and pops up a message box under Windows. Used for fatal internal
-wxWindows errors. See also \helpref{wxError}{wxerror}.
+\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}
-\wxheading{Include files}
+This function returns the full user name (something like "Mr. John Smith").
-<wx/utils.h>
+Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
+in the {\bf wxWidgets} section of the WIN.INI file. If PenWindows
+is running, the entry {\bf Current} in the section {\bf User} of
+the PENWIN.INI file is used.
-\membersection{::wxFindMenuItemId}
+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.
-\func{int}{wxFindMenuItemId}{\param{wxFrame *}{frame}, \param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
+\wxheading{See also}
-Find a menu item identifier associated with the given frame's menu bar.
+\helpref{wxGetUserId}{wxgetuserid}
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxFindWindowByLabel}
-\func{wxWindow *}{wxFindWindowByLabel}{\param{const wxString\& }{label}, \param{wxWindow *}{parent=NULL}}
-Find a window by its label. Depending on the type of window, the label may be a window title
-or panel item label. If {\it parent} is NULL, the search will start from all top-level
-frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy.
-The search is recursive in both cases.
+\section{String functions}\label{stringfunctions}
-\wxheading{Include files}
-<wx/utils.h>
+\membersection{::copystring}\label{copystring}
-\membersection{::wxFindWindowByName}\label{wxfindwindowbyname}
+\func{char *}{copystring}{\param{const char *}{s}}
-\func{wxWindow *}{wxFindWindowByName}{\param{const wxString\& }{name}, \param{wxWindow *}{parent=NULL}}
+Makes a copy of the string {\it s} using the C++ new operator, so it can be
+deleted with the {\it delete} operator.
-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.
+This function is deprecated, use \helpref{wxString}{wxstring} class instead.
-If no such named window is found, {\bf wxFindWindowByLabel} is called.
-\wxheading{Include files}
+\membersection{::wxGetTranslation}\label{wxgettranslation}
-<wx/utils.h>
+\func{const wxChar *}{wxGetTranslation}{\param{const wxChar* }{str},
+ \param{const wxChar* }{domain = NULL}}
-\membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
+\func{const wxChar *}{wxGetTranslation}{\param{const wxChar* }{str}, \param{const wxChar* }{strPlural}, \param{size\_t }{n},
+ \param{const wxChar* }{domain = NULL}}
-\func{wxWindow *}{wxGetActiveWindow}{\void}
+This function returns the translation of string {\it str} in the current
+\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
+message catalogs (see \helpref{internationalization overview}{internationalization}), the
+original string is returned. In debug build, an error message is logged -- this
+should help to find the strings which were not yet translated. If
+{\it domain} is specified then only that domain/catalog is searched
+for a matching string. As this function
+is used very often, an alternative (and also common in Unix world) syntax is
+provided: the \helpref{\_()}{underscore} macro is defined to do the same thing
+as wxGetTranslation.
-Gets the currently active window (Windows only).
+The second form is used when retrieving translation of string that has
+different singular and plural form in English or different plural forms in some
+other language. It takes two extra arguments: as above, \arg{str}
+parameter must contain the singular form of the string to be converted and
+is used as the key for the search in the catalog. The \arg{strPlural} parameter
+is the plural form (in English). The parameter \arg{n} is used to determine the
+plural form. If no message catalog is found \arg{str} is returned if `n == 1',
+otherwise \arg{strPlural}.
-\wxheading{Include files}
+See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150}
+for additional information on plural forms handling. For a shorter alternative
+see the \helpref{wxPLURAL()}{wxplural} macro.
-<wx/windows.h>
+Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}.
-\membersection{::wxGetDisplayName}\label{wxgetdisplayname}
+Note that this function is not suitable for literal strings in Unicode
+builds, since the literal strings must be enclosed into
+\helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them
+unrecognised by \texttt{xgettext}, and so they are not extracted to the message
+catalog. Instead, use the \helpref{\_()}{underscore} and
+\helpref{wxPLURAL}{wxplural} macro for all literal strings.
-\func{wxString}{wxGetDisplayName}{\void}
-Under X only, returns the current display name. See also \helpref{wxSetDisplayName}{wxsetdisplayname}.
+\membersection{::wxIsEmpty}\label{wxisempty}
-\wxheading{Include files}
+\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
-<wx/utils.h>
+Returns \true if the pointer is either {\tt NULL} or points to an empty
+string, \false otherwise.
-\membersection{::wxGetHomeDir}\label{wxgethomedir}
-\func{wxString}{wxGetHomeDir}{\void}
+\membersection{::wxStrcmp}\label{wxstrcmp}
-Return the (current) user's home directory.
+\func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}}
-\wxheading{See also}
+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.
-\helpref{wxGetUserHome}{wxgetuserhome}
+This function complements the standard C function {\it stricmp()} which performs
+case-insensitive comparison.
-\wxheading{Include files}
-<wx/utils.h>
+\membersection{::wxStricmp}\label{wxstricmp}
-\membersection{::wxGetElapsedTime}\label{wxgetelapsedtime}
+\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
-\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = 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-insensitive.
-Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
+This function complements the standard C function {\it strcmp()} which performs
+case-sensitive comparison.
-If {\it resetTimer} is TRUE (the default), the timer is reset to zero
-by this call.
-See also \helpref{wxTimer}{wxtimer}.
+\membersection{::wxStringEq}\label{wxstringeq}
-\wxheading{Include files}
+\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
-<wx/timer.h>
+{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead.
-\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
+A macro defined as:
-\func{long}{wxGetFreeMemory}{\void}
+\begin{verbatim}
+#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
+\end{verbatim}
-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{::wxStringMatch}\label{wxstringmatch}
-<wx/utils.h>
+\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
+ \param{bool}{ subString = true}, \param{bool}{ exact = false}}
-\membersection{::wxGetMousePosition}
+{\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
-\func{void}{wxGetMousePosition}{\param{int* }{x}, \param{int* }{y}}
+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.
-Returns the mouse position in screen coordinates.
-\wxheading{Include files}
+\membersection{::wxStringTokenize}\label{wxstringtokenize}
-<wx/utils.h>
+\func{wxArrayString}{wxStringTokenize}{\param{const wxString\& }{str},\\
+ \param{const wxString\& }{delims = wxDEFAULT\_DELIMITERS},\\
+ \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
-\membersection{::wxGetOsDescription}\label{wxgetosdescription}
+This is a convenience function wrapping
+\helpref{wxStringTokenizer}{wxstringtokenizer} which simply returns all tokens
+found in the given \arg{str} in an array.
-\func{wxString}{wxGetOsDescription}{\void}
+Please see
+\helpref{wxStringTokenizer::wxStringTokenizer}{wxstringtokenizerwxstringtokenizer}
+for the description of the other parameters.
-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}
+\membersection{::wxStrlen}\label{wxstrlen}
-\helpref{::wxGetOsVersion}{wxgetosversion}
+\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{::wxGetOsVersion}\label{wxgetosversion}
+\membersection{::wxSnprintf}\label{wxsnprintf}
-\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
+\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
-Gets operating system version information.
+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.
-\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}
+Returns the number of characters copied to the buffer or -1 if there is not
+enough space.
\wxheading{See also}
-\helpref{::wxGetOsDescription}{wxgetosdescription}
-
-\wxheading{Include files}
-
-<wx/utils.h>
+\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
-\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{wxT}\label{wxt}
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{float *}{value}, \param{const wxString\& }{file = NULL}}
+\func{wxChar}{wxT}{\param{char }{ch}}
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{long *}{value}, \param{const wxString\& }{file = NULL}}
+\func{const wxChar *}{wxT}{\param{const char *}{s}}
-\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{int *}{value}, \param{const wxString\& }{file = NULL}}
+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.
-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.
+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}
-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.
+\membersection{wxTRANSLATE}\label{wxtranslate}
-See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
+\func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}}
-\wxheading{Include files}
+This macro doesn't do anything in the program code -- it simply expands to the
+value of its argument (except in Unicode build where it is equivalent to
+\helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT
+with the same string which would be really unreadable).
-<wx/utils.h>
+However it does have a purpose and it is to mark the literal strings for the
+extraction into the message catalog created by {\tt xgettext} program. Usually
+this is achieved using \helpref{\_()}{underscore} but that macro not only marks
+the string for extraction but also expands into a
+\helpref{wxGetTranslation}{wxgettranslation} function call which means that it
+cannot be used in some situations, notably for static array
+initialization.
-\membersection{::wxGetUserId}
+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
-\func{bool}{wxGetUserId}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
+\begin{verbatim}
+static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
+...
+// use weekdays[n] as usual
+\end{verbatim}
-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''.
+the code wouldn't compile because the function calls are forbidden in the array
+initializer. So instead you should do
-\wxheading{Include files}
+\begin{verbatim}
+static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
+...
+// use wxGetTranslation(weekdays[n])
+\end{verbatim}
-<wx/utils.h>
+here.
-\membersection{::wxGetUserHome}\label{wxgetuserhome}
+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.
-\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
+\membersection{::wxVsnprintf}\label{wxvsnprintf}
-Returns the home directory for the given user. If the username is empty
-(default value), this function behaves like
-\helpref{wxGetHomeDir}{wxgethomedir}.
+\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
-\wxheading{Include files}
+The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list }
+argument instead of arbitrary number of parameters.
-<wx/utils.h>
+Note that if \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is set to 1, then this function supports
+positional arguments (see \helpref{wxString::Printf}{wxstringprintf} for more information).
+However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, wxVfprintf,
+wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional parameters
+even when \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is 1.
-\membersection{::wxGetUserName}
+\wxheading{See also}
-\func{bool}{wxGetUserName}{\param{const wxString\& }{buf}, \param{int}{ bufSize}}
+\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
-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''.
-\wxheading{Include files}
-<wx/utils.h>
+\membersection{\_}\label{underscore}
-\membersection{::wxKill}\label{wxkill}
+\func{const wxChar *}{\_}{\param{const char *}{s}}
-\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig}}
+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.
-Under Unix (the only supported platform), equivalent to the Unix kill function.
-Returns 0 on success, -1 on failure.
+Don't confuse this macro with \helpref{\_T()}{underscoret}!
-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.
-\wxheading{Include files}
+\membersection{wxPLURAL}\label{wxplural}
-<wx/utils.h>
+\func{const wxChar *}{wxPLURAL}{\param{const char *}{sing}, \param{const char *}{plur}, \param{size\_t}{n}}
-\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
+This macro is identical to \helpref{\_()}{underscore} but for the plural variant
+of \helpref{wxGetTranslation}{wxgettranslation}.
-\func{void}{wxInitAllImageHandlers}{\void}
-Initializes all available image handlers. For a list of available handlers,
-see \helpref{wxImage}{wximage}.
+\membersection{\_T}\label{underscoret}
-\wxheading{See also}
+\func{wxChar}{\_T}{\param{char }{ch}}
-\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
+\func{const wxChar *}{\_T}{\param{const wxChar }{ch}}
-\membersection{::wxIsBusy}\label{wxisbusy}
+This macro is exactly the same as \helpref{wxT}{wxt} and is defined in
+wxWidgets simply because it may be more intuitive for Windows programmers as
+the standard Win32 headers also define it (as well as yet another name for the
+same macro which is {\tt \_TEXT()}).
-\func{bool}{wxIsBusy}{\void}
+Don't confuse this macro with \helpref{\_()}{underscore}!
-Returns TRUE if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
-\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
-See also \helpref{wxBusyCursor}{wxbusycursor}.
-\wxheading{Include files}
+\section{Dialog functions}\label{dialogfunctions}
-<wx/utils.h>
+Below are a number of convenience functions for getting input from the
+user or displaying messages. Note that in these functions the last three
+parameters are optional. However, it is recommended to pass a parent frame
+parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
+the front when the dialog box is popped up.
-\membersection{::wxLoadUserResource}\label{wxloaduserresource}
-\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
+\membersection{::wxAboutBox}\label{wxaboutbox}
-Loads a user-defined Windows resource as a string. If the resource is found, the function creates
-a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, NULL is returned.
+\func{void}{wxAboutBox}{\param{const wxAboutDialogInfo\& }{info}}
-The resource must be defined in the {\tt .rc} file using the following syntax:
+This function shows the standard about dialog containing the information
+specified in \arg{info}. If the current platform has a native about dialog
+which is capable of showing all the fields in \arg{info}, the native dialog is
+used, otherwise the function falls back to the generic wxWidgets version of the
+dialog, i.e. does the same thing as \helpref{wxGenericAboutBox()}{wxgenericaboutbox}.
+Here is an example of how this function may be used:
\begin{verbatim}
-myResource TEXT file.ext
+void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event))
+{
+ wxAboutDialogInfo info;
+ info.SetName(_("My Program"));
+ info.SetVersion(_("1.2.3 Beta"));
+ info.SetDescription(_("This program does something great."));
+ info.SetCopyright(_T("(C) 2007 Me <my@email.addre.ss>"));
+
+ wxAboutBox(info);
+}
\end{verbatim}
-where {\tt file.ext} is a file that the resource compiler can find.
+Please see the \helpref{dialogs sample}{sampledialogs} for more examples of
+using this function and \helpref{wxAboutDialogInfo}{wxaboutdialoginfo} for the
+description of the information which can be shown in the about dialog.
-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}.
+\wxheading{Include files}
-This function is available under Windows only.
+<wx/aboutdlg.h>
-\wxheading{Include files}
-<wx/utils.h>
+\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
-\membersection{::wxNow}\label{wxnow}
+\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
-\func{wxString}{wxNow}{\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.
-Returns a string representing the current date and time.
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxPostDelete}\label{wxpostdelete}
-\func{void}{wxPostDelete}{\param{wxObject *}{object}}
+\membersection{::wxBell}\label{wxbell}
-Tells the system to delete the specified object when
-all other events have been processed. In some environments, it is
-necessary to use this instead of deleting a frame directly with the
-delete operator, because some GUIs will still send events to a deleted window.
+\func{void}{wxBell}{\void}
-Now obsolete: use \helpref{wxWindow::Close}{wxwindowclose} instead.
+Ring the system bell.
\wxheading{Include files}
<wx/utils.h>
-\membersection{::wxPostEvent}\label{wxpostevent}
-
-\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.
-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.
+\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
-See also \helpref{AddPendingEvent}{wxevthandleraddpendingevent} (which this function
-uses internally).
+\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
+ \param{size\_t }{currentTip}}
-\wxheading{Include files}
+This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
+used with \helpref{wxShowTip}{wxshowtip}.
-<wx/app.h>
+\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.}
-\membersection{::wxSafeYield}\label{wxsafeyield}
+\wxheading{See also}
-\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}}
+\helpref{Tips overview}{tipsoverview}
-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.
+\wxheading{Include files}
-Returns the result of the call to \helpref{::wxYield}{wxyield}.
+<wx/tipdlg.h>
-\wxheading{Include files}
-<wx/utils.h>
+\membersection{::wxDirSelector}\label{wxdirselector}
-\membersection{::wxSetDisplayName}\label{wxsetdisplayname}
+\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}}
-\func{void}{wxSetDisplayName}{\param{const wxString\& }{displayName}}
+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.
-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.
+The application must check for an empty return value (if the user pressed
+Cancel). For example:
-See also \helpref{wxGetDisplayName}{wxgetdisplayname}.
+\begin{verbatim}
+const wxString& dir = wxDirSelector("Choose a folder");
+if ( !dir.empty() )
+{
+ ...
+}
+\end{verbatim}
\wxheading{Include files}
-<wx/utils.h>
+<wx/dirdlg.h>
-\membersection{::wxShell}\label{wxshell}
-\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
+\membersection{::wxFileSelector}\label{wxfileselector}
-Executes a command in an interactive shell window. If no command is
-specified, then just the shell is spawned.
+\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
+ \param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\
+ \param{const wxString\& }{wildcard = "*.*"}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = -1}, \param{int}{ y = -1}}
-See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
+Pops up a file selector box. In Windows, this is the common file selector
+dialog. In X, this is a file selector box with the same functionality.
+The path and filename are distinct elements of a full file pathname.
+If path is empty, the current directory will be used. If filename is empty,
+no default filename will be supplied. The wildcard determines what files
+are displayed in the file selector, and file extension supplies a type
+extension for the required filename. Flags may be a combination of wxOPEN,
+wxSAVE, wxOVERWRITE\_PROMPT or wxFILE\_MUST\_EXIST. Note that wxMULTIPLE
+can only be used with \helpref{wxFileDialog}{wxfiledialog} and not here as this
+function only returns a single file name.
-\wxheading{Include files}
+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.
-<wx/utils.h>
+The wildcard may be a specification for multiple types of file
+with a description for each, such as:
-\membersection{::wxSleep}\label{wxsleep}
+\begin{verbatim}
+ "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
+\end{verbatim}
-\func{void}{wxSleep}{\param{int}{ secs}}
+The application must check for an empty return value (the user pressed
+Cancel). For example:
-Sleeps for the specified number of seconds.
+\begin{verbatim}
+wxString filename = wxFileSelector("Choose a file to open");
+if ( !filename.empty() )
+{
+ // work with the file
+ ...
+}
+//else: cancelled by user
+\end{verbatim}
\wxheading{Include files}
-<wx/utils.h>
+<wx/filedlg.h>
-\membersection{::wxStripMenuCodes}
-\func{wxString}{wxStripMenuCodes}{\param{const wxString\& }{in}}
+\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
-\func{void}{wxStripMenuCodes}{\param{char* }{in}, \param{char* }{out}}
+\func{void}{wxEndBusyCursor}{\void}
-Strips any menu codes from {\it in} and places the result
-in {\it out} (or returns the new string, in the first form).
+Changes the cursor back to the original cursor, for all windows in the application.
+Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
-Menu codes include \& (mark the next character with an underline
-as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
+See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
\wxheading{Include files}
<wx/utils.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}.
+\membersection{::wxGenericAboutBox}\label{wxgenericaboutbox}
-\wxheading{Include files}
+\func{void}{wxGenericAboutBox}{\param{const wxAboutDialogInfo\& }{info}}
-<wx/timer.h>
+This function does the same thing as \helpref{wxAboutBox}{wxaboutbox} except
+that it always uses the generic wxWidgets version of the dialog instead of the
+native one. This is mainly useful if you need to customize the dialog by e.g.
+adding custom controls to it (customizing the native dialog is not currently
+supported).
-\membersection{::wxToLower}\label{wxtolower}
+See the \helpref{dialogs sample}{sampledialogs} for an example of about dialog
+customization.
-\func{char}{wxToLower}{\param{char }{ch}}
+\wxheading{See also}
-Converts the character to lower case. This is implemented as a macro for efficiency.
+\helpref{wxAboutDialogInfo}{wxaboutdialoginfo}
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxToUpper}\label{wxtoupper}
+<wx/aboutdlg.h>\\
+<wx/generic/aboutdlgg.h>
-\func{char}{wxToUpper}{\param{char }{ch}}
-Converts the character to upper case. This is implemented as a macro for efficiency.
+\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
-\wxheading{Include files}
+\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}}
-<wx/utils.h>
+Shows the colour selection dialog and returns the colour selected by user or
+invalid colour (use \helpref{wxColour:IsOk}{wxcolourisok} to test whether a colour
+is valid) if the dialog was cancelled.
-\membersection{::wxTrace}\label{wxtrace}
+\wxheading{Parameters}
-\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
+\docparam{parent}{The parent window for the colour selection dialog}
-Takes printf-style variable argument syntax. Output
-is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
+\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+\docparam{caption}{If given, this will be used for the dialog caption.}
\wxheading{Include files}
-<wx/memory.h>
-
-\membersection{::wxTraceLevel}\label{wxtracelevel}
+<wx/colordlg.h>
-\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
-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{::wxGetFontFromUser}\label{wxgetfontfromuser}
-This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
+\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}, \param{const wxString\& }{caption = wxEmptyString}}
-\wxheading{Include files}
+Shows the font selection dialog and returns the font selected by user or
+invalid font (use \helpref{wxFont:IsOk}{wxfontisok} to test whether a font
+is valid) if the dialog was cancelled.
-<wx/memory.h>
+\wxheading{Parameters}
-\membersection{::wxUsleep}\label{wxusleep}
+\docparam{parent}{The parent window for the font selection dialog}
-\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
+\docparam{fontInit}{If given, this will be the font initially selected in the dialog.}
-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.
+\docparam{caption}{If given, this will be used for the dialog caption.}
\wxheading{Include files}
-<wx/utils.h>
-
-\membersection{::wxWriteResource}\label{wxwriteresource}
+<wx/fontdlg.h>
-\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}}
+\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
-\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
- \param{int }{value}, \param{const wxString\& }{file = NULL}}
+\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}}
-Writes a resource value into the resource database (for example, WIN.INI, or
-.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
-otherwise the specified file is used.
+\func{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}}
-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.
+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.
-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.
+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}.
-See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
+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{::wxYield}\label{wxyield}
+\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}{wxYield}{\void}
-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.
+\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
-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.
+\func{long}{wxGetNumberFromUser}{
+ \param{const wxString\& }{message},
+ \param{const wxString\& }{prompt},
+ \param{const wxString\& }{caption},
+ \param{long }{value},
+ \param{long }{min = 0},
+ \param{long }{max = 100},
+ \param{wxWindow *}{parent = NULL},
+ \param{const wxPoint\& }{pos = wxDefaultPosition}}
+
+Shows a dialog asking the user for numeric input. The dialogs title is set to
+{\it caption}, it contains a (possibly) multiline {\it message} above the
+single line {\it prompt} and the zone for entering the number.
+
+The number entered must be in the range {\it min}..{\it max} (both of which
+should be positive) and {\it value} is the initial value of it. If the user
+enters an invalid value or cancels the dialog, the function will return -1.
-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}.
+Dialog is centered on its {\it parent} unless an explicit position is given in
+{\it pos}.
\wxheading{Include files}
-<wx/app.h> or <wx/utils.h>
+<wx/numdlg.h>
-\membersection{::wxWakeUpIdle}\label{wxwakeupidle}
-\func{void}{wxWakeUpIdle}{\void}
+\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
-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{wxString}{wxGetPasswordFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
+ \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}}
+
+Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered
+in the dialog is not shown on screen but replaced with stars. This is intended
+to be used for entering passwords as the function name implies.
\wxheading{Include files}
-<wx/app.h>
+<wx/textdlg.h>
-\section{Macros}\label{macros}
-These macros are defined in wxWindows.
+\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
-\membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways}
+\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
+ \param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
+ \param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}}
-\func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}}
+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.
-\func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}}
+If {\it centre} is true, the message text (which may include new line characters)
+is centred; if false, the message is left-justified.
-\func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}}
+\wxheading{Include files}
-\func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
+<wx/textdlg.h>
-This macro will swap the bytes of the {\it value} variable from little
-endian to big endian or vice versa.
-\membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe}
+\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
-\func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}}
+\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}}
-\func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}}
+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.
-\func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}}
+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.
-\func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}}
+If Cancel is pressed, -1 is returned.
-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.
+{\it choices} is an array of {\it n} strings for the listbox.
-Use these macros to read data from and write data to a file that stores
-data in little endian (Intel i386) format.
+If {\it centre} is true, the message text (which may include new line characters)
+is centred; if false, the message is left-justified.
-\membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
+\wxheading{Include files}
-\func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}}
+<wx/choicdlg.h>
-\func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}}
-\func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}}
+\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
-\func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}}
+\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.
-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.
+\wxheading{Include files}
-Use these macros to read data from and write data to a file that stores
-data in big endian format.
+<wx/choicdlg.h>
-\membersection{CLASSINFO}\label{classinfo}
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
-\func{wxClassInfo *}{CLASSINFO}{className}
-Returns a pointer to the wxClassInfo object associated with this class.
+\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
-\wxheading{Include files}
+\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}}
-<wx/object.h>
+\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{DECLARE\_ABSTRACT\_CLASS}
+As {\bf wxGetSingleChoice} but returns the index representing the selected
+string. If the user pressed cancel, -1 is returned.
-\func{}{DECLARE\_ABSTRACT\_CLASS}{className}
+\wxheading{Include files}
-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.
+<wx/choicdlg.h>
-Example:
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}
-\begin{verbatim}
-class wxCommand: public wxObject
-{
- DECLARE_ABSTRACT_CLASS(wxCommand)
- private:
- ...
- public:
- ...
-};
-\end{verbatim}
+\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
-\wxheading{Include files}
+\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}}
-<wx/object.h>
+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}!
-\membersection{DECLARE\_APP}\label{declareapp}
+\wxheading{Include files}
-\func{}{DECLARE\_APP}{className}
+<wx/choicdlg.h>
-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)}.
+\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.}
-Example:
-\begin{verbatim}
- DECLARE_APP(MyApp)
-\end{verbatim}
+\membersection{::wxIsBusy}\label{wxisbusy}
-\wxheading{Include files}
+\func{bool}{wxIsBusy}{\void}
-<wx/app.h>
+Returns true if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
+\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
-\membersection{DECLARE\_CLASS}
+See also \helpref{wxBusyCursor}{wxbusycursor}.
-\func{}{DECLARE\_CLASS}{className}
+\wxheading{Include files}
-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.
+<wx/utils.h>
-\wxheading{Include files}
-<wx/object.h>
+\membersection{::wxMessageBox}\label{wxmessagebox}
-\membersection{DECLARE\_DYNAMIC\_CLASS}
+\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}}
-\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
+General purpose message dialog. {\it style} may be a bit list of the
+following identifiers:
-Used inside a class declaration to declare that the objects of this class should be dynamically
-createable from run-time type information.
+\begin{twocollist}\itemsep=0pt
+\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
+wxCANCEL.}
+\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May only be combined with
+wxYES\_NO or wxOK.}
+\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
+\twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.}
+\twocolitem{wxICON\_HAND}{Displays an error symbol.}
+\twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.}
+\twocolitem{wxICON\_QUESTION}{Displays a question mark symbol.}
+\twocolitem{wxICON\_INFORMATION}{Displays an information symbol.}
+\end{twocollist}
-Example:
+The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
-\begin{verbatim}
-class wxFrame: public wxWindow
-{
- DECLARE_DYNAMIC_CLASS(wxFrame)
+For example:
- private:
- const wxString\& frameTitle;
- public:
+\begin{verbatim}
+ ...
+ int answer = wxMessageBox("Quit program?", "Confirm",
+ wxYES_NO | wxCANCEL, main_frame);
+ if (answer == wxYES)
+ main_frame->Close();
...
-};
\end{verbatim}
+{\it message} may contain newline characters, in which case the
+message will be split into separate lines, to cater for large messages.
+
\wxheading{Include files}
-<wx/object.h>
+<wx/msgdlg.h>
-\membersection{IMPLEMENT\_ABSTRACT\_CLASS}
-\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
+\membersection{::wxShowTip}\label{wxshowtip}
-Used in a C++ implementation file to complete the declaration of
-a class that has run-time type information. The same as IMPLEMENT\_CLASS.
+\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
+ \param{wxTipProvider *}{tipProvider},
+ \param{bool }{showAtStartup = true}}
-Example:
+This function shows a "startup tip" to the user. The return value is the
+state of the `Show tips at startup' checkbox.
-\begin{verbatim}
-IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
+\docparam{parent}{The parent window for the modal dialog}
-wxCommand::wxCommand(void)
-{
-...
-}
-\end{verbatim}
+\docparam{tipProvider}{An object which is used to get the text of the tips.
+It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
+
+\docparam{showAtStartup}{Should be true if startup tips are shown, false
+otherwise. This is used as the initial value for "Show tips at startup"
+checkbox which is shown in the tips dialog.}
+
+\wxheading{See also}
+
+\helpref{Tips overview}{tipsoverview}
\wxheading{Include files}
-<wx/object.h>
+<wx/tipdlg.h>
-\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}
-\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
-Used in a C++ implementation file to complete the declaration of
-a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
+
+\section{Math functions}\label{mathfunctions}
\wxheading{Include files}
-<wx/object.h>
+<wx/math.h>
-\membersection{IMPLEMENT\_APP}\label{implementapp}
-\func{}{IMPLEMENT\_APP}{className}
+\membersection{wxFinite}\label{wxfinite}
-This is used in the application class implementation file to make the application class known to
-wxWindows for dynamic construction. You use this instead of
+\func{int}{wxFinite}{\param{double }{x}}
-Old form:
+Returns a non-zero value if {\it x} is neither infinite or NaN (not a number),
+returns 0 otherwise.
-\begin{verbatim}
- MyApp myApp;
-\end{verbatim}
-New form:
+\membersection{wxIsNaN}\label{wxisnan}
-\begin{verbatim}
- IMPLEMENT_APP(MyApp)
-\end{verbatim}
+\func{bool}{wxIsNaN}{\param{double }{x}}
-See also \helpref{DECLARE\_APP}{declareapp}.
+Returns a non-zero value if {\it x} is NaN (not a number), returns 0
+otherwise.
-\wxheading{Include files}
-<wx/app.h>
-\membersection{IMPLEMENT\_CLASS}
-\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
+\section{GDI functions}\label{gdifunctions}
-Used in a C++ implementation file to complete the declaration of
-a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
+The following are relevant to the GDI (Graphics Device Interface).
\wxheading{Include files}
-<wx/object.h>
+<wx/gdicmn.h>
-\membersection{IMPLEMENT\_CLASS2}
-\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
+\membersection{wxBITMAP}\label{wxbitmapmacro}
-Used in a C++ implementation file to complete the declaration of a
-class that has run-time type information and two base classes. The
-same as IMPLEMENT\_ABSTRACT\_CLASS2.
+\func{}{wxBITMAP}{bitmapName}
+
+This macro loads a bitmap from either application resources (on the platforms
+for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
+avoid using {\tt \#ifdef}s when creating bitmaps.
+
+\wxheading{See also}
+
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxICON}{wxiconmacro}
\wxheading{Include files}
-<wx/object.h>
+<wx/gdicmn.h>
-\membersection{IMPLEMENT\_DYNAMIC\_CLASS}
-\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
+\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect}
-Used in a C++ implementation file to complete the declaration of
-a class that has run-time type information, and whose instances
-can be created dynamically.
+\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
+\param{int *}{width}, \param{int *}{height}}
-Example:
+\func{wxRect}{wxGetClientDisplayRect}{\void}
-\begin{verbatim}
-IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
+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.
-wxFrame::wxFrame(void)
-{
-...
-}
-\end{verbatim}
-\wxheading{Include files}
+\membersection{::wxColourDisplay}\label{wxcolourdisplay}
-<wx/object.h>
+\func{bool}{wxColourDisplay}{\void}
-\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}
+Returns true if the display is colour, false otherwise.
-\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
-Used in a C++ implementation file to complete the declaration of
-a class that has run-time type information, and whose instances
-can be created dynamically. Use this for classes derived from two
-base classes.
+\membersection{::wxDisplayDepth}\label{wxdisplaydepth}
+
+\func{int}{wxDisplayDepth}{\void}
+
+Returns the depth of the display (a value of 1 denotes a monochrome display).
+
+
+\membersection{::wxDisplaySize}\label{wxdisplaysize}
+
+\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
+
+\func{wxSize}{wxGetDisplaySize}{\void}
+
+Returns the display size in pixels.
+
+
+\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm}
+
+\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
+
+\func{wxSize}{wxGetDisplaySizeMM}{\void}
+
+Returns the display size in millimeters.
+
+
+\membersection{::wxDROP\_ICON}\label{wxdropicon}
+
+\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
+
+This macro creates either a cursor (MSW) or an icon (elsewhere) with the given
+name. Under MSW, the cursor is loaded from the resource file and the icon is
+loaded from XPM file under other platforms.
+
+This macro should be used with
+\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}.
\wxheading{Include files}
-<wx/object.h>
+<wx/dnd.h>
-\membersection{wxBITMAP}\label{wxbitmapmacro}
-\func{}{wxBITMAP}{bitmapName}
+\membersection{wxICON}\label{wxiconmacro}
-This macro loads a bitmap from either application resources (on the platforms
+\func{}{wxICON}{iconName}
+
+This macro loads an icon from either application resources (on the platforms
for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
-avoid using {\tt \#ifdef}s when creating bitmaps.
+avoid using {\tt \#ifdef}s when creating icons.
\wxheading{See also}
-\helpref{Bitmaps and icons overview}{wxbitmapoverview},
-\helpref{wxICON}{wxiconmacro}
+\helpref{Bitmaps and icons overview}{wxbitmapoverview},
+\helpref{wxBITMAP}{wxbitmapmacro}
\wxheading{Include files}
<wx/gdicmn.h>
-\membersection{WXDEBUG\_NEW}\label{debugnew}
-\func{}{WXDEBUG\_NEW}{arg}
+\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
-This is defined in debug mode to be call the redefined new operator
-with filename and line number arguments. The definition is:
+\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
+ \param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
+
+Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
+makes it into a placeable metafile by prepending a header containing the given
+bounding box. The bounding box may be obtained from a device context after drawing
+into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
+
+In addition to adding the placeable metafile header, this function adds
+the equivalent of the following code to the start of the metafile data:
\begin{verbatim}
-#define WXDEBUG_NEW new(__FILE__,__LINE__)
+ SetMapMode(dc, MM_ANISOTROPIC);
+ SetWindowOrg(dc, minX, minY);
+ SetWindowExt(dc, maxX - minX, maxY - minY);
\end{verbatim}
-In non-debug mode, this is defined as the normal new operator.
+This simulates the wxMM\_TEXT mapping mode, which wxWidgets assumes.
+
+Placeable metafiles may be imported by many Windows applications, and can be
+used in RTF (Rich Text Format) files.
+
+{\it scale} allows the specification of scale for the metafile.
+
+This function is only available under Windows.
+
+
+\membersection{::wxSetCursor}\label{wxsetcursor}
+
+\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
+
+Globally sets the cursor; only has an effect in Windows and GTK.
+See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
+
+
+
+\section{Printer settings}\label{printersettings}
+
+{\bf NB:} These routines are obsolete and should no longer be used!
+
+The following functions are used to control PostScript printing. Under
+Windows, PostScript output can only be sent to a file.
\wxheading{Include files}
-<wx/object.h>
+<wx/dcps.h>
-\membersection{wxDynamicCast}\label{wxdynamiccast}
-\func{}{wxDynamicCast}{ptr, classname}
+\membersection{::wxGetPrinterCommand}\label{wxgetprintercommand}
-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.
+\func{wxString}{wxGetPrinterCommand}{\void}
-The {\it ptr} argument may be NULL, in which case NULL will be returned.
+Gets the printer command used to print a file. The default is {\tt lpr}.
-Example:
-\begin{verbatim}
- wxWindow *win = wxWindow::FindFocus();
- wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
- if ( text )
- {
- // a text control has the focus...
- }
- else
+\membersection{::wxGetPrinterFile}\label{wxgetprinterfile}
+
+\func{wxString}{wxGetPrinterFile}{\void}
+
+Gets the PostScript output filename.
+
+
+\membersection{::wxGetPrinterMode}\label{wxgetprintermode}
+
+\func{int}{wxGetPrinterMode}{\void}
+
+Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
+The default is PS\_PREVIEW.
+
+
+\membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions}
+
+\func{wxString}{wxGetPrinterOptions}{\void}
+
+Gets the additional options for the print command (e.g. specific printer). The default is nothing.
+
+
+\membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation}
+
+\func{int}{wxGetPrinterOrientation}{\void}
+
+Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+
+
+\membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand}
+
+\func{wxString}{wxGetPrinterPreviewCommand}{\void}
+
+Gets the command used to view a PostScript file. The default depends on the platform.
+
+
+\membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling}
+
+\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
+
+Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
+
+
+\membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation}
+
+\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
+
+Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+
+
+\membersection{::wxSetPrinterCommand}\label{wxsetprintercommand}
+
+\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
+
+Sets the printer command used to print a file. The default is {\tt lpr}.
+
+
+\membersection{::wxSetPrinterFile}\label{wxsetprinterfile}
+
+\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
+
+Sets the PostScript output filename.
+
+
+\membersection{::wxSetPrinterMode}\label{wxsetprintermode}
+
+\func{void}{wxSetPrinterMode}{\param{int }{mode}}
+
+Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
+The default is PS\_PREVIEW.
+
+
+\membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions}
+
+\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
+
+Sets the additional options for the print command (e.g. specific printer). The default is nothing.
+
+
+\membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation}
+
+\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
+
+Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
+
+
+\membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand}
+
+\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
+
+Sets the command used to view a PostScript file. The default depends on the platform.
+
+
+\membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling}
+
+\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
+
+Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
+
+
+\membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation}
+
+\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
+
+Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
+
+
+
+\section{Clipboard functions}\label{clipsboard}
+
+These clipboard functions are implemented for Windows only. The use of these functions
+is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard}
+class instead.
+
+\wxheading{Include files}
+
+<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{::wxGetKeyState}\label{wxgetkeystate}
+
+\func{bool}{wxGetKeyState}{\param{wxKeyCode }{key}}
+
+For normal keys, returns \true if the specified key is currently down.
+
+For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
+\true if the key is toggled such that its LED indicator is lit. There is
+currently no way to test whether togglable keys are up or down.
+
+Even though there are virtual key codes defined for mouse buttons, they
+cannot be used with this function currently.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\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{wxON\_BLOCK\_EXIT}\label{wxonblockexit}
+
+\func{}{wxON\_BLOCK\_EXIT0}{\param{}{func}}
+\func{}{wxON\_BLOCK\_EXIT1}{\param{}{func}, \param{}{p1}}
+\func{}{wxON\_BLOCK\_EXIT2}{\param{}{func}, \param{}{p1}, \param{}{p2}}
+
+This family of macros allows to ensure that the global function \arg{func}
+with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is
+executed on scope exit, whether due to a normal function return or because an
+exception has been thrown. A typical example of its usage:
+\begin{verbatim}
+ void *buf = malloc(size);
+ wxON_BLOCK_EXIT1(free, buf);
+\end{verbatim}
+
+Please see the original article by Andrei Alexandrescu and Petru Marginean
+published in December 2000 issue of \emph{C/C++ Users Journal} for more
+details.
+
+\wxheading{Include files}
+
+<wx/scopeguard.h>
+
+\wxheading{See also}
+
+\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}
+
+
+\membersection{wxON\_BLOCK\_EXIT\_OBJ}\label{wxonblockexitobj}
+
+\func{}{wxON\_BLOCK\_EXIT\_OBJ0}{\param{}{obj}, \param{}{method}}
+\func{}{wxON\_BLOCK\_EXIT\_OBJ1}{\param{}{obj}, \param{}{method}, \param{}{p1}}
+\func{}{wxON\_BLOCK\_EXIT\_OBJ2}{\param{}{obj}, \param{}{method}, \param{}{p1}, \param{}{p2}}
+
+This family of macros is similar to \helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}
+but calls a method of the given object instead of a free function.
+
+\wxheading{Include files}
+
+<wx/scopeguard.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 wxWidgets exits, to clean up the DDE system. This no longer needs to be
+called by the application.
+
+See also \helpref{wxDDEInitialize}{wxddeinitialize}.
+
+\wxheading{Include files}
+
+<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 wxWidgets if necessary.
+
+See also \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEConnection}{wxddeconnection},\rtfsp
+\helpref{wxDDECleanUp}{wxddecleanup}.
+
+\wxheading{Include files}
+
+<wx/dde.h>
+
+
+\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
+
+\func{void}{wxEnableTopLevelWindows}{\param{bool}{ enable = true}}
+
+This function enables or disables all top level windows. It is used by
+\helpref{::wxSafeYield}{wxsafeyield}.
+
+\wxheading{Include files}
+
+<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 (implemented for MSW and GTK only currently,
+always returns \NULL in the other ports).
+
+\wxheading{Include files}
+
+<wx/windows.h>
+
+
+\membersection{::wxGetBatteryState}\label{wxgetbatterystate}
+
+\func{wxBatteryState}{wxGetBatteryState}{\void}
+
+Returns battery state as one of \texttt{wxBATTERY\_NORMAL\_STATE},
+\texttt{wxBATTERY\_LOW\_STATE}, \texttt{wxBATTERY\_CRITICAL\_STATE},
+\texttt{wxBATTERY\_SHUTDOWN\_STATE} or \texttt{wxBATTERY\_UNKNOWN\_STATE}.
+\texttt{wxBATTERY\_UNKNOWN\_STATE} is also the default on platforms where
+this feature is not implemented (currently everywhere but MS Windows).
+
+\wxheading{Include files}
+
+<wx/utils.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{::wxGetPowerType}\label{wxgetpowertype}
+
+\func{wxPowerType}{wxGetPowerType}{\void}
+
+Returns the type of power source as one of \texttt{wxPOWER\_SOCKET},
+\texttt{wxPOWER\_BATTERY} or \texttt{wxPOWER\_UNKNOWN}.
+\texttt{wxPOWER\_UNKNOWN} is also the default on platforms where this
+feature is not implemented (currently everywhere but MS Windows).
+
+\wxheading{Include files}
+
+<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{::wxGetMouseState}\label{wxgetmousestate}
+
+\func{wxMouseState}{wxGetMouseState}{\void}
+
+Returns the current state of the mouse. Returns a wxMouseState
+instance that contains the current position of the mouse pointer in
+screen coordinants, as well as boolean values indicating the up/down
+status of the mouse buttons and the modifier keys.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+wxMouseState has the following interface:
+
+\begin{verbatim}
+class wxMouseState
+{
+public:
+ wxMouseState();
+
+ wxCoord GetX();
+ wxCoord GetY();
+
+ bool LeftDown();
+ bool MiddleDown();
+ bool RightDown();
+
+ bool ControlDown();
+ bool ShiftDown();
+ bool AltDown();
+ bool MetaDown();
+ bool CmdDown();
+
+ void SetX(wxCoord x);
+ void SetY(wxCoord y);
+
+ void SetLeftDown(bool down);
+ void SetMiddleDown(bool down);
+ void SetRightDown(bool down);
+
+ void SetControlDown(bool down);
+ void SetShiftDown(bool down);
+ void SetAltDown(bool down);
+ void SetMetaDown(bool down);
+};
+\end{verbatim}
+
+
+\membersection{::wxGetResource}\label{wxgetresource}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{const wxString\& *}{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{float *}{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{long *}{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxGetResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{int *}{value}, \param{const wxString\& }{file = NULL}}
+
+Gets a resource value from the resource database (for example, WIN.INI, or
+.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
+otherwise the specified file is used.
+
+Under X, if an application class (wxApp::GetClassName) has been defined,
+it is appended to the string /usr/lib/X11/app-defaults/ to try to find
+an applications default file when merging all resource databases.
+
+The reason for passing the result in an argument is that it
+can be convenient to define a default value, which gets overridden
+if the value exists in the resource file. It saves a separate
+test for that resource's existence, and it also allows
+the overloading of the function for different types.
+
+See also \helpref{wxWriteResource}{wxwriteresource}, \helpref{wxConfigBase}{wxconfigbase}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{::wxGetStockLabel}\label{wxgetstocklabel}
+
+\func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{const wxString\& }{accelerator = wxEmptyString}}
+
+Returns label that should be used for given {\it id} element.
+
+\wxheading{Parameters}
+
+\docparam{id}{given id of the \helpref{wxMenuItem}{wxmenuitem}, \helpref{wxButton}{wxbutton}, \helpref{wxToolBar}{wxtoolbar} tool, etc.}
+
+\docparam{withCodes}{if false then strip accelerator code from the label;
+usefull for getting labels without accelerator char code like for toolbar tooltip or
+under platforms without traditional keyboard like smartphones}
+
+\docparam{accelerator}{optional accelerator string automatically added to label; useful
+for building labels for \helpref{wxMenuItem}{wxmenuitem}}
+
+\wxheading{Include files}
+
+<wx/stockitem.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{::wxLaunchDefaultBrowser}\label{wxlaunchdefaultbrowser}
+
+\func{bool}{wxLaunchDefaultBrowser}{\param{const wxString\& }{url}, \param{int }{flags = $0$}}
+
+Open the \arg{url} in user's default browser. If \arg{flags} parameter contains
+\texttt{wxBROWSER\_NEW\_WINDOW} flag, a new window is opened for the URL
+(currently this is only supported under Windows).
+
+Returns \true if the application was successfully launched.
+
+\wxheading{Include files}
+
+<wx/utils.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\& }{str}, \param{int }{flags = wxStrip\_All}}
+
+Strips any menu codes from \arg{str} and returns the result.
+
+By default, the functions strips both the mnemonics character (\texttt{'\&'})
+which is used to indicate a keyboard shortkey, and the accelerators, which are
+used only in the menu items and are separated from the main text by the
+\texttt{$\backslash$t} (TAB) character. By using \arg{flags} of
+\texttt{wxStrip\_Mnemonics} or \texttt{wxStrip\_Accel} to strip only the former
+or the latter part, respectively.
+
+Notice that in most cases
+\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} or
+\helpref{wxControl::GetLabelText}{wxcontrolgetlabeltext} can be used instead.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{wxSTRINGIZE}\label{wxstringize}
+
+\func{}{wxSTRINGIZE}{\param{}{x}}
+
+Returns the string representation of the given symbol which can be either a
+literal or a macro (hence the advantage of using this macro instead of the
+standard preprocessor \texttt{\#} operator which doesn't work with macros).
+
+Notice that this macro always produces a \texttt{char} string, use
+\helpref{wxSTRINGIZE\_T}{wxstringizet} to build a wide string Unicode build.
+
+\wxheading{See also}
+
+\helpref{wxCONCAT}{wxconcat}
+
+
+\membersection{wxSTRINGIZE\_T}\label{wxstringizet}
+
+\func{}{wxSTRINGIZE\_T}{\param{}{x}}
+
+Returns the string representation of the given symbol as either an ASCII or
+Unicode string, depending on the current build. This is the Unicode-friendly
+equivalent of \helpref{wxSTRINGIZE}{wxstringize}.
+
+
+\membersection{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}\label{wxsuppressgccprivatedtorwarning}
+
+\func{}{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{\param{}{name}}
+
+GNU C++ compiler gives a warning for any class whose destructor is private
+unless it has a friend. This warning may sometimes be useful but it doesn't
+make sense for reference counted class which always delete themselves (hence
+destructor should be private) but don't necessarily have any friends, so this
+macro is provided to disable the warning in such case. The \arg{name} parameter
+should be the name of the class but is only used to construct a unique friend
+class name internally. Example of using the macro:
+
+\begin{verbatim}
+ class RefCounted
+ {
+ public:
+ RefCounted() { m_nRef = 1; }
+ void IncRef() { m_nRef++ ; }
+ void DecRef() { if ( !--m_nRef ) delete this; }
+
+ private:
+ ~RefCounted() { }
+
+ wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
+ };
+\end{verbatim}
+
+Notice that there should be no semicolon after this macro.
+
+
+\membersection{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{wxVaCopy}\label{wxvacopy}
+
+\func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{ argptrSrc}}
+
+This macro is the same as the standard C99 \texttt{va\_copy} for the compilers
+which support it or its replacement for those that don't. It must be used to
+preserve the value of a \texttt{va\_list} object if you need to use it after
+passing it to another function because it can be modified by the latter.
+
+As with \texttt{va\_start}, each call to \texttt{wxVaCopy} must have a matching
+\texttt{va\_end}.
+
+
+\membersection{::wxWriteResource}\label{wxwriteresource}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{const wxString\& }{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{float }{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{long }{value}, \param{const wxString\& }{file = NULL}}
+
+\func{bool}{wxWriteResource}{\param{const wxString\& }{section}, \param{const wxString\& }{entry},
+ \param{int }{value}, \param{const wxString\& }{file = NULL}}
+
+Writes a resource value into the resource database (for example, WIN.INI, or
+.Xdefaults). If {\it file} is NULL, WIN.INI or .Xdefaults is used,
+otherwise the specified file is used.
+
+Under X, the resource databases are cached until the internal function
+\rtfsp{\bf wxFlushResources} is called automatically on exit, when
+all updated resource databases are written to their files.
+
+Note that it is considered bad manners to write to the .Xdefaults
+file under Unix, although the WIN.INI file is fair game under Windows.
+
+See also \helpref{wxGetResource}{wxgetresource}, \helpref{wxConfigBase}{wxconfigbase}.
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
+\membersection{\_\_WXFUNCTION\_\_}\label{wxfunction}
+
+\func{}{\_\_WXFUNCTION\_\_}{\void}
+
+This macro expands to the name of the current function if the compiler supports
+any of \texttt{\_\_FUNCTION\_\_}, \texttt{\_\_func\_\_} or equivalent variables
+or macros or to \NULL if none of them is available.
+
+
+
+\section{Byte order macros}\label{byteordermacros}
+
+The endian-ness issues (that is the difference between big-endian and
+little-endian architectures) are important for the portable programs working
+with the external binary data (for example, data files or data coming from
+network) which is usually in some fixed, platform-independent format. The
+macros are helpful for transforming the data to the correct format.
+
+
+\membersection{wxINTXX\_SWAP\_ALWAYS}\label{intswapalways}
+
+\func{wxInt32}{wxINT32\_SWAP\_ALWAYS}{\param{wxInt32 }{value}}
+
+\func{wxUint32}{wxUINT32\_SWAP\_ALWAYS}{\param{wxUint32 }{value}}
+
+\func{wxInt16}{wxINT16\_SWAP\_ALWAYS}{\param{wxInt16 }{value}}
+
+\func{wxUint16}{wxUINT16\_SWAP\_ALWAYS}{\param{wxUint16 }{value}}
+
+These macros will swap the bytes of the {\it value} variable from little
+endian to big endian or vice versa unconditionally, i.e. independently of the
+current platform.
+
+
+\membersection{wxINTXX\_SWAP\_ON\_BE}\label{intswaponbe}
+
+\func{wxInt32}{wxINT32\_SWAP\_ON\_BE}{\param{wxInt32 }{value}}
+
+\func{wxUint32}{wxUINT32\_SWAP\_ON\_BE}{\param{wxUint32 }{value}}
+
+\func{wxInt16}{wxINT16\_SWAP\_ON\_BE}{\param{wxInt16 }{value}}
+
+\func{wxUint16}{wxUINT16\_SWAP\_ON\_BE}{\param{wxUint16 }{value}}
+
+This macro will swap the bytes of the {\it value} variable from little
+endian to big endian or vice versa if the program is compiled on a
+big-endian architecture (such as Sun work stations). If the program has
+been compiled on a little-endian architecture, the value will be unchanged.
+
+Use these macros to read data from and write data to a file that stores
+data in little-endian (for example Intel i386) format.
+
+
+\membersection{wxINTXX\_SWAP\_ON\_LE}\label{intswaponle}
+
+\func{wxInt32}{wxINT32\_SWAP\_ON\_LE}{\param{wxInt32 }{value}}
+
+\func{wxUint32}{wxUINT32\_SWAP\_ON\_LE}{\param{wxUint32 }{value}}
+
+\func{wxInt16}{wxINT16\_SWAP\_ON\_LE}{\param{wxInt16 }{value}}
+
+\func{wxUint16}{wxUINT16\_SWAP\_ON\_LE}{\param{wxUint16 }{value}}
+
+This macro will swap the bytes of the {\it value} variable from little
+endian to big endian or vice versa if the program is compiled on a
+little-endian architecture (such as Intel PCs). If the program has
+been compiled on a big-endian architecture, the value will be unchanged.
+
+Use these macros to read data from and write data to a file that stores
+data in big-endian format.
+
+
+
+\section{RTTI functions}\label{rttimacros}
+
+wxWidgets uses its own RTTI ("run-time type identification") system which
+predates the current standard C++ RTTI and so is kept for backwards
+compatibility reasons but also because it allows some things which the
+standard RTTI doesn't directly support (such as creating a class from its
+name).
+
+The standard C++ RTTI can be used in the user code without any problems and in
+general you shouldn't need to use the functions and the macros in this section
+unless you are thinking of modifying or adding any wxWidgets classes.
+
+\wxheading{See also}
+
+\helpref{RTTI overview}{runtimeclassoverview}
+
+
+\membersection{CLASSINFO}\label{classinfo}
+
+\func{wxClassInfo *}{CLASSINFO}{className}
+
+Returns a pointer to the wxClassInfo object associated with this class.
+
+\wxheading{Include files}
+
+<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 make the class known to wxWidgets RTTI
+system and also declare that the objects of this class should be dynamically
+creatable from run-time type information. Notice that this implies that the
+class should have a default constructor, if this is not the case consider using
+\helpref{DECLARE\_CLASS}{declareclass}.
+
+Example:
+
+\begin{verbatim}
+class wxFrame: public wxWindow
+{
+ DECLARE_DYNAMIC_CLASS(wxFrame)
+
+ private:
+ const wxString& frameTitle;
+ public:
+ ...
+};
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_ABSTRACT\_CLASS}\label{implementabstractclass}
+
+\func{}{IMPLEMENT\_ABSTRACT\_CLASS}{className, baseClassName}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information. The same as IMPLEMENT\_CLASS.
+
+Example:
+
+\begin{verbatim}
+IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
+
+wxCommand::wxCommand(void)
+{
+...
+}
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_ABSTRACT\_CLASS2}\label{implementabstractclass2}
+
+\func{}{IMPLEMENT\_ABSTRACT\_CLASS2}{className, baseClassName1, baseClassName2}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information and two base classes. The same as IMPLEMENT\_CLASS2.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_APP}\label{implementapp}
+
+\func{}{IMPLEMENT\_APP}{className}
+
+This is used in the application class implementation file to make the application class known to
+wxWidgets for dynamic construction. You use this instead of
+
+Old form:
+
+\begin{verbatim}
+ MyApp myApp;
+\end{verbatim}
+
+New form:
+
+\begin{verbatim}
+ IMPLEMENT_APP(MyApp)
+\end{verbatim}
+
+See also \helpref{DECLARE\_APP}{declareapp}.
+
+\wxheading{Include files}
+
+<wx/app.h>
+
+
+\membersection{IMPLEMENT\_CLASS}\label{implementclass}
+
+\func{}{IMPLEMENT\_CLASS}{className, baseClassName}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information. The same as IMPLEMENT\_ABSTRACT\_CLASS.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_CLASS2}\label{implementclass2}
+
+\func{}{IMPLEMENT\_CLASS2}{className, baseClassName1, baseClassName2}
+
+Used in a C++ implementation file to complete the declaration of a
+class that has run-time type information and two base classes. The
+same as IMPLEMENT\_ABSTRACT\_CLASS2.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_DYNAMIC\_CLASS}\label{implementdynamicclass}
+
+\func{}{IMPLEMENT\_DYNAMIC\_CLASS}{className, baseClassName}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information, and whose instances
+can be created dynamically.
+
+Example:
+
+\begin{verbatim}
+IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
+
+wxFrame::wxFrame(void)
+{
+...
+}
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{IMPLEMENT\_DYNAMIC\_CLASS2}\label{implementdynamicclass2}
+
+\func{}{IMPLEMENT\_DYNAMIC\_CLASS2}{className, baseClassName1, baseClassName2}
+
+Used in a C++ implementation file to complete the declaration of
+a class that has run-time type information, and whose instances
+can be created dynamically. Use this for classes derived from two
+base classes.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{wxConstCast}\label{wxconstcast}
+
+\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{wx\_const\_cast}{wxconstcastraw}\\
+\helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxStaticCast}{wxstaticcast}
+
+
+\membersection{::wxCreateDynamicObject}\label{wxcreatedynamicobject}
+
+\func{wxObject *}{wxCreateDynamicObject}{\param{const wxString\& }{className}}
+
+Creates and returns an object of the given class, if the class has been
+registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.
+
+
+\membersection{WXDEBUG\_NEW}\label{debugnew}
+
+\func{}{WXDEBUG\_NEW}{arg}
+
+This is defined in debug mode to be call the redefined new operator
+with filename and line number arguments. The definition is:
+
+\begin{verbatim}
+#define WXDEBUG_NEW new(__FILE__,__LINE__)
+\end{verbatim}
+
+In non-debug mode, this is defined as the normal new operator.
+
+\wxheading{Include files}
+
+<wx/object.h>
+
+
+\membersection{wxDynamicCast}\label{wxdynamiccast}
+
+\func{classname *}{wxDynamicCast}{ptr, classname}
+
+This macro returns the pointer {\it ptr} cast to the type {\it classname *} if
+the pointer is of this type (the check is done during the run-time) or
+{\tt NULL} otherwise. Usage of this macro is preferred over obsoleted
+wxObject::IsKindOf() function.
+
+The {\it ptr} argument may be {\tt NULL}, in which case {\tt NULL} will be
+returned.
+
+Example:
+
+\begin{verbatim}
+ wxWindow *win = wxWindow::FindFocus();
+ wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
+ if ( text )
+ {
+ // a text control has the focus...
+ }
+ else
{
- // no window has the focus or it'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{wxStaticCast}{wxstaticcast}
+
+
+\membersection{wxDynamicCastThis}\label{wxdynamiccastthis}
+
+\func{classname *}{wxDynamicCastThis}{classname}
+
+This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the
+latter provokes spurious compilation warnings from some compilers (because it
+tests whether {\tt this} pointer is non-{\tt NULL} which is always true), so
+this macro should be used to avoid them.
+
+\wxheading{See also}
+
+\helpref{wxDynamicCast}{wxdynamiccast}
+
+
+\membersection{wxStaticCast}\label{wxstaticcast}
+
+\func{classname *}{wxStaticCast}{ptr, classname}
+
+This macro checks that the cast is valid in debug mode (an assert failure will
+result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the
+result of executing an equivalent of {\tt static\_cast<classname *>(ptr)}.
+
+\wxheading{See also}
+
+\helpref{wx\_static\_cast}{wxstaticcastraw}\\
+\helpref{wxDynamicCast}{wxdynamiccast}\\
+\helpref{wxConstCast}{wxconstcast}
+
+
+\membersection{wx\_const\_cast}\label{wxconstcastraw}
+
+\func{T}{wx\_const\_cast}{T, x}
+
+Same as \texttt{const\_cast<T>(x)} if the compiler supports const cast or
+\texttt{(T)x} for old compilers. Unlike \helpref{wxConstCast}{wxconstcast},
+the cast it to the type \arg{T} and not to \texttt{T *} and also the order of
+arguments is the same as for the standard cast.
+
+\wxheading{See also}
+
+\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\
+\helpref{wx\_static\_cast}{wxstaticcastraw}
+
+
+\membersection{wx\_reinterpret\_cast}\label{wxreinterpretcastraw}
+
+\func{T}{wx\_reinterpret\_cast}{T, x}
+
+Same as \texttt{reinterpret\_cast<T>(x)} if the compiler supports reinterpret cast or
+\texttt{(T)x} for old compilers.
+
+\wxheading{See also}
+
+\helpref{wx\_const\_cast}{wxconstcastraw},\\
+\helpref{wx\_static\_cast}{wxstaticcastraw}
+
+
+\membersection{wx\_static\_cast}\label{wxstaticcastraw}
+
+\func{T}{wx\_static\_cast}{T, x}
+
+Same as \texttt{static\_cast<T>(x)} if the compiler supports static cast or
+\texttt{(T)x} for old compilers. Unlike \helpref{wxStaticCast}{wxstaticcast},
+there are no checks being done and the meaning of the macro arguments is exactly
+the same as for the standard static cast, i.e. \arg{T} is the full type name and
+star is not appended to it.
+
+\wxheading{See also}
+
+\helpref{wx\_const\_cast}{wxconstcastraw},\\
+\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\
+\helpref{wx\_truncate\_cast}{wxtruncatecast}
+
+
+\membersection{wx\_truncate\_cast}\label{wxtruncatecast}
+
+\func{T}{wx\_truncate\_cast}{T, x}
+
+This case doesn't correspond to any standard cast but exists solely to make
+casts which possibly result in a truncation of an integer value more readable.
+
+\wxheading{See also}
+
+\helpref{wx\_static\_cast}{wxstaticcastraw}
+
+
+\section{Log functions}\label{logfunctions}
+
+These functions provide a variety of logging functions: see \helpref{Log classes overview}{wxlogoverview} for
+further information. The functions use (implicitly) the currently active log
+target, so their descriptions here may not apply if the log target is not the
+standard one (installed by wxWidgets in the beginning of the program).
+
+\wxheading{Include files}
+
+<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 = "wxWidgets 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
+wxWidgets 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 = "wxWidgets 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
+wxWidgets 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).
+
+\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 wxWidgets itself, but might be handy for logging errors after
+system call (API function) failure. It logs the specified message text as well
+as the last system error code ({\it errno} or {\it ::GetLastError()} depending
+on the platform) and the corresponding error message. The second form
+of this function takes the error code explicitly as the first argument.
+
+\wxheading{See also}
+
+\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} or by setting
+\helpref{{\tt WXTRACE} environment variable}{envvars}.
+The predefined string trace masks
+used by wxWidgets are:
+
+\begin{itemize}\itemsep=0pt
+\item wxTRACE\_MemAlloc: trace memory allocation (new/delete)
+\item wxTRACE\_Messages: trace window messages/X callbacks
+\item wxTRACE\_ResAlloc: trace GDI resource allocation
+\item wxTRACE\_RefCount: trace various ref counting operations
+\item wxTRACE\_OleCalls: trace OLE method calls (Win32 only)
+\end{itemize}
+
+{\bf Caveats:} since both the mask and the format string are strings,
+this might lead to function signature confusion in some cases:
+if you intend to call the format string only version of wxLogTrace,
+then add a \%s format string parameter and then supply a second string parameter for that \%s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function.
+In this case you'll unfortunately have to avoid having two leading
+string parameters, e.g. by adding a bogus integer (with its \%d format string).
+
+The third version of the function only logs the message if all the bits
+corresponding to the {\it mask} are set in the wxLog trace mask which can be
+set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less
+flexible than the previous one because it doesn't allow defining the user
+trace masks easily - this is why it is deprecated in favour of using string
+trace masks.
+
+\begin{itemize}\itemsep=0pt
+\item wxTraceMemAlloc: trace memory allocation (new/delete)
+\item wxTraceMessages: trace window messages/X callbacks
+\item wxTraceResAlloc: trace GDI resource allocation
+\item wxTraceRefCount: trace various ref counting operations
+\item wxTraceOleCalls: trace OLE method calls (Win32 only)
+\end{itemize}
+
+
+\membersection{::wxSafeShowMessage}\label{wxsafeshowmessage}
+
+\func{void}{wxSafeShowMessage}{\param{const wxString\& }{title}, \param{const wxString\& }{text}}
+
+This function shows a message to the user in a safe way and should be safe to
+call even before the application has been initialized or if it is currently in
+some other strange state (for example, about to crash). Under Windows this
+function shows a message box using a native dialog instead of
+\helpref{wxMessageBox}{wxmessagebox} (which might be unsafe to call), elsewhere
+it simply prints the message to the standard output using the title as prefix.
+
+\wxheading{Parameters}
+
+\docparam{title}{The title of the message box shown to the user or the prefix
+of the message string}
+
+\docparam{text}{The text to show to the user}
+
+\wxheading{See also}
+
+\helpref{wxLogFatalError}{wxlogfatalerror}
+
+\wxheading{Include files}
+
+<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{wxICON}\label{wxiconmacro}
-\func{}{wxICON}{iconName}
+\membersection{::wxSysErrorMsg}\label{wxsyserrormsg}
-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{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}}
-\wxheading{See also}
+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.
-\helpref{Bitmaps and icons overview}{wxbitmapoverview},
-\helpref{wxBITMAP}{wxbitmapmacro}
+\wxheading{See also}
-\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{::wxMicroSleep}\label{wxmicrosleep}
-\membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
+\func{void}{wxMicroSleep}{\param{unsigned long}{ microseconds}}
-\func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{const wxString\& }{xbm\_data}, \param{int }{width},
-\param{int }{height}, \param{wxResourceTable *}{table = NULL}}
+Sleeps for the specified number of microseconds. The microsecond resolution may
+not, in fact, be available on all platforms (currently only Unix platforms with
+nanosleep(2) may provide it) in which case this is the same as
+\helpref{wxMilliSleep}{wxmillisleep}(\arg{microseconds}$/1000$).
-\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{::wxMilliSleep}\label{wxmillisleep}
-\section{Log functions}\label{logfunctions}
+\func{void}{wxMilliSleep}{\param{unsigned long}{ milliseconds}}
-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 milliseconds. Notice that usage of this
+function is encouraged instead of calling usleep(3) directly because the
+standard usleep() function is not MT safe.
\wxheading{Include files}
-<wx/log.h>
+<wx/utils.h>
-\membersection{::wxLogError}\label{wxlogerror}
-\func{void}{wxLogError}{\param{const char*}{ formatString}, \param{...}{}}
+\membersection{::wxNow}\label{wxnow}
-The function to use for error messages, i.e. the messages that must be shown
-to the user. The default processing is to pop up a message box to inform the
-user about it.
+\func{wxString}{wxNow}{\void}
-\membersection{::wxLogFatalError}\label{wxlogfatalerror}
+Returns a string representing the current date and time.
-\func{void}{wxLogFatalError}{\param{const char*}{ formatString}, \param{...}{}}
+\wxheading{Include files}
-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.
+<wx/utils.h>
-\membersection{::wxLogWarning}\label{wxlogwarning}
-\func{void}{wxLogWarning}{\param{const char*}{ formatString}, \param{...}{}}
+\membersection{::wxSleep}\label{wxsleep}
-For warnings - they are also normally shown to the user, but don't interrupt
-the program work.
+\func{void}{wxSleep}{\param{int}{ secs}}
-\membersection{::wxLogMessage}\label{wxlogmessage}
+Sleeps for the specified number of seconds.
-\func{void}{wxLogMessage}{\param{const char*}{ formatString}, \param{...}{}}
+\wxheading{Include files}
-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.
+<wx/utils.h>
-\membersection{::wxLogVerbose}\label{wxlogverbose}
-\func{void}{wxLogVerbose}{\param{const char*}{ formatString}, \param{...}{}}
+\membersection{::wxStartTimer}\label{wxstarttimer}
-For verbose output. Normally, it's suppressed, but
-might be activated if the user wishes to know more details about the program
-progress (another, but possibly confusing name for the same function is {\bf wxLogInfo}).
+\func{void}{wxStartTimer}{\void}
-\membersection{::wxLogStatus}\label{wxlogstatus}
+Starts a stopwatch; use \helpref{::wxGetElapsedTime}{wxgetelapsedtime} to get the elapsed time.
-\func{void}{wxLogStatus}{\param{wxFrame *}{frame}, \param{const char*}{ formatString}, \param{...}{}}
+See also \helpref{wxTimer}{wxtimer}.
-\func{void}{wxLogStatus}{\param{const char*}{ formatString}, \param{...}{}}
+\wxheading{Include files}
-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).
+<wx/timer.h>
-If the target frame doesn't have a statusbar, the message will be lost.
-\membersection{::wxLogSysError}\label{wxlogsyserror}
+\membersection{::wxUsleep}\label{wxusleep}
-\func{void}{wxLogSysError}{\param{const char*}{ formatString}, \param{...}{}}
+\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
-Mostly used by wxWindows itself, but might be handy for logging errors after
-system call (API function) failure. It logs the specified message text as well
-as the last system error code ({\it errno} or {\it ::GetLastError()} depending
-on the platform) and the corresponding error message. The second form
-of this function takes the error code explitly as the first argument.
+This function is deprecated because its name is misleading: notice that the
+argument is in milliseconds, not microseconds. Please use either
+\helpref{wxMilliSleep}{wxmillisleep} or \helpref{wxMicroSleep}{wxmicrosleep}
+depending on the resolution you need.
-\wxheading{See also}
-\helpref{wxSysErrorCode}{wxsyserrorcode},
-\helpref{wxSysErrorMsg}{wxsyserrormsg}
-\membersection{::wxLogDebug}\label{wxlogdebug}
+\section{Debugging macros and functions}\label{debugmacros}
-\func{void}{wxLogDebug}{\param{const char*}{ formatString}, \param{...}{}}
+Useful macros and functions for error checking and defensive programming.
+wxWidgets defines three families of the assert-like macros:
+the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined
+(in other words, in the debug build) but disappear completely in the release
+build. On the other hand, the wxCHECK macros stay event in release builds but a
+check failure doesn't generate any user-visible effects then. Finally, the
+compile time assertions don't happen during the run-time but result in the
+compilation error messages if the condition they check fail.
-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).
+\wxheading{Include files}
-\membersection{::wxLogTrace}\label{wxlogtrace}
+<wx/debug.h>
-\func{void}{wxLogTrace}{\param{const char*}{ formatString}, \param{...}{}}
-\func{void}{wxLogTrace}{\param{const char *}{mask}, \param{const char *}{formatString}, \param{...}{}}
+\membersection{::wxOnAssert}\label{wxonassert}
-\func{void}{wxLogTrace}{\param{wxTraceMask}{ mask}, \param{const char *}{formatString}, \param{...}{}}
+\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{func}, \param{const char *}{cond}, \param{const char *}{msg = NULL}}
-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.
+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 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).
+To override the default behaviour in the debug builds which is to show the user
+a dialog asking whether he wants to abort the program, continue or continue
+ignoring any subsequent assert failures, you may override
+\helpref{wxApp::OnAssertFailure}{wxapponassertfailure} which is called by this function if
+the global application object exists.
-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}
+\membersection{wxASSERT}\label{wxassert}
-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.
+\func{}{wxASSERT}{\param{}{condition}}
-\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}
+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.
-\membersection{::wxSysErrorCode}\label{wxsyserrorcode}
+Please note that the condition in wxASSERT() should have no side effects
+because it will not be executed in release mode at all.
-\func{unsigned long}{wxSysErrorCode}{\void}
+\wxheading{See also}
-Returns the error code from the last system call. This function uses
-{\tt errno} on Unix platforms and {\tt GetLastError} under Win32.
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
-\wxheading{See also}
-\helpref{wxSysErrorMsg}{wxsyserrormsg},
-\helpref{wxLogSysError}{wxlogsyserror}
+\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize}
-\membersection{::wxSysErrorMsg}\label{wxsyserrormsg}
+\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
-\func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}}
+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.
-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.
+You may use it like this, for example:
-\wxheading{See also}
+\begin{verbatim}
+ // we rely on the int being able to hold values up to 2^32
+ wxASSERT_MIN_BITSIZE(int, 32);
-\helpref{wxSysErrorCode}{wxsyserrorcode},
-\helpref{wxLogSysError}{wxlogsyserror}
+ // can't work with the platforms using UTF-8 for wchar_t
+ wxASSERT_MIN_BITSIZE(wchar_t, 16);
+\end{verbatim}
-\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.
+\membersection{wxASSERT\_MSG}\label{wxassertmsg}
-\wxheading{Include files}
+\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
-<wx/debug.h>
+Assert macro with message. An error message will be generated if the condition is false.
-\membersection{::wxOnAssert}\label{wxonassert}
+\wxheading{See also}
-\func{void}{wxOnAssert}{\param{const char*}{ fileName}, \param{int}{ lineNumber}, \param{const char*}{ msg = NULL}}
+\helpref{wxASSERT}{wxassert},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
-This function may be redefined to do something non trivial and is called
-whenever one of debugging macros fails (i.e. condition is false in an
-assertion).
-% TODO: this should probably be an overridable in wxApp.
-\membersection{wxASSERT}\label{wxassert}
+\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert}
-\func{}{wxASSERT}{\param{}{condition}}
+\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
-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.
+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.
-Please note that the condition in wxASSERT() should have no side effects
-because it will not be executed in release mode at all.
+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.
-See also: \helpref{wxASSERT\_MSG}{wxassertmsg}
+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.
-\membersection{wxASSERT\_MSG}\label{wxassertmsg}
+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.
+
+\wxheading{See also}
+
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}
-\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
-Assert macro with message. An error message will be generated if the condition is FALSE.
+\membersection{wxCOMPILE\_TIME\_ASSERT2}\label{wxcompiletimeassert2}
+
+\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}, \param{}{name}}
+
+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 \true if the program is running under debugger, \false otherwise.
+
+Please note that this function is currently only implemented for Win32 and Mac
+builds using CodeWarrior and always returns \false elsewhere.
+
+
+
+
+\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 \true if the variable exists, \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 \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 \true on success.
projects / wxWidgets.git / blobdiff