function.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

if successful, false otherwise.

\wxheading{See also}

\helpref{wxGetUserName}{wxgetusername}

\wxheading{Include files}

<wx/utils.h>


\membersection{::wxGetUserName}\label{wxgetusername}

\func{wxString}{wxGetUserName}{\void}

\func{bool}{wxGetUserName}{\param{char * }{buf}, \param{int }{sz}}

This function returns the full user name (something like "Mr. John Smith").

Under Windows or NT, this function looks for the entry {\bf UserName}\rtfsp
in the {\bf wxWidgets} section of the WIN.INI file. If PenWindows
is running, the entry {\bf Current} in the section {\bf User} of
the PENWIN.INI file is used.

The first variant of this function returns the user name if successful or an
empty string otherwise. The second (deprecated) function returns \true
if successful, \false otherwise.

\wxheading{See also}

\helpref{wxGetUserId}{wxgetuserid}

\wxheading{Include files}

<wx/utils.h>



\section{String functions}\label{stringfunctions}


\membersection{::copystring}\label{copystring}

\func{char *}{copystring}{\param{const char *}{s}}

Makes a copy of the string {\it s} using the C++ new operator, so it can be
deleted with the {\it delete} operator.

This function is deprecated, use \helpref{wxString}{wxstring} class instead.


\membersection{::wxGetTranslation}\label{wxgettranslation}

\func{const wxChar *}{wxGetTranslation}{\param{const wxChar* }{str},
  \param{const wxChar* }{domain = NULL}}

\func{const wxChar *}{wxGetTranslation}{\param{const wxChar* }{str}, \param{const wxChar* }{strPlural}, \param{size\_t }{n},
  \param{const wxChar* }{domain = NULL}}

This function returns the translation of string {\it str} in the current
\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
message catalogs (see \helpref{internationalization overview}{internationalization}), the
original string is returned. In debug build, an error message is logged -- this
should help to find the strings which were not yet translated.  If
{\it domain} is specified then only that domain/catalog is searched
for a matching string.  As this function
is used very often, an alternative (and also common in Unix world) syntax is
provided: the \helpref{\_()}{underscore} macro is defined to do the same thing
as wxGetTranslation.

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}
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}
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 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
\helpref{wxPLURAL}{wxplural} macro for all literal strings.


\membersection{::wxIsEmpty}\label{wxisempty}

\func{bool}{wxIsEmpty}{\param{const char *}{ p}}

Returns \true if the pointer is either {\tt NULL} or points to an empty
string, \false otherwise.


\membersection{::wxStrcmp}\label{wxstrcmp}

\func{int}{wxStrcmp}{\param{const char *}{p1}, \param{const char *}{p2}}

Returns a negative value, 0, or positive value if {\it p1} is less than, equal
to or greater than {\it p2}. The comparison is case-sensitive.

This function complements the standard C function {\it stricmp()} which performs
case-insensitive comparison.


\membersection{::wxStricmp}\label{wxstricmp}

\func{int}{wxStricmp}{\param{const char *}{p1}, \param{const char *}{p2}}

Returns a negative value, 0, or positive value if {\it p1} is less than, equal
to or greater than {\it p2}. The comparison is case-insensitive.

This function complements the standard C function {\it strcmp()} which performs
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},\\
  \param{bool}{ subString = true}, \param{bool}{ exact = false}}

{\bf NB:} This function is obsolete, use \helpref{wxString::Find}{wxstringfind} instead.

Returns \true if the substring {\it s1} is found within {\it s2},
ignoring case if {\it exact} is false. If {\it subString} is \false,
no substring matching is done.


\membersection{::wxStringTokenize}\label{wxstringtokenize}

\func{wxArrayString}{wxStringTokenize}{\param{const wxString\& }{str},\\
  \param{const wxString\& }{delims = wxDEFAULT\_DELIMITERS},\\
  \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}

This is a convenience function wrapping
\helpref{wxStringTokenizer}{wxstringtokenizer} which simply returns all tokens
found in the given \arg{str} in an array.

Please see
\helpref{wxStringTokenizer::wxStringTokenizer}{wxstringtokenizerwxstringtokenizer}
for the description of the other parameters.


\membersection{::wxStrlen}\label{wxstrlen}

\func{size\_t}{wxStrlen}{\param{const char *}{ p}}

This is a safe version of standard function {\it strlen()}: it does exactly the
same thing (i.e. returns the length of the string) except that it returns 0 if
{\it p} is the {\tt NULL} pointer.


\membersection{::wxSnprintf}\label{wxsnprintf}

\func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}

This function replaces the dangerous standard function {\tt sprintf()} and is
like {\tt snprintf()} available on some platforms. The only difference with
sprintf() is that an additional argument - buffer size - is taken and the
buffer is never overflowed.

Returns the number of characters copied to the buffer or -1 if there is not
enough space.

