X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/965b4f87d9d59c7c6d58da6567dca176d9131296..71aba8333cc915afff9e740c944f7fa7247abacb:/docs/latex/wx/function.tex

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index b5261ffb0b..0318e25402 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}\\
@@ -201,6 +210,7 @@ the corresponding topic.
 \helpref{wxSplitPath}{wxsplitfunction}\\
 \helpref{wxStartTimer}{wxstarttimer}\\
 \helpref{wxStaticCast}{wxstaticcast}\\
+\helpref{wxStrcmp}{wxstrcmp}\\
 \helpref{wxStricmp}{wxstricmp}\\
 \helpref{wxStringEq}{wxstringeq}\\
 \helpref{wxStringMatch}{wxstringmatch}\\
@@ -450,7 +460,7 @@ the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and
 
 \wxheading{Include files}
 
-<wx/app.h>
+<wx/event.h>
 
 \section{Process control functions}\label{processfunctions}
 
@@ -461,17 +471,23 @@ processes.
 
 \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}}
 
-\perlnote{In wxPerl this function only takes the {\tt command} argument,
+\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}}
 
-\perlnote{In wxPerl this function only takes the {\tt command} argument,
+\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.}
 
@@ -670,6 +686,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}
 
 <wx/thread.h>
@@ -678,6 +704,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}
@@ -1226,6 +1331,16 @@ as wxGetTranslation.
 Returns {\tt true} if the pointer is either {\tt NULL} or points to an empty
 string, {\tt 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}}
@@ -1403,8 +1518,6 @@ same macro which is {\tt \_TEXT()}).
 
 Don't confuse this macro with \helpref{\_()}{underscore}!
 
-\membersection{\_}\label{underscore}
-
 \section{Dialog functions}\label{dialogfunctions}
 
 Below are a number of convenience functions for getting input from the
@@ -1813,7 +1926,7 @@ See also \helpref{wxBusyCursor}{wxbusycursor}.
 
 \membersection{::wxMessageBox}\label{wxmessagebox}
 
-\func{int}{wxMessageBox}{\param{const wxString\& }{message}, \param{const wxString\& }{caption = ``Message"}, \param{int}{ style = wxOK \pipe wxCENTRE},\\
+\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
@@ -1825,7 +1938,6 @@ wxCANCEL.}
 \twocolitem{wxCANCEL}{Puts a Cancel button on the message box. May be combined with
 wxYES\_NO or wxOK.}
 \twocolitem{wxOK}{Puts an Ok button on the message box. May be combined with wxCANCEL.}
-\twocolitem{wxCENTRE}{Centres the text.}
 \twocolitem{wxICON\_EXCLAMATION}{Displays an exclamation mark symbol.}
 \twocolitem{wxICON\_HAND}{Displays an error symbol.}
 \twocolitem{wxICON\_ERROR}{Displays an error symbol - the same as wxICON\_HAND.}
@@ -1842,18 +1954,13 @@ For example:
   int answer = wxMessageBox("Quit program?", "Confirm",
                             wxYES_NO | wxCANCEL, main_frame);
   if (answer == wxYES)
-    delete main_frame;
+    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.
 
-Under Windows, the native MessageBox function is used unless wxCENTRE
-is specified in the style, in which case a generic function is used.
-This is because the native MessageBox function cannot centre text.
-The symbols are not shown when the generic function is used.
-
 \wxheading{Include files}
 
 <wx/msgdlg.h>
@@ -2252,8 +2359,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
@@ -3610,6 +3743,18 @@ In release mode this function does nothing.
 
 <wx/debug.h>
 
+
+\membersection{::wxIsDebuggerRunning}\label{wxisdebuggerrunning}
+
+\func{bool}{wxIsDebuggerRunning}{\void}
+
+Returns {\tt true} if the program is running under debugger, {\tt false} 
+otherwise.
+
+Please note that this function is currently only implemented for Mac builds
+using CodeWarrior and always returns {\tt false} elsewhere.
+
+
 \section{Environment access functions}\label{environfunctions}
 
 The functions in this section allow to access (get) or change value of
