Added wxDataViewTreeCtrl

[wxWidgets.git] / docs / latex / wx / function.tex

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index e145da28863227e84e970bc25a83729004a74912..f8c78e68aafd42c8662b3a14f7c0d92cf0aa7822 100644 (file)
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -9,7 +9,7 @@
 %% License:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 %% License:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 

-\chapter{Functions}\label{functions}
+\chapter{Functions and macros}\label{functions}

 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
 \setfooter{\thepage}{}{}{}{}{\thepage}
 
 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
 \setfooter{\thepage}{}{}{}{}{\thepage}
 


@@ -76,6 +76,7 @@ the corresponding topic.
 \helpref{WXDEBUG\_NEW}{debugnew}\\
 \helpref{wxDEPRECATED}{wxdeprecated}\\
 \helpref{wxDEPRECATED\_BUT\_USED\_INTERNALLY}{wxdeprecatedbutusedinternally}\\
 \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}\\
 \helpref{wxDirExists}{functionwxdirexists}\\
 \helpref{wxDirSelector}{wxdirselector}\\
 \helpref{wxDisplayDepth}{wxdisplaydepth}\\


@@ -168,6 +169,7 @@ the corresponding topic.
 \helpref{wxGetenv}{wxgetenvmacro}\\
 \helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}\\
 \helpref{wxICON}{wxiconmacro}\\
 \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}\\
 \helpref{wxINTXX\_SWAP\_ALWAYS}{intswapalways}\\
 \helpref{wxINTXX\_SWAP\_ON\_BE}{intswaponbe}\\
 \helpref{wxINTXX\_SWAP\_ON\_LE}{intswaponle}\\


@@ -492,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.
 
 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}
 
 
 \membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}
 


@@ -1570,11 +1577,14 @@ that there isn't always a standard way to do a reliable check on the OS architec
 
 \membersection{::wxGetUserHome}\label{wxgetuserhome}
 
 
 \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}
 
 
 \wxheading{Include files}
 


@@ -1801,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
 \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
 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


@@ -1820,7 +1828,7 @@ translated (note that it is a bad example, really, as
 day names already). If you write
 
 \begin{verbatim}
 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}
 ...
 // use weekdays[n] as usual
 \end{verbatim}


@@ -1829,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}
 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}
 ...
 // use wxGetTranslation(weekdays[n])
 \end{verbatim}


@@ -1841,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.
 
 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}}
 \membersection{::wxVsnprintf}\label{wxvsnprintf}
 
 \func{int}{wxVsnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{va\_list }{argPtr}}


@@ -1959,6 +1968,8 @@ See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.
 
 Ring the system bell.
 
 
 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>
 \wxheading{Include files}
 
 <wx/utils.h>


@@ -2099,7 +2110,7 @@ customization.
 
 \membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser}
 
 
 \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
 
 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


@@ -2113,6 +2124,10 @@ is valid) if the dialog was cancelled.
 
 \docparam{caption}{If given, this will be used for the dialog caption.}
 
 
 \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>
 \wxheading{Include files}
 
 <wx/colordlg.h>


@@ -2341,6 +2356,23 @@ and {\tt choices}, and the client data array must have the
 same length as the choices array.}
 
 
 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}
 \membersection{::wxIsBusy}\label{wxisbusy}
 
 \func{bool}{wxIsBusy}{\void}


@@ -2838,7 +2870,7 @@ Passes data to the clipboard.
 The clipboard must have previously been opened for this call to succeed.
 
 
 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}
 
 
 \membersection{wxBase64Decode}\label{wxbase64decode}


@@ -2853,6 +2885,11 @@ The clipboard must have previously been opened for this call to succeed.
 \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\
 \param{size\_t }{*posErr = \NULL}}
 
 \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
 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


@@ -2875,7 +2912,8 @@ necessary buffer size.}
 \docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is
 \NULL.}
 
 \docparam{dstLen}{The size of the output buffer, ignored if \arg{dst} is
 \NULL.}
 

-\docparam{src}{The input string, must not be \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
 
 \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


@@ -2953,6 +2991,26 @@ to \helpref{wxBase64Encode}{wxbase64encode}.
 This macro returns the concatenation of two tokens \arg{x} and \arg{y}.
 
 
 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}}
 \membersection{wxDYNLIB\_FUNCTION}\label{wxdynlibfunction}
 
 \func{}{wxDYNLIB\_FUNCTION}{\param{}{type}, \param{}{name}, \param{}{dynlib}}


@@ -3009,6 +3067,25 @@ used from the user code or, in case of Visual C++, even when it is simply
 overridden.
 
 
 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
 \membersection{wxEXPLICIT}\label{wxexplicit}
 
 {\tt wxEXPLICIT} is a macro which expands to the C++ {\tt explicit} keyword if


@@ -3264,7 +3341,10 @@ and current pointer position in screen coordinates.
 \membersection{wxFromString}\label{wxfromstring}
 
 \func{bool}{wxFromString}{\param{const wxString\& }{str},
 \membersection{wxFromString}\label{wxfromstring}
 
 \func{bool}{wxFromString}{\param{const wxString\& }{str},

-                           \param{wxColourBase* }{col}}
+                           \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}.
 
 Converts string to the type of the second argument. Returns \true on success.
 See also: \helpref{wxToString}{wxtostring}.


@@ -3339,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
 
 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}
 status of the mouse buttons and the modifier keys.
 
 \wxheading{Include files}


@@ -3394,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;
 \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}}
 
 \docparam{accelerator}{optional accelerator string automatically added to label; useful
 for building labels for \helpref{wxMenuItem}{wxmenuitem}}


@@ -3587,7 +3667,9 @@ Notice that there should be no semicolon after this macro.
 
 \membersection{wxToString}\label{wxtostring}
 
 
 \membersection{wxToString}\label{wxtostring}
 

-\func{wxString}{wxToString}{\param{const wxColourBase\& }{col}}
+\func{wxString}{wxToString}{\param{const wxColour\& }{col}}
+
+\func{wxString}{wxToString}{\param{const wxFont\& }{col}}

 
 Converts its argument to string.
 See also: \helpref{wxFromString}{wxfromstring}.
 
 Converts its argument to string.
 See also: \helpref{wxFromString}{wxfromstring}.


@@ -3701,6 +3783,59 @@ Use these macros to read data from and write data to a file that stores
 data in big-endian format.
 
 
 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}
 
 
 \section{RTTI functions}\label{rttimacros}