X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e6d4038a8bf3ae178bc89cceaf60a0652749ea9b..6d0f32ddb8e1aec3b8707db31ed244758c242672:/docs/latex/wx/function.tex diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index d47a983c0e..b6de53e475 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}\\ @@ -223,6 +225,7 @@ the corresponding topic. \helpref{wxRemoveFile}{wxremovefile}\\ \helpref{wxRenameFile}{wxrenamefile}\\ \helpref{wxRmdir}{wxrmdir}\\ +\helpref{wxS}{wxs}\\ \helpref{wxSafeShowMessage}{wxsafeshowmessage}\\ \helpref{wxSafeYield}{wxsafeyield}\\ \helpref{wxSetClipboardData}{wxsetclipboarddata}\\ @@ -492,6 +495,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 +1578,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} @@ -1686,6 +1697,25 @@ Returns \true if the pointer is either {\tt NULL} or points to an empty string, \false otherwise. +\membersection{wxS}\label{wxs} + +\func{wxStringCharType}{wxS}{\param{char }{ch}} + +\func{const wxStringCharType *}{wxS}{\param{const char *}{s}} + +wxS is macro which can be used with character and string literals to either +convert them to wide characters or strings in \texttt{wchar\_t}-based Unicode +builds or keep them unchanged in UTF-8 builds. The use of this macro is +optional as the translation will always be done at run-time even if there is a +mismatch between the kind of the literal used and wxStringCharType used in the +current build, but using it can be beneficial in performance-sensitive code to +do the conversion at compile-time instead. + +\wxheading{See also} + +\helpref{wxT}{wxt} + + \membersection{::wxStrcmp}\label{wxstrcmp} \func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}} @@ -1958,6 +1988,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} @@ -2098,7 +2130,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 @@ -2112,6 +2144,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} @@ -2340,6 +2376,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} @@ -2837,7 +2890,7 @@ 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} @@ -2852,6 +2905,11 @@ The clipboard must have previously been opened for this call to succeed. \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 @@ -2874,7 +2932,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 @@ -2952,6 +3011,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}} @@ -3008,6 +3087,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 @@ -3341,7 +3439,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} @@ -3396,8 +3494,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}} @@ -3705,6 +3803,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}