X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2686d9339bc059c1637fb443307ad39b4d7b3a27..038c03337f139d64f99d3334edfd1aa08354d9f0:/docs/latex/wx/function.tex

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index 1e8528186b..f8c78e68aa 100644
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -9,7 +9,7 @@
 %% License:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\chapter{Functions}\label{functions}
+\chapter{Functions and macros}\label{functions}
 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
 \setfooter{\thepage}{}{}{}{}{\thepage}
 
@@ -35,6 +35,10 @@ the corresponding topic.
 \helpref{wxASSERT}{wxassert}\\
 \helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\
 \helpref{wxASSERT\_MSG}{wxassertmsg}\\
+\helpref{wxAtomicDec}{wxatomicdec}\\
+\helpref{wxAtomicInc}{wxatomicinc}\\
+\helpref{wxBase64Decode}{wxbase64decode}\\
+\helpref{wxBase64Encode}{wxbase64encode}\\
 \helpref{wxBeginBusyCursor}{wxbeginbusycursor}\\
 \helpref{wxBell}{wxbell}\\
 \helpref{wxBITMAP}{wxbitmapmacro}\\
@@ -72,6 +76,7 @@ the corresponding topic.
 \helpref{WXDEBUG\_NEW}{debugnew}\\
 \helpref{wxDEPRECATED}{wxdeprecated}\\
 \helpref{wxDEPRECATED\_BUT\_USED\_INTERNALLY}{wxdeprecatedbutusedinternally}\\
+\helpref{wxDEPRECATED\_INLINE}{wxdeprecatedinline}\\
 \helpref{wxDirExists}{functionwxdirexists}\\
 \helpref{wxDirSelector}{wxdirselector}\\
 \helpref{wxDisplayDepth}{wxdisplaydepth}\\
@@ -164,6 +169,7 @@ the corresponding topic.
 \helpref{wxGetenv}{wxgetenvmacro}\\
 \helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\
 \helpref{wxICON}{wxiconmacro}\\
+\helpref{wxInfoMessageBox}{wxinfomessagebox}\\
 \helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\
 \helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\
 \helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\
@@ -488,6 +494,11 @@ 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.
 
+Notice that this function is only available if 
+\texttt{wxUSE\_ON\_FATAL\_EXCEPTION} is $1$ and under Windows platform this
+requires a compiler with support for SEH (structured exception handling) which
+currently means only Microsoft Visual C++ or a recent Borland C++ version.
+
 
 \membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
 
@@ -1566,11 +1577,14 @@ that there isn't always a standard way to do a reliable check on the OS architec
 
 \membersection{::wxGetUserHome}\label{wxgetuserhome}
 
-\func{const wxChar *}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
+\func{wxString}{wxGetUserHome}{\param{const wxString\& }{user = ""}}
+
+Returns the home directory for the given user. If the \arg{user} is empty
+(default value), this function behaves like 
+\helpref{wxGetHomeDir}{wxgethomedir} i.e. returns the current user home
+directory.
 
-Returns the home directory for the given user. If the username is empty
-(default value), this function behaves like
-\helpref{wxGetHomeDir}{wxgethomedir}.
+If the home directory couldn't be determined, an empty string is returned.
 
 \wxheading{Include files}
 
@@ -1797,11 +1811,9 @@ build. In fact, its definition is:
 \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).
+value of its argument.
 
-However it does have a purpose and it is to mark the literal strings for the
+However it does have a purpose which 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
@@ -1816,7 +1828,7 @@ translated (note that it is a bad example, really, as
 day names already). If you write
 
 \begin{verbatim}
-static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
+static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 ...
 // use weekdays[n] as usual
 \end{verbatim}
@@ -1825,7 +1837,7 @@ 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") };
+static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
 ...
 // use wxGetTranslation(weekdays[n])
 \end{verbatim}
@@ -1837,6 +1849,7 @@ 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}}
@@ -1955,6 +1968,8 @@ See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
 
 Ring the system bell.
 
+Note that this function is categorized as a GUI one and so is not thread-safe.
+
 \wxheading{Include files}
 
 <wx/utils.h>
@@ -2095,7 +2110,7 @@ customization.
 
 \membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
 
-\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}}
+\func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}, \param{wxColourData *}{data = \NULL}}
 
 Shows the colour selection dialog and returns the colour selected by user or
 invalid colour (use \helpref{wxColour:IsOk}{wxcolourisok} to test whether a colour
@@ -2109,6 +2124,10 @@ is valid) if the dialog was cancelled.
 
 \docparam{caption}{If given, this will be used for the dialog caption.}
 
