function.tex

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

\func{int}{wxEntry}{\param{HINSTANCE }{hInstance}, \param{HINSTANCE }{hPrevInstance = \NULL}, \param{char *}{pCmdLine = \NULL}, \param{int }{nCmdShow = \texttt{SW\_SHOWNORMAL}}}

(notice that under Windows CE platform, and only there, the type of 
\arg{pCmdLine} is \texttt{wchar\_t *}, otherwise it is \texttt{char *}, even in
Unicode build).

\wxheading{See also}

\helpref{wxEntryStart}{wxentrystart}

\wxheading{Remarks}

To clean up wxWidgets, call wxApp::OnExit followed by the static function
wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWidgets:

\begin{verbatim}
int CTheApp::ExitInstance()
{
  // OnExit isn't called by CleanUp so must be called explicitly.
  wxTheApp->OnExit();
  wxApp::CleanUp();

  return CWinApp::ExitInstance();
}
\end{verbatim}

\wxheading{Include files}

<wx/app.h>



\membersection{::wxEntryCleanup}\label{wxentrycleanup}

\func{void}{wxEntryCleanup}{\void}

Free resources allocated by a successful call to \helpref{wxEntryStart}{wxentrystart}.

\wxheading{Include files}

<wx/init.h>


\membersection{::wxEntryStart}\label{wxentrystart}

\func{bool}{wxEntryStart}{\param{int\&}{ argc}, \param{wxChar **}{argv}}

This function can be used to perform the initialization of wxWidgets if you
can't use the default initialization code for any reason.

If the function returns \true, the initialization was successful and the global 
\helpref{wxApp}{wxapp} object \texttt{wxTheApp} has been created. Moreover, 
\helpref{wxEntryCleanup}{wxentrycleanup} must be called afterwards. If the
function returns \false, a catastrophic initialization error occured and (at
least the GUI part of) the library can't be used at all.

Notice that parameters \arg{argc} and \arg{argv} may be modified by this
function.

\wxheading{Include files}

<wx/init.h>


\membersection{::wxGetApp}\label{wxgetapp}

\func{wxAppDerivedClass\&}{wxGetApp}{\void}

This function doesn't exist in wxWidgets but it is created by using
the \helpref{IMPLEMENT\_APP}{implementapp} macro. Thus, before using it
anywhere but in the same module where this macro is used, you must make it
available using \helpref{DECLARE\_APP}{declareapp}.

The advantage of using this function compared to directly using the global
wxTheApp pointer is that the latter is of type {\tt wxApp *} and so wouldn't
allow you to access the functions specific to your application class but not
present in wxApp while wxGetApp() returns the object of the right type.


\membersection{::wxHandleFatalExceptions}\label{wxhandlefatalexceptions}

\func{bool}{wxHandleFatalExceptions}{\param{bool}{ doIt = true}}

If {\it doIt} is true, the fatal exceptions (also known as general protection
faults under Windows or segmentation violations in the Unix world) will be
caught and passed to \helpref{wxApp::OnFatalException}{wxapponfatalexception}.
By default, i.e. before this function is called, they will be handled in the
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.


\membersection{::wxInitAllImageHandlers}\label{wxinitallimagehandlers}

\func{void}{wxInitAllImageHandlers}{\void}

Initializes all available image handlers. For a list of available handlers,
see \helpref{wxImage}{wximage}.

\wxheading{See also}

\helpref{wxImage}{wximage}, \helpref{wxImageHandler}{wximagehandler}

\wxheading{Include files}

<wx/image.h>


\membersection{::wxInitialize}\label{wxinitialize}

\func{bool}{wxInitialize}{\void}

This function is used in wxBase only and only if you don't create
\helpref{wxApp}{wxapp} object at all. In this case you must call it from your
{\tt main()} function before calling any other wxWidgets functions.

If the function returns \false the initialization could not be performed,
in this case the library cannot be used and
\helpref{wxUninitialize}{wxuninitialize} shouldn't be called neither.

This function may be called several times but
\helpref{wxUninitialize}{wxuninitialize} must be called for each successful
call to this function.

\wxheading{Include files}

<wx/app.h>


\membersection{::wxSafeYield}\label{wxsafeyield}

\func{bool}{wxSafeYield}{\param{wxWindow*}{ win = NULL}, \param{bool}{
    onlyIfNeeded = false}}

