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.
5 #ifndef UI_AURA_TEST_EVENT_GENERATOR_H_
6 #define UI_AURA_TEST_EVENT_GENERATOR_H_
11 #include "base/basictypes.h"
12 #include "base/callback.h"
13 #include "base/memory/scoped_ptr.h"
14 #include "ui/events/event_constants.h"
15 #include "ui/events/keycodes/keyboard_codes.h"
16 #include "ui/gfx/point.h"
35 class ScreenPositionClient;
40 typedef base::Callback<void(ui::EventType, const gfx::Vector2dF&)>
43 // A delegate interface for EventGenerator that provides a way to
44 // locate aura root window for given point.
45 class EventGeneratorDelegate {
47 virtual ~EventGeneratorDelegate() {}
49 // Returns a root window for given point.
50 virtual RootWindow* GetRootWindowAt(const gfx::Point& point) const = 0;
52 // Returns the screen position client that determines the
53 // coordinates used in EventGenerator. EventGenerator uses
54 // RootWindow's coordinate if this retruns NULL.
55 virtual client::ScreenPositionClient* GetScreenPositionClient(
56 const aura::Window* window) const = 0;
59 // EventGenerator is a tool that generates and dispatch events.
60 // Unlike |ui_controls| package in ui/base/test, this does not
61 // generate platform native events. Insetad, it directly posts event
62 // to |aura::RootWindow| synchronously.
64 // Advantage of using this class, compared to |ui_controls| is that
65 // you can write the tests that involves events in synchronus
66 // way. There is no need to wait for native
68 // On the other hand, this class is not suited for the following
71 // 1) If your test depends on native events (ui::Event::native_event()).
72 // This return is empty/NULL event with EventGenerator.
73 // 2) If your test involves nested message loop, such as
74 // menu or drag & drop. Because this class directly
75 // post an event to RootWindow, this event will not be
76 // handled in the nested message loop.
77 // 3) Similarly, |base::MessagePumpObserver| will not be invoked.
78 // 4) Any other code that requires native events, such as
79 // tests for WindowTreeHostWin/WindowTreeHostX11.
81 // If one of these applies to your test, please use |ui_controls|
84 // Note: The coordinates of the points in API is determined by the
85 // EventGeneratorDelegate.
86 class EventGenerator {
88 // Creates an EventGenerator with the mouse/touch location (0,0),
89 // which uses the |root_window|'s coordinates.
90 explicit EventGenerator(Window* root_window);
92 // Create an EventGenerator with EventGeneratorDelegate,
93 // which uses the coordinates used by |delegate|.
94 explicit EventGenerator(EventGeneratorDelegate* delegate);
96 // Creates an EventGenerator with the mouse/touch location
97 // at |initial_location|, which uses the |root_window|'s coordinates.
98 EventGenerator(Window* root_window, const gfx::Point& initial_location);
100 // Creates an EventGenerator with the mouse/touch location
101 // centered over |window|, which uses the |root_window|'s coordinates.
102 EventGenerator(Window* root_window, Window* window);
104 virtual ~EventGenerator();
106 // Explicitly sets the location used by mouse/touch events. This is set by the
107 // various methods that take a location but can be manipulated directly,
108 // typically for touch.
109 void set_current_location(const gfx::Point& location) {
110 current_location_ = location;
112 const gfx::Point& current_location() const { return current_location_; }
114 void set_async(bool async) { async_ = async; }
115 bool async() const { return async_; }
117 // Resets the event flags bitmask.
118 void set_flags(int flags) { flags_ = flags; }
120 // Generates a left button press event.
121 void PressLeftButton();
123 // Generates a left button release event.
124 void ReleaseLeftButton();
126 // Generates events to click (press, release) left button.
127 void ClickLeftButton();
129 // Generates a double click event using the left button.
130 void DoubleClickLeftButton();
132 // Generates a right button press event.
133 void PressRightButton();
135 // Generates a right button release event.
136 void ReleaseRightButton();
138 // Generates a mouse exit.
139 void SendMouseExit();
141 // Generates events to move mouse to be the given |point| in the
142 // |current_root_window_|'s host window coordinates.
143 void MoveMouseToInHost(const gfx::Point& point_in_host);
144 void MoveMouseToInHost(int x, int y) {
145 MoveMouseToInHost(gfx::Point(x, y));
148 // Generates events to move mouse to be the given |point| in screen
150 void MoveMouseTo(const gfx::Point& point_in_screen, int count);
151 void MoveMouseTo(const gfx::Point& point_in_screen) {
152 MoveMouseTo(point_in_screen, 1);
154 void MoveMouseTo(int x, int y) {
155 MoveMouseTo(gfx::Point(x, y));
158 // Generates events to move mouse to be the given |point| in |window|'s
160 void MoveMouseRelativeTo(const Window* window, const gfx::Point& point);
161 void MoveMouseRelativeTo(const Window* window, int x, int y) {
162 MoveMouseRelativeTo(window, gfx::Point(x, y));
165 void MoveMouseBy(int x, int y) {
166 MoveMouseTo(current_location_ + gfx::Vector2d(x, y));
169 // Generates events to drag mouse to given |point|.
170 void DragMouseTo(const gfx::Point& point);
172 void DragMouseTo(int x, int y) {
173 DragMouseTo(gfx::Point(x, y));
176 void DragMouseBy(int dx, int dy) {
177 DragMouseTo(current_location_ + gfx::Vector2d(dx, dy));
180 // Generates events to move the mouse to the center of the window.
181 void MoveMouseToCenterOf(Window* window);
183 // Generates a touch press event.
186 // Generates a touch press event with |touch_id|.
187 void PressTouchId(int touch_id);
189 // Generates a ET_TOUCH_MOVED event to |point|.
190 void MoveTouch(const gfx::Point& point);
192 // Generates a ET_TOUCH_MOVED event to |point| with |touch_id|.
193 void MoveTouchId(const gfx::Point& point, int touch_id);
195 // Generates a touch release event.
198 // Generates a touch release event with |touch_id|.
199 void ReleaseTouchId(int touch_id);
201 // Generates press, move and release event to move touch
202 // to be the given |point|.
203 void PressMoveAndReleaseTouchTo(const gfx::Point& point);
205 void PressMoveAndReleaseTouchTo(int x, int y) {
206 PressMoveAndReleaseTouchTo(gfx::Point(x, y));
209 void PressMoveAndReleaseTouchBy(int x, int y) {
210 PressMoveAndReleaseTouchTo(current_location_ + gfx::Vector2d(x, y));
213 // Generates press, move and release events to move touch
214 // to the center of the window.
215 void PressMoveAndReleaseTouchToCenterOf(Window* window);
217 // Generates and dispatches a Win8 edge-swipe event (swipe up from bottom or
218 // swipe down from top). Note that it is not possible to distinguish between
219 // the two edges with this event.
220 void GestureEdgeSwipe();
222 // Generates and dispatches touch-events required to generate a TAP gesture.
223 // Note that this can generate a number of other gesture events at the same
224 // time (e.g. GESTURE_BEGIN, TAP_DOWN, END).
225 void GestureTapAt(const gfx::Point& point);
227 // Generates press and release touch-events to generate a TAP_DOWN event, but
228 // without generating any scroll or tap events. This can also generate a few
229 // other gesture events (e.g. GESTURE_BEGIN, END).
230 void GestureTapDownAndUp(const gfx::Point& point);
232 // Generates press, move, release touch-events to generate a sequence of
233 // scroll events. |duration| and |steps| affect the velocity of the scroll,
234 // and depending on these values, this may also generate FLING scroll
235 // gestures. If velocity/fling is irrelevant for the test, then any non-zero
236 // values for these should be sufficient.
237 void GestureScrollSequence(const gfx::Point& start,
238 const gfx::Point& end,
239 const base::TimeDelta& duration,
242 // The same as GestureScrollSequence(), with the exception that |callback| is
243 // called at each step of the scroll sequence. |callback| is called at the
244 // start of the sequence with ET_GESTURE_SCROLL_BEGIN, followed by one or more
245 // ET_GESTURE_SCROLL_UPDATE and ends with an ET_GESTURE_SCROLL_END.
246 void GestureScrollSequenceWithCallback(const gfx::Point& start,
247 const gfx::Point& end,
248 const base::TimeDelta& duration,
250 const ScrollStepCallback& callback);
252 // Generates press, move, release touch-events to generate a sequence of
253 // multi-finger scroll events. |count| specifies the number of touch-points
254 // that should generate the scroll events. |start| are the starting positions
255 // of all the touch points. |steps| and |event_separation_time_ms| are
256 // relevant when testing velocity/fling/swipe, otherwise these can be any
257 // non-zero value. |delta_x| and |delta_y| are the amount that each finger
258 // should be moved. Internally calls GestureMultiFingerScrollWithDelays
259 // with zeros as |delay_adding_finger_ms| forcing all touch down events to be
261 void GestureMultiFingerScroll(int count,
262 const gfx::Point start[],
263 int event_separation_time_ms,
268 // Generates press, move, release touch-events to generate a sequence of
269 // multi-finger scroll events. |count| specifies the number of touch-points
270 // that should generate the scroll events. |start| are the starting positions
271 // of all the touch points. |delay_adding_finger_ms| are delays in ms from the
272 // starting time till touching down of each finger. |delay_adding_finger_ms|
273 // is useful when testing complex gestures that start with 1 or 2 fingers and
274 // add fingers with a delay. |steps| and |event_separation_time_ms| are
275 // relevant when testing velocity/fling/swipe, otherwise these can be any
276 // non-zero value. |delta_x| and |delta_y| are the amount that each finger
278 void GestureMultiFingerScrollWithDelays(int count,
279 const gfx::Point start[],
280 const int delay_adding_finger_ms[],
281 int event_separation_time_ms,
286 // Generates scroll sequences of a FlingCancel, Scrolls, FlingStart, with
287 // constant deltas to |x_offset| and |y_offset| in |steps|.
288 void ScrollSequence(const gfx::Point& start,
289 const base::TimeDelta& step_delay,
295 // Generates scroll sequences of a FlingCancel, Scrolls, FlingStart, sending
296 // scrolls of each of the values in |offsets|.
297 void ScrollSequence(const gfx::Point& start,
298 const base::TimeDelta& step_delay,
299 const std::vector<gfx::Point>& offsets,
302 // Generates a key press event. On platforms except Windows and X11, a key
303 // event without native_event() is generated. Note that ui::EF_ flags should
304 // be passed as |flags|, not the native ones like 'ShiftMask' in <X11/X.h>.
305 // TODO(yusukes): Support native_event() on all platforms.
306 void PressKey(ui::KeyboardCode key_code, int flags);
308 // Generates a key release event. On platforms except Windows and X11, a key
309 // event without native_event() is generated. Note that ui::EF_ flags should
310 // be passed as |flags|, not the native ones like 'ShiftMask' in <X11/X.h>.
311 // TODO(yusukes): Support native_event() on all platforms.
312 void ReleaseKey(ui::KeyboardCode key_code, int flags);
314 // Dispatch the event to the RootWindow.
315 void Dispatch(ui::Event* event);
317 void set_current_root_window(RootWindow* root_window) {
318 current_root_window_ = root_window;
322 // Dispatch a key event to the RootWindow.
323 void DispatchKeyEvent(bool is_press, ui::KeyboardCode key_code, int flags);
325 void UpdateCurrentRootWindow(const gfx::Point& point);
326 void PressButton(int flag);
327 void ReleaseButton(int flag);
329 // Convert a point between API's coordinates and
330 // |target|'s coordinates.
331 void ConvertPointFromTarget(const aura::Window* target,
332 gfx::Point* point) const;
333 void ConvertPointToTarget(const aura::Window* target,
334 gfx::Point* point) const;
336 gfx::Point GetLocationInCurrentRoot() const;
337 gfx::Point CenterOfWindow(const Window* window) const;
339 void DispatchNextPendingEvent();
340 void DoDispatchEvent(ui::Event* event, bool async);
342 scoped_ptr<EventGeneratorDelegate> delegate_;
343 gfx::Point current_location_;
344 RootWindow* current_root_window_;
347 std::list<ui::Event*> pending_events_;
348 // Set to true to cause events to be posted asynchronously.
351 DISALLOW_COPY_AND_ASSIGN(EventGenerator);
357 #endif // UI_AURA_TEST_EVENT_GENERATOR_H_