\wxheading{See also}

\helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}


\membersection{wxT}\label{wxt}

\func{wxChar}{wxT}{\param{char }{ch}}

\func{const wxChar *}{wxT}{\param{const char *}{s}}

wxT() is a macro which can be used with character and string literals (in other
words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in
Unicode build configuration. Please see the
\helpref{Unicode overview}{unicode} for more information.

This macro is simply returns the value passed to it without changes in ASCII
build. In fact, its definition is:
\begin{verbatim}
#ifdef UNICODE
#define wxT(x) L ## x
#else // !Unicode
#define wxT(x) x
#endif
\end{verbatim}


\membersection{wxTRANSLATE}\label{wxtranslate}

\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).

However it does have a purpose and it 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
\helpref{wxGetTranslation}{wxgettranslation} function call which means that it
cannot be used in some situations, notably for static array
initialization.

Here is an example which should make it more clear: suppose that you have a
static array of strings containing the weekday names and which have to be
translated (note that it is a bad example, really, as
\helpref{wxDateTime}{wxdatetime} already can be used to get the localized week
day names already). If you write

\begin{verbatim}
static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
...
// use weekdays[n] as usual
\end{verbatim}

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

here.

Note that although the code {\bf would} compile if you simply omit
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}}

The same as \helpref{wxSnprintf}{wxsnprintf} but takes a {\tt va\_list }
argument instead of arbitrary number of parameters.

Note that if \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is set to 1, then this function supports
positional arguments (see \helpref{wxString::Printf}{wxstringprintf} for more information).
However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, wxVfprintf,
wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional parameters
even when \texttt{wxUSE\_PRINTF\_POS\_PARAMS} is 1.

\wxheading{See also}

\helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}



\membersection{\_}\label{underscore}

\func{const wxChar *}{\_}{\param{const char *}{s}}

This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation}
function, so it marks the message for the extraction by {\tt xgettext} just as
\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of
the string for the current locale during execution.

Don't confuse this macro with \helpref{\_T()}{underscoret}!


\membersection{wxPLURAL}\label{wxplural}

\func{const wxChar *}{wxPLURAL}{\param{const char *}{sing}, \param{const char *}{plur}, \param{size\_t}{n}}

This macro is identical to \helpref{\_()}{underscore} but for the plural variant
of \helpref{wxGetTranslation}{wxgettranslation}.


\membersection{\_T}\label{underscoret}

\func{wxChar}{\_T}{\param{char }{ch}}

\func{const wxChar *}{\_T}{\param{const wxChar }{ch}}

This macro is exactly the same as \helpref{wxT}{wxt} and is defined in
wxWidgets simply because it may be more intuitive for Windows programmers as
the standard Win32 headers also define it (as well as yet another name for the
same macro which is {\tt \_TEXT()}).

Don't confuse this macro with \helpref{\_()}{underscore}!



\section{Dialog functions}\label{dialogfunctions}

Below are a number of convenience functions for getting input from the
user or displaying messages. Note that in these functions the last three
parameters are optional. However, it is recommended to pass a parent frame
parameter, or (in MS Windows or Motif) the wrong window frame may be brought to
the front when the dialog box is popped up.


\membersection{::wxAboutBox}\label{wxaboutbox}

\func{void}{wxAboutBox}{\param{const wxAboutDialogInfo\& }{info}}

This function shows the standard about dialog containing the information
specified in \arg{info}. If the current platform has a native about dialog
which is capable of showing all the fields in \arg{info}, the native dialog is
used, otherwise the function falls back to the generic wxWidgets version of the
dialog, i.e. does the same thing as \helpref{wxGenericAboutBox()}{wxgenericaboutbox}.

Here is an example of how this function may be used:
\begin{verbatim}
void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event))
{
    wxAboutDialogInfo info;
    info.SetName(_("My Program"));
    info.SetVersion(_("1.2.3 Beta"));
    info.SetDescription(_("This program does something great."));
    info.SetCopyright(_T("(C) 2007 Me <[e-mail]>"));

    wxAboutBox(info);
}
\end{verbatim}

Please see the \helpref{dialogs sample}{sampledialogs} for more examples of
using this function and \helpref{wxAboutDialogInfo}{wxaboutdialoginfo} for the
description of the information which can be shown in the about dialog.

\wxheading{Include files}

<wx/aboutdlg.h>


\membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor}

\func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}}

Changes the cursor to the given cursor for all windows in the application.
Use \helpref{wxEndBusyCursor}{wxendbusycursor} to revert the cursor back
to its previous state. These two calls can be nested, and a counter
ensures that only the outer calls take effect.

See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}.

\wxheading{Include files}

<wx/utils.h>


\membersection{::wxBell}\label{wxbell}

\func{void}{wxBell}{\void}

Ring the system bell.

\wxheading{Include files}

<wx/utils.h>