%% License: wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{Functions}\label{functions}
+\chapter{Functions and macros}\label{functions}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}
\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{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{wxRemoveFile}{wxremovefile}\\
\helpref{wxRenameFile}{wxrenamefile}\\
\helpref{wxRmdir}{wxrmdir}\\
+\helpref{wxS}{wxs}\\
\helpref{wxSafeShowMessage}{wxsafeshowmessage}\\
\helpref{wxSafeYield}{wxsafeyield}\\
\helpref{wxSetClipboardData}{wxsetclipboarddata}\\
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{::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}
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}}
\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
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}
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}
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}}
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>
\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
\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>
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}
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}}
\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
\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}}
\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
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}}
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{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}
\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}
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}
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}
\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}}
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}}
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}
projects / wxWidgets.git / blobdiff