0900766967
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@38433 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
4583 lines
147 KiB
TeX
4583 lines
147 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% 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 and macros defined in wxWidgets are described here: you can
|
|
either look up a function using the alphabetical listing of them or find it in
|
|
the corresponding topic.
|
|
|
|
\section{Alphabetical functions and macros list}\label{functionsalphabetically}
|
|
|
|
\helpref{CLASSINFO}{classinfo}\\
|
|
\helpref{copystring}{copystring}\\
|
|
\helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\
|
|
\helpref{DECLARE\_APP}{declareapp}\\
|
|
\helpref{DECLARE\_CLASS}{declareclass}\\
|
|
\helpref{DECLARE\_DYNAMIC\_CLASS}{declaredynamicclass}\\
|
|
\helpref{IMPLEMENT\_ABSTRACT\_CLASS2}{implementabstractclass2}\\
|
|
\helpref{IMPLEMENT\_ABSTRACT\_CLASS}{implementabstractclass}\\
|
|
\helpref{IMPLEMENT\_APP}{implementapp}\\
|
|
\helpref{IMPLEMENT\_CLASS2}{implementclass2}\\
|
|
\helpref{IMPLEMENT\_CLASS}{implementclass}\\
|
|
\helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\
|
|
\helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\
|
|
\helpref{wxASSERT}{wxassert}\\
|
|
\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\
|
|
\helpref{wxASSERT\_MSG}{wxassertmsg}\\
|
|
\helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\
|
|
\helpref{wxBell}{wxbell}\\
|
|
\helpref{wxBITMAP}{wxbitmapmacro}\\
|
|
\helpref{wxCHANGE\_UMASK}{wxchangeumask}\\
|
|
\helpref{wxCHECK}{wxcheck}\\
|
|
\helpref{wxCHECK2\_MSG}{wxcheck2msg}\\
|
|
\helpref{wxCHECK2}{wxcheck2}\\
|
|
\helpref{wxCHECK\_GCC\_VERSION}{wxcheckgccversion}\\
|
|
\helpref{wxCHECK\_MSG}{wxcheckmsg}\\
|
|
\helpref{wxCHECK\_RET}{wxcheckret}\\
|
|
\helpref{wxCHECK\_VERSION}{wxcheckversion}\\
|
|
\helpref{wxCHECK\_VERSION\_FULL}{wxcheckversionfull}\\
|
|
\helpref{wxCHECK\_W32API\_VERSION}{wxcheckw32apiversion}\\
|
|
\helpref{wxClientDisplayRect}{wxclientdisplayrect}\\
|
|
\helpref{wxClipboardOpen}{functionwxclipboardopen}\\
|
|
\helpref{wxCloseClipboard}{wxcloseclipboard}\\
|
|
\helpref{wxColourDisplay}{wxcolourdisplay}\\
|
|
\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\
|
|
\helpref{wxCOMPILE\_TIME\_ASSERT2}{wxcompiletimeassert2}\\
|
|
\helpref{wxCONCAT}{wxconcat}\\
|
|
\helpref{wxConcatFiles}{wxconcatfiles}\\
|
|
\helpref{wxConstCast}{wxconstcast}\\
|
|
\helpref{wxCopyFile}{wxcopyfile}\\
|
|
\helpref{wxCreateDynamicObject}{wxcreatedynamicobject}\\
|
|
\helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider}\\
|
|
\helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}\\
|
|
\helpref{wxCRIT\_SECT\_DECLARE\_MEMBER}{wxcritsectdeclaremember}\\
|
|
\helpref{wxCRIT\_SECT\_LOCKER}{wxcritsectlocker}\\
|
|
\helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro}\\ % wxcs already taken!
|
|
\helpref{wxDDECleanUp}{wxddecleanup}\\
|
|
\helpref{wxDDEInitialize}{wxddeinitialize}\\
|
|
\helpref{wxDROP\_ICON}{wxdropicon}\\
|
|
\helpref{wxDebugMsg}{wxdebugmsg}\\
|
|
\helpref{WXDEBUG\_NEW}{debugnew}\\
|
|
\helpref{wxDirExists}{functionwxdirexists}\\
|
|
\helpref{wxDirSelector}{wxdirselector}\\
|
|
\helpref{wxDisplayDepth}{wxdisplaydepth}\\
|
|
\helpref{wxDisplaySize}{wxdisplaysize}\\
|
|
\helpref{wxDisplaySizeMM}{wxdisplaysizemm}\\
|
|
\helpref{wxDos2UnixFilename}{wxdos2unixfilename}\\
|
|
\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
|
|
\helpref{wxDynamicCast}{wxdynamiccast}\\
|
|
\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}\\
|
|
\helpref{wxEmptyClipboard}{wxemptyclipboard}\\
|
|
\helpref{wxEnableTopLevelWindows}{wxenabletoplevelwindows}\\
|
|
\helpref{wxEndBusyCursor}{wxendbusycursor}\\
|
|
\helpref{wxENTER\_CRIT\_SECT}{wxentercritsect}\\
|
|
\helpref{wxEntry}{wxentry}\\
|
|
\helpref{wxEnumClipboardFormats}{wxenumclipboardformats}\\
|
|
\helpref{wxError}{wxerror}\\
|
|
\helpref{wxExecute}{wxexecute}\\
|
|
\helpref{wxExit}{wxexit}\\
|
|
\helpref{wxEXPLICIT}{wxexplicit}\\
|
|
\helpref{wxFAIL\_MSG}{wxfailmsg}\\
|
|
\helpref{wxFAIL}{wxfail}\\
|
|
\helpref{wxFatalError}{wxfatalerror}\\
|
|
\helpref{wxFileExists}{functionwxfileexists}\\
|
|
\helpref{wxFileModificationTime}{wxfilemodificationtime}\\
|
|
\helpref{wxFileNameFromPath}{wxfilenamefrompath}\\
|
|
\helpref{wxFileSelector}{wxfileselector}\\
|
|
\helpref{wxFindFirstFile}{wxfindfirstfile}\\
|
|
\helpref{wxFindMenuItemId}{wxfindmenuitemid}\\
|
|
\helpref{wxFindNextFile}{wxfindnextfile}\\
|
|
\helpref{wxFindWindowAtPointer}{wxfindwindowatpointer}\\
|
|
\helpref{wxFindWindowAtPoint}{wxfindwindowatpoint}\\
|
|
\helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\
|
|
\helpref{wxFindWindowByName}{wxfindwindowbyname}\\
|
|
\helpref{wxFinite}{wxfinite}\\
|
|
\helpref{wxGetActiveWindow}{wxgetactivewindow}\\
|
|
\helpref{wxGetApp}{wxgetapp}\\
|
|
\helpref{wxGetBatteryState}{wxgetbatterystate}\\
|
|
\helpref{wxGetClipboardData}{wxgetclipboarddata}\\
|
|
\helpref{wxGetClipboardFormatName}{wxgetclipboardformatname}\\
|
|
\helpref{wxGetColourFromUser}{wxgetcolourfromuser}\\
|
|
\helpref{wxGetCwd}{wxgetcwd}\\
|
|
\helpref{wxGetDiskSpace}{wxgetdiskspace}\\
|
|
\helpref{wxGetDisplayName}{wxgetdisplayname}\\
|
|
\helpref{wxGetDisplaySize}{wxdisplaysize}\\
|
|
\helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\
|
|
\helpref{wxGetElapsedTime}{wxgetelapsedtime}\\
|
|
\helpref{wxGetEmailAddress}{wxgetemailaddress}\\
|
|
\helpref{wxGetEnv}{wxgetenv}\\
|
|
\helpref{wxGetFileKind}{wxgetfilekind}\\
|
|
\helpref{wxGetFontFromUser}{wxgetfontfromuser}\\
|
|
\helpref{wxGetFreeMemory}{wxgetfreememory}\\
|
|
\helpref{wxGetFullHostName}{wxgetfullhostname}\\
|
|
\helpref{wxGetHomeDir}{wxgethomedir}\\
|
|
\helpref{wxGetHostName}{wxgethostname}\\
|
|
\helpref{wxGetKeyState}{wxgetkeystate}\\
|
|
\helpref{wxGetLocalTimeMillis}{wxgetlocaltimemillis}\\
|
|
\helpref{wxGetLocalTime}{wxgetlocaltime}\\
|
|
\helpref{wxGetMousePosition}{wxgetmouseposition}\\
|
|
\helpref{wxGetMouseState}{wxgetmousestate}\\
|
|
\helpref{wxGetMultipleChoices}{wxgetmultiplechoices}\\
|
|
\helpref{wxGetMultipleChoice}{wxgetmultiplechoice}\\
|
|
\helpref{wxGetNumberFromUser}{wxgetnumberfromuser}\\
|
|
\helpref{wxGetOSDirectory}{wxgetosdirectory}\\
|
|
\helpref{wxGetOsDescription}{wxgetosdescription}\\
|
|
\helpref{wxGetOsVersion}{wxgetosversion}\\
|
|
\helpref{wxGetPasswordFromUser}{wxgetpasswordfromuser}\\
|
|
\helpref{wxGetPowerType}{wxgetpowertype}\\
|
|
\helpref{wxGetPrinterCommand}{wxgetprintercommand}\\
|
|
\helpref{wxGetPrinterFile}{wxgetprinterfile}\\
|
|
\helpref{wxGetPrinterMode}{wxgetprintermode}\\
|
|
\helpref{wxGetPrinterOptions}{wxgetprinteroptions}\\
|
|
\helpref{wxGetPrinterOrientation}{wxgetprinterorientation}\\
|
|
\helpref{wxGetPrinterPreviewCommand}{wxgetprinterpreviewcommand}\\
|
|
\helpref{wxGetPrinterScaling}{wxgetprinterscaling}\\
|
|
\helpref{wxGetPrinterTranslation}{wxgetprintertranslation}\\
|
|
\helpref{wxGetProcessId}{wxgetprocessid}\\
|
|
\helpref{wxGetResource}{wxgetresource}\\
|
|
\helpref{wxGetSingleChoiceData}{wxgetsinglechoicedata}\\
|
|
\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex}\\
|
|
\helpref{wxGetSingleChoice}{wxgetsinglechoice}\\
|
|
\helpref{wxGetTempFileName}{wxgettempfilename}\\
|
|
\helpref{wxGetTextFromUser}{wxgettextfromuser}\\
|
|
\helpref{wxGetTopLevelParent}{wxgettoplevelparent}\\
|
|
\helpref{wxGetTranslation}{wxgettranslation}\\
|
|
\helpref{wxGetUTCTime}{wxgetutctime}\\
|
|
\helpref{wxGetUserHome}{wxgetuserhome}\\
|
|
\helpref{wxGetUserId}{wxgetuserid}\\
|
|
\helpref{wxGetUserName}{wxgetusername}\\
|
|
\helpref{wxGetWorkingDirectory}{wxgetworkingdirectory}\\
|
|
\helpref{wxGetenv}{wxgetenvmacro}\\
|
|
\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\
|
|
\helpref{wxICON}{wxiconmacro}\\
|
|
\helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\
|
|
\helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\
|
|
\helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\
|
|
\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}\\
|
|
\helpref{wxInitialize}{wxinitialize}\\
|
|
\helpref{wxIsAbsolutePath}{wxisabsolutepath}\\
|
|
\helpref{wxIsBusy}{wxisbusy}\\
|
|
\helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\
|
|
\helpref{wxIsDebuggerRunning}{wxisdebuggerrunning}\\
|
|
\helpref{wxIsEmpty}{wxisempty}\\
|
|
\helpref{wxIsMainThread}{wxismainthread}\\
|
|
\helpref{wxIsNaN}{wxisnan}\\
|
|
\helpref{wxIsWild}{wxiswild}\\
|
|
\helpref{wxKill}{wxkill}\\
|
|
\helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser}\\
|
|
\helpref{wxLEAVE\_CRIT\_SECT}{wxleavecritsect}\\
|
|
\helpref{wxLoadUserResource}{wxloaduserresource}\\
|
|
\helpref{wxLogDebug}{wxlogdebug}\\
|
|
\helpref{wxLogError}{wxlogerror}\\
|
|
\helpref{wxLogFatalError}{wxlogfatalerror}\\
|
|
\helpref{wxLogMessage}{wxlogmessage}\\
|
|
\helpref{wxLogStatus}{wxlogstatus}\\
|
|
\helpref{wxLogSysError}{wxlogsyserror}\\
|
|
\helpref{wxLogTrace}{wxlogtrace}\\
|
|
\helpref{wxLogVerbose}{wxlogverbose}\\
|
|
\helpref{wxLogWarning}{wxlogwarning}\\
|
|
\helpref{wxLL}{wxll}\\
|
|
\helpref{wxLongLongFmtSpec}{wxlonglongfmtspec}\\
|
|
\helpref{wxMakeMetafilePlaceable}{wxmakemetafileplaceable}\\
|
|
\helpref{wxMatchWild}{wxmatchwild}\\
|
|
\helpref{wxMessageBox}{wxmessagebox}\\
|
|
\helpref{wxMilliSleep}{wxmillisleep}\\
|
|
\helpref{wxMicroSleep}{wxmicrosleep}\\
|
|
\helpref{wxMkdir}{wxmkdir}\\
|
|
\helpref{wxMutexGuiEnter}{wxmutexguienter}\\
|
|
\helpref{wxMutexGuiLeave}{wxmutexguileave}\\
|
|
\helpref{wxNewId}{wxnewid}\\
|
|
\helpref{wxNow}{wxnow}\\
|
|
\helpref{wxOnAssert}{wxonassert}\\
|
|
\helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}\\
|
|
\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}\\
|
|
\helpref{wxOpenClipboard}{wxopenclipboard}\\
|
|
\helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\
|
|
\helpref{wxPathOnly}{wxpathonly}\\
|
|
\helpref{wxPLURAL}{wxplural}\\
|
|
\helpref{wxPostDelete}{wxpostdelete}\\
|
|
\helpref{wxPostEvent}{wxpostevent}\\
|
|
\helpref{wxRegisterClipboardFormat}{wxregisterclipboardformat}\\
|
|
\helpref{wxRegisterId}{wxregisterid}\\
|
|
\helpref{wxRemoveFile}{wxremovefile}\\
|
|
\helpref{wxRenameFile}{wxrenamefile}\\
|
|
\helpref{wxRmdir}{wxrmdir}\\
|
|
\helpref{wxSafeShowMessage}{wxsafeshowmessage}\\
|
|
\helpref{wxSafeYield}{wxsafeyield}\\
|
|
\helpref{wxSetClipboardData}{wxsetclipboarddata}\\
|
|
\helpref{wxSetCursor}{wxsetcursor}\\
|
|
\helpref{wxSetDisplayName}{wxsetdisplayname}\\
|
|
\helpref{wxSetEnv}{wxsetenv}\\
|
|
\helpref{wxSetPrinterCommand}{wxsetprintercommand}\\
|
|
\helpref{wxSetPrinterFile}{wxsetprinterfile}\\
|
|
\helpref{wxSetPrinterMode}{wxsetprintermode}\\
|
|
\helpref{wxSetPrinterOptions}{wxsetprinteroptions}\\
|
|
\helpref{wxSetPrinterOrientation}{wxsetprinterorientation}\\
|
|
\helpref{wxSetPrinterPreviewCommand}{wxsetprinterpreviewcommand}\\
|
|
\helpref{wxSetPrinterScaling}{wxsetprinterscaling}\\
|
|
\helpref{wxSetPrinterTranslation}{wxsetprintertranslation}\\
|
|
\helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}\\
|
|
\helpref{wxShell}{wxshell}\\
|
|
\helpref{wxShowTip}{wxshowtip}\\
|
|
\helpref{wxShutdown}{wxshutdown}\\
|
|
\helpref{wxSleep}{wxsleep}\\
|
|
\helpref{wxSnprintf}{wxsnprintf}\\
|
|
\helpref{wxSplitPath}{wxsplitfunction}\\
|
|
\helpref{wxStartTimer}{wxstarttimer}\\
|
|
\helpref{wxStaticCast}{wxstaticcast}\\
|
|
\helpref{wxStrcmp}{wxstrcmp}\\
|
|
\helpref{wxStricmp}{wxstricmp}\\
|
|
\helpref{wxStringEq}{wxstringeq}\\
|
|
\helpref{wxStringMatch}{wxstringmatch}\\
|
|
\helpref{wxStringTokenize}{wxstringtokenize}\\
|
|
\helpref{wxStripMenuCodes}{wxstripmenucodes}\\
|
|
\helpref{wxStrlen}{wxstrlen}\\
|
|
\helpref{wxSUPPRESS\_GCC\_PRIVATE\_DTOR\_WARNING}{wxsuppressgccprivatedtorwarning}\\
|
|
\helpref{wxSysErrorCode}{wxsyserrorcode}\\
|
|
\helpref{wxSysErrorMsg}{wxsyserrormsg}\\
|
|
\helpref{wxT}{wxt}\\
|
|
\helpref{wxTrace}{wxtrace}\\
|
|
\helpref{WXTRACE}{trace}\\
|
|
\helpref{wxTraceLevel}{wxtracelevel}\\
|
|
\helpref{WXTRACELEVEL}{tracelevel}\\
|
|
\helpref{wxTransferFileToStream}{wxtransferfiletostream}\\
|
|
\helpref{wxTransferStreamToFile}{wxtransferstreamtofile}\\
|
|
\helpref{wxTrap}{wxtrap}\\
|
|
\helpref{wxULL}{wxull}\\
|
|
\helpref{wxUninitialize}{wxuninitialize}\\
|
|
\helpref{wxUnix2DosFilename}{wxunix2dosfilename}\\
|
|
\helpref{wxUnsetEnv}{wxunsetenv}\\
|
|
\helpref{wxUsleep}{wxusleep}\\
|
|
\helpref{wxVaCopy}{wxvacopy}\\
|
|
\helpref{wxVsnprintf}{wxvsnprintf}\\
|
|
\helpref{wxWakeUpIdle}{wxwakeupidle}\\
|
|
\helpref{wxWriteResource}{wxwriteresource}\\
|
|
\helpref{wxYield}{wxyield}\\
|
|
\helpref{wx\_const\_cast}{wxconstcastraw}\\
|
|
\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\
|
|
\helpref{wx\_static\_cast}{wxstaticcastraw}\\
|
|
\helpref{wx\_truncate\_cast}{wxtruncatecast}\\
|
|
\helpref{\_}{underscore}\\
|
|
\helpref{\_T}{underscoret}
|
|
\helpref{\_\_WXFUNCTION\_\_}{wxfunction}
|
|
|
|
|
|
|
|
\section{Version macros}\label{versionfunctions}
|
|
|
|
The following constants are defined in wxWidgets:
|
|
|
|
\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/version.h> or <wx/defs.h>
|
|
|
|
|
|
\membersection{wxCHECK\_GCC\_VERSION}\label{wxcheckgccversion}
|
|
|
|
\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}}
|
|
|
|
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$.
|
|
|
|
|
|
\membersection{wxCHECK\_VERSION}\label{wxcheckversion}
|
|
|
|
\func{bool}{wxCHECK\_VERSION}{\param{}{major, minor, release}}
|
|
|
|
This is a macro which evaluates to true if the current wxWidgets version is at
|
|
least major.minor.release.
|
|
|
|
For example, to test if the program is compiled with wxWidgets 2.2 or higher,
|
|
the following can be done:
|
|
|
|
\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}
|
|
|
|
|
|
\membersection{wxCHECK\_VERSION\_FULL}\label{wxcheckversionfull}
|
|
|
|
\func{bool}{wxCHECK\_VERSION\_FULL}{\param{}{major, minor, release, subrel}}
|
|
|
|
Same as \helpref{wxCHECK\_VERSION}{wxcheckversion} but also checks that
|
|
\texttt{wxSUBRELEASE\_NUMBER} is at least \arg{subrel}.
|
|
|
|
|
|
\membersection{wxCHECK\_W32API\_VERSION}\label{wxcheckw32apiversion}
|
|
|
|
\func{bool}{wxCHECK\_GCC\_VERSION}{\param{}{major, minor, release}}
|
|
|
|
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$.
|
|
|
|
|
|
|
|
\section{Application initialization and termination}\label{appinifunctions}
|
|
|
|
The functions in this section are used on application startup/shutdown and also
|
|
to control the behaviour of the main event loop of the GUI programs.
|
|
|
|
|
|
\membersection{::wxEntry}\label{wxentry}
|
|
|
|
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}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
|
|
\param{const wxString\& }{commandLine}, \param{int}{ cmdShow}, \param{bool}{ enterLoop = true}}
|
|
|
|
wxWidgets initialization under Windows (non-DLL). If {\it enterLoop} is false, the
|
|
function will return immediately after calling wxApp::OnInit. Otherwise, the wxWidgets
|
|
message loop will be entered.
|
|
|
|
\func{void}{wxEntry}{\param{HANDLE}{ hInstance}, \param{HANDLE}{ hPrevInstance},
|
|
\param{WORD}{ wDataSegment}, \param{WORD}{ wHeapSize}, \param{const wxString\& }{ commandLine}}
|
|
|
|
wxWidgets initialization under Windows (for applications constructed as a DLL).
|
|
|
|
\func{int}{wxEntry}{\param{int}{ argc}, \param{const wxString\& *}{argv}}
|
|
|
|
wxWidgets initialization under Unix.
|
|
|
|
\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:
|
|
|
|
\begin{verbatim}
|
|
int CTheApp::ExitInstance()
|
|
{
|
|
// OnExit isn't called by CleanUp so must be called explicitly.
|
|
wxTheApp->OnExit();
|
|
wxApp::CleanUp();
|
|
|
|
return CWinApp::ExitInstance();
|
|
}
|
|
\end{verbatim}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/app.h>
|
|
|
|
|
|
|
|
\membersection{::wxGetApp}\label{wxgetapp}
|
|
|
|
\func{wxAppDerivedClass\&}{wxGetApp}{\void}
|
|
|
|
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}.
|
|
|
|
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{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions}
|
|
|
|
\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = true}}
|
|
|
|
If {\it doIt} is true, the fatal exceptions (also known as general protection
|
|
faults under Windows or segmentation violations in the Unix world) will be
|
|
caught and passed to \helpref{wxApp::OnFatalException}{wxapponfatalexception}.
|
|
By default, i.e. before this function is called, they will be handled in the
|
|
normal way which usually just means that the application will be terminated.
|
|
Calling wxHandleFatalExceptions() with {\it doIt} equal to false will restore
|
|
this default behaviour.
|
|
|
|
|
|
\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
|
|
|
|
\func{void}{wxInitAllImageHandlers}{\void}
|
|
|
|
Initializes all available image handlers. For a list of available handlers,
|
|
see \helpref{wxImage}{wximage}.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/image.h>
|
|
|
|
|
|
\membersection{::wxInitialize}\label{wxinitialize}
|
|
|
|
\func{bool}{wxInitialize}{\void}
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
This function may be called several times but
|
|
\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
|
|
call to this function.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/app.h>
|
|
|
|
|
|
\membersection{::wxSafeYield}\label{wxsafeyield}
|
|
|
|
\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}, \param{bool}{
|
|
onlyIfNeeded = false}}
|
|
|
|
This function is similar to wxYield, except that it disables the user input to
|
|
all program windows before calling wxYield and re-enables it again
|
|
afterwards. If {\it win} is not NULL, this window will remain enabled,
|
|
allowing the implementation of some limited user interaction.
|
|
|
|
Returns the result of the call to \helpref{::wxYield}{wxyield}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxUninitialize}\label{wxuninitialize}
|
|
|
|
\func{void}{wxUninitialize}{\void}
|
|
|
|
This function is for use in console (wxBase) programs only. It must be called
|
|
once for each previous successful call to \helpref{wxInitialize}{wxinitialize}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/app.h>
|
|
|
|
|
|
\membersection{::wxYield}\label{wxyield}
|
|
|
|
\func{bool}{wxYield}{\void}
|
|
|
|
Calls \helpref{wxApp::Yield}{wxappyield}.
|
|
|
|
This function is kept only for backwards compatibility. Please use
|
|
the \helpref{wxApp::Yield}{wxappyield} method instead in any new code.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/app.h> or <wx/utils.h>
|
|
|
|
|
|
\membersection{::wxWakeUpIdle}\label{wxwakeupidle}
|
|
|
|
\func{void}{wxWakeUpIdle}{\void}
|
|
|
|
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}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/event.h>
|
|
|
|
|
|
|
|
\section{Process control functions}\label{processfunctions}
|
|
|
|
The functions in this section are used to launch or terminate the other
|
|
processes.
|
|
|
|
|
|
\membersection{::wxExecute}\label{wxexecute}
|
|
|
|
\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
|
|
|
|
\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteCommand}}
|
|
|
|
\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}
|
|
|
|
\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteArgs}}
|
|
|
|
\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{int }{flags = 0}}
|
|
|
|
\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.}
|
|
|
|
\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}, \param{int }{flags = 0}}
|
|
|
|
\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdoutStderr}
|
|
and it only takes the {\tt command} argument,
|
|
and returns a 3-element list {\tt ( status, output, errors )}, where
|
|
{\tt output} and {\tt errors} are array references.}
|
|
|
|
Executes another program in Unix or Windows.
|
|
|
|
The first form takes a command string, such as {\tt "emacs file.txt"}.
|
|
|
|
The second form takes an array of values: a command, any number of
|
|
arguments, terminated by NULL.
|
|
|
|
The semantics of the third and fourth versions is different from the first two
|
|
and is described in more details below.
|
|
|
|
If {\it flags} parameter contains {\tt wxEXEC\_ASYNC} flag (the default), flow
|
|
of control immediately returns. If it contains {\tt wxEXEC\_SYNC}, the current
|
|
application waits until the other program has terminated.
|
|
|
|
In the case of synchronous execution, the return value is the exit code of
|
|
the process (which terminates by the moment the function returns) and will be
|
|
$-1$ if the process couldn't be started and typically 0 if the process
|
|
terminated successfully. Also, while waiting for the process to
|
|
terminate, wxExecute will call \helpref{wxYield}{wxyield}. Because of this, by
|
|
default this function disables all application windows to avoid unexpected
|
|
reentrancies which could result from the users interaction with the program
|
|
while the child process is running. If you are sure that it is safe to not
|
|
disable the program windows, you may pass \texttt{wxEXEC\_NODISABLE} flag to
|
|
prevent this automatic disabling from happening.
|
|
|
|
For asynchronous execution, however, the return value is the process id and
|
|
zero value indicates that the command could not be executed. As an added
|
|
complication, the return value of $-1$ in this case indicates that we didn't
|
|
launch a new process, but connected to the running one (this can only happen in
|
|
case of using DDE under Windows for command execution). In particular, in this,
|
|
and only this, case the calling code will not get the notification about
|
|
process termination.
|
|
|
|
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).
|
|
|
|
Finally, you may use the third overloaded version of this function to execute
|
|
a process (always synchronously, the contents of \arg{flags} is or'd with
|
|
\texttt{wxEXEC\_SYNC}) and capture its output in the array \arg{output}. The
|
|
fourth version adds the possibility to additionally capture the messages from
|
|
standard error output in the \arg{errors} array.
|
|
|
|
{\bf NB:} Currently wxExecute() can only be used from the main thread, calling
|
|
this function from another thread will result in an assert failure in debug
|
|
build and won't work.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, \helpref{Exec sample}{sampleexec}.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{command}{The command to execute and any parameters to pass to it as a
|
|
single string.}
|
|
|
|
\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.}
|
|
|
|
\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},\rtfsp
|
|
{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}}
|
|
|
|
\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}}
|
|
|
|
\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{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/app.h>
|
|
|
|
|
|
\membersection{::wxKill}\label{wxkill}
|
|
|
|
\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}, \param{int }{flags = 0}}
|
|
|
|
Equivalent to the Unix kill function: send the given signal {\it sig} to the
|
|
process with PID {\it pid}. The valid signal values are
|
|
|
|
\begin{verbatim}
|
|
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}
|
|
|
|
{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
|
|
under both Unix and Windows but all the other signals are equivalent to
|
|
{\tt wxSIGTERM} under Windows.
|
|
|
|
Returns 0 on success, -1 on failure. If {\it rc} parameter is not NULL, it will
|
|
be filled with an element of {\tt wxKillError} enum:
|
|
|
|
\begin{verbatim}
|
|
enum wxKillError
|
|
{
|
|
wxKILL_OK, // no error
|
|
wxKILL_BAD_SIGNAL, // no such signal
|
|
wxKILL_ACCESS_DENIED, // permission denied
|
|
wxKILL_NO_PROCESS, // no such process
|
|
wxKILL_ERROR // another, unspecified error
|
|
};
|
|
\end{verbatim}
|
|
|
|
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{wxProcess::Kill}{wxprocesskill},\rtfsp
|
|
\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
|
|
\helpref{Exec sample}{sampleexec}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetProcessId}\label{wxgetprocessid}
|
|
|
|
\func{unsigned long}{wxGetProcessId}{\void}
|
|
|
|
Returns the number uniquely identifying the current process in the system.
|
|
|
|
If an error occurs, $0$ is returned.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxShell}\label{wxshell}
|
|
|
|
\func{bool}{wxShell}{\param{const wxString\& }{command = NULL}}
|
|
|
|
Executes a command in an interactive shell window. If no command is
|
|
specified, then just the shell is spawned.
|
|
|
|
See also \helpref{wxExecute}{wxexecute}, \helpref{Exec sample}{sampleexec}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxShutdown}\label{wxshutdown}
|
|
|
|
\func{bool}{wxShutdown}{\param{wxShutdownFlags}{flags}}
|
|
|
|
This function shuts down or reboots the computer depending on the value of the
|
|
{\it flags}. Please notice that doing this requires the corresponding access
|
|
rights (superuser under Unix, {\tt SE\_SHUTDOWN} privelege under Windows NT)
|
|
and that this function is only implemented under Unix and Win32.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{flags}{Either {\tt wxSHUTDOWN\_POWEROFF} or {\tt wxSHUTDOWN\_REBOOT}}
|
|
|
|
\wxheading{Returns}
|
|
|
|
\true on success, \false if an error occurred.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
|
|
\section{Thread functions}\label{threadfunctions}
|
|
|
|
The functions and macros here mainly exist to make it writing the code which
|
|
may be compiled in multi thread build ({\tt wxUSE\_THREADS} $= 1$) as well as
|
|
in single thread configuration ({\tt wxUSE\_THREADS} $= 0$).
|
|
|
|
For example, a static variable must be protected against simultaneous access by
|
|
multiple threads in the former configuration but in the latter the extra
|
|
overhead of using the critical section is not needed. To solve this problem,
|
|
the \helpref{wxCRITICAL\_SECTION}{wxcriticalsectionmacro} macro may be used
|
|
to create and use the critical section only when needed.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/thread.h>
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
|
|
|
|
|
|
|
|
\membersection{wxCRIT\_SECT\_DECLARE}\label{wxcritsectdeclare}
|
|
|
|
\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}}
|
|
|
|
This macro declares a (static) critical section object named {\it cs} if
|
|
{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$.
|
|
|
|
|
|
|
|
\membersection{wxCRIT\_SECT\_DECLARE\_MEMBER}\label{wxcritsectdeclaremember}
|
|
|
|
\func{}{wxCRIT\_SECT\_DECLARE}{\param{}{cs}}
|
|
|
|
This macro declares a critical section object named {\it cs} if
|
|
{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$. As it doesn't
|
|
include the {\tt static} keyword (unlike
|
|
\helpref{wxCRIT\_SECT\_DECLARE}{wxcritsectdeclare}), it can be used to declare
|
|
a class or struct member which explains its name.
|
|
|
|
|
|
|
|
\membersection{wxCRIT\_SECT\_LOCKER}\label{wxcritsectlocker}
|
|
|
|
\func{}{wxCRIT\_SECT\_LOCKER}{\param{}{name}, \param{}{cs}}
|
|
|
|
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{wxCRITICAL\_SECTION}\label{wxcriticalsectionmacro}
|
|
|
|
\func{}{wxCRITICAL\_SECTION}{\param{}{name}}
|
|
|
|
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}
|
|
int IncCount()
|
|
{
|
|
static int s_counter = 0;
|
|
|
|
wxCRITICAL_SECTION(counter);
|
|
|
|
return ++s_counter;
|
|
}
|
|
\end{verbatim}
|
|
|
|
(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).
|
|
|
|
|
|
|
|
\membersection{wxENTER\_CRIT\_SECT}\label{wxentercritsect}
|
|
|
|
\func{}{wxENTER\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}}
|
|
|
|
This macro is equivalent to \helpref{cs.Enter()}{wxcriticalsectionenter} if
|
|
{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$.
|
|
|
|
|
|
|
|
\membersection{::wxIsMainThread}\label{wxismainthread}
|
|
|
|
\func{bool}{wxIsMainThread}{\void}
|
|
|
|
Returns \true if this thread is the main one. Always returns \true if
|
|
{\tt wxUSE\_THREADS} is $0$.
|
|
|
|
|
|
|
|
\membersection{wxLEAVE\_CRIT\_SECT}\label{wxleavecritsect}
|
|
|
|
\func{}{wxLEAVE\_CRIT\_SECT}{\param{wxCriticalSection\& }{cs}}
|
|
|
|
This macro is equivalent to \helpref{cs.Leave()}{wxcriticalsectionleave} if
|
|
{\tt wxUSE\_THREADS} is $1$ and does nothing if it is $0$.
|
|
|
|
|
|
|
|
\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
|
|
|
|
\func{void}{wxMutexGuiEnter}{\void}
|
|
|
|
This function must be called when any thread other than the main GUI thread
|
|
wants to get access to the GUI library. This function will block the execution
|
|
of the calling thread until the main thread (or any other thread holding the
|
|
main GUI lock) leaves the GUI library and no other thread will enter the GUI
|
|
library until the calling thread calls \helpref{::wxMutexGuiLeave()}{wxmutexguileave}.
|
|
|
|
Typically, these functions are used like this:
|
|
|
|
\begin{verbatim}
|
|
void MyThread::Foo(void)
|
|
{
|
|
// before doing any GUI calls we must ensure that this thread is the only
|
|
// one doing it!
|
|
|
|
wxMutexGuiEnter();
|
|
|
|
// Call GUI here:
|
|
my_window->DrawSomething();
|
|
|
|
wxMutexGuiLeave();
|
|
}
|
|
\end{verbatim}
|
|
|
|
Note that under GTK, no creation of top-level windows is allowed in any
|
|
thread but the main one.
|
|
|
|
This function is only defined on platforms which support preemptive
|
|
threads.
|
|
|
|
|
|
\membersection{::wxMutexGuiLeave}\label{wxmutexguileave}
|
|
|
|
\func{void}{wxMutexGuiLeave}{\void}
|
|
|
|
See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
|
|
|
|
This function is only defined on platforms which support preemptive
|
|
threads.
|
|
|
|
|
|
|
|
\section{File functions}\label{filefunctions}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/filefn.h>
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxPathList}{wxpathlist}\\
|
|
\helpref{wxDir}{wxdir}\\
|
|
\helpref{wxFile}{wxfile}\\
|
|
\helpref{wxFileName}{wxfilename}
|
|
|
|
|
|
\membersection{::wxDos2UnixFilename}\label{wxdos2unixfilename}
|
|
|
|
\func{void}{wxDos2UnixFilename}{\param{wxChar *}{s}}
|
|
|
|
Converts a DOS to a Unix filename by replacing backslashes with forward
|
|
slashes.
|
|
|
|
|
|
\membersection{::wxFileExists}\label{functionwxfileexists}
|
|
|
|
\func{bool}{wxFileExists}{\param{const wxString\& }{filename}}
|
|
|
|
Returns true if the file exists and is a plain file.
|
|
|
|
|
|
\membersection{::wxFileModificationTime}\label{wxfilemodificationtime}
|
|
|
|
\func{time\_t}{wxFileModificationTime}{\param{const wxString\& }{filename}}
|
|
|
|
Returns time of last modification of given file.
|
|
|
|
The return value is $0$ if an error occured (e.g. file not found).
|
|
|
|
|
|
\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath}
|
|
|
|
\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
|
|
|
|
\func{char *}{wxFileNameFromPath}{\param{char *}{path}}
|
|
|
|
{\bf NB:} This function is obsolete, please use
|
|
\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
|
|
|
|
Returns the filename for a full path. The second form returns a pointer to
|
|
temporary storage that should not be deallocated.
|
|
|
|
|
|
\membersection{::wxFindFirstFile}\label{wxfindfirstfile}
|
|
|
|
\func{wxString}{wxFindFirstFile}{\param{const char *}{spec}, \param{int}{ flags = 0}}
|
|
|
|
This function does directory searching; returns the first file
|
|
that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
|
|
get the next matching file. Neither will report the current directory "." or the
|
|
parent directory "..".
|
|
|
|
\wxheading{Warning}
|
|
|
|
As of wx 2.5.2, these functions are not thread-safe! (they use static variables). You probably want to use \helpref{wxDir::GetFirst}{wxdirgetfirst} or \helpref{wxDirTraverser}{wxdirtraverser} instead.
|
|
|
|
{\it spec} may contain wildcards.
|
|
|
|
{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
|
|
|
|
For example:
|
|
|
|
\begin{verbatim}
|
|
wxString f = wxFindFirstFile("/home/project/*.*");
|
|
while ( !f.empty() )
|
|
{
|
|
...
|
|
f = wxFindNextFile();
|
|
}
|
|
\end{verbatim}
|
|
|
|
|
|
\membersection{::wxFindNextFile}\label{wxfindnextfile}
|
|
|
|
\func{wxString}{wxFindNextFile}{\void}
|
|
|
|
Returns the next file that matches the path passed to \helpref{wxFindFirstFile}{wxfindfirstfile}.
|
|
|
|
See \helpref{wxFindFirstFile}{wxfindfirstfile} for an example.
|
|
|
|
|
|
\membersection{::wxGetDiskSpace}\label{wxgetdiskspace}
|
|
|
|
\func{bool}{wxGetDiskSpace}{\param{const wxString\& }{path}, \param{wxLongLong }{*total = NULL}, \param{wxLongLong }{*free = NULL}}
|
|
|
|
This function returns the total number of bytes and number of free bytes on
|
|
the disk containing the directory {\it path} (it should exist). Both
|
|
{\it total} and {\it free} parameters may be {\tt NULL} if the corresponding
|
|
information is not needed.
|
|
|
|
\wxheading{Returns}
|
|
|
|
\true on success, \false if an error occurred (for example, the
|
|
directory doesn't exist).
|
|
|
|
\wxheading{Portability}
|
|
|
|
This function is implemented for Win32,
|
|
Mac OS and generic Unix provided the system has {\tt statfs()} function.
|
|
|
|
This function first appeared in wxWidgets 2.3.2.
|
|
|
|
|
|
\membersection{::wxGetFileKind}\label{wxgetfilekind}
|
|
|
|
\func{wxFileKind}{wxGetFileKind}{\param{int }{fd}}
|
|
|
|
\func{wxFileKind}{wxGetFileKind}{\param{FILE *}{fp}}
|
|
|
|
Returns the type of an open file. Possible return values are:
|
|
|
|
\begin{verbatim}
|
|
enum wxFileKind
|
|
{
|
|
wxFILE_KIND_UNKNOWN,
|
|
wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets
|
|
wxFILE_KIND_TERMINAL, // a tty
|
|
wxFILE_KIND_PIPE // a pipe
|
|
};
|
|
|
|
\end{verbatim}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/filefn.h>
|
|
|
|
|
|
\membersection{::wxGetOSDirectory}\label{wxgetosdirectory}
|
|
|
|
\func{wxString}{wxGetOSDirectory}{\void}
|
|
|
|
Returns the Windows directory under Windows; on other platforms returns the empty string.
|
|
|
|
|
|
\membersection{::wxIsAbsolutePath}\label{wxisabsolutepath}
|
|
|
|
\func{bool}{wxIsAbsolutePath}{\param{const wxString\& }{filename}}
|
|
|
|
Returns true if the argument is an absolute filename, i.e. with a slash
|
|
or drive name at the beginning.
|
|
|
|
|
|
\membersection{::wxDirExists}\label{functionwxdirexists}
|
|
|
|
\func{bool}{wxDirExists}{\param{const wxString\& }{dirname}}
|
|
|
|
Returns true if the path exists.
|
|
|
|
|
|
\membersection{::wxPathOnly}\label{wxpathonly}
|
|
|
|
\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
|
|
|
|
Returns the directory part of the filename.
|
|
|
|
|
|
\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename}
|
|
|
|
\func{void}{wxUnix2DosFilename}{\param{wxChar *}{s}}
|
|
|
|
This function is deprecated, use \helpref{wxFileName}{wxfilename} instead.
|
|
|
|
Converts a Unix to a DOS filename by replacing forward
|
|
slashes with backslashes.
|
|
|
|
|
|
\membersection{wxCHANGE\_UMASK}\label{wxchangeumask}
|
|
|
|
\func{}{wxCHANGE\_UMASK}{\param{int }{mask}}
|
|
|
|
Under Unix this macro changes the current process umask to the given value,
|
|
unless it is equal to $-1$ in which case nothing is done, and restores it to
|
|
the original value on scope exit. It works by declaring a variable which sets
|
|
umask to \arg{mask} in its constructor and restores it in its destructor.
|
|
|
|
Under other platforms this macro expands to nothing.
|
|
|
|
|
|
\membersection{::wxConcatFiles}\label{wxconcatfiles}
|
|
|
|
\func{bool}{wxConcatFiles}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2},
|
|
\param{const wxString\& }{file3}}
|
|
|
|
Concatenates {\it file1} and {\it file2} to {\it file3}, returning
|
|
true if successful.
|
|
|
|
|
|
\membersection{::wxCopyFile}\label{wxcopyfile}
|
|
|
|
\func{bool}{wxCopyFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}, \param{bool }{overwrite = true}}
|
|
|
|
Copies {\it file1} to {\it file2}, returning true if successful. If
|
|
{\it overwrite} parameter is true (default), the destination file is overwritten
|
|
if it exists, but if {\it overwrite} is false, the functions fails in this
|
|
case.
|
|
|
|
|
|
\membersection{::wxGetCwd}\label{wxgetcwd}
|
|
|
|
\func{wxString}{wxGetCwd}{\void}
|
|
|
|
Returns a string containing the current (or working) directory.
|
|
|
|
|
|
\membersection{::wxGetWorkingDirectory}\label{wxgetworkingdirectory}
|
|
|
|
\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}}
|
|
|
|
{\bf NB:} This function is deprecated: use \helpref{wxGetCwd}{wxgetcwd} instead.
|
|
|
|
Copies the current working directory into the buffer if supplied, or
|
|
copies the working directory into new storage (which you {\emph must} delete
|
|
yourself) if the buffer is NULL.
|
|
|
|
{\it sz} is the size of the buffer if supplied.
|
|
|
|
|
|
\membersection{::wxGetTempFileName}\label{wxgettempfilename}
|
|
|
|
\func{char *}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char *}{buf=NULL}}
|
|
|
|
\func{bool}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{wxString\& }{buf}}
|
|
|
|
%% Makes a temporary filename based on {\it prefix}, opens and closes the file,
|
|
%% and places the name in {\it buf}. If {\it buf} is NULL, new store
|
|
%% is allocated for the temporary filename using {\it new}.
|
|
%%
|
|
%% Under Windows, the filename will include the drive and name of the
|
|
%% directory allocated for temporary files (usually the contents of the
|
|
%% TEMP variable). Under Unix, the {\tt /tmp} directory is used.
|
|
%%
|
|
%% It is the application's responsibility to create and delete the file.
|
|
|
|
{\bf NB:} These functions are obsolete, please use\rtfsp
|
|
\helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename}\rtfsp
|
|
instead.
|
|
|
|
|
|
\membersection{::wxIsWild}\label{wxiswild}
|
|
|
|
\func{bool}{wxIsWild}{\param{const wxString\& }{pattern}}
|
|
|
|
Returns true if the pattern contains wildcards. See \helpref{wxMatchWild}{wxmatchwild}.
|
|
|
|
|
|
\membersection{::wxMatchWild}\label{wxmatchwild}
|
|
|
|
\func{bool}{wxMatchWild}{\param{const wxString\& }{pattern}, \param{const wxString\& }{text}, \param{bool}{ dot\_special}}
|
|
|
|
Returns true if the \arg{pattern}\/ matches the {\it text}\/; if {\it
|
|
dot\_special}\/ is true, filenames beginning with a dot are not matched
|
|
with wildcard characters. See \helpref{wxIsWild}{wxiswild}.
|
|
|
|
|
|
\membersection{::wxMkdir}\label{wxmkdir}
|
|
|
|
\func{bool}{wxMkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}}
|
|
|
|
Makes the directory \arg{dir}, returning true if successful.
|
|
|
|
{\it perm} is the access mask for the directory for the systems on which it is
|
|
supported (Unix) and doesn't have effect for the other ones.
|
|
|
|
|
|
\membersection{::wxParseCommonDialogsFilter}\label{wxparsecommondialogsfilter}
|
|
|
|
\func{int}{wxParseCommonDialogsFilter}{\param{const wxString\& }{wildCard}, \param{wxArrayString\& }{descriptions}, \param{wxArrayString\& }{filters}}
|
|
|
|
Parses the \arg{wildCard}, returning the number of filters.
|
|
Returns 0 if none or if there's a problem.
|
|
The arrays will contain an equal number of items found before the error.
|
|
On platforms where native dialogs handle only one filter per entry,
|
|
entries in arrays are automatically adjusted.
|
|
\arg{wildCard} is in the form:
|
|
\begin{verbatim}
|
|
"All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
|
|
\end{verbatim}
|
|
|
|
\membersection{::wxRemoveFile}\label{wxremovefile}
|
|
|
|
\func{bool}{wxRemoveFile}{\param{const wxString\& }{file}}
|
|
|
|
Removes \arg{file}, returning true if successful.
|
|
|
|
|
|
\membersection{::wxRenameFile}\label{wxrenamefile}
|
|
|
|
\func{bool}{wxRenameFile}{\param{const wxString\& }{file1}, \param{const wxString\& }{file2}}
|
|
|
|
Renames \arg{file1} to \arg{file2}, returning true if successful.
|
|
|
|
|
|
\membersection{::wxRmdir}\label{wxrmdir}
|
|
|
|
\func{bool}{wxRmdir}{\param{const wxString\& }{dir}, \param{int}{ flags=0}}
|
|
|
|
Removes the directory {\it dir}, returning true if successful. Does not work under VMS.
|
|
|
|
The {\it flags} parameter is reserved for future use.
|
|
|
|
|
|
\membersection{::wxSetWorkingDirectory}\label{wxsetworkingdirectory}
|
|
|
|
\func{bool}{wxSetWorkingDirectory}{\param{const wxString\& }{dir}}
|
|
|
|
Sets the current working directory, returning true if the operation succeeded.
|
|
Under MS Windows, the current drive is also changed if {\it dir} contains a drive specification.
|
|
|
|
|
|
\membersection{::wxSplitPath}\label{wxsplitfunction}
|
|
|
|
\func{void}{wxSplitPath}{\param{const char *}{ fullname}, \param{wxString *}{ path}, \param{wxString *}{ name}, \param{wxString *}{ ext}}
|
|
|
|
{\bf NB:} This function is obsolete, please use
|
|
\helpref{wxFileName::SplitPath}{wxfilenamesplitpath} instead.
|
|
|
|
This function splits a full file name into components: the path (including possible disk/drive
|
|
specification under Windows), the base name and the extension. Any of the output parameters
|
|
({\it path}, {\it name} or {\it ext}) may be NULL if you are not interested in the value of
|
|
a particular component.
|
|
|
|
wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under
|
|
Windows, however it will not consider backslashes as path separators under Unix (where backslash
|
|
is a valid character in a filename).
|
|
|
|
On entry, {\it fullname} should be non-NULL (it may be empty though).
|
|
|
|
On return, {\it path} contains the file path (without the trailing separator), {\it name}
|
|
contains the file name and {\it ext} contains the file extension without leading dot. All
|
|
three of them may be empty if the corresponding component is. The old contents of the
|
|
strings pointed to by these parameters will be overwritten in any case (if the pointers
|
|
are not NULL).
|
|
|
|
|
|
\membersection{::wxTransferFileToStream}\label{wxtransferfiletostream}
|
|
|
|
\func{bool}{wxTransferFileToStream}{\param{const wxString\& }{filename}, \param{ostream\& }{stream}}
|
|
|
|
Copies the given file to {\it stream}. Useful when converting an old application to
|
|
use streams (within the document/view framework, for example).
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/docview.h>
|
|
|
|
|
|
\membersection{::wxTransferStreamToFile}\label{wxtransferstreamtofile}
|
|
|
|
\func{bool}{wxTransferStreamToFile}{\param{istream\& }{stream} \param{const wxString\& }{filename}}
|
|
|
|
Copies the given stream to the file {\it filename}. Useful when converting an old application to
|
|
use streams (within the document/view framework, for example).
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/docview.h>
|
|
|
|
|
|
|
|
\section{Network, user and OS functions}\label{networkfunctions}
|
|
|
|
The functions in this section are used to retrieve information about the
|
|
current computer and/or user characteristics.
|
|
|
|
|
|
\membersection{::wxGetEmailAddress}\label{wxgetemailaddress}
|
|
|
|
\func{wxString}{wxGetEmailAddress}{\void}
|
|
|
|
\func{bool}{wxGetEmailAddress}{\param{char * }{buf}, \param{int }{sz}}
|
|
|
|
Copies the user's email address into the supplied buffer, by
|
|
concatenating the values returned by \helpref{wxGetFullHostName}{wxgetfullhostname}\rtfsp
|
|
and \helpref{wxGetUserId}{wxgetuserid}.
|
|
|
|
Returns true if successful, false otherwise.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetFreeMemory}\label{wxgetfreememory}
|
|
|
|
\func{wxMemorySize}{wxGetFreeMemory}{\void}
|
|
|
|
Returns the amount of free memory in bytes under environments which
|
|
support it, and -1 if not supported or failed to perform measurement.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetFullHostName}\label{wxgetfullhostname}
|
|
|
|
\func{wxString}{wxGetFullHostName}{\void}
|
|
|
|
Returns the FQDN (fully qualified domain host name) or an empty string on
|
|
error.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxGetHostName}{wxgethostname}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetHomeDir}\label{wxgethomedir}
|
|
|
|
\func{wxString}{wxGetHomeDir}{\void}
|
|
|
|
Return the (current) user's home directory.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxGetUserHome}{wxgetuserhome}\\
|
|
\helpref{wxStandardPaths}{wxstandardpaths}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetHostName}\label{wxgethostname}
|
|
|
|
\func{wxString}{wxGetHostName}{\void}
|
|
|
|
\func{bool}{wxGetHostName}{\param{char * }{buf}, \param{int }{sz}}
|
|
|
|
Copies the current host machine's name into the supplied buffer. Please note
|
|
that the returned name is {\it not} fully qualified, i.e. it does not include
|
|
the domain name.
|
|
|
|
Under Windows or NT, this function first looks in the environment
|
|
variable SYSTEM\_NAME; if this is not found, the entry {\bf HostName}\rtfsp
|
|
in the {\bf wxWidgets} section of the WIN.INI file is tried.
|
|
|
|
The first variant of this function returns the hostname if successful or an
|
|
empty string otherwise. The second (deprecated) function returns true
|
|
if successful, false otherwise.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxGetFullHostName}{wxgetfullhostname}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetOsDescription}\label{wxgetosdescription}
|
|
|
|
\func{wxString}{wxGetOsDescription}{\void}
|
|
|
|
Returns the string containing the description of the current platform in a
|
|
user-readable form. For example, this function may return strings like
|
|
{\tt Windows NT Version 4.0} or {\tt Linux 2.2.2 i386}.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{::wxGetOsVersion}{wxgetosversion}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetOsVersion}\label{wxgetosversion}
|
|
|
|
\func{int}{wxGetOsVersion}{\param{int *}{major = NULL}, \param{int *}{minor = NULL}}
|
|
|
|
Gets operating system version information.
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
|
\twocolitemruled{Platform}{Return types}
|
|
\twocolitem{Mac OS}{Return value is wxMAC when compiled with CodeWarrior under Mac OS 8.x/9.x and Mac OS X, wxMAC\_DARWIN when compiled with the Apple Developer Tools under Mac OS X.
|
|
|
|
Both {\it major} and {\it minor} have to be looked at as hexadecimal numbers. So System 10.2.4 returns 0x10, resp 16 for {\it major} and 0x24, resp 36 for {\it minor}. }
|
|
\twocolitem{GTK}{Return value is wxGTK, For GTK 1.0, {\it major} is 1, {\it minor} is 0. }
|
|
\twocolitem{Motif}{Return value is wxMOTIF\_X, {\it major} is X version, {\it minor} is X revision.}
|
|
\twocolitem{OS/2}{Return value is wxOS2\_PM.}
|
|
\twocolitem{Windows 3.1}{Return value is wxWINDOWS, {\it major} is 3, {\it minor} is 1.}
|
|
\twocolitem{Windows NT/2000}{Return value is wxWINDOWS\_NT, version is returned in {\it major} and {\it minor}.}
|
|
\twocolitem{Windows 98}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 1 or greater.}
|
|
\twocolitem{Windows 95}{Return value is wxWIN95, {\it major} is 4, {\it minor} is 0.}
|
|
\twocolitem{Win32s (Windows 3.1)}{Return value is wxWIN32S, {\it major} is 3, {\it minor} is 1.}
|
|
\twocolitem{Windows PocketPC}{Return value is wxWINDOWS\_POCKETPC, version is returned in {\it major} and {\it minor}.}
|
|
\twocolitem{Windows Smartphone}{Return value is wxWINDOWS\_SMARTPHONE, version is returned in {\it major} and {\it minor}.}
|
|
\twocolitem{Windows CE (non-specific)}{Return value is wxWINDOWS\_CE, version is returned in {\it major} and {\it minor}.}
|
|
\twocolitem{Watcom C++ 386 supervisor mode (Windows 3.1)}{Return value is wxWIN386, {\it major} is 3, {\it minor} is 1.}
|
|
\end{twocollist}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{::wxGetOsDescription}{wxgetosdescription}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetUserHome}\label{wxgetuserhome}
|
|
|
|
\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
|
|
|
|
Returns the home directory for the given user. If the username is empty
|
|
(default value), this function behaves like
|
|
\helpref{wxGetHomeDir}{wxgethomedir}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetUserId}\label{wxgetuserid}
|
|
|
|
\func{wxString}{wxGetUserId}{\void}
|
|
|
|
\func{bool}{wxGetUserId}{\param{char * }{buf}, \param{int }{sz}}
|
|
|
|
This function returns the "user id" also known as "login name" under Unix i.e.
|
|
something like "jsmith". It uniquely identifies the current user (on this system).
|
|
|
|
Under Windows or NT, this function first looks in the environment
|
|
variables USER and LOGNAME; if neither of these is found, the entry {\bf UserId}\rtfsp
|
|
in the {\bf wxWidgets} section of the WIN.INI file is tried.
|
|
|
|
The first variant of this function returns the login name if successful or an
|
|
empty string otherwise. The second (deprecated) function returns true
|
|
if successful, false otherwise.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxGetUserName}{wxgetusername}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<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 wxWidgets} section of the WIN.INI file. If PenWindows
|
|
is running, the entry {\bf Current} in the section {\bf User} of
|
|
the PENWIN.INI file is used.
|
|
|
|
The first variant of this function returns the user name if successful or an
|
|
empty string otherwise. The second (deprecated) function returns \true
|
|
if successful, \false otherwise.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxGetUserId}{wxgetuserid}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
|
|
\section{String functions}\label{stringfunctions}
|
|
|
|
|
|
\membersection{::copystring}\label{copystring}
|
|
|
|
\func{char *}{copystring}{\param{const char *}{s}}
|
|
|
|
Makes a copy of the string {\it s} using the C++ new operator, so it can be
|
|
deleted with the {\it delete} operator.
|
|
|
|
This function is deprecated, use \helpref{wxString}{wxstring} class instead.
|
|
|
|
|
|
\membersection{::wxGetTranslation}\label{wxgettranslation}
|
|
|
|
\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
|
|
|
|
\func{const char *}{wxGetTranslation}{\param{const char * }{str}, \param{const char * }{strPlural}, \param{size\_t }{n}}
|
|
|
|
This function returns the translation of string {\it str} in the current
|
|
\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
|
|
message catalogs (see \helpref{internationalization overview}{internationalization}), the
|
|
original string is returned. In debug build, an error message is logged -- this
|
|
should help to find the strings which were not yet translated. As this function
|
|
is used very often, an alternative (and also common in Unix world) syntax is
|
|
provided: the \helpref{\_()}{underscore} macro is defined to do the same thing
|
|
as wxGetTranslation.
|
|
|
|
The second form is used when retrieving translation of string that has
|
|
different singular and plural form in English or different plural forms in some
|
|
other language. It takes two extra arguments: as above, \arg{str}
|
|
parameter must contain the singular form of the string to be converted and
|
|
is used as the key for the search in the catalog. The \arg{strPlural} parameter
|
|
is the plural form (in English). The parameter \arg{n} is used to determine the
|
|
plural form. If no message catalog is found \arg{str} is returned if `n == 1',
|
|
otherwise \arg{strPlural}.
|
|
|
|
See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150}
|
|
for additional information on plural forms handling. For a shorter alternative
|
|
see the \helpref{wxPLURAL()}{wxplural} macro.
|
|
|
|
Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}.
|
|
|
|
Note that this function is not suitable for literal strings in Unicode
|
|
builds, since the literal strings must be enclosed into
|
|
\helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them
|
|
unrecognised by \texttt{xgettext}, and so they are not extracted to the message
|
|
catalog. Instead, use the \helpref{\_()}{underscore} and
|
|
\helpref{wxPLURAL}{wxplural} macro for all literal strings.
|
|
|
|
|
|
\membersection{::wxIsEmpty}\label{wxisempty}
|
|
|
|
\func{bool}{wxIsEmpty}{\param{const char *}{ p}}
|
|
|
|
Returns \true if the pointer is either {\tt NULL} or points to an empty
|
|
string, \false otherwise.
|
|
|
|
|
|
\membersection{::wxStrcmp}\label{wxstrcmp}
|
|
|
|
\func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}}
|
|
|
|
Returns a negative value, 0, or positive value if {\it p1} is less than, equal
|
|
to or greater than {\it p2}. The comparison is case-sensitive.
|
|
|
|
This function complements the standard C function {\it stricmp()} which performs
|
|
case-insensitive comparison.
|
|
|
|
|
|
\membersection{::wxStricmp}\label{wxstricmp}
|
|
|
|
\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}
|
|
|
|
Returns a negative value, 0, or positive value if {\it p1} is less than, equal
|
|
to or greater than {\it p2}. The comparison is case-insensitive.
|
|
|
|
This function complements the standard C function {\it strcmp()} which performs
|
|
case-sensitive comparison.
|
|
|
|
|
|
\membersection{::wxStringEq}\label{wxstringeq}
|
|
|
|
\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
|
|
|
|
{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead.
|
|
|
|
A macro defined as:
|
|
|
|
\begin{verbatim}
|
|
#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
|
|
\end{verbatim}
|
|
|
|
|
|
\membersection{::wxStringMatch}\label{wxstringmatch}
|
|
|
|
\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
|
|
\param{bool}{ subString = true}, \param{bool}{ exact = false}}
|
|
|
|
{\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.
|
|
|
|
Returns \true if the substring {\it s1} is found within {\it s2},
|
|
ignoring case if {\it exact} is false. If {\it subString} is \false,
|
|
no substring matching is done.
|
|
|
|
|
|
\membersection{::wxStringTokenize}\label{wxstringtokenize}
|
|
|
|
\func{wxArrayString}{wxStringTokenize}{\param{const wxString\& }{str},\\
|
|
\param{const wxString\& }{delims = wxDEFAULT\_DELIMITERS},\\
|
|
\param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
|
|
|
|
This is a convenience function wrapping
|
|
\helpref{wxStringTokenizer}{wxstringtokenizer} which simply returns all tokens
|
|
found in the given \arg{str} in an array.
|
|
|
|
Please see
|
|
\helpref{wxStringTokenizer::wxStringTokenizer}{wxstringtokenizerwxstringtokenizer}
|
|
for the description of the other parameters.
|
|
|
|
|
|
\membersection{::wxStrlen}\label{wxstrlen}
|
|
|
|
\func{size\_t}{wxStrlen}{\param{const char *}{ p}}
|
|
|
|
This is a safe version of standard function {\it strlen()}: it does exactly the
|
|
same thing (i.e. returns the length of the string) except that it returns 0 if
|
|
{\it p} is the {\tt NULL} pointer.
|
|
|
|
|
|
\membersection{::wxSnprintf}\label{wxsnprintf}
|
|
|
|
\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
|
|
|
|
This function replaces the dangerous standard function {\tt sprintf()} and is
|
|
like {\tt snprintf()} available on some platforms. The only difference with
|
|
sprintf() is that an additional argument - buffer size - is taken and the
|
|
buffer is never overflowed.
|
|
|
|
Returns the number of characters copied to the buffer or -1 if there is not
|
|
enough space.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
|
|
|
|
|
|
\membersection{wxT}\label{wxt}
|
|
|
|
\func{wxChar}{wxT}{\param{char }{ch}}
|
|
|
|
\func{const wxChar *}{wxT}{\param{const char *}{s}}
|
|
|
|
wxT() is a macro which can be used with character and string literals (in other
|
|
words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in
|
|
Unicode build configuration. Please see the
|
|
\helpref{Unicode overview}{unicode} for more information.
|
|
|
|
This macro is simply returns the value passed to it without changes in ASCII
|
|
build. In fact, its definition is:
|
|
\begin{verbatim}
|
|
#ifdef UNICODE
|
|
#define wxT(x) L ## x
|
|
#else // !Unicode
|
|
#define wxT(x) x
|
|
#endif
|
|
\end{verbatim}
|
|
|
|
|
|
\membersection{wxTRANSLATE}\label{wxtranslate}
|
|
|
|
\func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}}
|
|
|
|
This macro doesn't do anything in the program code -- it simply expands to the
|
|
value of its argument (except in Unicode build where it is equivalent to
|
|
\helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT
|
|
with the same string which would be really unreadable).
|
|
|
|
However it does have a purpose and it is to mark the literal strings for the
|
|
extraction into the message catalog created by {\tt xgettext} program. Usually
|
|
this is achieved using \helpref{\_()}{underscore} but that macro not only marks
|
|
the string for extraction but also expands into a
|
|
\helpref{wxGetTranslation}{wxgettranslation} function call which means that it
|
|
cannot be used in some situations, notably for static array
|
|
initialization.
|
|
|
|
Here is an example which should make it more clear: suppose that you have a
|
|
static array of strings containing the weekday names and which have to be
|
|
translated (note that it is a bad example, really, as
|
|
\helpref{wxDateTime}{wxdatetime} already can be used to get the localized week
|
|
day names already). If you write
|
|
|
|
\begin{verbatim}
|
|
static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
|
|
...
|
|
// use weekdays[n] as usual
|
|
\end{verbatim}
|
|
|
|
the code wouldn't compile because the function calls are forbidden in the array
|
|
initializer. So instead you should do
|
|
|
|
\begin{verbatim}
|
|
static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
|
|
...
|
|
// use wxGetTranslation(weekdays[n])
|
|
\end{verbatim}
|
|
|
|
here.
|
|
|
|
Note that although the code {\bf would} compile if you simply omit
|
|
wxTRANSLATE() in the above, it wouldn't work as expected because there would be
|
|
no translations for the weekday names in the program message catalog and
|
|
wxGetTranslation wouldn't find them.
|
|
|
|
\membersection{::wxVsnprintf}\label{wxvsnprintf}
|
|
|
|
\func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}
|
|
|
|
The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list }
|
|
argument instead of arbitrary number of parameters.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
|
|
|
|
|
|
|
|
\membersection{\_}\label{underscore}
|
|
|
|
\func{const wxChar *}{\_}{\param{const char *}{s}}
|
|
|
|
This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation}
|
|
function, so it marks the message for the extraction by {\tt xgettext} just as
|
|
\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of
|
|
the string for the current locale during execution.
|
|
|
|
Don't confuse this macro with \helpref{\_T()}{underscoret}!
|
|
|
|
|
|
\membersection{wxPLURAL}\label{wxplural}
|
|
|
|
\func{const wxChar *}{wxPLURAL}{\param{const char *}{sing}, \param{const char *}{plur}, \param{size\_t}{n}}
|
|
|
|
This macro is identical to \helpref{\_()}{underscore} but for the plural variant
|
|
of \helpref{wxGetTranslation}{wxgettranslation}.
|
|
|
|
|
|
\membersection{\_T}\label{underscoret}
|
|
|
|
\func{wxChar}{\_T}{\param{char }{ch}}
|
|
|
|
\func{const wxChar *}{\_T}{\param{const wxChar }{ch}}
|
|
|
|
This macro is exactly the same as \helpref{wxT}{wxt} and is defined in
|
|
wxWidgets simply because it may be more intuitive for Windows programmers as
|
|
the standard Win32 headers also define it (as well as yet another name for the
|
|
same macro which is {\tt \_TEXT()}).
|
|
|
|
Don't confuse this macro with \helpref{\_()}{underscore}!
|
|
|
|
|
|
|
|
\section{Dialog functions}\label{dialogfunctions}
|
|
|
|
Below are a number of convenience functions for getting input from the
|
|
user or displaying messages. Note that in these functions the last three
|
|
parameters are optional. However, it is recommended to pass a parent frame
|
|
parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
|
|
the front when the dialog box is popped up.
|
|
|
|
|
|
\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}
|
|
|
|
\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}
|
|
|
|
Changes the cursor to the given cursor for all windows in the application.
|
|
Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
|
|
to its previous state. These two calls can be nested, and a counter
|
|
ensures that only the outer calls take effect.
|
|
|
|
See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxBell}\label{wxbell}
|
|
|
|
\func{void}{wxBell}{\void}
|
|
|
|
Ring the system bell.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxCreateFileTipProvider}\label{wxcreatefiletipprovider}
|
|
|
|
\func{wxTipProvider *}{wxCreateFileTipProvider}{\param{const wxString\& }{filename},
|
|
\param{size\_t }{currentTip}}
|
|
|
|
This function creates a \helpref{wxTipProvider}{wxtipprovider} which may be
|
|
used with \helpref{wxShowTip}{wxshowtip}.
|
|
|
|
\docparam{filename}{The name of the file containing the tips, one per line}
|
|
\docparam{currentTip}{The index of the first tip to show - normally this index
|
|
is remembered between the 2 program runs.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{Tips overview}{tipsoverview}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/tipdlg.h>
|
|
|
|
|
|
\membersection{::wxDirSelector}\label{wxdirselector}
|
|
|
|
\func{wxString}{wxDirSelector}{\param{const wxString\& }{message = wxDirSelectorPromptStr},\\
|
|
\param{const wxString\& }{default\_path = ""},\\
|
|
\param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition},\\
|
|
\param{wxWindow *}{parent = NULL}}
|
|
|
|
Pops up a directory selector dialog. The arguments have the same meaning as
|
|
those of wxDirDialog::wxDirDialog(). The message is displayed at the top,
|
|
and the default\_path, if specified, is set as the initial selection.
|
|
|
|
The application must check for an empty return value (if the user pressed
|
|
Cancel). For example:
|
|
|
|
\begin{verbatim}
|
|
const wxString& dir = wxDirSelector("Choose a folder");
|
|
if ( !dir.empty() )
|
|
{
|
|
...
|
|
}
|
|
\end{verbatim}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/dirdlg.h>
|
|
|
|
|
|
\membersection{::wxFileSelector}\label{wxfileselector}
|
|
|
|
\func{wxString}{wxFileSelector}{\param{const wxString\& }{message}, \param{const wxString\& }{default\_path = ""},\\
|
|
\param{const wxString\& }{default\_filename = ""}, \param{const wxString\& }{default\_extension = ""},\\
|
|
\param{const wxString\& }{wildcard = "*.*"}, \param{int }{flags = 0}, \param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = -1}, \param{int}{ y = -1}}
|
|
|
|
Pops up a file selector box. In Windows, this is the common file selector
|
|
dialog. In X, this is a file selector box with the same functionality.
|
|
The path and filename are distinct elements of a full file pathname.
|
|
If path is empty, the current directory will be used. If filename is empty,
|
|
no default filename will be supplied. The wildcard determines what files
|
|
are displayed in the file selector, and file extension supplies a type
|
|
extension for the required filename. Flags may be a combination of wxOPEN,
|
|
wxSAVE, wxOVERWRITE\_PROMPT or wxFILE\_MUST\_EXIST. Note that wxMULTIPLE
|
|
can only be used with \helpref{wxFileDialog}{wxfiledialog} and not here as this
|
|
function only returns a single file name.
|
|
|
|
Both the Unix and Windows versions implement a wildcard filter. Typing a
|
|
filename containing wildcards (*, ?) in the filename text item, and
|
|
clicking on Ok, will result in only those files matching the pattern being
|
|
displayed.
|
|
|
|
The wildcard may be a specification for multiple types of file
|
|
with a description for each, such as:
|
|
|
|
\begin{verbatim}
|
|
"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
|
|
\end{verbatim}
|
|
|
|
The application must check for an empty return value (the user pressed
|
|
Cancel). For example:
|
|
|
|
\begin{verbatim}
|
|
wxString filename = wxFileSelector("Choose a file to open");
|
|
if ( !filename.empty() )
|
|
{
|
|
// work with the file
|
|
...
|
|
}
|
|
//else: cancelled by user
|
|
\end{verbatim}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/filedlg.h>
|
|
|
|
|
|
\membersection{::wxEndBusyCursor}\label{wxendbusycursor}
|
|
|
|
\func{void}{wxEndBusyCursor}{\void}
|
|
|
|
Changes the cursor back to the original cursor, for all windows in the application.
|
|
Use with \helpref{wxBeginBusyCursor}{wxbeginbusycursor}.
|
|
|
|
See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
|
|
|
|
\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}}
|
|
|
|
Shows the colour selection dialog and returns the colour selected by user or
|
|
invalid colour (use \helpref{wxColour::Ok}{wxcolourok} to test whether a colour
|
|
is valid) if the dialog was cancelled.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{parent}{The parent window for the colour selection dialog}
|
|
|
|
\docparam{colInit}{If given, this will be the colour initially selected in the dialog.}
|
|
|
|
\docparam{caption}{If given, this will be used for the dialog caption.}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/colordlg.h>
|
|
|
|
|
|
\membersection{::wxGetFontFromUser}\label{wxgetfontfromuser}
|
|
|
|
\func{wxFont}{wxGetFontFromUser}{\param{wxWindow *}{parent}, \param{const wxFont\& }{fontInit}, \param{const wxString\& }{caption = wxEmptyString}}
|
|
|
|
Shows the font selection dialog and returns the font selected by user or
|
|
invalid font (use \helpref{wxFont::Ok}{wxfontok} to test whether a font
|
|
is valid) if the dialog was cancelled.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{parent}{The parent window for the font selection dialog}
|
|
|
|
\docparam{fontInit}{If given, this will be the font initially selected in the dialog.}
|
|
|
|
\docparam{caption}{If given, this will be used for the dialog caption.}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/fontdlg.h>
|
|
|
|
|
|
|
|
\membersection{::wxGetMultipleChoices}\label{wxgetmultiplechoices}
|
|
|
|
\func{size\_t}{wxGetMultipleChoices}{\\
|
|
\param{wxArrayInt\& }{selections},\\
|
|
\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{const wxArrayString\& }{aChoices},\\
|
|
\param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true},\\
|
|
\param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
\func{size\_t}{wxGetMultipleChoices}{\\
|
|
\param{wxArrayInt\& }{selections},\\
|
|
\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{int}{ n}, \param{const wxString\& }{choices[]},\\
|
|
\param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true},\\
|
|
\param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
Pops up a dialog box containing a message, OK/Cancel buttons and a
|
|
multiple-selection listbox. The user may choose an arbitrary (including 0)
|
|
number of items in the listbox whose indices will be returned in
|
|
{\it selection} array. The initial contents of this array will be used to
|
|
select the items when the dialog is shown.
|
|
|
|
You may pass the list of strings to choose from either using {\it choices}
|
|
which is an array of {\it n} strings for the listbox or by using a single
|
|
{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
|
|
|
|
If {\it centre} is true, the message text (which may include new line
|
|
characters) is centred; if false, the message is left-justified.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/choicdlg.h>
|
|
|
|
\perlnote{In wxPerl there is just an array reference in place of {\tt n}
|
|
and {\tt choices}, and no {\tt selections} parameter; the function
|
|
returns an array containing the user selections.}
|
|
|
|
|
|
\membersection{::wxGetNumberFromUser}\label{wxgetnumberfromuser}
|
|
|
|
\func{long}{wxGetNumberFromUser}{
|
|
\param{const wxString\& }{message},
|
|
\param{const wxString\& }{prompt},
|
|
\param{const wxString\& }{caption},
|
|
\param{long }{value},
|
|
\param{long }{min = 0},
|
|
\param{long }{max = 100},
|
|
\param{wxWindow *}{parent = NULL},
|
|
\param{const wxPoint\& }{pos = wxDefaultPosition}}
|
|
|
|
Shows a dialog asking the user for numeric input. The dialogs title is set to
|
|
{\it caption}, it contains a (possibly) multiline {\it message} above the
|
|
single line {\it prompt} and the zone for entering the number.
|
|
|
|
The number entered must be in the range {\it min}..{\it max} (both of which
|
|
should be positive) and {\it value} is the initial value of it. If the user
|
|
enters an invalid value or cancels the dialog, the function will return -1.
|
|
|
|
Dialog is centered on its {\it parent} unless an explicit position is given in
|
|
{\it pos}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/numdlg.h>
|
|
|
|
|
|
\membersection{::wxGetPasswordFromUser}\label{wxgetpasswordfromuser}
|
|
|
|
\func{wxString}{wxGetPasswordFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
|
|
\param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}}
|
|
|
|
Similar to \helpref{wxGetTextFromUser}{wxgettextfromuser} but the text entered
|
|
in the dialog is not shown on screen but replaced with stars. This is intended
|
|
to be used for entering passwords as the function name implies.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/textdlg.h>
|
|
|
|
|
|
\membersection{::wxGetTextFromUser}\label{wxgettextfromuser}
|
|
|
|
\func{wxString}{wxGetTextFromUser}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Input text"},\\
|
|
\param{const wxString\& }{default\_value = ``"}, \param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = wxDefaultCoord}, \param{int}{ y = wxDefaultCoord}, \param{bool}{ centre = true}}
|
|
|
|
Pop up a dialog box with title set to {\it caption}, {\it message}, and a
|
|
\rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
|
|
or press Cancel to return the empty string.
|
|
|
|
If {\it centre} is true, the message text (which may include new line characters)
|
|
is centred; if false, the message is left-justified.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/textdlg.h>
|
|
|
|
|
|
\membersection{::wxGetMultipleChoice}\label{wxgetmultiplechoice}
|
|
|
|
\func{int}{wxGetMultipleChoice}{\param{const wxString\& }{message}, \param{const wxString\& }{caption}, \param{int}{ n}, \param{const wxString\& }{choices[]},\\
|
|
\param{int }{nsel}, \param{int *}{selection},
|
|
\param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection
|
|
listbox. The user may choose one or more item(s) and press OK or Cancel.
|
|
|
|
The number of initially selected choices, and array of the selected indices,
|
|
are passed in; this array will contain the user selections on exit, with
|
|
the function returning the number of selections. {\it selection} must be
|
|
as big as the number of choices, in case all are selected.
|
|
|
|
If Cancel is pressed, -1 is returned.
|
|
|
|
{\it choices} is an array of {\it n} strings for the listbox.
|
|
|
|
If {\it centre} is true, the message text (which may include new line characters)
|
|
is centred; if false, the message is left-justified.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/choicdlg.h>
|
|
|
|
|
|
\membersection{::wxGetSingleChoice}\label{wxgetsinglechoice}
|
|
|
|
\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{const wxArrayString\& }{aChoices},\\
|
|
\param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true},\\
|
|
\param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
\func{wxString}{wxGetSingleChoice}{\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{int}{ n}, \param{const wxString\& }{choices[]},\\
|
|
\param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true},\\
|
|
\param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
Pops up a dialog box containing a message, OK/Cancel buttons and a
|
|
single-selection listbox. The user may choose an item and press OK to return a
|
|
string or Cancel to return the empty string. Use
|
|
\helpref{wxGetSingleChoiceIndex}{wxgetsinglechoiceindex} if empty string is a
|
|
valid choice and if you want to be able to detect pressing Cancel reliably.
|
|
|
|
You may pass the list of strings to choose from either using {\it choices}
|
|
which is an array of {\it n} strings for the listbox or by using a single
|
|
{\it aChoices} parameter of type \helpref{wxArrayString}{wxarraystring}.
|
|
|
|
If {\it centre} is true, the message text (which may include new line
|
|
characters) is centred; if false, the message is left-justified.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/choicdlg.h>
|
|
|
|
\perlnote{In wxPerl there is just an array reference in place of {\tt n}
|
|
and {\tt choices}.}
|
|
|
|
|
|
\membersection{::wxGetSingleChoiceIndex}\label{wxgetsinglechoiceindex}
|
|
|
|
\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{const wxArrayString\& }{aChoices},\\
|
|
\param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
\func{int}{wxGetSingleChoiceIndex}{\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{int}{ n}, \param{const wxString\& }{choices[]},\\
|
|
\param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
As {\bf wxGetSingleChoice} but returns the index representing the selected
|
|
string. If the user pressed cancel, -1 is returned.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/choicdlg.h>
|
|
|
|
\perlnote{In wxPerl there is just an array reference in place of {\tt n}
|
|
and {\tt choices}.}
|
|
|
|
|
|
\membersection{::wxGetSingleChoiceData}\label{wxgetsinglechoicedata}
|
|
|
|
\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{const wxArrayString\& }{aChoices},\\
|
|
\param{const wxString\& }{client\_data[]},\\
|
|
\param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
\func{wxString}{wxGetSingleChoiceData}{\param{const wxString\& }{message},\\
|
|
\param{const wxString\& }{caption},\\
|
|
\param{int}{ n}, \param{const wxString\& }{choices[]},\\
|
|
\param{const wxString\& }{client\_data[]},\\
|
|
\param{wxWindow *}{parent = NULL},\\
|
|
\param{int}{ x = -1}, \param{int}{ y = -1},\\
|
|
\param{bool}{ centre = true}, \param{int }{width=150}, \param{int }{height=200}}
|
|
|
|
As {\bf wxGetSingleChoice} but takes an array of client data pointers
|
|
corresponding to the strings, and returns one of these pointers or NULL if
|
|
Cancel was pressed. The {\it client\_data} array must have the same number of
|
|
elements as {\it choices} or {\it aChoices}!
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/choicdlg.h>
|
|
|
|
\perlnote{In wxPerl there is just an array reference in place of {\tt n}
|
|
and {\tt choices}, and the client data array must have the
|
|
same length as the choices array.}
|
|
|
|
|
|
\membersection{::wxIsBusy}\label{wxisbusy}
|
|
|
|
\func{bool}{wxIsBusy}{\void}
|
|
|
|
Returns true if between two \helpref{wxBeginBusyCursor}{wxbeginbusycursor} and\rtfsp
|
|
\helpref{wxEndBusyCursor}{wxendbusycursor} calls.
|
|
|
|
See also \helpref{wxBusyCursor}{wxbusycursor}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxMessageBox}\label{wxmessagebox}
|
|
|
|
\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK},\\
|
|
\param{wxWindow *}{parent = NULL}, \param{int}{ x = -1}, \param{int}{ y = -1}}
|
|
|
|
General purpose message dialog. {\it style} may be a bit list of the
|
|
following identifiers:
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
|
\twocolitem{wxYES\_NO}{Puts Yes and No buttons on the message box. May be combined with
|
|
wxCANCEL.}
|
|
\twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May only be combined with
|
|
wxYES\_NO or wxOK.}
|
|
\twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
|
|
\twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.}
|
|
\twocolitem{wxICON\_HAND}{Displays an error symbol.}
|
|
\twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.}
|
|
\twocolitem{wxICON\_QUESTION}{Displays a question mark symbol.}
|
|
\twocolitem{wxICON\_INFORMATION}{Displays an information symbol.}
|
|
\end{twocollist}
|
|
|
|
The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.
|
|
|
|
For example:
|
|
|
|
\begin{verbatim}
|
|
...
|
|
int answer = wxMessageBox("Quit program?", "Confirm",
|
|
wxYES_NO | wxCANCEL, main_frame);
|
|
if (answer == wxYES)
|
|
main_frame->Close();
|
|
...
|
|
\end{verbatim}
|
|
|
|
{\it message} may contain newline characters, in which case the
|
|
message will be split into separate lines, to cater for large messages.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/msgdlg.h>
|
|
|
|
|
|
\membersection{::wxShowTip}\label{wxshowtip}
|
|
|
|
\func{bool}{wxShowTip}{\param{wxWindow *}{parent},
|
|
\param{wxTipProvider *}{tipProvider},
|
|
\param{bool }{showAtStartup = true}}
|
|
|
|
This function shows a "startup tip" to the user. The return value is the
|
|
state of the `Show tips at startup' checkbox.
|
|
|
|
\docparam{parent}{The parent window for the modal dialog}
|
|
|
|
\docparam{tipProvider}{An object which is used to get the text of the tips.
|
|
It may be created with the \helpref{wxCreateFileTipProvider}{wxcreatefiletipprovider} function.}
|
|
|
|
\docparam{showAtStartup}{Should be true if startup tips are shown, false
|
|
otherwise. This is used as the initial value for "Show tips at startup"
|
|
checkbox which is shown in the tips dialog.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{Tips overview}{tipsoverview}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/tipdlg.h>
|
|
|
|
|
|
|
|
|
|
\section{Math functions}\label{mathfunctions}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/math.h>
|
|
|
|
|
|
\membersection{wxFinite}\label{wxfinite}
|
|
|
|
\func{int}{wxFinite}{\param{double }{x}}
|
|
|
|
Returns a non-zero value if {\it x} is neither infinite or NaN (not a number),
|
|
returns 0 otherwise.
|
|
|
|
|
|
\membersection{wxIsNaN}\label{wxisnan}
|
|
|
|
\func{bool}{wxIsNaN}{\param{double }{x}}
|
|
|
|
Returns a non-zero value if {\it x} is NaN (not a number), returns 0
|
|
otherwise.
|
|
|
|
|
|
|
|
|
|
\section{GDI functions}\label{gdifunctions}
|
|
|
|
The following are relevant to the GDI (Graphics Device Interface).
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/gdicmn.h>
|
|
|
|
|
|
\membersection{wxBITMAP}\label{wxbitmapmacro}
|
|
|
|
\func{}{wxBITMAP}{bitmapName}
|
|
|
|
This macro loads a bitmap from either application resources (on the platforms
|
|
for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
|
|
avoid using {\tt \#ifdef}s when creating bitmaps.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{Bitmaps and icons overview}{wxbitmapoverview},
|
|
\helpref{wxICON}{wxiconmacro}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/gdicmn.h>
|
|
|
|
|
|
\membersection{::wxClientDisplayRect}\label{wxclientdisplayrect}
|
|
|
|
\func{void}{wxClientDisplayRect}{\param{int *}{x}, \param{int *}{y},
|
|
\param{int *}{width}, \param{int *}{height}}
|
|
|
|
\func{wxRect}{wxGetClientDisplayRect}{\void}
|
|
|
|
Returns the dimensions of the work area on the display. On Windows
|
|
this means the area not covered by the taskbar, etc. Other platforms
|
|
are currently defaulting to the whole display until a way is found to
|
|
provide this info for all window managers, etc.
|
|
|
|
|
|
\membersection{::wxColourDisplay}\label{wxcolourdisplay}
|
|
|
|
\func{bool}{wxColourDisplay}{\void}
|
|
|
|
Returns true if the display is colour, false otherwise.
|
|
|
|
|
|
\membersection{::wxDisplayDepth}\label{wxdisplaydepth}
|
|
|
|
\func{int}{wxDisplayDepth}{\void}
|
|
|
|
Returns the depth of the display (a value of 1 denotes a monochrome display).
|
|
|
|
|
|
\membersection{::wxDisplaySize}\label{wxdisplaysize}
|
|
|
|
\func{void}{wxDisplaySize}{\param{int *}{width}, \param{int *}{height}}
|
|
|
|
\func{wxSize}{wxGetDisplaySize}{\void}
|
|
|
|
Returns the display size in pixels.
|
|
|
|
|
|
\membersection{::wxDisplaySizeMM}\label{wxdisplaysizemm}
|
|
|
|
\func{void}{wxDisplaySizeMM}{\param{int *}{width}, \param{int *}{height}}
|
|
|
|
\func{wxSize}{wxGetDisplaySizeMM}{\void}
|
|
|
|
Returns the display size in millimeters.
|
|
|
|
|
|
\membersection{::wxDROP\_ICON}\label{wxdropicon}
|
|
|
|
\func{wxIconOrCursor}{wxDROP\_ICON}{\param{const char *}{name}}
|
|
|
|
This macro creates either a cursor (MSW) or an icon (elsewhere) with the given
|
|
name. Under MSW, the cursor is loaded from the resource file and the icon is
|
|
loaded from XPM file under other platforms.
|
|
|
|
This macro should be used with
|
|
\helpref{wxDropSource constructor}{wxdropsourcewxdropsource}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/dnd.h>
|
|
|
|
|
|
\membersection{wxICON}\label{wxiconmacro}
|
|
|
|
\func{}{wxICON}{iconName}
|
|
|
|
This macro loads an icon from either application resources (on the platforms
|
|
for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
|
|
avoid using {\tt \#ifdef}s when creating icons.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{Bitmaps and icons overview}{wxbitmapoverview},
|
|
\helpref{wxBITMAP}{wxbitmapmacro}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/gdicmn.h>
|
|
|
|
|
|
\membersection{::wxMakeMetafilePlaceable}\label{wxmakemetafileplaceable}
|
|
|
|
\func{bool}{wxMakeMetafilePlaceable}{\param{const wxString\& }{filename}, \param{int }{minX}, \param{int }{minY},
|
|
\param{int }{maxX}, \param{int }{maxY}, \param{float }{scale=1.0}}
|
|
|
|
Given a filename for an existing, valid metafile (as constructed using \helpref{wxMetafileDC}{wxmetafiledc})
|
|
makes it into a placeable metafile by prepending a header containing the given
|
|
bounding box. The bounding box may be obtained from a device context after drawing
|
|
into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY.
|
|
|
|
In addition to adding the placeable metafile header, this function adds
|
|
the equivalent of the following code to the start of the metafile data:
|
|
|
|
\begin{verbatim}
|
|
SetMapMode(dc, MM_ANISOTROPIC);
|
|
SetWindowOrg(dc, minX, minY);
|
|
SetWindowExt(dc, maxX - minX, maxY - minY);
|
|
\end{verbatim}
|
|
|
|
This simulates the wxMM\_TEXT mapping mode, which wxWidgets assumes.
|
|
|
|
Placeable metafiles may be imported by many Windows applications, and can be
|
|
used in RTF (Rich Text Format) files.
|
|
|
|
{\it scale} allows the specification of scale for the metafile.
|
|
|
|
This function is only available under Windows.
|
|
|
|
|
|
\membersection{::wxSetCursor}\label{wxsetcursor}
|
|
|
|
\func{void}{wxSetCursor}{\param{wxCursor *}{cursor}}
|
|
|
|
Globally sets the cursor; only has an effect in Windows and GTK.
|
|
See also \helpref{wxCursor}{wxcursor}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor}.
|
|
|
|
|
|
|
|
\section{Printer settings}\label{printersettings}
|
|
|
|
{\bf NB:} These routines are obsolete and should no longer be used!
|
|
|
|
The following functions are used to control PostScript printing. Under
|
|
Windows, PostScript output can only be sent to a file.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/dcps.h>
|
|
|
|
|
|
\membersection{::wxGetPrinterCommand}\label{wxgetprintercommand}
|
|
|
|
\func{wxString}{wxGetPrinterCommand}{\void}
|
|
|
|
Gets the printer command used to print a file. The default is {\tt lpr}.
|
|
|
|
|
|
\membersection{::wxGetPrinterFile}\label{wxgetprinterfile}
|
|
|
|
\func{wxString}{wxGetPrinterFile}{\void}
|
|
|
|
Gets the PostScript output filename.
|
|
|
|
|
|
\membersection{::wxGetPrinterMode}\label{wxgetprintermode}
|
|
|
|
\func{int}{wxGetPrinterMode}{\void}
|
|
|
|
Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
|
|
The default is PS\_PREVIEW.
|
|
|
|
|
|
\membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions}
|
|
|
|
\func{wxString}{wxGetPrinterOptions}{\void}
|
|
|
|
Gets the additional options for the print command (e.g. specific printer). The default is nothing.
|
|
|
|
|
|
\membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation}
|
|
|
|
\func{int}{wxGetPrinterOrientation}{\void}
|
|
|
|
Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
|
|
|
|
|
|
\membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand}
|
|
|
|
\func{wxString}{wxGetPrinterPreviewCommand}{\void}
|
|
|
|
Gets the command used to view a PostScript file. The default depends on the platform.
|
|
|
|
|
|
\membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling}
|
|
|
|
\func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
|
|
|
|
Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
|
|
|
|
|
|
\membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation}
|
|
|
|
\func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
|
|
|
|
Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
|
|
|
|
|
|
\membersection{::wxSetPrinterCommand}\label{wxsetprintercommand}
|
|
|
|
\func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
|
|
|
|
Sets the printer command used to print a file. The default is {\tt lpr}.
|
|
|
|
|
|
\membersection{::wxSetPrinterFile}\label{wxsetprinterfile}
|
|
|
|
\func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
|
|
|
|
Sets the PostScript output filename.
|
|
|
|
|
|
\membersection{::wxSetPrinterMode}\label{wxsetprintermode}
|
|
|
|
\func{void}{wxSetPrinterMode}{\param{int }{mode}}
|
|
|
|
Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
|
|
The default is PS\_PREVIEW.
|
|
|
|
|
|
\membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions}
|
|
|
|
\func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
|
|
|
|
Sets the additional options for the print command (e.g. specific printer). The default is nothing.
|
|
|
|
|
|
\membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation}
|
|
|
|
\func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
|
|
|
|
Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
|
|
|
|
|
|
\membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand}
|
|
|
|
\func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
|
|
|
|
Sets the command used to view a PostScript file. The default depends on the platform.
|
|
|
|
|
|
\membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling}
|
|
|
|
\func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
|
|
|
|
Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
|
|
|
|
|
|
\membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation}
|
|
|
|
\func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
|
|
|
|
Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
|
|
|
|
|
|
|
|
\section{Clipboard functions}\label{clipsboard}
|
|
|
|
These clipboard functions are implemented for Windows only. The use of these functions
|
|
is deprecated and the code is no longer maintained. Use the \helpref{wxClipboard}{wxclipboard}
|
|
class instead.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<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 (Windows only).
|
|
|
|
\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.
|
|
|
|
\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.
|
|
|
|
\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\& }{in}}
|
|
|
|
\func{void}{wxStripMenuCodes}{\param{char *}{in}, \param{char *}{out}}
|
|
|
|
{\bf NB:} This function is obsolete, please use
|
|
\helpref{wxMenuItem::GetLabelFromText}{wxmenuitemgetlabelfromtext} instead.
|
|
|
|
Strips any menu codes from {\it in} and places the result
|
|
in {\it out} (or returns the new string, in the first form).
|
|
|
|
Menu codes include \& (mark the next character with an underline
|
|
as a keyboard shortkey in Windows and Motif) and $\backslash$t (tab in Windows).
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{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 is not a text control
|
|
}
|
|
\end{verbatim}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{RTTI overview}{runtimeclassoverview}\\
|
|
\helpref{wxDynamicCastThis}{wxdynamiccastthis}\\
|
|
\helpref{wxConstCast}{wxconstcast}\\
|
|
\helpref{wxStaticCast}{wxstaticcast}
|
|
|
|
|
|
\membersection{wxDynamicCastThis}\label{wxdynamiccastthis}
|
|
|
|
\func{classname *}{wxDynamicCastThis}{classname}
|
|
|
|
This macro is equivalent to {\tt wxDynamicCast(this, classname)} but the
|
|
latter provokes spurious compilation warnings from some compilers (because it
|
|
tests whether {\tt this} pointer is non {\tt NULL} which is always true), so
|
|
this macro should be used to avoid them.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxDynamicCast}{wxdynamiccast}
|
|
|
|
|
|
\membersection{wxStaticCast}\label{wxstaticcast}
|
|
|
|
\func{classname *}{wxStaticCast}{ptr, classname}
|
|
|
|
This macro checks that the cast is valid in debug mode (an assert failure will
|
|
result if {\tt wxDynamicCast(ptr, classname) == NULL}) and then returns the
|
|
result of executing an equivalent of {\tt static\_cast<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{::wxSysErrorMsg}\label{wxsyserrormsg}
|
|
|
|
\func{const wxChar *}{wxSysErrorMsg}{\param{unsigned long }{errCode = 0}}
|
|
|
|
Returns the error message corresponding to the given system error code. If
|
|
{\it errCode} is $0$ (default), the last error code (as returned by
|
|
\helpref{wxSysErrorCode}{wxsyserrorcode}) is used.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxSysErrorCode}{wxsyserrorcode},
|
|
\helpref{wxLogSysError}{wxlogsyserror}
|
|
|
|
|
|
\membersection{WXTRACE}\label{trace}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/object.h>
|
|
|
|
\func{}{WXTRACE}{formatString, ...}
|
|
|
|
{\bf NB:} This macro is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
|
|
|
|
Calls wxTrace with printf-style variable argument syntax. Output
|
|
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
|
|
|
|
\wxheading{Include files}
|
|
|
|
<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.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/memory.h>
|
|
|
|
|
|
\membersection{::wxTrace}\label{wxtrace}
|
|
|
|
\func{void}{wxTrace}{\param{const wxString\& }{fmt}, \param{...}{}}
|
|
|
|
{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
|
|
|
|
Takes printf-style variable argument syntax. Output
|
|
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/memory.h>
|
|
|
|
|
|
\membersection{::wxTraceLevel}\label{wxtracelevel}
|
|
|
|
\func{void}{wxTraceLevel}{\param{int}{ level}, \param{const wxString\& }{fmt}, \param{...}{}}
|
|
|
|
{\bf NB:} This function is now obsolete, replaced by \helpref{Log functions}{logfunctions}.
|
|
|
|
Takes printf-style variable argument syntax. Output
|
|
is directed to the current output stream (see \helpref{wxDebugContext}{wxdebugcontextoverview}).
|
|
The first argument should be the level at which this information is appropriate.
|
|
It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than
|
|
this value.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/memory.h>
|
|
|
|
|
|
|
|
\section{Time functions}\label{timefunctions}
|
|
|
|
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{::wxGetElapsedTime}\label{wxgetelapsedtime}
|
|
|
|
\func{long}{wxGetElapsedTime}{\param{bool}{ resetTimer = true}}
|
|
|
|
Gets the time in milliseconds since the last \helpref{::wxStartTimer}{wxstarttimer}.
|
|
|
|
If {\it resetTimer} is true (the default), the timer is reset to zero
|
|
by this call.
|
|
|
|
See also \helpref{wxTimer}{wxtimer}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/timer.h>
|
|
|
|
|
|
\membersection{::wxGetLocalTime}\label{wxgetlocaltime}
|
|
|
|
\func{long}{wxGetLocalTime}{\void}
|
|
|
|
Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxDateTime::Now}{wxdatetimenow}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/timer.h>
|
|
|
|
|
|
\membersection{::wxGetLocalTimeMillis}\label{wxgetlocaltimemillis}
|
|
|
|
\func{wxLongLong}{wxGetLocalTimeMillis}{\void}
|
|
|
|
Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxDateTime::Now}{wxdatetimenow},\\
|
|
\helpref{wxLongLong}{wxlonglong}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/timer.h>
|
|
|
|
|
|
\membersection{::wxGetUTCTime}\label{wxgetutctime}
|
|
|
|
\func{long}{wxGetUTCTime}{\void}
|
|
|
|
Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxDateTime::Now}{wxdatetimenow}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/timer.h>
|
|
|
|
|
|
\membersection{::wxMicroSleep}\label{wxmicrosleep}
|
|
|
|
\func{void}{wxMicroSleep}{\param{unsigned long}{ microseconds}}
|
|
|
|
Sleeps for the specified number of microseconds. The microsecond resolution may
|
|
not, in fact, be available on all platforms (currently only Unix platforms with
|
|
nanosleep(2) may provide it) in which case this is the same as
|
|
\helpref{wxMilliSleep}{wxmillisleep}(\arg{microseconds}$/1000$).
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxMilliSleep}\label{wxmillisleep}
|
|
|
|
\func{void}{wxMilliSleep}{\param{unsigned long}{ milliseconds}}
|
|
|
|
Sleeps for the specified number of milliseconds. Notice that usage of this
|
|
function is encouraged instead of calling usleep(3) directly because the
|
|
standard usleep() function is not MT safe.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxNow}\label{wxnow}
|
|
|
|
\func{wxString}{wxNow}{\void}
|
|
|
|
Returns a string representing the current date and time.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/utils.h>
|
|
|
|
|
|
\membersection{::wxSleep}\label{wxsleep}
|
|
|
|
\func{void}{wxSleep}{\param{int}{ secs}}
|
|
|
|
Sleeps for the specified number of seconds.
|
|
|
|
\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}.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/timer.h>
|
|
|
|
|
|
\membersection{::wxUsleep}\label{wxusleep}
|
|
|
|
\func{void}{wxUsleep}{\param{unsigned long}{ milliseconds}}
|
|
|
|
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.
|
|
|
|
|
|
|
|
\section{Debugging macros and functions}\label{debugmacros}
|
|
|
|
Useful macros and functions for error checking and defensive programming.
|
|
wxWidgets defines three families of the assert-like macros:
|
|
the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined
|
|
(in other words, in the debug build) but disappear completely in the release
|
|
build. On the other hand, the wxCHECK macros stay event in release builds but a
|
|
check failure doesn't generate any user-visible effects then. Finally, the
|
|
compile time assertions don't happen during the run-time but result in the
|
|
compilation error messages if the condition they check fail.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/debug.h>
|
|
|
|
|
|
\membersection{::wxOnAssert}\label{wxonassert}
|
|
|
|
\func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{func}, \param{const char *}{cond}, \param{const char *}{msg = NULL}}
|
|
|
|
This function is called whenever one of debugging macros fails (i.e. condition
|
|
is false in an assertion). It is only defined in the debug mode, in release
|
|
builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything.
|
|
|
|
To override the default behaviour in the debug builds which is to show the user
|
|
a dialog asking whether he wants to abort the program, continue or continue
|
|
ignoring any subsequent assert failures, you may override
|
|
\helpref{wxApp::OnAssertFailure}{wxapponassertfailure} which is called by this function if
|
|
the global application object exists.
|
|
|
|
|
|
\membersection{wxASSERT}\label{wxassert}
|
|
|
|
\func{}{wxASSERT}{\param{}{condition}}
|
|
|
|
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.
|
|
|
|
Please note that the condition in wxASSERT() should have no side effects
|
|
because it will not be executed in release mode at all.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxASSERT\_MSG}{wxassertmsg},\\
|
|
\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
|
|
|
|
|
|
\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize}
|
|
|
|
\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
|
|
|
|
This macro results in a
|
|
\helpref{compile time assertion failure}{wxcompiletimeassert} if the size
|
|
of the given type {\it type} is less than {\it size} bits.
|
|
|
|
You may use it like this, for example:
|
|
|
|
\begin{verbatim}
|
|
// we rely on the int being able to hold values up to 2^32
|
|
wxASSERT_MIN_BITSIZE(int, 32);
|
|
|
|
// can't work with the platforms using UTF-8 for wchar_t
|
|
wxASSERT_MIN_BITSIZE(wchar_t, 16);
|
|
\end{verbatim}
|
|
|
|
|
|
\membersection{wxASSERT\_MSG}\label{wxassertmsg}
|
|
|
|
\func{}{wxASSERT\_MSG}{\param{}{condition}, \param{}{msg}}
|
|
|
|
Assert macro with message. An error message will be generated if the condition is false.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxASSERT}{wxassert},\\
|
|
\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
|
|
|
|
|
|
\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert}
|
|
|
|
\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
|
|
|
|
Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the
|
|
specified {\it condition} is false. The compiler error message should include
|
|
the {\it msg} identifier - please note that it must be a valid C++ identifier
|
|
and not a string unlike in the other cases.
|
|
|
|
This 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.
|
|
|
|
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.
|
|
|
|
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}
|
|
|
|
|
|
\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}.
|
|
|
|
|
|
\membersection{wxFAIL}\label{wxfail}
|
|
|
|
\func{}{wxFAIL}{\void}
|
|
|
|
Will always generate an assert error if this code is reached (in debug mode).
|
|
|
|
See also: \helpref{wxFAIL\_MSG}{wxfailmsg}
|
|
|
|
|
|
\membersection{wxFAIL\_MSG}\label{wxfailmsg}
|
|
|
|
\func{}{wxFAIL\_MSG}{\param{}{msg}}
|
|
|
|
Will always generate an assert error with specified message if this code is reached (in debug mode).
|
|
|
|
This macro is useful for marking unreachable" code areas, for example
|
|
it may be used in the "default:" branch of a switch statement if all possible
|
|
cases are processed above.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxFAIL}{wxfail}
|
|
|
|
|
|
\membersection{wxCHECK}\label{wxcheck}
|
|
|
|
\func{}{wxCHECK}{\param{}{condition}, \param{}{retValue}}
|
|
|
|
Checks that the condition is true, returns with the given return value if not (FAILs in debug mode).
|
|
This check is done even in release mode.
|
|
|
|
|
|
\membersection{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
|
|
\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
|
|
\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
|
|
\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
|
|
\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.
|