X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..b0d053c1eac3100e02468c73798111028819ad0a:/interface/wx/process.h
diff --git a/interface/wx/process.h b/interface/wx/process.h
index 1401717d76..b47276ebc4 100644
--- a/interface/wx/process.h
+++ b/interface/wx/process.h
@@ -3,48 +3,12 @@
// 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
- @wxheader{process.h}
The objects of this class are used in conjunction with the ::wxExecute() function.
When a wxProcess object is passed to ::wxExecute(), its OnTerminate() virtual method
@@ -52,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().
@@ -64,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
{
@@ -101,7 +79,7 @@ public:
/**
Destroys the wxProcess object.
*/
- ~wxProcess();
+ virtual ~wxProcess();
/**
Closes the output stream (the one connected to the stdin of the child
@@ -110,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 identical 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();
@@ -148,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;
@@ -203,19 +192,21 @@ 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.
@param status
The exit code of the process.
*/
- void OnTerminate(int pid, int status);
+ virtual void OnTerminate(int pid, int status);
/**
This static method replaces the standard @c popen() function: it launches
@@ -258,21 +249,21 @@ public:
/**
@class wxProcessEvent
- @wxheader{process.h}
- 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
{
@@ -292,6 +283,9 @@ public:
/**
Returns the process id.
*/
- int GetPid() const;
+ int GetPid();
};
+
+wxEventType wxEVT_END_PROCESS;
+