X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/91c82e2cac91889646722ec06d3df508fa5fdc00..ea11bf3abcec34e31b9919a2e222e61f82643830:/interface/wx/process.h?ds=sidebyside diff --git a/interface/wx/process.h b/interface/wx/process.h index a0f1c11b84..7d62189291 100644 --- a/interface/wx/process.h +++ b/interface/wx/process.h @@ -3,7 +3,7 @@ // Purpose: interface of wxProcess // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -51,11 +51,14 @@ enum wxKillError notified about the process termination and also retrieve its exit status which is unavailable from ::wxExecute() in the case of asynchronous execution. - @note 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 wxProcess::Detach for others). + @note + If the @c wxEVT_END_PROCESS event sent after termination is processed by the + parent, then it is responsible for deleting the wxProcess object which sent it. + However, if it is not processed, the object will <b>delete itself</b> and so the + library users should only delete those objects whose notifications have been + processed (and call wxProcess::Detach for others). + This also means that unless you're going to process the @c wxEVT_END_PROCESS event, + you <b>must</b> allocate the wxProcess class on the heap. wxProcess also supports IO redirection of the child process. For this, you have to call its Redirect() method before passing it to ::wxExecute(). @@ -72,6 +75,11 @@ enum wxKillError @library{wxbase} @category{appmanagement} + @beginWxPerlOnly + In wxPerl this class has an additional @c Destroy method, + for explicit destruction. + @endWxPerlOnly + @see wxExecute(), @ref page_samples_exec */ class wxProcess : public wxEvtHandler @@ -115,19 +123,27 @@ public: 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. + + Notice that GetOutputStream() will return @NULL after the output stream + is closed. */ void CloseOutput(); /** + Detaches this event handler from the parent specified in the constructor + (see wxEvtHandler::Unlink() for a similar but not identic function). + 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 @b should not delete the wxProcess object, but - @b 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. + 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 @b should not delete the wxProcess + object, but @b 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. */ void Detach(); @@ -153,15 +169,18 @@ public: wxInputStream* GetInputStream() const; /** - It returns an output stream correspoding to the input stream of the subprocess. - If it is @NULL, you have not turned on the redirection. + It returns an output stream corresponding to the input stream of the subprocess. + + If it is @NULL, you have not turned on the redirection or already + called CloseOutput(). @see Redirect(). */ wxOutputStream* GetOutputStream() const; /** - Returns the process ID of the process launched by Open(). + Returns the process ID of the process launched by Open() or set by + wxExecute() (if you passed this wxProcess as argument). */ long GetPid() const; @@ -214,6 +233,8 @@ public: /** It is called when the process with the pid @a pid finishes. It raises a wxWidgets event when it isn't overridden. + + Note that this function won't be called if you Kill() the process. @param pid The pid of the process which has just terminated.