+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: function.tex
+%% Purpose: Functions and macros
+%% Author: wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets Team
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\chapter{Functions}\label{functions}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}
\helpref{wxNewId}{wxnewid}\\
\helpref{wxNow}{wxnow}\\
\helpref{wxOnAssert}{wxonassert}\\
+\helpref{wxON\_BLOCK\_EXIT}{wxonblockexit}\\
+\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}\\
\helpref{wxOpenClipboard}{wxopenclipboard}\\
\helpref{wxParseCommonDialogsFilter}{wxparsecommondialogsfilter}\\
\helpref{wxDirExists}{functionwxdirexists}\\
\helpref{wxStricmp}{wxstricmp}\\
\helpref{wxStringEq}{wxstringeq}\\
\helpref{wxStringMatch}{wxstringmatch}\\
+\helpref{wxStringTokenize}{wxstringtokenize}\\
\helpref{wxStripMenuCodes}{wxstripmenucodes}\\
\helpref{wxStrlen}{wxstrlen}\\
\helpref{wxSysErrorCode}{wxsyserrorcode}\\
\helpref{wx\_const\_cast}{wxconstcastraw}\\
\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}\\
\helpref{wx\_static\_cast}{wxstaticcastraw}\\
+\helpref{wx\_truncate\_cast}{wxtruncatecast}\\
\helpref{\_}{underscore}\\
\helpref{wxPLURAL}{wxplural}\\
\helpref{\_T}{underscoret}
Returns time of last modification of given file.
+The return value is $0$ if an error occured (e.g. file not found).
+
\membersection{::wxFileNameFromPath}\label{wxfilenamefrompath}
\membersection{::wxUnix2DosFilename}\label{wxunix2dosfilename}
-\func{void}{wxUnix2DosFilename}{\param{const wxString\& }{s}}
+\func{void}{wxUnix2DosFilename}{\param{wxChar *}{s}}
+
+This function is deprecated, use \helpref{wxFileName}{wxfilename} instead.
Converts a Unix to a DOS filename by replacing forward
slashes with backslashes.
\func{wxString}{wxGetWorkingDirectory}{\param{char *}{buf=NULL}, \param{int }{sz=1000}}
-{\bf NB:} This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
+{\bf NB:} This function is deprecated: use \helpref{wxGetCwd}{wxgetcwd} instead.
Copies the current working directory into the buffer if supplied, or
copies the working directory into new storage (which you {\emph must} delete
\wxheading{See also}
-\helpref{wxGetUserHome}{wxgetuserhome}
+\helpref{wxGetUserHome}{wxgetuserhome}\\
+\helpref{wxStandardPaths}{wxstandardpaths}
\wxheading{Include files}
The second form is used when retrieving translation of string that has
different singular and plural form in English or different plural forms in some
-other language. It takes two extra arguments: as above, \arg{str}
+other language. It takes two extra arguments: as above, \arg{str}
parameter must contain the singular form of the string to be converted and
is used as the key for the search in the catalog. The \arg{strPlural} parameter
is the plural form (in English). The parameter \arg{n} is used to determine the
plural form. If no message catalog is found \arg{str} is returned if `n == 1',
otherwise \arg{strPlural}.
-See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150}
+See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150}
for additional information on plural forms handling. For a shorter alternative
see the \helpref{wxPLURAL()}{wxplural} macro.
Both versions call \helpref{wxLocale::GetString}{wxlocalegetstring}.
Note that this function is not suitable for literal strings in Unicode
-builds, since you the literal strings must be enclosed into
+builds, since the literal strings must be enclosed into
\helpref{\_T()}{underscoret} or \helpref{wxT}{wxt} macro which makes them
unrecognised by \texttt{xgettext}, and so they are not extracted to the message
-catalog. Instead, use the \helpref{\_()}{underscore} and
+catalog. Instead, use the \helpref{\_()}{underscore} and
\helpref{wxPLURAL}{wxplural} macro for all literal strings.
case-sensitive comparison.
+\membersection{::wxStringEq}\label{wxstringeq}
+
+\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
+
+{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead.
+
+A macro defined as:
+
+\begin{verbatim}
+#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
+\end{verbatim}
+
+
\membersection{::wxStringMatch}\label{wxstringmatch}
\func{bool}{wxStringMatch}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2},\\
no substring matching is done.
-\membersection{::wxStringEq}\label{wxstringeq}
+\membersection{::wxStringTokenize}\label{wxstringtokenize}
-\func{bool}{wxStringEq}{\param{const wxString\& }{s1}, \param{const wxString\& }{s2}}
+\func{wxArrayString}{wxStringTokenize}{\param{const wxString\& }{str},\\
+ \param{const wxString\& }{delims = wxDEFAULT\_DELIMITERS},\\
+ \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
-{\bf NB:} This function is obsolete, use \helpref{wxString}{wxstring} instead.
-
-A macro defined as:
+This is a convenience function wrapping
+\helpref{wxStringTokenizer}{wxstringtokenizer} which simply returns all tokens
+found in the given \arg{str} in an array.
-\begin{verbatim}
-#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
-\end{verbatim}
+Please see
+\helpref{wxStringTokenizer::wxStringTokenizer}{wxstringtokenizerwxstringtokenizer}
+for the description of the other parameters.
\membersection{::wxStrlen}\label{wxstrlen}
\membersection{::wxEnumClipboardFormats}\label{wxenumclipboardformats}
-\func{int}{wxEnumClipboardFormats}{\param{int}{dataFormat}}
+\func{int}{wxEnumClipboardFormats}{\param{int}{ dataFormat}}
Enumerates the formats found in a list of available formats that belong
to the clipboard. Each call to this function specifies a known
\membersection{::wxGetClipboardData}\label{wxgetclipboarddata}
-\func{wxObject *}{wxGetClipboardData}{\param{int}{dataFormat}}
+\func{wxObject *}{wxGetClipboardData}{\param{int}{ dataFormat}}
Gets data from the clipboard.
\membersection{::wxGetClipboardFormatName}\label{wxgetclipboardformatname}
-\func{bool}{wxGetClipboardFormatName}{\param{int}{dataFormat}, \param{const wxString\& }{formatName}, \param{int}{maxCount}}
+\func{bool}{wxGetClipboardFormatName}{\param{int}{ dataFormat}, \param{const wxString\& }{formatName}, \param{int}{ maxCount}}
Gets the name of a registered clipboard format, and puts it into the buffer {\it formatName} which is of maximum
length {\it maxCount}. {\it dataFormat} must not specify a predefined clipboard format.
\membersection{::wxIsClipboardFormatAvailable}\label{wxisclipboardformatavailable}
-\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{dataFormat}}
+\func{bool}{wxIsClipboardFormatAvailable}{\param{int}{ dataFormat}}
Returns true if the given data format is available on the clipboard.
\membersection{::wxSetClipboardData}\label{wxsetclipboarddata}
-\func{bool}{wxSetClipboardData}{\param{int}{dataFormat}, \param{wxObject *}{data}, \param{int}{width}, \param{int}{height}}
+\func{bool}{wxSetClipboardData}{\param{int}{ dataFormat}, \param{wxObject*}{ data}, \param{int}{ width}, \param{int}{ height}}
Passes data to the clipboard.
The clipboard must have previously been opened for this call to succeed.
-
-
\section{Miscellaneous functions}\label{miscellany}
<wx/utils.h>
+\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}
+with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is
+executed on scope exit, whether due to a normal function return or because an
+exception has been thrown. A typical example of its usage:
+\begin{verbatim}
+ void *buf = malloc(size);
+ wxON_BLOCK_EXIT1(free, buf);
+\end{verbatim}
+
+Please see the original article by Andrei Alexandrescu and Petru Marginean
+published in December 2000 issue of \emph{C/C++ Users Journal} for more
+details.
+
+\wxheading{Include files}
+
+<wx/scopeguard.h>
+
+\wxheading{See also}
+
+\helpref{wxON\_BLOCK\_EXIT\_OBJ}{wxonblockexitobj}
+
+
+\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}
+but calls a method of the given object instead of a free function.
+
+\wxheading{Include files}
+
+<wx/scopeguard.h>
+
+
\membersection{::wxRegisterId}\label{wxregisterid}
\func{void}{wxRegisterId}{\param{long}{ id}}
\membersection{::wxEnableTopLevelWindows}\label{wxenabletoplevelwindows}
-\func{void}{wxEnableTopLevelWindow}{\param{bool}{ enable = true}}
+\func{void}{wxEnableTopLevelWindows}{\param{bool}{ enable = true}}
This function enables or disables all top level windows. It is used by
\helpref{::wxSafeYield}{wxsafeyield}.
\membersection{::wxGetStockLabel}\label{wxgetstocklabel}
-\func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{wxString }{accelerator = wxEmptyString}}
+\func{wxString}{wxGetStockLabel}{\param{wxWindowID }{id}, \param{bool }{withCodes = true}, \param{const wxString\& }{accelerator = wxEmptyString}}
Returns label that should be used for given {\it id} element.
\membersection{::wxLaunchDefaultBrowser}\label{wxlaunchdefaultbrowser}
-\func{bool}{wxLaunchDefaultBrowser}{\param{const wxString\& }{sUrl}}
+\func{bool}{wxLaunchDefaultBrowser}{\param{const wxString\& }{url}, \param{int }{flags = $0$}}
-Launches the user's default browser and tells it to open the location at {\tt sUrl}.
+Open the \arg{url} in user's default browser. If \arg{flags} parameter contains
+\texttt{wxBROWSER\_NEW\_WINDOW} flag, a new window is opened for the URL
+(currently this is only supported under Windows).
-Returns true if the application was successfully launched.
+Returns \true if the application was successfully launched.
\wxheading{Include files}
<wx/utils.h>
+
\membersection{::wxLoadUserResource}\label{wxloaduserresource}
\func{wxString}{wxLoadUserResource}{\param{const wxString\& }{resourceName}, \param{const wxString\& }{resourceType=``TEXT"}}
\membersection{wxVaCopy}\label{wxvacopy}
-\func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{argptrSrc}}
+\func{void}{wxVaCopy}{\param{va\_list }{argptrDst}, \param{va\_list}{ argptrSrc}}
This macro is the same as the standard C99 \texttt{va\_copy} for the compilers
which support it or its replacement for those that don't. It must be used to
\func{}{DECLARE\_DYNAMIC\_CLASS}{className}
-Used inside a class declaration to declare that the objects of this class should be dynamically
-creatable from run-time type information.
+Used inside a class declaration to make the class known to wxWidgets RTTI
+system and also declare that the objects of this class should be dynamically
+creatable from run-time type information. Notice that this implies that the
+class should have a default constructor, if this is not the case consider using
+\helpref{DECLARE\_CLASS}{declareclass}.
Example:
\wxheading{See also}
\helpref{wx\_const\_cast}{wxconstcastraw},\\
-\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw}
+\helpref{wx\_reinterpret\_cast}{wxreinterpretcastraw},\\
+\helpref{wx\_truncate\_cast}{wxtruncatecast}
+
+\membersection{wx\_truncate\_cast}\label{wxtruncatecast}
+
+\func{T}{wx\_truncate\_cast}{T, x}
+
+This case doesn't correspond to any standard cast but exists solely to make
+casts which possibly result in a truncation of an integer value more readable.
+
+\wxheading{See also}
+
+\helpref{wx\_static\_cast}{wxstaticcastraw}
\section{Log functions}\label{logfunctions}
function.
Returns \true on success.
-
projects / wxWidgets.git / blobdiff