1// Copyright 2013 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef CONTENT_BROWSER_RENDERER_HOST_INPUT_GESTURE_EVENT_FILTER_H_
6#define CONTENT_BROWSER_RENDERER_HOST_INPUT_GESTURE_EVENT_FILTER_H_
7
8#include <deque>
9
10#include "base/basictypes.h"
11#include "base/memory/scoped_ptr.h"
12#include "base/timer/timer.h"
13#include "content/common/content_export.h"
14#include "content/port/browser/event_with_latency_info.h"
15#include "content/port/common/input_event_ack_state.h"
16#include "third_party/WebKit/public/web/WebInputEvent.h"
17#include "ui/gfx/transform.h"
18
19namespace content {
20class GestureEventFilterTest;
21class InputRouter;
22class MockRenderWidgetHost;
23class TouchpadTapSuppressionController;
24class TouchpadTapSuppressionControllerClient;
25class TouchscreenTapSuppressionController;
26
27// Interface with which the GestureEventFilter can forward gesture events, and
28// dispatch gesture event responses.
29class CONTENT_EXPORT GestureEventFilterClient {
30 public:
31  virtual ~GestureEventFilterClient() {}
32
33  virtual void SendGestureEventImmediately(
34      const GestureEventWithLatencyInfo& event) = 0;
35
36  virtual void OnGestureEventAck(
37      const GestureEventWithLatencyInfo& event,
38      InputEventAckState ack_result) = 0;
39};
40
41// Maintains WebGestureEvents in a queue before forwarding them to the renderer
42// to apply a sequence of filters on them:
43// 1. Zero-velocity fling-starts from touchpad are filtered.
44// 2. The sequence is filtered for bounces. A bounce is when the finger lifts
45//    from the screen briefly during an in-progress scroll. Ifco this happens,
46//    non-GestureScrollUpdate events are queued until the de-bounce interval
47//    passes or another GestureScrollUpdate event occurs.
48// 3. Unnecessary GestureFlingCancel events are filtered. These are
49//    GestureFlingCancels that have no corresponding GestureFlingStart in the
50//    queue.
51// 4. Taps immediately after a GestureFlingCancel (caused by the same tap) are
52//    filtered.
53// 5. Whenever possible, events in the queue are coalesced to have as few events
54//    as possible and therefore maximize the chance that the event stream can be
55//    handled entirely by the compositor thread.
56// Events in the queue are forwarded to the renderer one by one; i.e., each
57// event is sent after receiving the ACK for previous one. The only exception is
58// that if a GestureScrollUpdate is followed by a GesturePinchUpdate, they are
59// sent together.
60// TODO(rjkroege): Possibly refactor into a filter chain:
61// http://crbug.com/148443.
62class CONTENT_EXPORT GestureEventFilter {
63 public:
64  // Both |client| and |touchpad_client| must outlive the GestureEventFilter.
65  GestureEventFilter(GestureEventFilterClient* client,
66                     TouchpadTapSuppressionControllerClient* touchpad_client);
67  ~GestureEventFilter();
68
69  // Returns |true| if the caller should immediately forward the provided
70  // |GestureEventWithLatencyInfo| argument to the renderer.
71  bool ShouldForward(const GestureEventWithLatencyInfo&);
72
73  // Indicates that the caller has received an acknowledgement from the renderer
74  // with state |ack_result| and event |type|. May send events if the queue is
75  // not empty.
76  void ProcessGestureAck(InputEventAckState ack_result,
77                         blink::WebInputEvent::Type type,
78                         const ui::LatencyInfo& latency);
79
80  // Sets the state of the |fling_in_progress_| field to indicate that a fling
81  // is definitely not in progress.
82  void FlingHasBeenHalted();
83
84  // Returns the |TouchpadTapSuppressionController| instance.
85  TouchpadTapSuppressionController* GetTouchpadTapSuppressionController();
86
87  // Returns whether there are any gesture event in the queue.
88  bool HasQueuedGestureEvents() const;
89
90  void ForwardGestureEvent(const GestureEventWithLatencyInfo& gesture_event);
91
92  void set_debounce_enabled_for_testing(bool enabled) {
93    debounce_enabled_ = enabled;
94  }
95
96  void set_debounce_interval_time_ms_for_testing(int interval_time_ms) {
97    debounce_interval_time_ms_ = interval_time_ms;
98  }
99
100 private:
101  friend class GestureEventFilterTest;
102  friend class MockRenderWidgetHost;
103
104  // TODO(mohsen): There are a bunch of ShouldForward.../ShouldDiscard...
105  // methods that are getting confusing. This should be somehow fixed. Maybe
106  // while refactoring GEF: http://crbug.com/148443.
107
108  // Inovked on the expiration of the debounce interval to release
109  // deferred events.
110  void SendScrollEndingEventsNow();
111
112  // Returns |true| if the given GestureFlingCancel should be discarded
113  // as unnecessary.
114  bool ShouldDiscardFlingCancelEvent(
115      const GestureEventWithLatencyInfo& gesture_event) const;
116
117  // Returns |true| if the only event in the queue is the current event and
118  // hence that event should be handled now.
119  bool ShouldHandleEventNow() const;
120
121  // Merge or append a GestureScrollUpdate or GesturePinchUpdate into
122  // the coalescing queue.
123  void MergeOrInsertScrollAndPinchEvent(
124      const GestureEventWithLatencyInfo& gesture_event);
125
126  // Sub-filter for removing zero-velocity fling-starts from touchpad.
127  bool ShouldForwardForZeroVelocityFlingStart(
128      const GestureEventWithLatencyInfo& gesture_event) const;
129
130  // Sub-filter for removing bounces from in-progress scrolls.
131  bool ShouldForwardForBounceReduction(
132      const GestureEventWithLatencyInfo& gesture_event);
133
134  // Sub-filter for removing unnecessary GestureFlingCancels.
135  bool ShouldForwardForGFCFiltering(
136      const GestureEventWithLatencyInfo& gesture_event) const;
137
138  // Sub-filter for suppressing taps immediately after a GestureFlingCancel.
139  bool ShouldForwardForTapSuppression(
140      const GestureEventWithLatencyInfo& gesture_event);
141
142  // Puts the events in a queue to forward them one by one; i.e., forward them
143  // whenever ACK for previous event is received. This queue also tries to
144  // coalesce events as much as possible.
145  bool ShouldForwardForCoalescing(
146      const GestureEventWithLatencyInfo& gesture_event);
147
148  // Whether the event_in_queue is GesturePinchUpdate or
149  // GestureScrollUpdate and it has the same modifiers as the
150  // new event.
151  bool ShouldTryMerging(
152      const GestureEventWithLatencyInfo& new_event,
153      const GestureEventWithLatencyInfo& event_in_queue)const;
154
155  // Returns the transform matrix corresponding to the gesture event.
156  // Assumes the gesture event sent is either GestureScrollUpdate or
157  // GesturePinchUpdate. Returns the identity matrix otherwise.
158  gfx::Transform GetTransformForEvent(
159      const GestureEventWithLatencyInfo& gesture_event) const;
160
161  // Adds |gesture_event| to the |coalesced_gesture_events_|, resetting the
162  // accumulation of |combined_scroll_pinch_|.
163  void EnqueueEvent(const GestureEventWithLatencyInfo& gesture_event);
164
165  // The receiver of all forwarded gesture events.
166  GestureEventFilterClient* client_;
167
168  // True if a GestureFlingStart is in progress on the renderer or
169  // queued without a subsequent queued GestureFlingCancel event.
170  bool fling_in_progress_;
171
172  // True if a GestureScrollUpdate sequence is in progress.
173  bool scrolling_in_progress_;
174
175  // True if two related gesture events were sent before without waiting
176  // for an ACK, so the next gesture ACK should be ignored.
177  bool ignore_next_ack_;
178
179  // Transform that holds the combined transform matrix for the current
180  // scroll-pinch sequence at the end of the queue.
181  gfx::Transform combined_scroll_pinch_;
182
183  // An object tracking the state of touchpad on the delivery of mouse events to
184  // the renderer to filter mouse immediately after a touchpad fling canceling
185  // tap.
186  // TODO(mohsen): Move touchpad tap suppression out of GestureEventFilter since
187  // GEF is meant to only be used for touchscreen gesture events.
188  scoped_ptr<TouchpadTapSuppressionController>
189      touchpad_tap_suppression_controller_;
190
191  // An object tracking the state of touchscreen on the delivery of gesture tap
192  // events to the renderer to filter taps immediately after a touchscreen fling
193  // canceling tap.
194  scoped_ptr<TouchscreenTapSuppressionController>
195      touchscreen_tap_suppression_controller_;
196
197  typedef std::deque<GestureEventWithLatencyInfo> GestureEventQueue;
198
199  // Queue of coalesced gesture events not yet sent to the renderer. If
200  // |ignore_next_ack_| is false, then the event at the front of the queue has
201  // been sent and is awaiting an ACK, and all other events have yet to be sent.
202  // If |ignore_next_ack_| is true, then the two events at the front of the
203  // queue have been sent, and the second is awaiting an ACK. All other events
204  // have yet to be sent.
205  GestureEventQueue coalesced_gesture_events_;
206
207  // Timer to release a previously deferred gesture event.
208  base::OneShotTimer<GestureEventFilter> debounce_deferring_timer_;
209
210  // Queue of events that have been deferred for debounce.
211  GestureEventQueue debouncing_deferral_queue_;
212
213  // Time window in which to debounce scroll/fling ends.
214  // TODO(rjkroege): Make this dynamically configurable.
215  int debounce_interval_time_ms_;
216
217  // Whether scroll-ending events should be deferred when a scroll is active.
218  // Defaults to true.
219  bool debounce_enabled_;
220
221  DISALLOW_COPY_AND_ASSIGN(GestureEventFilter);
222};
223
224}  // namespace content
225
226#endif  // CONTENT_BROWSER_RENDERER_HOST_INPUT_GESTURE_EVENT_FILTER_H_
227