+\docparam{data}{Optional object storing additional colour dialog settings, such
+as custom colours. If none is provided the same settings as the last time are
+used.}
+
 \wxheading{Include files}
 
 <wx/colordlg.h>
@@ -2337,6 +2356,23 @@ and {\tt choices}, and the client data array must have the
 same length as the choices array.}
 
 
+\membersection{::wxInfoMessageBox}\label{wxinfomessagebox}
+
+\func{void}{wxInfoMessageBox}{\param{wxWindow (}{parent = \NULL}}
+
+Shows a message box with the information about the wxWidgets build used,
+including its version, most important build parameters and the version of the
+underlying GUI toolkit. This is mainly used for diagnostic purposes and can be
+invoked by Ctrl-Alt-middle clicking on any wxWindow which doesn't otherwise
+handle this event.
+
+\newsince{2.9.0}
+
+\wxheading{Include files}
+
+<wx/utils.h>
+
+
 \membersection{::wxIsBusy}\label{wxisbusy}
 
 \func{bool}{wxIsBusy}{\void}
@@ -2433,7 +2469,7 @@ checkbox which is shown in the tips dialog.}
 
 \func{int}{wxFinite}{\param{double }{x}}
 
-Returns a non-zero value if {\it x} is neither infinite or NaN (not a number),
+Returns a non-zero value if {\it x} is neither infinite nor NaN (not a number),
 returns 0 otherwise.
 
 
@@ -2834,7 +2870,118 @@ Passes data to the clipboard.
 The clipboard must have previously been opened for this call to succeed.
 
 
-\section{Miscellaneous functions}\label{miscellany}
+\section{Miscellaneous functions and macros}\label{miscellany}
+
+
+\membersection{wxBase64Decode}\label{wxbase64decode}
+
+\func{size\_t}{wxBase64Decode}{\param{void *}{dst}, \param{size\_t }{dstLen}, 
+\param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN}, 
+\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict}, 
+\param{size\_t }{*posErr = \NULL}}
+
+\func{wxMemoryBuffer}{wxBase64Decode}{\\
+\param{const char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN},\\
+\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
+\param{size\_t }{*posErr = \NULL}}
+
+\func{wxMemoryBuffer}{wxBase64Decode}{\\
+\param{const wxString\& }{src},\\
+\param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
+\param{size\_t }{*posErr = \NULL}}
+
+These function decode a Base64-encoded string. The first version is a raw
+decoding function and decodes the data into the provided buffer \arg{dst} of
+the given size \arg{dstLen}. An error is returned if the buffer is not large
+enough -- that is not at least \helpref{wxBase64DecodedSize(srcLen)}{wxbase64decodedsize} 
+bytes. The second version allocates memory internally and returns it as
+\helpref{wxMemoryBuffer}{wxmemorybuffer} and is recommended for normal use.
+
+The first version returns the number of bytes written to the buffer or the
+necessary buffer size if \arg{dst} was \NULL or \texttt{wxCONV\_FAILED} on
+error, e.g. if the output buffer is too small or invalid characters were
+encountered in the input string. The second version returns a buffer with the
+base64 decoded binary equivalent of the input string. In neither case is the
+buffer NUL-terminated.
+
+\wxheading{Parameters}
+
+\docparam{dst}{Pointer to output buffer, may be \NULL to just compute the
+necessary buffer size.}
+
+\docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is
+\NULL.}
+
+\docparam{src}{The input string, must not be \NULL. For the version using
+wxString, the input string should contain only ASCII characters.}
+
+\docparam{srcLen}{The length of the input string or special value
+\texttt{wxNO\_LEN} if the string is \NUL-terminated and the length should be
+computed by this function itself.}
+
+\docparam{mode}{This parameter specifies the function behaviour when invalid
+characters are encountered in input. By default, any such character stops the
+decoding with error. If the mode is wxBase64DecodeMode\_SkipWS, then the white
+space characters are silently skipped instead. And if it is
+wxBase64DecodeMode\_Relaxed, then all invalid characters are skipped.}
+
+\docparam{posErr}{If this pointer is non-\NULL and an error occurs during
+decoding, it is filled with the index of the invalid character.}
+
+\wxheading{Include files}
+
+<wx/base64.h>
+
+
+\membersection{wxBase64DecodedSize}\label{wxbase64decodedsize}
+
+\func{size\_t}{wxBase64DecodedSize}{\param{size\_t }{srcLen}}
+
+Returns the size of the buffer necessary to contain the data encoded in a
+base64 string of length \arg{srcLen}. This can be useful for allocating a
+buffer to be passed to \helpref{wxBase64Decode}{wxbase64decode}.
+
+
+\membersection{wxBase64Encode}\label{wxbase64encode}
+
+\func{size\_t}{wxBase64Encode}{\param{char *}{dst}, \param{size\_t }{dstLen}, 
+\param{const void *}{src}, \param{size\_t }{srcLen}}
+
+\func{wxString}{wxBase64Encode}{\param{const void *}{src}, \param{size\_t }{srcLen}}
+
+\func{wxString}{wxBase64Encode}{\param{const wxMemoryBuffer\& }{buf}}
+
+These functions encode the given data using base64. The first of them is the
+raw encoding function writing the output string into provided buffer while the
+other ones return the output as wxString. There is no error return for these
+functions except for the first one which returns \texttt{wxCONV\_FAILED} if the
+output buffer is too small. To allocate the buffer of the correct size, use 
+\helpref{wxBase64EncodedSize}{wxbase64encodedsize} or call this function with 
+\arg{dst} set to \NULL -- it will then return the necessary buffer size.
+
+\wxheading{Parameters}
+
+\docparam{dst}{The output buffer, may be \NULL to retrieve the needed buffer
+size.}
+
+\docparam{dstLen}{The output buffer size, ignored if \arg{dst} is \NULL.}
+
+\docparam{src}{The input buffer, must not be \NULL.}
+
+\docparam{srcLen}{The length of the input data.}
+
+\wxheading{Include files}
+
+<wx/base64.h>
+
+
+\membersection{wxBase64EncodedSize}\label{wxbase64encodedsize}
+
+\func{size\_t}{wxBase64EncodedSize}{\param{size\_t }{len}}
+
+Returns the length of the string with base64 representation of a buffer of
+specified size \arg{len}. This can be useful for allocating the buffer passed
+to \helpref{wxBase64Encode}{wxbase64encode}.
 
 
 \membersection{wxCONCAT}\label{wxconcat}
