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
<b>it is imperative that the wxEvtHandler(-derived) class is the first
class inherited</b> such that the @c this pointer for the overall object
will be identical to the @c this pointer of the wxEvtHandler portion.
/**
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();
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
/**
- @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.
*/
//@{
/**
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;
//@}
};
Constructor.
*/
wxWindowCreateEvent(wxWindow* win = NULL);
+
+ /// Retutn the window being created.
+ wxWindow *GetWindow() const;
};
/**
@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}
Constructor.
*/
wxWindowDestroyEvent(wxWindow* win = NULL);
+
+ /// Retutn the window being destroyed.
+ wxWindow *GetWindow() const;
};
projects / wxWidgets.git / blobdiff