Add wxEventFilter and related functionality.

Allow defining event filters to globally pre-process all application events
without having to override wxApp::FilterEvent().

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

include/wx/app.h

@@ -18,6 +18,7 @@
 // ----------------------------------------------------------------------------
 
 #include "wx/event.h"       // for the base class
+#include "wx/eventfilter.h" // (and another one)
 #include "wx/build.h"
 #include "wx/cmdargs.h"     // for wxCmdLineArgsArray used by wxApp::argv
 #include "wx/init.h"        // we must declare wxEntry()
@@ -70,7 +71,8 @@ extern WXDLLIMPEXP_DATA_BASE(wxList) wxPendingDelete;
 // wxAppConsoleBase: wxApp for non-GUI applications
 // ----------------------------------------------------------------------------
 
-class WXDLLIMPEXP_BASE wxAppConsoleBase : public wxEvtHandler
+class WXDLLIMPEXP_BASE wxAppConsoleBase : public wxEvtHandler,
+                                          public wxEventFilter
 {
 public:
     // ctor and dtor
@@ -238,13 +240,8 @@ public:
     // event processing functions
     // --------------------------
 
-    // 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
+    // Implement the inherited wxEventFilter method but just return -1 from it
+    // to indicate that default processing should take place.
     virtual int FilterEvent(wxEvent& event);
 
     // return true if we're running event loop, i.e. if the events can

include/wx/event.h

@@ -39,6 +39,7 @@
 
 class WXDLLIMPEXP_FWD_BASE wxList;
 class WXDLLIMPEXP_FWD_BASE wxEvent;
+class WXDLLIMPEXP_FWD_BASE wxEventFilter;
 #if wxUSE_GUI
     class WXDLLIMPEXP_FWD_CORE wxDC;
     class WXDLLIMPEXP_FWD_CORE wxMenu;
@@ -3013,6 +3014,19 @@ public:
     bool IsUnlinked() const;
 
 
+    // Global event filters
+    // --------------------
+
+    // Add an event filter whose FilterEvent() method will be called for each
+    // and every event processed by wxWidgets. The filters are called in LIFO
+    // order and wxApp is registered as an event filter by default. The pointer
+    // must remain valid until it's removed with RemoveFilter() and is not
+    // deleted by wxEvtHandler.
+    static void AddFilter(wxEventFilter* filter);
+
+    // Remove a filter previously installed with AddFilter().
+    static void RemoveFilter(wxEventFilter* filter);
+
 
     // Event queuing and processing
     // ----------------------------
@@ -3360,6 +3374,9 @@ private:
     // try to process events in all handlers chained to this one
     bool DoTryChain(wxEvent& event);
 
+    // Head of the event filter linked list.
+    static wxEventFilter* ms_filterList;
+
     DECLARE_DYNAMIC_CLASS_NO_COPY(wxEvtHandler)
 };
 

include/wx/eventfilter.h

@@ -0,0 +1,72 @@
+///////////////////////////////////////////////////////////////////////////////
+// Name:        wx/eventfilter.h
+// Purpose:     wxEventFilter class declaration.
+// Author:      Vadim Zeitlin
+// Created:     2011-11-21
+// RCS-ID:      $Id: wxhead.h,v 1.12 2010-04-22 12:44:51 zeitlin Exp $
+// Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
+// Licence:     wxWindows licence
+///////////////////////////////////////////////////////////////////////////////
+
+#ifndef _WX_EVENTFILTER_H_
+#define _WX_EVENTFILTER_H_
+
+#include "wx/defs.h"
+
+class WXDLLIMPEXP_FWD_BASE wxEvent;
+class WXDLLIMPEXP_FWD_BASE wxEvtHandler;
+
+// ----------------------------------------------------------------------------
+// wxEventFilter is used with wxEvtHandler::AddFilter() and ProcessEvent().
+// ----------------------------------------------------------------------------
+
+class wxEventFilter
+{
+public:
+    // Possible return values for FilterEvent().
+    //
+    // Notice that the values of these enum elements are fixed due to backwards
+    // compatibility constraints.
+    enum
+    {
+        // Process event as usual.
+        Event_Skip = -1,
+
+        // Don't process the event normally at all.
+        Event_Ignore = 0,
+
+        // Event was already handled, don't process it normally.
+        Event_Processed = 1
+    };
+
+    wxEventFilter()
+    {
+        m_next = NULL;
+    }
+
+    virtual ~wxEventFilter()
+    {
+        wxASSERT_MSG( !m_next, "Forgot to call wxEvtHandler::RemoveFilter()?" );
+    }
+
+    // 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) = 0;
+
+private:
+    // Objects of this class are made to be stored in a linked list in
+    // wxEvtHandler so put the next node ponter directly in the class itself.
+    wxEventFilter* m_next;
+
+    // And provide access to it for wxEvtHandler [only].
+    friend class wxEvtHandler;
+
+    wxDECLARE_NO_COPY_CLASS(wxEventFilter);
+};
+
+#endif // _WX_EVENTFILTER_H_