@@ -2844,6 +2991,26 @@ The clipboard must have previously been opened for this call to succeed.
 This macro returns the concatenation of two tokens \arg{x} and \arg{y}.
 
 
+\membersection{wxDECLARE\_APP}\label{wxdeclareapp}
+
+\func{}{wxDECLARE\_APP}{className}
+
+This is used in headers to create a forward declaration of the
+\helpref{wxGetApp}{wxgetapp} function implemented by
+\helpref{wxIMPLEMENT\_APP}{wximplementapp}. It creates the declaration
+{\tt className\& wxGetApp(void)}.
+
+Example:
+
+\begin{verbatim}
+  wxDECLARE_APP(MyApp)
+\end{verbatim}
+
+\wxheading{Include files}
+
+<wx/app.h>
+
+
 \membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction}
 
 \func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}}
@@ -2900,6 +3067,25 @@ used from the user code or, in case of Visual C++, even when it is simply
 overridden.
 
 
+\membersection{wxDEPRECATED\_INLINE}\label{wxdeprecatedinline}
+
+\func{}{wxDEPRECATED\_INLINE}{\param{}{func}, \param{}{body}}
+
+This macro is similar to \helpref{wxDEPRECATED}{wxdeprecated} but can be used
+to not only declare the function \arg{func} as deprecated but to also provide
+its (inline) implementation \arg{body}.
+
+It can be used as following:
+\begin{verbatim}
+    class wxFoo
+    {
+    public:
+        // OldMethod() is deprecated, use NewMethod() instead
+        void NewMethod();
+        wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
+    };
+\end{verbatim}
+
 \membersection{wxEXPLICIT}\label{wxexplicit}
 
 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if
@@ -2991,7 +3177,9 @@ Generates an integer identifier unique to this run of the program.
 \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}
@@ -3019,7 +3207,9 @@ details.
 \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}
@@ -3148,6 +3338,18 @@ Find the deepest window at the mouse pointer position, returning the window
 and current pointer position in screen coordinates.
 
 
+\membersection{wxFromString}\label{wxfromstring}
+
+\func{bool}{wxFromString}{\param{const wxString\& }{str},
+                           \param{wxColour* }{col}}
+
+\func{bool}{wxFromString}{\param{const wxString\& }{str},
+                           \param{wxFont* }{col}}
+
+Converts string to the type of the second argument. Returns \true on success.
+See also: \helpref{wxToString}{wxtostring}.
+
+
 \membersection{::wxGetActiveWindow}\label{wxgetactivewindow}
 
 \func{wxWindow *}{wxGetActiveWindow}{\void}
@@ -3217,7 +3419,7 @@ Returns the mouse position in screen coordinates.
 
 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
+screen coordinates, as well as boolean values indicating the up/down
 status of the mouse buttons and the modifier keys.
 
 \wxheading{Include files}
