X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..b02dd12239c8a59b9a545d9fcb04974f8ad02c6b:/interface/wx/process.h

diff --git a/interface/wx/process.h b/interface/wx/process.h
index c18af8660d..edbe214ffa 100644
--- a/interface/wx/process.h
+++ b/interface/wx/process.h
@@ -3,44 +3,9 @@
 // Purpose:     interface of wxProcess
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
-/**
-    Signal constants used by wxProcess.
-*/
-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
-};
-
-/**
-    Return values for wxProcess::Kill.
-*/
-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
-};
-
 
 /**
     @class wxProcess
@@ -51,11 +16,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().
@@ -63,10 +31,21 @@ enum wxKillError
     and GetErrorStream() can then be used to retrieve the streams corresponding to the
     child process standard output, input and error output respectively.
 
+    @beginEventEmissionTable{wxProcessEvent}
+    @event{EVT_END_PROCESS(id, func)}
+        Process a @c wxEVT_END_PROCESS event, sent by wxProcess::OnTerminate upon
+        the external process termination.
+    @endEventTable
+
     @library{wxbase}
     @category{appmanagement}
 
-    @see wxExecute(), @ref page_samples_exec "exec sample"
+    @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
 {
@@ -109,19 +88,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();
 
@@ -147,15 +134,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;
 
@@ -202,12 +192,14 @@ public:
 
         @see Exists(), wxKill(), @ref page_samples_exec "Exec sample"
     */
-    static wxKillError Kill(int pid, wxSignal signal = wxSIGNONE,
+    static wxKillError Kill(int pid, wxSignal sig = wxSIGTERM,
                             int flags = wxKILL_NOCHILDREN);
 
     /**
         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.
@@ -258,19 +250,20 @@ public:
 /**
     @class wxProcessEvent
 
-    A process event is sent when a process is terminated.
+    A process event is sent to the wxEvtHandler specified to wxProcess
+    when a process is terminated.
 
     @beginEventTable{wxProcessEvent}
     @event{EVT_END_PROCESS(id, func)}
-           Process a @c wxEVT_END_PROCESS event. @a id is the identifier of the process
-           object (the id passed to the wxProcess constructor) or a window to receive
-           the event.
+        Process a @c wxEVT_END_PROCESS event. @a id is the identifier of the process
+        object (the id passed to the wxProcess constructor) or a window to receive
+        the event.
     @endEventTable
 
     @library{wxbase}
     @category{events}
 
-    @see wxProcess, @ref overview_eventhandling
+    @see wxProcess, @ref overview_events
 */
 class wxProcessEvent : public wxEvent
 {
@@ -293,3 +286,6 @@ public:
     int GetPid();
 };
 
+
+wxEventType wxEVT_END_PROCESS;
+