+ Asynchronously call the given method.
+
+ Calling this function on an object schedules an asynchronous call to
+ the method specified as CallAfter() argument at a (slightly) later
+ time. This is useful when processing some events as certain actions
+ typically can't be performed inside their handlers, e.g. you shouldn't
+ show a modal dialog from a mouse click event handler as this would
+ break the mouse capture state -- but you can call a method showing
+ this message dialog after the current event handler completes.
+
+ The method being called must be the method of the object on which
+ CallAfter() itself is called.
+
+ Notice that it is safe to use CallAfter() from other, non-GUI,
+ threads, but that the method will be always called in the main, GUI,
+ thread context.
+
+ Example of use:
+ @code
+ class MyFrame : public wxFrame {
+ void OnClick(wxMouseEvent& event) {
+ CallAfter(&MyFrame::ShowPosition, event.GetPosition());
+ }
+
+ void ShowPosition(const wxPoint& pos) {
+ if ( wxMessageBox(
+ wxString::Format("Perform click at (%d, %d)?",
+ pos.x, pos.y), "", wxYES_NO) == wxYES )
+ {
+ ... do take this click into account ...
+ }
+ }
+ };
+ @endcode
+
+ @param method The method to call.
+ @param x1 The (optional) first parameter to pass to the method.
+ @param x2 The (optional) second parameter to pass to the method.
+
+ Note that currently only up to 2 arguments can be passed. For more
+ complicated needs, you can use the CallAfter<T>(const T& fn) overload
+ that can call any functor.
+
+ @note This method is not available with Visual C++ before version 8
+ (Visual Studio 2005) as earlier versions of the compiler don't
+ have the required support for C++ templates to implement it.
+
+ @since 2.9.5
+ */
+ template<typename T, typename T1, ...>
+ void CallAfter(void (T::*method)(T1, ...), T1 x1, ...);
+
+ /**
+ Asynchronously call the given functor.
+
+ Calling this function on an object schedules an asynchronous call to
+ the functor specified as CallAfter() argument at a (slightly) later
+ time. This is useful when processing some events as certain actions
+ typically can't be performed inside their handlers, e.g. you shouldn't
+ show a modal dialog from a mouse click event handler as this would
+ break the mouse capture state -- but you can call a function showing
+ this message dialog after the current event handler completes.
+
+ Notice that it is safe to use CallAfter() from other, non-GUI,
+ threads, but that the method will be always called in the main, GUI,
+ thread context.
+
+ This overload is particularly useful in combination with C++11 lambdas:
+ @code
+ wxGetApp().CallAfter([]{
+ wxBell();
+ });
+ @endcode
+
+ @param functor The functor to call.
+
+ @note This method is not available with Visual C++ before version 8
+ (Visual Studio 2005) as earlier versions of the compiler don't
+ have the required support for C++ templates to implement it.
+
+ @since 2.9.6
+ */
+ template<typename T>
+ void CallAfter(const T& functor);
+
+ /**
+ 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().
projects / wxWidgets.git / blobdiff