@@ -3272,8 +3474,8 @@ Returns label that should be used for given {\it id} element.
 \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}
+useful for getting labels without accelerator char code like for toolbar tooltip or
+on platforms without traditional keyboard like smartphones}
 
 \docparam{accelerator}{optional accelerator string automatically added to label; useful
 for building labels for \helpref{wxMenuItem}{wxmenuitem}}
@@ -3463,6 +3665,16 @@ class name internally. Example of using the macro:
 Notice that there should be no semicolon after this macro.
 
 
+\membersection{wxToString}\label{wxtostring}
+
+\func{wxString}{wxToString}{\param{const wxColour\& }{col}}
+
+\func{wxString}{wxToString}{\param{const wxFont\& }{col}}
+
+Converts its argument to string.
+See also: \helpref{wxFromString}{wxfromstring}.
+
+
 \membersection{wxULL}\label{wxull}
 
 \func{wxLongLong\_t}{wxULL}{\param{}{number}}
@@ -3571,6 +3783,59 @@ Use these macros to read data from and write data to a file that stores
 data in big-endian format.
 
 
+\membersection{wxFORCE\_LINK\_THIS\_MODULE}\label{wxforcelinkthismodule}
+
+\func{}{wxFORCE\_LINK\_THIS\_MODULE}{moduleName}
+
+This macro can be used in conjunction with the
+\helpref{wxFORCE\_LINK\_MODULE}{wxforcelinkmodule} macro to force
+the linker to include in its output a specific object file.
+
+In particular, you should use this macro in the source file which you want
+to force for inclusion. The \tt{moduleName} needs to be a name not already
+in use in other \tt{wxFORCE\_LINK\_THIS\_MODULE} macros, but is not required
+to be e.g. the same name of the source file (even if it's a good choice).
+
+\wxheading{Include files}
+
+<wx/link.h>
+
+
+\membersection{wxFORCE\_LINK\_MODULE}\label{wxforcelinkmodule}
+
+\func{}{wxFORCE\_LINK\_MODULE}{moduleName}
+
+This macro can be used in conjunction with the
+\helpref{wxFORCE\_LINK\_THIS\_MODULE}{wxforcelinkthismodule} macro to force
+the linker to include in its output a specific object file.
+
+In particular, you should use this macro in a source file which you know
+for sure is linked in the output (e.g. the source file containing the "main()"
+of your app). The \tt{moduleName} is the name of the module you want to forcefully link
+(i.e. the name you used in the relative \helpref{wxFORCE\_LINK\_THIS\_MODULE}{wxforcelinkthismodule} macro.
+
+\wxheading{Include files}
+
+<wx/link.h>
+
+
+\membersection{wxIMPLEMENT\_APP}\label{wximplementapp}
+
+\func{}{wxIMPLEMENT\_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 as:
+
+\begin{verbatim}
+  wxIMPLEMENT_APP(MyApp)
+\end{verbatim}
+
+See also \helpref{wxDECLARE\_APP}{wxdeclareapp}.
+
+\wxheading{Include files}
+
+<wx/app.h>
+
 
 \section{RTTI functions}\label{rttimacros}
 
@@ -4721,3 +4986,42 @@ Returns \true on success.
 \wxheading{See also}
 
 \helpref{wxSetEnv}{wxsetenv}
+
+
+\section{Atomic operations}\label{atomicoperations}
+
+When using multi-threaded applications, it is often required to access or
+modify memory which is shared between threads. Atomic integer and pointer
+operations are an efficient way to handle this issue (another, less efficient,
+way is to use a \helpref{mutex}{wxmutex} or \helpref{critical
+section}{wxcriticalsection}). A native implementation exists for Windows,
+Linux, Solaris and Mac OS X, for other OS, a 
+\helpref{wxCriticalSection}{wxcriticalsection} is used to protect the data.
+
+One particular application is reference counting (used by so-called smart
+pointers).
+
+You should define your variable with the type wxAtomicInt in order to apply
+atomic operations to it.
+
+\wxheading{Include files}
+
+<wx/atomic.h>
+
+\membersection{::wxAtomicInc}\label{wxatomicinc}
+
+\func{void}{wxAtomicInc}{\param{wxAtomicInt\& }{value}}
+
+This function increments \arg{value} in an atomic manner.
+
+
+\membersection{::wxAtomicDec}\label{wxatomicdec}
+
+\func{wxInt32}{wxAtomicDec}{\param{wxAtomicInt\& }{value}}
+
+This function decrements \arg{value} in an atomic manner.
+
+Returns 0 if \arg{value} is 0 after decrementation or any non-zero value (not
+necessarily equal to the value of the variable) otherwise.
+
+
