added/documented wxApp::FilterEvent

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

docs/latex/wx/app.tex

@@ -85,6 +85,17 @@ This can be used for programming event loops, e.g.
 
 \helpref{wxApp::Pending}{wxapppending}
 
+\membersection{wxApp::FilterEvent}\label{wxappfilterevent}
+
+\func{int}{FilterEvent}{\param{wxEvent\& }{event}}
+
+This function is called before processing any event and allows the application
+to preempt the processing of some events. If this method returns $-1$ the event
+is processed normally, otherwise either {\tt TRUE} or {\tt FALSE} should be
+returned and the event processing stops immediately considering that the event
+had been already processed (for the former return value) or that it is not
+going to be processed at all (for the latter one).
+
 \membersection{wxApp::GetAppName}\label{wxappgetappname}
 
 \constfunc{wxString}{GetAppName}{\void}

include/wx/app.h

@@ -315,6 +315,15 @@ public:
     virtual void SetActive(bool isActive, wxWindow *lastFocus);
 #endif // wxUSE_GUI
 
+    // this method allows to filter all the events processed by the program, so
+    // you should try to return quickly from it to avoid slowing down the
+    // program to the crawl
+    //
+    // return value should be -1 to continue with the normal event processing,
+    // or TRUE or FALSE to stop further processing and pretend that the event
+    // had been already processed or won't be processed at all, respectively
+    virtual int FilterEvent(wxEvent& event);
+
     // debugging support
     // -----------------
 

src/common/appcmn.cpp

@@ -182,6 +182,12 @@ void wxAppBase::SetActive(bool active, wxWindow * WXUNUSED(lastFocus))
 
 #endif // wxUSE_GUI
 
+int wxAppBase::FilterEvent(wxEvent& WXUNUSED(event))
+{
+    // process the events normally by default
+    return -1;
+}
+
 // ----------------------------------------------------------------------------
 // cmd line parsing
 // ----------------------------------------------------------------------------

src/common/event.cpp

@@ -744,12 +744,32 @@ bool wxEvtHandler::ProcessEvent(wxEvent& event)
     info = CLASSINFO(wxWindow);
 #endif
 
-    wxASSERT_MSG( m_isWindow == IsKindOf(info),
+    if ( m_isWindow != IsKindOf(info) )
-                  wxString(GetClassInfo()->GetClassName()) + _T(" should [not] be a window but it is [not]") );
+    {
-#endif
+        wxString msg = GetClassInfo()->GetClassName();
+        msg += _T(" should [not] be a window but it is [not]");
+
+        wxFAIL_MSG( msg );
+    }
+
+#endif // __WXDEBUG__
 
 #endif // wxUSE_GUI
 
+    // allow the application to hook into event processing
+    if ( wxTheApp )
+    {
+        int rc = wxTheApp->FilterEvent(event);
+        if ( rc != -1 )
+        {
+            wxASSERT_MSG( rc == 1 || rc == 0,
+                          _T("unexpected wxApp::FilterEvent return value") );
+
+            return rc != 0;
+        }
+        //else: proceed normally
+    }
+
     // An event handler can be enabled or disabled
     if ( GetEvtHandlerEnabled() )
     {