Add wxEvtHandler::CallAfter() for asynchronous method calls.

Add wxAsyncMethodCallEvent that is handled simply by calling the method this
event was created for and add default handler for this event to wxEvtHandler.

Implement CallAfter() overloads for up to 2 parameters only for now.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@72722 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -529,6 +529,7 @@ Major new features in this release
 
 All:
 
+- Add wxEvtHandler::CallAfter() method for asynchronous method calls.
 - Add support for symlinks to wxFileName (David Hart).
 - Allow testing for symlink/FIFO/socket existence in wxFileName (David Hart).
 - Many important bug fixes in wxFileSystemWatcher (David Hart).

interface/wx/event.h

@@ -477,6 +477,53 @@ public:
     */
     virtual void AddPendingEvent(const wxEvent& event);
 
+    /**
+         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.
+
+         @since 2.9.5
+     */
+    template<typename T, typename T1, ...>
+    void CallAfter(void (T::*method)(T1, ...), T1 x1, ...);
+
     /**
         Processes an event, searching event tables and calling zero or more suitable
         event handler function(s).

src/common/event.cpp

@@ -156,8 +156,9 @@ const wxEventType wxEVT_NULL = wxNewEventType();
 
 wxDEFINE_EVENT( wxEVT_IDLE, wxIdleEvent );
 
-// Thread event
+// Thread and asynchronous call events
 wxDEFINE_EVENT( wxEVT_THREAD, wxThreadEvent );
+wxDEFINE_EVENT( wxEVT_ASYNC_METHOD_CALL, wxAsyncMethodCallEvent );
 
 #endif // wxUSE_BASE
 
@@ -1564,6 +1565,15 @@ bool wxEvtHandler::TryHereOnly(wxEvent& event)
     if ( GetEventHashTable().HandleEvent(event, this) )
         return true;
 
+    // There is an implicit entry for async method calls procession in every
+    // event handler:
+    if ( event.GetEventType() == wxEVT_ASYNC_METHOD_CALL &&
+            event.GetEventObject() == this )
+    {
+        static_cast<wxAsyncMethodCallEvent&>(event).Execute();
+        return true;
+    }
+
     // We don't have a handler for this event.
     return false;
 }