1// Copyright (c) 2012 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 UI_EVENTS_GESTURES_GESTURE_RECOGNIZER_H_
6#define UI_EVENTS_GESTURES_GESTURE_RECOGNIZER_H_
7
8#include <vector>
9
10#include "base/memory/scoped_vector.h"
11#include "ui/events/event_constants.h"
12#include "ui/events/events_export.h"
13#include "ui/events/gestures/gesture_types.h"
14#include "ui/gfx/geometry/point_f.h"
15
16namespace ui {
17// A GestureRecognizer is an abstract base class for conversion of touch events
18// into gestures.
19class EVENTS_EXPORT GestureRecognizer {
20 public:
21  static GestureRecognizer* Create();
22  static GestureRecognizer* Get();
23  static void Reset();
24
25  // List of GestureEvent*.
26  typedef ScopedVector<GestureEvent> Gestures;
27
28  virtual ~GestureRecognizer() {}
29
30  // Invoked before event dispatch. If the event is invalid given the current
31  // touch sequence, marks it as handled.
32  virtual bool ProcessTouchEventPreDispatch(const TouchEvent& event,
33                                            GestureConsumer* consumer) = 0;
34  // Returns a list of zero or more GestureEvents. The caller is responsible for
35  // freeing the returned events. Called synchronously after event dispatch.
36  virtual Gestures* ProcessTouchEventPostDispatch(
37      const TouchEvent& event,
38      ui::EventResult result,
39      GestureConsumer* consumer) = 0;
40  // Returns a list of zero or more GestureEvents. The caller is responsible for
41  // freeing the returned events. Called when a touch event receives an
42  // asynchronous ack.
43  virtual Gestures* ProcessTouchEventOnAsyncAck(const TouchEvent& event,
44                                                ui::EventResult result,
45                                                GestureConsumer* consumer) = 0;
46
47  // This is called when the consumer is destroyed. So this should cleanup any
48  // internal state maintained for |consumer|. Returns true iff there was
49  // state relating to |consumer| to clean up.
50  virtual bool CleanupStateForConsumer(GestureConsumer* consumer) = 0;
51
52  // Return the window which should handle this TouchEvent, in the case where
53  // the touch is already associated with a target.
54  // Otherwise, returns null.
55  virtual GestureConsumer* GetTouchLockedTarget(const TouchEvent& event) = 0;
56
57  // Return the window which should handle this GestureEvent.
58  virtual GestureConsumer* GetTargetForGestureEvent(
59      const GestureEvent& event) = 0;
60
61  // Returns the target of the nearest active touch with source device of
62  // |source_device_id|, within
63  // GestureConfiguration::max_separation_for_gesture_touches_in_pixels of
64  // |location|, or NULL if no such point exists.
65  virtual GestureConsumer* GetTargetForLocation(
66      const gfx::PointF& location, int source_device_id) = 0;
67
68  // Makes |new_consumer| the target for events previously targeting
69  // |current_consumer|. All other targets are canceled.
70  // The caller is responsible for updating the state of the consumers to
71  // be aware of this transfer of control (there are no ENTERED/EXITED events).
72  // If |new_consumer| is NULL, all events are canceled.
73  // If |old_consumer| is NULL, all events not already targeting |new_consumer|
74  // are canceled.
75  virtual void TransferEventsTo(GestureConsumer* current_consumer,
76                                GestureConsumer* new_consumer) = 0;
77
78  // If a gesture is underway for |consumer| |point| is set to the last touch
79  // point and true is returned. If no touch events have been processed for
80  // |consumer| false is returned and |point| is untouched.
81  virtual bool GetLastTouchPointForTarget(GestureConsumer* consumer,
82                                          gfx::PointF* point) = 0;
83
84  // Sends a touch cancel event for every active touch. Returns true iff any
85  // touch cancels were sent.
86  virtual bool CancelActiveTouches(GestureConsumer* consumer) = 0;
87
88  // Subscribes |helper| for dispatching async gestures such as long press.
89  // The Gesture Recognizer does NOT take ownership of |helper| and it is the
90  // responsibility of the |helper| to call |RemoveGestureEventHelper()| on
91  // destruction.
92  virtual void AddGestureEventHelper(GestureEventHelper* helper) = 0;
93
94  // Unsubscribes |helper| from async gesture dispatch.
95  // Since the GestureRecognizer does not own the |helper|, it is not deleted
96  // and must be cleaned up appropriately by the caller.
97  virtual void RemoveGestureEventHelper(GestureEventHelper* helper) = 0;
98};
99
100}  // namespace ui
101
102#endif  // UI_EVENTS_GESTURES_GESTURE_RECOGNIZER_H_
103