This function is similar to wxYield, except that it disables the user input to
all program windows before calling wxYield and re-enables it again
afterwards. If {\it win} is not NULL, this window will remain enabled,
allowing the implementation of some limited user interaction.

Returns the result of the call to \helpref{::wxYield}{wxyield}.

\wxheading{Include files}

<wx/utils.h>


\membersection{::wxUninitialize}\label{wxuninitialize}

\func{void}{wxUninitialize}{\void}

This function is for use in console (wxBase) programs only. It must be called
once for each previous successful call to \helpref{wxInitialize}{wxinitialize}.

\wxheading{Include files}

<wx/app.h>


\membersection{::wxYield}\label{wxyield}

\func{bool}{wxYield}{\void}

Calls \helpref{wxApp::Yield}{wxappyield}.

This function is kept only for backwards compatibility. Please use
the \helpref{wxApp::Yield}{wxappyield} method instead in any new code.

\wxheading{Include files}

<wx/app.h> or <wx/utils.h>


\membersection{::wxWakeUpIdle}\label{wxwakeupidle}

\func{void}{wxWakeUpIdle}{\void}

This functions wakes up the (internal and platform dependent) idle system, i.e. it
will force the system to send an idle event even if the system currently {\it is}
 idle and thus would not send any idle event until after some other event would get
sent. This is also useful for sending events between two threads and is used by
the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and
\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.

\wxheading{Include files}

<wx/app.h>



\section{Process control functions}\label{processfunctions}

The functions in this section are used to launch or terminate the other
processes.


\membersection{::wxExecute}\label{wxexecute}

\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{int }{sync = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}

\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteCommand}}

\func{long}{wxExecute}{\param{char **}{argv}, \param{int }{flags = wxEXEC\_ASYNC}, \param{wxProcess *}{callback = NULL}}

\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteArgs}}

\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{int }{flags = 0}}

\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdout} and it
only takes the {\tt command} argument,
and returns a 2-element list {\tt ( status, output )}, where {\tt output} is
an array reference.}

\func{long}{wxExecute}{\param{const wxString\& }{command}, \param{wxArrayString\& }{output}, \param{wxArrayString\& }{errors}, \param{int }{flags = 0}}

\perlnote{In wxPerl this function is called \texttt{Wx::ExecuteStdoutStderr}
and it only takes the {\tt command} argument,
and returns a 3-element list {\tt ( status, output, errors )}, where
{\tt output} and {\tt errors} are array references.}

Executes another program in Unix or Windows.

The first form takes a command string, such as {\tt "emacs file.txt"}.

The second form takes an array of values: a command, any number of
arguments, terminated by NULL.

The semantics of the third and fourth versions is different from the first two
and is described in more details below.

If {\it flags} parameter contains {\tt wxEXEC\_ASYNC} flag (the default), flow
of control immediately returns. If it contains {\tt wxEXEC\_SYNC}, the current
application waits until the other program has terminated.

In the case of synchronous execution, the return value is the exit code of
the process (which terminates by the moment the function returns) and will be
$-1$ if the process couldn't be started and typically 0 if the process
terminated successfully. Also, while waiting for the process to
terminate, wxExecute will call \helpref{wxYield}{wxyield}. Because of this, by
default this function disables all application windows to avoid unexpected
reentrancies which could result from the users interaction with the program
while the child process is running. If you are sure that it is safe to not
disable the program windows, you may pass \texttt{wxEXEC\_NODISABLE} flag to
prevent this automatic disabling from happening.

For asynchronous execution, however, the return value is the process id and
zero value indicates that the command could not be executed. As an added
complication, the return value of $-1$ in this case indicates that we didn't
launch a new process, but connected to the running one (this can only happen in
case of using DDE under Windows for command execution). In particular, in this,
and only this, case the calling code will not get the notification about
process termination.

If callback isn't NULL and if execution is asynchronous,
\helpref{wxProcess::OnTerminate}{wxprocessonterminate} will be called when
the process finishes. Specifying this parameter also allows you to redirect the
standard input and/or output of the process being launched by calling
\helpref{Redirect}{wxprocessredirect}. If the child process IO is redirected,
under Windows the process window is not shown by default (this avoids having to
flush an unnecessary console for the processes which don't create any windows
anyhow) but a {\tt wxEXEC\_NOHIDE} flag can be used to prevent this from
happening, i.e. with this flag the child process window will be shown normally.

