X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4db03d266bba0da0fa2d96c408fb3bb697b96128..85136e3bf5dadf921652519e71da5db351fb3194:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index 39d4e61b67..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} @@ -76,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}\\ @@ -168,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}\\ @@ -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. +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} @@ -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} -\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} @@ -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 -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 @@ -1820,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} @@ -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} -static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") }; +static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") }; ... // 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. + \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. +Note that this function is categorized as a GUI one and so is not thread-safe. + \wxheading{Include files} @@ -2099,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 @@ -2113,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} @@ -2341,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} + + + + \membersection{::wxIsBusy}\label{wxisbusy} \func{bool}{wxIsBusy}{\void} @@ -2838,18 +2870,23 @@ 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},\\ +\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 char * }{src}, \param{size\_t }{srcLen = wxNO\_LEN},\\ +\param{const wxString\& }{src},\\ \param{wxBase64DecodeMode }{mode = wxBase64DecodeMode\_Strict},\\ \param{size\_t }{*posErr = \NULL}} @@ -2875,7 +2912,8 @@ 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.} +\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 @@ -2906,10 +2944,10 @@ buffer to be passed to \helpref{wxBase64Decode}{wxbase64decode}. \membersection{wxBase64Encode}\label{wxbase64encode} -\func{size\_t}{wxBase64Encode}{\param{char *}{dst}, \param{size\_t}{dstLen},\\ +\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 void *}{src}, \param{size\_t }{srcLen}} \func{wxString}{wxBase64Encode}{\param{const wxMemoryBuffer\& }{buf}} @@ -2939,7 +2977,7 @@ size.} \membersection{wxBase64EncodedSize}\label{wxbase64encodedsize} -\func{size\_t}{wxBase64EncodedSize}{\param{size\_t}{len}} +\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 @@ -2953,6 +2991,26 @@ to \helpref{wxBase64Encode}{wxbase64encode}. 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} + + + + \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. +\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 @@ -3100,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} @@ -3128,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} @@ -3257,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} @@ -3326,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} @@ -3381,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}} @@ -3572,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}} @@ -3680,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} + + + + +\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} + + + + +\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} + + + \section{RTTI functions}\label{rttimacros}