1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  You may obtain a copy of the License at
8
//
9
//   http://www.apache.org/licenses/LICENSE-2.0
10
//
11
// Unless required by applicable law or agreed to in writing,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
/**
19
 * @fileoverview Synthetic events for fun and profit.
20
 */
21

22
goog.provide('webdriver.atoms.inputs');
23

24
goog.require('bot.Keyboard');
25
goog.require('bot.Mouse');
26
goog.require('bot.action');
27
goog.require('bot.dom');
28
goog.require('goog.dom');
29
goog.require('goog.math.Coordinate');
30
goog.require('goog.style');
31
goog.require('webdriver.atoms.element');
32

33

34
/**
35
 * Send keyboard input to a particular element.
36
 *
37
 * @param {?Element} element The element to send the keyboard input to, or
38
 *     `null` to use the document's active element.
39
 * @param {!Array.<string>} keys The keys to type on the element.
40
 * @param {bot.Keyboard.State=} opt_state The predefined keyboard state to use.
41
 * @param {boolean=} opt_persistModifiers Whether modifier keys should remain
42
 *     pressed when this function ends.
43
 * @return {bot.Keyboard.State} The keyboard state.
44
 */
45
webdriver.atoms.inputs.sendKeys = function(
46
    element, keys, opt_state, opt_persistModifiers) {
47
  var keyboard = new bot.Keyboard(opt_state);
48
  if (!element) {
49
    element = bot.dom.getActiveElement(document);
50
  }
51
  if (!element) {
52
    throw Error('No element to send keys to');
53
  }
54
  webdriver.atoms.element.type(element, keys, keyboard, opt_persistModifiers);
55

56
  return keyboard.getState();
57
};
58

59

60
/**
61
 * Click on an element.
62
 *
63
 * @param {?Element} element The element to click.
64
 * @param {bot.Mouse.State=} opt_state The serialized state of the mouse.
65
 * @return {!bot.Mouse.State} The mouse state.
66
 */
67
webdriver.atoms.inputs.click = function(element, opt_state) {
68
  var mouse = new bot.Mouse(opt_state);
69
  if (!element) {
70
    element = mouse.getState().element;
71
  }
72
  if (!element) {
73
    throw Error('No element to send keys to');
74
  }
75
  bot.action.click(element, null, mouse);
76
  return mouse.getState();
77
};
78

79

80
/**
81
 * Move the mouse to a specific element and/or coordinate location.
82
 *
83
 * @param {?Element} element The element to move the mouse to.
84
 * @param {?number} xOffset The x coordinate to use as an offset.
85
 * @param {?number} yOffset The y coordinate to use as an offset.
86
 * @param {bot.Mouse.State=} opt_state The serialized state of the mouse.
87
 * @return {!bot.Mouse.State} The mouse state.
88
 * @suppress {reportUnknownTypes}
89
 */
90
webdriver.atoms.inputs.mouseMove = function(element, xOffset, yOffset,
91
    opt_state) {
92
  var mouse = new bot.Mouse(opt_state);
93
  var target = element || mouse.getState()['element'];
94

95
  var offsetSpecified = (xOffset != null) && (yOffset != null);
96
  xOffset = xOffset || 0;
97
  yOffset = yOffset || 0;
98

99
  // If we have specified an element and no offset, we should
100
  // move the mouse to the center of the specified element.
101
  if (element) {
102
    if (!offsetSpecified) {
103
      var size = bot.action.getInteractableSize(element);
104
      xOffset = Math.floor(size.width / 2);
105
      yOffset = Math.floor(size.height / 2);
106
    }
107
  } else {
108
    // Moving to an absolute offset from the current target element,
109
    // so we have to account for the existing offset of the current
110
    // mouse position to the element origin (upper-left corner).
111
    var pos = goog.style.getClientPosition(target);
112
    xOffset += (mouse.getState()['clientXY']['x'] - pos.x);
113
    yOffset += (mouse.getState()['clientXY']['y'] - pos.y);
114
  }
115

116
  var doc = goog.dom.getOwnerDocument(target);
117
  goog.dom.getWindow(doc);
118
  bot.action.scrollIntoView(
119
      target, new goog.math.Coordinate(xOffset, yOffset));
120

121
  var coords = new goog.math.Coordinate(xOffset, yOffset);
122
  mouse.move(target, coords);
123
  return mouse.getState();
124
};
125

126

127
/**
128
 * Presses the primary mouse button at the current location.
129
 *
130
 * @param {bot.Mouse.State=} opt_state The serialized state of the mouse.
131
 * @return {!bot.Mouse.State} The mouse state.
132
 */
133
webdriver.atoms.inputs.mouseButtonDown = function(opt_state) {
134
  var mouse = new bot.Mouse(opt_state);
135
  mouse.pressButton(bot.Mouse.Button.LEFT);
136
  return mouse.getState();
137
};
138

139

140
/**
141
 * Releases the primary mouse button at the current location.
142
 *
143
 * @param {bot.Mouse.State=} opt_state The serialized state of the mouse.
144
 * @return {!bot.Mouse.State} The mouse state.
145
 */
146
webdriver.atoms.inputs.mouseButtonUp = function(opt_state) {
147
  var mouse = new bot.Mouse(opt_state);
148
  mouse.releaseButton();
149
  return mouse.getState();
150
};
151

152

153
/**
154
 * Double-clicks primary mouse button at the current location.
155
 *
156
 * @param {bot.Mouse.State=} opt_state The state of the mouse.
157
 * @return {!bot.Mouse.State} The mouse state.
158
 */
159
webdriver.atoms.inputs.doubleClick = function(opt_state) {
160
  var mouse = new bot.Mouse(opt_state);
161
  mouse.pressButton(bot.Mouse.Button.LEFT);
162
  mouse.releaseButton();
163
  mouse.pressButton(bot.Mouse.Button.LEFT);
164
  mouse.releaseButton();
165
  return mouse.getState();
166
};
167

168

169
/**
170
 * Right-clicks mouse button at the current location.
171
 *
172
 * @param {bot.Mouse.State=} opt_state The serialized state of the mouse.
173
 * @return {!bot.Mouse.State} The mouse state.
174
 * @deprecated Use {@link webdriver.atoms.inputs.mouseClick}.
175
 */
176
webdriver.atoms.inputs.rightClick = function(opt_state) {
177
  var mouse = new bot.Mouse(opt_state);
178
  mouse.pressButton(bot.Mouse.Button.RIGHT);
179
  mouse.releaseButton();
180
  return mouse.getState();
181
};
182

183

184
/**
185
 * Executes a mousedown/up with the given button at the current mouse
186
 * location.
187
 *
188
 * @param {bot.Mouse.Button} button The button to press.
189
 * @param {bot.Mouse.State=} opt_state The state of the mouse.
190
 * @return {!bot.Mouse.State} The mouse state.
191
 * @suppress {reportUnknownTypes}
192
 */
193
webdriver.atoms.inputs.mouseClick = function(button, opt_state) {
194
  // If no target element is specified, try to find it from the
195
  // client (x, y) location. No, this is not exact.
196
  if (opt_state && opt_state['clientXY'] && !opt_state['element'] &&
197
      document.elementFromPoint) {
198
    opt_state['element'] = document.elementFromPoint(
199
        opt_state['clientXY']['x'], opt_state['clientXY']['y']);
200
  }
201
  var mouse = new bot.Mouse(opt_state);
202
  mouse.pressButton(button);
203
  mouse.releaseButton();
204
  return mouse.getState();
205
};
206

207