content/browser/renderer_host/input/touch_event_queue.h

   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_TOUCH_EVENT_QUEUE_H_
   6 #define CONTENT_BROWSER_RENDERER_HOST_INPUT_TOUCH_EVENT_QUEUE_H_
   7
   8 #include <deque>
   9 #include <map>
  10
  11 #include "base/basictypes.h"
  12 #include "base/time/time.h"
  13 #include "content/browser/renderer_host/event_with_latency_info.h"
  14 #include "content/common/content_export.h"
  15 #include "content/common/input/input_event_ack_state.h"
  16 #include "third_party/WebKit/public/web/WebInputEvent.h"
  17 #include "ui/gfx/geometry/point_f.h"
  18
  19 namespace content {
  20
  21 class CoalescedWebTouchEvent;
  22
  23 // Interface with which TouchEventQueue can forward touch events, and dispatch
  24 // touch event responses.
  25 class CONTENT_EXPORT TouchEventQueueClient {
  26  public:
  27   virtual ~TouchEventQueueClient() {}
  28
  29   virtual void SendTouchEventImmediately(
  30       const TouchEventWithLatencyInfo& event) = 0;
  31
  32   virtual void OnTouchEventAck(
  33       const TouchEventWithLatencyInfo& event,
  34       InputEventAckState ack_result) = 0;
  35 };
  36
  37 // A queue for throttling and coalescing touch-events.
  38 class CONTENT_EXPORT TouchEventQueue {
  39  public:
  40   // Different ways of dealing with touch events during scrolling.
  41   // TODO(rbyers): Remove this once we're confident that touch move absorption
  42   // is OK. http://crbug.com/350430
  43   enum TouchScrollingMode {
  44     // Send a touchcancel on scroll start and no further touch events for the
  45     // duration of the scroll.  Chrome Android's traditional behavior.
  46     TOUCH_SCROLLING_MODE_TOUCHCANCEL,
  47     // Send touchmove events throughout a scroll, blocking on each ACK and
  48     // using the disposition to determine whether a scroll update should be
  49     // sent.  Mobile Safari's default overflow scroll behavior.
  50     TOUCH_SCROLLING_MODE_SYNC_TOUCHMOVE,
  51     // Send touchmove events throughout a scroll, but throttle sending and
  52     // ignore the ACK as long as scrolling remains possible.  Unconsumed scroll
  53     // events return touchmove events to being dispatched synchronously.
  54     TOUCH_SCROLLING_MODE_ASYNC_TOUCHMOVE,
  55     TOUCH_SCROLLING_MODE_DEFAULT = TOUCH_SCROLLING_MODE_ASYNC_TOUCHMOVE
  56   };
  57
  58   struct CONTENT_EXPORT Config {
  59     Config();
  60
  61     // Determines the bounds of the (square) touchmove slop suppression region.
  62     // Defaults to 0 (disabled).
  63     double touchmove_slop_suppression_length_dips;
  64
  65     // Determines the type of touch scrolling.
  66     // Defaults to TouchEventQueue:::TOUCH_SCROLLING_MODE_DEFAULT.
  67     TouchEventQueue::TouchScrollingMode touch_scrolling_mode;
  68
  69     // Controls whether touch ack timeouts will trigger touch cancellation.
  70     // Defaults to 200ms.
  71     base::TimeDelta touch_ack_timeout_delay;
  72
  73     // Whether the platform supports touch ack timeout behavior.
  74     // Defaults to false (disabled).
  75     bool touch_ack_timeout_supported;
  76   };
  77
  78   // The |client| must outlive the TouchEventQueue.
  79   TouchEventQueue(TouchEventQueueClient* client, const Config& config);
  80
  81   ~TouchEventQueue();
  82
  83   // Adds an event to the queue. The event may be coalesced with previously
  84   // queued events (e.g. consecutive touch-move events can be coalesced into a
  85   // single touch-move event). The event may also be immediately forwarded to
  86   // the renderer (e.g. when there are no other queued touch event).
  87   void QueueEvent(const TouchEventWithLatencyInfo& event);
  88
  89   // Notifies the queue that a touch-event has been processed by the renderer.
  90   // At this point, the queue may send one or more gesture events and/or
  91   // additional queued touch-events to the renderer.
  92   void ProcessTouchAck(InputEventAckState ack_result,
  93                        const ui::LatencyInfo& latency_info);
  94
  95   // When GestureScrollBegin is received, we send a touch cancel to renderer,
  96   // route all the following touch events directly to client, and ignore the
  97   // ack for the touch cancel. When Gesture{ScrollEnd,FlingStart} is received,
  98   // resume the normal flow of sending touch events to the renderer.
  99   void OnGestureScrollEvent(const GestureEventWithLatencyInfo& gesture_event);
 100
 101   void OnGestureEventAck(
 102       const GestureEventWithLatencyInfo& event,
 103       InputEventAckState ack_result);
 104
 105   // Notifies the queue whether the renderer has at least one touch handler.
 106   void OnHasTouchEventHandlers(bool has_handlers);
 107
 108   // Returns whether the currently pending touch event (waiting ACK) is for
 109   // a touch start event.
 110   bool IsPendingAckTouchStart() const;
 111
 112   // Sets whether a delayed touch ack will cancel and flush the current
 113   // touch sequence. Note that, if the timeout was previously disabled, enabling
 114   // it will take effect only for the following touch sequence.
 115   void SetAckTimeoutEnabled(bool enabled);
 116
 117   bool empty() const WARN_UNUSED_RESULT {
 118     return touch_queue_.empty();
 119   }
 120
 121   size_t size() const {
 122     return touch_queue_.size();
 123   }
 124
 125   bool ack_timeout_enabled() const {
 126     return ack_timeout_enabled_;
 127   }
 128
 129   bool has_handlers() const {
 130     return touch_filtering_state_ != DROP_ALL_TOUCHES;
 131   }
 132
 133  private:
 134   class TouchTimeoutHandler;
 135   class TouchMoveSlopSuppressor;
 136   friend class TouchTimeoutHandler;
 137   friend class TouchEventQueueTest;
 138
 139   bool HasPendingAsyncTouchMoveForTesting() const;
 140   bool IsTimeoutRunningForTesting() const;
 141   const TouchEventWithLatencyInfo& GetLatestEventForTesting() const;
 142
 143   // Empties the queue of touch events. This may result in any number of gesture
 144   // events being sent to the renderer.
 145   void FlushQueue();
 146
 147   // Walks the queue, checking each event with |FilterBeforeForwarding()|.
 148   // If allowed, forwards the touch event and stops processing further events.
 149   // Otherwise, acks the event with |INPUT_EVENT_ACK_STATE_NO_CONSUMER_EXISTS|.
 150   void TryForwardNextEventToRenderer();
 151
 152   // Forwards the event at the head of the queue to the renderer.
 153   void ForwardNextEventToRenderer();
 154
 155   // Pops the touch-event from the head of the queue and acks it to the client.
 156   void PopTouchEventToClient(InputEventAckState ack_result);
 157
 158   // Pops the touch-event from the top of the queue and acks it to the client,
 159   // updating the event with |renderer_latency_info|.
 160   void PopTouchEventToClient(InputEventAckState ack_result,
 161                              const ui::LatencyInfo& renderer_latency_info);
 162
 163   // Ack all coalesced events in |acked_event| to the client with |ack_result|.
 164   void AckTouchEventToClient(InputEventAckState ack_result,
 165                              scoped_ptr<CoalescedWebTouchEvent> acked_event);
 166
 167   // Safely pop the head of the queue.
 168   scoped_ptr<CoalescedWebTouchEvent> PopTouchEvent();
 169
 170   // Dispatch |touch| to the client.
 171   void SendTouchEventImmediately(const TouchEventWithLatencyInfo& touch);
 172
 173   enum PreFilterResult {
 174     ACK_WITH_NO_CONSUMER_EXISTS,
 175     ACK_WITH_NOT_CONSUMED,
 176     FORWARD_TO_RENDERER,
 177   };
 178   // Filter touches prior to forwarding to the renderer, e.g., if the renderer
 179   // has no touch handler.
 180   PreFilterResult FilterBeforeForwarding(const blink::WebTouchEvent& event);
 181   void ForwardToRenderer(const TouchEventWithLatencyInfo& event);
 182   void UpdateTouchAckStates(const blink::WebTouchEvent& event,
 183                             InputEventAckState ack_result);
 184   bool AllTouchAckStatesHaveState(InputEventAckState ack_state) const;
 185
 186
 187   // Handles touch event forwarding and ack'ed event dispatch.
 188   TouchEventQueueClient* client_;
 189
 190   typedef std::deque<CoalescedWebTouchEvent*> TouchQueue;
 191   TouchQueue touch_queue_;
 192
 193   // Maintain the ACK status for each touch point.
 194   typedef std::map<int, InputEventAckState> TouchPointAckStates;
 195   TouchPointAckStates touch_ack_states_;
 196
 197   // Position of the first touch in the most recent sequence forwarded to the
 198   // client.
 199   gfx::PointF touch_sequence_start_position_;
 200
 201   // Used to defer touch forwarding when ack dispatch triggers |QueueEvent()|.
 202   // If not NULL, |dispatching_touch_ack_| is the touch event of which the ack
 203   // is being dispatched.
 204   const CoalescedWebTouchEvent* dispatching_touch_ack_;
 205
 206   // Used to prevent touch timeout scheduling if we receive a synchronous
 207   // ack after forwarding a touch event to the client.
 208   bool dispatching_touch_;
 209
 210   enum TouchFilteringState {
 211     FORWARD_ALL_TOUCHES,           // Don't filter at all - the default.
 212     FORWARD_TOUCHES_UNTIL_TIMEOUT, // Don't filter unless we get an ACK timeout.
 213     DROP_TOUCHES_IN_SEQUENCE,      // Filter all events until a new touch
 214                                    // sequence is received.
 215     DROP_ALL_TOUCHES,              // Filter all events, e.g., no touch handler.
 216     TOUCH_FILTERING_STATE_DEFAULT = FORWARD_ALL_TOUCHES,
 217   };
 218   TouchFilteringState touch_filtering_state_;
 219
 220   // Optional handler for timed-out touch event acks.
 221   bool ack_timeout_enabled_;
 222   scoped_ptr<TouchTimeoutHandler> timeout_handler_;
 223
 224   // Suppression of TouchMove's within a slop region when a sequence has not yet
 225   // been preventDefaulted.
 226   scoped_ptr<TouchMoveSlopSuppressor> touchmove_slop_suppressor_;
 227
 228   // Whether touch events should remain buffered and dispatched asynchronously
 229   // while a scroll sequence is active.  In this mode, touchmove's are throttled
 230   // and ack'ed immediately, but remain buffered in |pending_async_touchmove_|
 231   // until a sufficient time period has elapsed since the last sent touch event.
 232   // For details see the design doc at http://goo.gl/lVyJAa.
 233   bool send_touch_events_async_;
 234   bool needs_async_touchmove_for_outer_slop_region_;
 235   scoped_ptr<TouchEventWithLatencyInfo> pending_async_touchmove_;
 236   double last_sent_touch_timestamp_sec_;
 237
 238   // How touch events are handled during scrolling.  For now this is a global
 239   // setting for experimentation, but we may evolve it into an app-controlled
 240   // mode.
 241   const TouchScrollingMode touch_scrolling_mode_;
 242
 243   DISALLOW_COPY_AND_ASSIGN(TouchEventQueue);
 244 };
 245
 246 }  // namespace content
 247
 248 #endif  // CONTENT_BROWSER_RENDERER_HOST_INPUT_TOUCH_EVENT_QUEUE_H_