X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..38aae140acbfd562df1388ae76108efcc52f871c:/interface/wx/process.h diff --git a/interface/wx/process.h b/interface/wx/process.h index c18af8660d..d7ab0baff0 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 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(); @@ -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. @@ -251,6 +243,20 @@ public: The caught output stream is returned by GetInputStream() as a non-seekable stream. */ void Redirect(); + + /** + Sets the priority of the process, between 0 (lowest) and 100 (highest). + It can only be set before the process is created. + + The following symbolic constants can be used in addition to raw + values in 0..100 range: + - @b wxPRIORITY_MIN: 0 + - @b wxPRIORITY_DEFAULT: 50 + - @b wxPRIORITY_MAX: 100 + + @since 2.9.5 + */ + void SetPriority(unsigned priority); }; @@ -258,19 +264,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 +300,6 @@ public: int GetPid(); }; + +wxEventType wxEVT_END_PROCESS; +