Under Unix the flag {\tt wxEXEC\_MAKE\_GROUP\_LEADER} may be used to ensure
that the new process is a group leader (this will create a new session if
needed). Calling \helpref{wxKill}{wxkill} passing wxKILL\_CHILDREN will
kill this process as well as all of its children (except those which have
started their own session).

Finally, you may use the third overloaded version of this function to execute
a process (always synchronously, the contents of \arg{flags} is or'd with
\texttt{wxEXEC\_SYNC}) and capture its output in the array \arg{output}. The
fourth version adds the possibility to additionally capture the messages from
standard error output in the \arg{errors} array.

{\bf NB:} Currently wxExecute() can only be used from the main thread, calling
this function from another thread will result in an assert failure in debug
build and won't work.

\wxheading{See also}

\helpref{wxShell}{wxshell}, \helpref{wxProcess}{wxprocess}, \helpref{Exec sample}{sampleexec}.

\wxheading{Parameters}

\docparam{command}{The command to execute and any parameters to pass to it as a
single string.}

\docparam{argv}{The command to execute should be the first element of this
array, any additional ones are the command parameters and the array must be
terminated with a NULL pointer.}

\docparam{flags}{Combination of bit masks {\tt wxEXEC\_ASYNC},\rtfsp
{\tt wxEXEC\_SYNC} and {\tt wxEXEC\_NOHIDE}}

\docparam{callback}{An optional pointer to \helpref{wxProcess}{wxprocess}}

\wxheading{Include files}

<wx/utils.h>


\membersection{::wxExit}\label{wxexit}

\func{void}{wxExit}{\void}

Exits application after calling \helpref{wxApp::OnExit}{wxapponexit}.
Should only be used in an emergency: normally the top-level frame
should be deleted (after deleting all other frames) to terminate the
application. See \helpref{wxCloseEvent}{wxcloseevent} and \helpref{wxApp}{wxapp}.

\wxheading{Include files}

<wx/app.h>


\membersection{::wxKill}\label{wxkill}

\func{int}{wxKill}{\param{long}{ pid}, \param{int}{ sig = wxSIGTERM}, \param{wxKillError }{*rc = NULL}, \param{int }{flags = 0}}

Equivalent to the Unix kill function: send the given signal {\it sig} to the
process with PID {\it pid}. The valid signal values are

\begin{verbatim}
enum wxSignal
{
    wxSIGNONE = 0,  // verify if the process exists under Unix
    wxSIGHUP,
    wxSIGINT,
    wxSIGQUIT,
    wxSIGILL,
    wxSIGTRAP,
    wxSIGABRT,
    wxSIGEMT,
    wxSIGFPE,
    wxSIGKILL,      // forcefully kill, dangerous!
    wxSIGBUS,
    wxSIGSEGV,
    wxSIGSYS,
    wxSIGPIPE,
    wxSIGALRM,
    wxSIGTERM       // terminate the process gently
};
\end{verbatim}

{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
under both Unix and Windows but all the other signals are equivalent to
{\tt wxSIGTERM} under Windows.

Returns 0 on success, -1 on failure. If {\it rc} parameter is not NULL, it will
be filled with an element of {\tt wxKillError} enum:

\begin{verbatim}
enum wxKillError
{
    wxKILL_OK,              // no error
    wxKILL_BAD_SIGNAL,      // no such signal
    wxKILL_ACCESS_DENIED,   // permission denied
    wxKILL_NO_PROCESS,      // no such process
    wxKILL_ERROR            // another, unspecified error
};
\end{verbatim}

The {\it flags} parameter can be wxKILL\_NOCHILDREN (the default),
or wxKILL\_CHILDREN, in which case the child processes of this
process will be killed too. Note that under Unix, for wxKILL\_CHILDREN
to work you should have created the process by passing wxEXEC\_MAKE\_GROUP\_LEADER
to wxExecute.

\wxheading{See also}

\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
\helpref{Exec sample}{sampleexec}

\wxheading{Include files}

<wx/utils.h>


\membersection{::wxGetProcessId}\label{wxgetprocessid}