X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/db82d78bc9a74b08cfcc06246feb2ac29e7b9f60..232b2162776e08c0b16d5280b90f5c075f38c667:/interface/wx/event.h?ds=inline diff --git a/interface/wx/event.h b/interface/wx/event.h index b7a7c5c7ce..7fa2d397e6 100644 --- a/interface/wx/event.h +++ b/interface/wx/event.h @@ -258,7 +258,7 @@ public: wxWindow is (and therefore all window classes are) derived from this class. When events are received, wxEvtHandler invokes the method listed in the - event table using itself as the object. When using multiple inheritance + event table using itself as the object. When using multiple inheritance it is imperative that the wxEvtHandler(-derived) class is the first class inherited such that the @c this pointer for the overall object will be identical to the @c this pointer of the wxEvtHandler portion. @@ -279,8 +279,8 @@ public: /** Destructor. - If the handler is part of a chain, the destructor will unlink itself and - restore the previous and next handlers so that they point to each other. + If the handler is part of a chain, the destructor will unlink itself + (see Unlink()). */ virtual ~wxEvtHandler(); @@ -382,17 +382,23 @@ public: The normal order of event table searching is as follows: -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) - the function skips to step (6). + the function skips to step (6). -# If the object is a wxWindow, ProcessEvent() is recursively called on the - window's wxValidator. If this returns @true, the function exits. + window's wxValidator. If this returns @true, the function exits. -# SearchEventTable() is called for this event handler. If this fails, the base - class table is tried, and so on until no more tables exist or an appropriate - function was found, in which case the function exits. + class table is tried, and so on until no more tables exist or an appropriate + function was found, in which case the function exits. -# The search is applied down the entire chain of event handlers (usually the - chain has a length of one). If this succeeds, the function exits. + chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler(): + @image html overview_eventhandling_chain.png + (referring to the image, if @c A->ProcessEvent is called and it doesn't handle + the event, @c B->ProcessEvent will be called and so on...). + Note that in the case of wxWindow you can build a stack of event handlers + (see wxWindow::PushEventHandler() for more info). + If any of the handlers of the chain return @true, the function exits. -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent() - is recursively applied to the parent window's event handler. - If this returns true, the function exits. + is recursively applied to the parent window's event handler. + If this returns @true, the function exits. -# Finally, ProcessEvent() is called on the wxApp object. @param event @@ -620,7 +626,10 @@ public: /** - @name Event handler chain + @name Event handler chaining + + wxEvtHandler can be arranged in a double-linked list of handlers + which is automatically iterated by ProcessEvent() if needed. */ //@{ @@ -664,21 +673,60 @@ public: /** Sets the pointer to the next handler. + @remarks + See ProcessEvent() for more info about how the chains of event handlers + are internally used. + Also remember that wxEvtHandler uses double-linked lists and thus if you + use this function, you should also call SetPreviousHandler() on the + argument passed to this function: + @code + handlerA->SetNextHandler(handlerB); + handlerB->SetPreviousHandler(handlerA); + @endcode + @param handler - Event handler to be set as the next handler. + The event handler to be set as the next handler. + Cannot be @NULL. - @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(), - wxWindow::PushEventHandler, wxWindow::PopEventHandler + @see @ref overview_eventhandling_processing */ - void SetNextHandler(wxEvtHandler* handler); + virtual void SetNextHandler(wxEvtHandler* handler); /** Sets the pointer to the previous handler. + All remarks about SetNextHandler() apply to this function as well. @param handler - Event handler to be set as the previous handler. + The event handler to be set as the previous handler. + Cannot be @NULL. + + @see @ref overview_eventhandling_processing + */ + virtual void SetPreviousHandler(wxEvtHandler* handler); + + /** + Unlinks this event handler from the chain it's part of (if any); + then links the "previous" event handler to the "next" one + (so that the chain won't be interrupted). + + E.g. if before calling Unlink() you have the following chain: + @image html evthandler_unlink_before.png + then after calling @c B->Unlink() you'll have: + @image html evthandler_unlink_after.png + + @since 2.9.0 */ - void SetPreviousHandler(wxEvtHandler* handler); + void Unlink(); + + /** + Returns @true if the next and the previous handler pointers of this + event handler instance are @NULL. + + @since 2.9.0 + + @see SetPreviousHandler(), SetNextHandler() + */ + bool IsUnlinked() const; //@} }; @@ -1061,6 +1109,9 @@ public: Constructor. */ wxWindowCreateEvent(wxWindow* win = NULL); + + /// Retutn the window being created. + wxWindow *GetWindow() const; }; @@ -2749,17 +2800,23 @@ public: /** @class wxWindowDestroyEvent - This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a - window is destroyed. + This event is sent as early as possible during the window destruction + process. + + For the top level windows, as early as possible means that this is done by + wxFrame or wxDialog destructor, i.e. after the destructor of the derived + class was executed and so any methods specific to the derived class can't + be called any more from this event handler. If you need to do this, you + must call wxWindow::SendDestroyEvent() from your derived class destructor. - When a class derived from wxWindow is destroyed its destructor will have - already run by the time this event is sent. Therefore this event will not - usually be received at all. + For the child windows, this event is generated just before deleting the + window from wxWindow::Destroy() (which is also called when the parent + window is deleted) or from the window destructor if operator @c delete was + used directly (which is not recommended for this very reason). - To receive this event wxEvtHandler::Connect() must be used (using an event - table macro will not work). Since it is received after the destructor has run, - an object should not handle its own wxWindowDestroyEvent, but it can be used - to get notification of the destruction of another window. + It is usually pointless to handle this event in the window itself but it ca + be very useful to receive notifications about the window destruction in the + parent window or in any other object interested in this window. @library{wxcore} @category{events} @@ -2773,6 +2830,9 @@ public: Constructor. */ wxWindowDestroyEvent(wxWindow* win = NULL); + + /// Retutn the window being destroyed. + wxWindow *GetWindow() const; };