X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/dc0cecbcc9fcac18e47e8a6a55076af7519743b5..2c6f14e1a7b5062fcf77eda40824d820d9ac288e:/docs/latex/wx/function.tex?ds=sidebyside diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index 6df137cc7f..ffd7eb45df 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -49,6 +49,10 @@ the corresponding topic. \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}\\ @@ -61,9 +65,11 @@ the corresponding topic. \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}\\ @@ -144,10 +150,13 @@ the corresponding topic. \helpref{wxIsAbsolutePath}{wxisabsolutepath}\\ \helpref{wxIsBusy}{wxisbusy}\\ \helpref{wxIsClipboardFormatAvailable}{wxisclipboardformatavailable}\\ +\helpref{wxIsDebuggerRunning}{wxisdebuggerrunning}\\ \helpref{wxIsEmpty}{wxisempty}\\ +\helpref{wxIsMainThread}{wxismainthread}\\ \helpref{wxIsNaN}{wxisnan}\\ \helpref{wxIsWild}{wxiswild}\\ \helpref{wxKill}{wxkill}\\ +\helpref{wxLEAVE\_CRIT\_SECT}{wxleavecritsect}\\ \helpref{wxLoadUserResource}{wxloaduserresource}\\ \helpref{wxLogDebug}{wxlogdebug}\\ \helpref{wxLogError}{wxlogerror}\\ @@ -451,7 +460,7 @@ the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and \wxheading{Include files} - + \section{Process control functions}\label{processfunctions} @@ -671,6 +680,16 @@ and that this function is only implemented under Unix and Win32. \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} @@ -679,6 +698,85 @@ and that this function is only implemented under Unix and Win32. \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 {\tt true} if this thread is the main one. Always returns {\tt 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} @@ -2257,8 +2355,34 @@ Passes data to the clipboard. The clipboard must have previously been opened for this call to succeed. + \section{Miscellaneous functions}\label{miscellany} +\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 @@ -3615,6 +3739,18 @@ In release mode this function does nothing. + +\membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning} + +\func{bool}{wxIsDebuggerRunning}{\void} + +Returns {\tt true} if the program is running under debugger, {\tt false} +otherwise. + +Please note that this function is currently only implemented for Mac builds +using CodeWarrior and always returns {\tt false} elsewhere. + + \section{Environment access functions}\label{environfunctions} The functions in this section allow to access (get) or change value of