+ Processes an event, searching event tables and calling zero or more suitable
+ event handler function(s).
+
+ Normally, your application would not call this function: it is called in the
+ wxWidgets implementation to dispatch incoming user interface events to the
+ framework (and application).
+
+ However, you might need to call it if implementing new functionality
+ (such as a new control) where you define new event types, as opposed to
+ allowing the user to override virtual functions.
+
+ Notice that you don't usually need to override ProcessEvent() to
+ customize the event handling, overriding the specially provided
+ TryBefore() and TryAfter() functions is usually enough. For example,
+ wxMDIParentFrame may override TryBefore() to ensure that the menu
+ events are processed in the active child frame before being processed
+ in the parent frame itself.
+
+ The normal order of event table searching is as follows:
+ -# wxApp::FilterEvent() is called. If it returns anything but @c -1
+ (default) the processing stops here.
+ -# TryBefore() is called (this is where wxValidator are taken into
+ account for wxWindow objects). If this returns @true, the function exits.
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (7).
+ -# Dynamic event table of the handlers bound using Bind<>() is
+ searched. If a handler is found, it is executed and the function
+ returns @true unless the handler used wxEvent::Skip() to indicate
+ that it didn't handle the event in which case the search continues.
+ -# Static events table of the handlers bound using event table
+ macros is searched for this event handler. If this fails, the base
+ class event table is tried, and so on until no more tables
+ exist or an appropriate function was found. If a handler is found,
+ the same logic as in the previous step applies.
+ -# The search is applied down the entire chain of event handlers (usually the
+ chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler():
+ @image html overview_events_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.
+ -# TryAfter() is called: for the wxWindow object this may propagate the
+ event to the window parent (recursively). If the event is still not
+ processed, ProcessEvent() on wxTheApp object is called as the last
+ step.
+
+ Notice that steps (2)-(6) are performed in ProcessEventLocally()
+ which is called by this function.
+
+ @param event
+ Event to process.
+ @return
+ @true if a suitable event handler function was found and executed,
+ and the function did not call wxEvent::Skip.
+
+ @see SearchEventTable()
+ */
+ virtual bool ProcessEvent(wxEvent& event);
+
+ /**
+ Try to process the event in this handler and all those chained to it.
+
+ As explained in ProcessEvent() documentation, the event handlers may be
+ chained in a doubly-linked list. This function tries to process the
+ event in this handler (including performing any pre-processing done in
+ TryBefore(), e.g. applying validators) and all those following it in
+ the chain until the event is processed or the chain is exhausted.
+
+ This function is called from ProcessEvent() and, in turn, calls
+ TryBefore() and TryAfter(). It is not virtual and so cannot be
+ overridden but can, and should, be called to forward an event to
+ another handler instead of ProcessEvent() which would result in a
+ duplicate call to TryAfter(), e.g. resulting in all unprocessed events
+ being sent to the application object multiple times.
+
+ @since 2.9.1
+
+ @param event
+ Event to process.
+ @return
+ @true if this handler of one of those chained to it processed the
+ event.
+ */
+ bool ProcessEventLocally(wxEvent& event);
+
+ /**
+ Processes an event by calling ProcessEvent() and handles any exceptions
+ that occur in the process.
+ If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
+
+ @param event
+ Event to process.
+
+ @return @true if the event was processed, @false if no handler was found
+ or an exception was thrown.
+
+ @see wxWindow::HandleWindowEvent
+ */
+ bool SafelyProcessEvent(wxEvent& event);
+
+ /**
+ Processes the pending events previously queued using QueueEvent() or
+ AddPendingEvent(); you must call this function only if you are sure
+ there are pending events for this handler, otherwise a @c wxCHECK
+ will fail.
+
+ The real processing still happens in ProcessEvent() which is called by this
+ function.
+
+ Note that this function needs a valid application object (see
+ wxAppConsole::GetInstance()) because wxApp holds the list of the event
+ handlers with pending events and this function manipulates that list.
+ */
+ void ProcessPendingEvents();
+
+ /**
+ Deletes all events queued on this event handler using QueueEvent() or
+ AddPendingEvent().
+
+ Use with care because the events which are deleted are (obviously) not
+ processed and this may have unwanted consequences (e.g. user actions events
+ will be lost).
+ */
+ void DeletePendingEvents();
+
+ /**
+ Searches the event table, executing an event handler function if an appropriate
+ one is found.
+
+ @param table
+ Event table to be searched.
+ @param event
+ Event to be matched against an event table entry.
+
+ @return @true if a suitable event handler function was found and
+ executed, and the function did not call wxEvent::Skip.
+
+ @remarks This function looks through the object's event table and tries
+ to find an entry that will match the event.
+ An entry will match if:
+ @li The event type matches, and
+ @li the identifier or identifier range matches, or the event table
+ entry's identifier is zero.
+
+ If a suitable function is called but calls wxEvent::Skip, this
+ function will fail, and searching will continue.
+
+ @todo this function in the header is listed as an "implementation only" function;
+ are we sure we want to document it?
+
+ @see ProcessEvent()
+ */
+ virtual bool SearchEventTable(wxEventTable& table,
+ wxEvent& event);
+
+ //@}
+
+
+ /**
+ @name Connecting and disconnecting
+ */
+ //@{
+
+ /**
+ Connects the given function dynamically with the event handler, id and
+ event type.
+
+ Notice that Bind() provides a more flexible and safer way to do the
+ same thing as Connect(), please use it in any new code -- while
+ Connect() is not formally deprecated due to its existing widespread
+ usage, it has no advantages compared to Bind().
+
+ This is an alternative to the use of static event tables. It is more
+ flexible as it allows to connect events generated by some object to an
+ event handler defined in a different object of a different class (which
+ is impossible to do directly with the event tables -- the events can be
+ only handled in another object if they are propagated upwards to it).
+ Do make sure to specify the correct @a eventSink when connecting to an
+ event of a different object.
projects / wxWidgets.git / blobdiff