Added wxCURSOR_ARROWWAIT which is the default arrow+hourglass cursor

[wxWidgets.git] / docs / latex / wx / process.tex

diff --git a/docs/latex/wx/process.tex b/docs/latex/wx/process.tex
index 160d34e1b24235fa1fd8a7133a372f3a51f986bf..425930487f78f58e74c892f360ebe113af8292a2 100644 (file)
--- a/docs/latex/wx/process.tex
+++ b/docs/latex/wx/process.tex
@@ -1,13 +1,41 @@
 \section{\class{wxProcess}}\label{wxprocess}
 
 \section{\class{wxProcess}}\label{wxprocess}
 

-This class contains a method which is invoked when a process finishes.
-It can raise a \helpref{wxProcessEvent}{wxprocessevent} if wxProcess::OnTerminate
-isn't overriden.
+The objects of this class are used in conjunction with the 
+\helpref{wxExecute}{wxexecute} function. When a wxProcess object is passed to
+wxExecute(), its \helpref{OnTerminate()}{wxprocessonterminate} virtual method
+is called when the process terminates. This allows the program to be
+(asynchronously) notified about the process termination and also retrieve its
+exit status which is unavailable from wxExecute() in the case of
+asynchronous execution.
+
+Please note that if the process termination notification is processed by the
+parent, it is responsible for deleting the wxProcess object which sent it.
+However, if it is not processed, the object will delete itself and so the
+library users should only delete those objects whose notifications have been
+processed (and call \helpref{Detach()}{wxprocessdetach} for others).
+
+wxProcess also supports IO redirection of the child process. For this, you have
+to call its \helpref{Redirect}{wxprocessredirect} method before passing it to 
+\helpref{wxExecute}{wxexecute}. If the child process was launched successfully, 
+\helpref{GetInputStream}{wxprocessgetinputstream}, 
+\helpref{GetOutputStream}{wxprocessgetoutputstream} and 
+\helpref{GetErrorStream}{wxprocessgeterrorstream} can then be used to retrieve
+the streams corresponding to the child process stdandard output, input and
+error output respectively.

 
 \wxheading{Derived from}
 
 \helpref{wxEvtHandler}{wxevthandler}
 
 
 \wxheading{Derived from}
 
 \helpref{wxEvtHandler}{wxevthandler}
 

+\wxheading{Include files}
+
+<wx/process.h>
+
+\wxheading{See also}
+
+\helpref{wxExecute}{wxexecute}\\
+\helpref{exec sample}{sampleexec}
+

 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxProcess::wxProcess}\label{wxprocessconstr}
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxProcess::wxProcess}\label{wxprocessconstr}


@@ -15,7 +43,12 @@ isn't overriden.
 \func{}{wxProcess}{\param{wxEvtHandler *}{ parent = NULL}, \param{int}{ id = -1}}
 
 Constructs a process object. {\it id} is only used in the case you want to
 \func{}{wxProcess}{\param{wxEvtHandler *}{ parent = NULL}, \param{int}{ id = -1}}
 
 Constructs a process object. {\it id} is only used in the case you want to

-use wxWindows events. 
+use wxWindows events. It identifies this object, or another window that will
+receive the event.
+
+If the {\it parent} parameter is different from NULL, it will receive
+a wxEVT\_END\_PROCESS notification event (you should insert EVT\_END\_PROCESS
+macro in the event table of the parent to handle it) with the given {\it id}.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -29,11 +62,69 @@ use wxWindows events.
 
 Destroys the wxProcess object.
 
 
 Destroys the wxProcess object.
 

+\membersection{wxProcess::CloseOutput}\label{wxprocesscloseoutput}
+
+\func{void}{CloseOutput}{\void}
+
+Closes the output stream (the one connected to the stdin of the child
+process). This function can be used to indicate to the child process that
+there is no more data to be read - usually, a filter program will only
+terminate when the input stream is closed.
+
+\membersection{wxProcess::Detach}\label{wxprocessdetach}
+
+\func{void}{Detach}{\void}
+
+Normally, a wxProcess object is deleted by its parent when it receives the
+notification about the process termination. However, it might happen that the
+parent object is destroyed before the external process is terminated (e.g. a
+window from which this external process was launched is closed by the user)
+and in this case it {\bf should not delete} the wxProcess object, but 
+{\bf should call Detach()} instead. After the wxProcess object is detached
+from its parent, no notification events will be sent to the parent and the
+object will delete itself upon reception of the process termination
+notification.
+
+\membersection{wxProcess::GetErrorStream}\label{wxprocessgeterrorstream}
+
+\constfunc{wxInputStream* }{GetErrorStream}{\void}
+
+Returns an input stream which corresponds to the standard error output (stderr)
+of the child process.
+
+\membersection{wxProcess::GetInputStream}\label{wxprocessgetinputstream}
+
+\constfunc{wxInputStream* }{GetInputStream}{\void}
+
+It returns an input stream corresponding to the standard output stream of the
+subprocess. If it is NULL, you have not turned on the redirection.
+See \helpref{wxProcess::Redirect}{wxprocessredirect}.
+
+\membersection{wxProcess::GetOutputStream}\label{wxprocessgetoutputstream}
+
+\constfunc{wxOutputStream* }{GetOutputStream}{\void}
+
+It returns an output stream correspoding to the input stream of the subprocess.
+If it is NULL, you have not turned on the redirection.
+See \helpref{wxProcess::Redirect}{wxprocessredirect}.
+

 \membersection{wxProcess::OnTerminate}\label{wxprocessonterminate}
 
 \membersection{wxProcess::OnTerminate}\label{wxprocessonterminate}
 

-\constfunc{void}{OnTerminate}{\param{int}{ pid}}
+\constfunc{void}{OnTerminate}{\param{int}{ pid}, \param{int}{ status}}

 
 It is called when the process with the pid {\it pid} finishes.
 
 It is called when the process with the pid {\it pid} finishes.

-It raises a wxWindows event when it isn't overriden.
+It raises a wxWindows event when it isn't overridden.
+
+\docparam{pid}{The pid of the process which has just terminated.}
+
+\docparam{status}{The exit code of the process.}
+
+\membersection{wxProcess::Redirect}\label{wxprocessredirect}
+
+\func{void}{Redirect}{\void}
+
+Turns on redirection. wxExecute will try to open a couple of pipes
+to catch the subprocess stdio. The caught input stream is returned by
+GetOutputStream() as a non-seekable stream. The caught output stream is returned
+by GetInputStream() as a non-seekable stream.

 
 

-\docparam{pid}{The pid of the process which ends.}