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 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()
*/
- void SetPreviousHandler(wxEvtHandler* handler);
+ bool IsUnlinked() const;
//@}
};
Both key events provide untranslated key codes while the char event carries
the translated one. The untranslated code for alphanumeric keys is always
an upper case value. For the other keys it is one of @c WXK_XXX values
- from the @ref page_keycodes.
+ from the ::wxKeyCode enumeration.
The translated key is, in general, the character the user expects to appear
as the result of the key combination when typing the text into a text entry
zone, for example.
/**
Returns the virtual key code. ASCII events return normal ASCII values,
while non-ASCII events return values such as @b WXK_LEFT for the left cursor
- key. See @ref page_keycodes for a full list of the virtual key codes.
+ key. See ::wxKeyCode for a full list of the virtual key codes.
Note that in Unicode build, the returned value is meaningful only if the
user entered a character that can be represented in current locale's default
projects / wxWidgets.git / blobdiff