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

interface/wx/app.h

@@ -37,7 +37,8 @@
 
     @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
 */
-class wxAppConsole : public wxEvtHandler
+class wxAppConsole : public wxEvtHandler,
+                     public wxEventFilter
 {
 protected:
     /**
@@ -81,13 +82,14 @@ public:
     virtual void ExitMainLoop();
 
     /**
-        This function is called before processing any event and allows the application
-        to preempt the processing of some events.
+        Overridden wxEventFilter method.
 
-        If this method returns -1 the event is processed normally, otherwise either
-        @true or @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).
+        This function is called before processing any event and allows the application
+        to preempt the processing of some events, see wxEventFilter
+        documentation for more information.
+
+        wxApp implementation of this method always return -1 indicating that
+        the event should be processed normally.
     */
     virtual int FilterEvent(wxEvent& event);
 

interface/wx/event.h

@@ -1088,6 +1088,40 @@ public:
 
     //@}
 
+    /**
+        @name Global event filters.
+
+        Methods for working with the global list of event filters.
+
+        Event filters can be defined to pre-process all the events that happen
+        in an application, see wxEventFilter documentation for more information.
+     */
+    //@{
+
+    /**
+        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.
+
+        @since 2.9.3
+     */
+    static void AddFilter(wxEventFilter* filter);
+
+    /**
+        Remove a filter previously installed with AddFilter().
+
+        It's an error to remove a filter that hadn't been previously added or
+        was already removed.
+
+        @since 2.9.3
+     */
+    static void RemoveFilter(wxEventFilter* filter);
+
+    //@}
+
 protected:
     /**
         Method called by ProcessEvent() before examining this object event

interface/wx/eventfilter.h

@@ -0,0 +1,139 @@
+///////////////////////////////////////////////////////////////////////////////
+// Name:        interface/wx/eventfilter.h
+// Purpose:     wxEventFilter class documentation
+// Author:      Vadim Zeitlin
+// Created:     2011-11-21
+// RCS-ID:      $Id$
+// Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
+// Licence:     wxWindows licence
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+    A global event filter for pre-processing all the events generated in the
+    program.
+
+    This is a very simple class which just provides FilterEvent() virtual
+    method to be called by wxEvtHandler before starting process of any event.
+    Thus, inheriting from this class and overriding FilterEvent() allows to
+    capture and possibly handle or ignore all the events happening in the
+    program. Of course, having event filters adds additional overhead to every
+    event processing and so should not be used lightly and your FilterEvent()
+    code should try to return as quickly as possible, especially for the events
+    it is not interested in.
+
+    An example of using this class:
+    @code
+    // This class allows to determine the last time the user has worked with
+    // this application:
+    class LastActivityTimeDetector : public wxEventFilter
+    {
+    public:
+        LastActivityTimeDetector()
+        {
+            wxEvtHandler::AddFilter(this);
+
+            m_last = wxDateTime::Now();
+        }
+
+        virtual ~LastActivityTimeDetector()
+        {
+            wxEvtHandler::RemoveFilter(this);
+        }
+
+        virtual int FilterEvent(wxEvent& event)
+        {
+            // Update the last user activity
+            const wxEventType t = event.GetEventType();
+            if ( t == wxEVT_KEY_DOWN || t == wxEVT_MOTION ||
+                    t == wxEVT_LEFT_DOWN ||
+                        t == wxEVT_RIGHT_DOWN ||
+                            t == wxEVT_MIDDLE_DOWN )
+            {
+                m_last = wxDateTime::Now();
+            }
+
+            // Continue processing the event normally as well.
+            return Event_Skip;
+        }
+
+        // This function could be called periodically from some timer to
+        // do something (e.g. hide sensitive data or log out from remote
+        // server) if the user has been inactive for some time period.
+        bool IsInactiveFor(const wxTimeSpan& diff) const
+        {
+            return wxDateTime::Now() - diff > m_last;
+        }
+
+    private:
+        wxDateTime m_last;
+    };
+    @endcode
+
+    Notice that wxApp derives from wxEventFilter and is registered as an event
+    filter during its creation so you may also override FilterEvent() method in
+    your wxApp-derived class and, in fact, this is often the most convenient
+    way to do it. However creating a new class deriving directly from
+    wxEventFilter allows to isolate the event filtering code in its own
+    separate class and also to have several independent filters, if necessary.
+
+    @category{events}
+
+    @since 2.9.3
+ */
+class wxEventFilter
+{
+public:
+    /// Possible return values for FilterEvent().
+    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
+    };
+
+    /**
+        Default constructor.
+
+        Constructor does not register this filter using
+        wxEvtHandler::AddFilter(), it's your responsibility to do it when
+        necessary.
+
+        Notice that the objects of this class can't be copied.
+     */
+    wxEventFilter();
+
+    /**
+        Destructor.
+
+        You must call wxEvtHandler::RemoveFilter() before destroying this
+        object (possibly from the derived class destructor), failure to do this
+        is indicated by an assert unless assertions are disabled.
+     */
+    virtual ~wxEventFilter();
+
+    /**
+        Override this method to implement event pre-processing.
+
+        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.
+
+        Although the return type of this method is @c int, this is only due to
+        backwards compatibility concerns and the actual return value must be
+        one of the @c Event_XXX constants defined above:
+            - Event_Skip to continue processing the event normally (this should
+            be used in most cases).
+            - Event_Ignore to not process this event at all (this can be used
+            to suppress some events).
+            - Event_Processed to not process this event normally but indicate
+            that it was already processed by the event filter and so no default
+            processing should take place neither (this should only be used if
+            the filter really did process the event).
+     */
+    virtual int FilterEvent(wxEvent& event) = 0;
+};