| // Licensed to the Software Freedom Conservancy (SFC) under one | |
| // or more contributor license agreements. See the NOTICE file | |
| // distributed with this work for additional information | |
| // regarding copyright ownership. The SFC licenses this file | |
| // to you under the Apache License, Version 2.0 (the | |
| // "License"); you may not use this file except in compliance | |
| // with the License. You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, | |
| // software distributed under the License is distributed on an | |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| // KIND, either express or implied. See the License for the | |
| // specific language governing permissions and limitations | |
| // under the License. | |
| /** | |
| * @fileoverview The file contains an abstraction of a mouse for | |
| * simulating the mouse actions. | |
| */ | |
| goog.provide('bot.Mouse'); | |
| goog.provide('bot.Mouse.Button'); | |
| goog.require('bot'); | |
| goog.require('bot.Device'); | |
| goog.require('bot.Error'); | |
| goog.require('bot.ErrorCode'); | |
| goog.require('bot.dom'); | |
| goog.require('bot.events'); | |
| goog.require('bot.userAgent'); | |
| goog.require('goog.dom'); | |
| goog.require('goog.dom.TagName'); | |
| goog.require('goog.math.Coordinate'); | |
| goog.require('goog.userAgent'); | |
| goog.require('goog.utils'); | |
| /** | |
| * A mouse that provides atomic mouse actions. This mouse currently only | |
| * supports having one button pressed at a time. | |
| * @param {bot.Mouse.State=} opt_state The mouse's initial state. | |
| * @param {bot.Device.ModifiersState=} opt_modifiersState State of the keyboard. | |
| * @param {bot.Device.EventEmitter=} opt_eventEmitter An object that should be | |
| * used to fire events. | |
| * @constructor | |
| * @extends {bot.Device} | |
| */ | |
| bot.Mouse = function (opt_state, opt_modifiersState, opt_eventEmitter) { | |
| bot.Device.call(this, opt_modifiersState, opt_eventEmitter); | |
| /** @private {?bot.Mouse.Button} */ | |
| this.buttonPressed_ = null; | |
| /** @private {Element} */ | |
| this.elementPressed_ = null; | |
| /** @private {!goog.math.Coordinate} */ | |
| this.clientXY_ = new goog.math.Coordinate(0, 0); | |
| /** @private {boolean} */ | |
| this.nextClickIsDoubleClick_ = false; | |
| /** | |
| * Whether this Mouse has ever explicitly interacted with any element. | |
| * @private {boolean} | |
| */ | |
| this.hasEverInteracted_ = false; | |
| if (opt_state) { | |
| if (typeof opt_state['buttonPressed'] === 'number') { | |
| this.buttonPressed_ = opt_state['buttonPressed']; | |
| } | |
| try { | |
| if (bot.dom.isElement(opt_state['elementPressed'])) { | |
| this.elementPressed_ = opt_state['elementPressed']; | |
| } | |
| } catch (ignored) { | |
| this.buttonPressed_ = null; | |
| } | |
| this.clientXY_ = new goog.math.Coordinate( | |
| opt_state['clientXY']['x'], | |
| opt_state['clientXY']['y']); | |
| this.nextClickIsDoubleClick_ = !!opt_state['nextClickIsDoubleClick']; | |
| this.hasEverInteracted_ = !!opt_state['hasEverInteracted']; | |
| try { | |
| if (opt_state['element'] && bot.dom.isElement(opt_state['element'])) { | |
| this.setElement(/** @type {!Element} */(opt_state['element'])); | |
| } | |
| } catch (ignored) { | |
| this.buttonPressed_ = null; | |
| } | |
| } | |
| }; | |
| goog.utils.inherits(bot.Mouse, bot.Device); | |
| /** | |
| * Describes the state of the mouse. This type should be treated as a | |
| * dictionary with all properties accessed using array notation to | |
| * ensure properties are not renamed by the compiler. | |
| * @typedef {{buttonPressed: ?bot.Mouse.Button, | |
| * elementPressed: Element, | |
| * clientXY: {x: number, y: number}, | |
| * nextClickIsDoubleClick: boolean, | |
| * hasEverInteracted: boolean, | |
| * element: Element}} | |
| */ | |
| bot.Mouse.State; | |
| /** | |
| * Enumeration of mouse buttons that can be pressed. | |
| * | |
| * @enum {number} | |
| */ | |
| bot.Mouse.Button = { | |
| LEFT: 0, | |
| MIDDLE: 1, | |
| RIGHT: 2 | |
| }; | |
| /** | |
| * Index to indicate no button pressed in bot.Mouse.MOUSE_BUTTON_VALUE_MAP_. | |
| * @private {number} | |
| * @const | |
| */ | |
| bot.Mouse.NO_BUTTON_VALUE_INDEX_ = 3; | |
| /** | |
| * Maps mouse events to an array of button argument value for each mouse button. | |
| * The array is indexed by the bot.Mouse.Button values. It encodes this table, | |
| * where each cell contains the (left/middle/right/none) button values. | |
| * <pre> | |
| * click/ mouseup/ mouseout/ mousemove contextmenu | |
| * dblclick mousedown mouseover | |
| * IE_DOC_PRE9 0 0 0 X 1 4 2 X 0 0 0 0 1 4 2 0 X X 0 X | |
| * WEBKIT/IE9 0 1 2 X 0 1 2 X 0 1 2 0 0 1 2 0 X X 2 X | |
| * GECKO 0 1 2 X 0 1 2 X 0 0 0 0 0 0 0 0 X X 2 X | |
| * </pre> | |
| * @private {!Object<?, !Array.<?number>>} | |
| * @const | |
| */ | |
| bot.Mouse.MOUSE_BUTTON_VALUE_MAP_ = (function () { | |
| // EventTypes can safely be used as keys without collisions in a JS Object, | |
| // because its toString method returns a unique string (the event type name). | |
| var buttonValueMap = {}; | |
| if (bot.userAgent.IE_DOC_PRE9) { | |
| buttonValueMap[bot.events.EventType.CLICK] = [0, 0, 0, null]; | |
| buttonValueMap[bot.events.EventType.CONTEXTMENU] = [null, null, 0, null]; | |
| buttonValueMap[bot.events.EventType.MOUSEUP] = [1, 4, 2, null]; | |
| buttonValueMap[bot.events.EventType.MOUSEOUT] = [0, 0, 0, 0]; | |
| buttonValueMap[bot.events.EventType.MOUSEMOVE] = [1, 4, 2, 0]; | |
| } else if (goog.userAgent.WEBKIT || bot.userAgent.IE_DOC_9) { | |
| buttonValueMap[bot.events.EventType.CLICK] = [0, 1, 2, null]; | |
| buttonValueMap[bot.events.EventType.CONTEXTMENU] = [null, null, 2, null]; | |
| buttonValueMap[bot.events.EventType.MOUSEUP] = [0, 1, 2, null]; | |
| buttonValueMap[bot.events.EventType.MOUSEOUT] = [0, 1, 2, 0]; | |
| buttonValueMap[bot.events.EventType.MOUSEMOVE] = [0, 1, 2, 0]; | |
| } else { | |
| buttonValueMap[bot.events.EventType.CLICK] = [0, 1, 2, null]; | |
| buttonValueMap[bot.events.EventType.CONTEXTMENU] = [null, null, 2, null]; | |
| buttonValueMap[bot.events.EventType.MOUSEUP] = [0, 1, 2, null]; | |
| buttonValueMap[bot.events.EventType.MOUSEOUT] = [0, 0, 0, 0]; | |
| buttonValueMap[bot.events.EventType.MOUSEMOVE] = [0, 0, 0, 0]; | |
| } | |
| if (bot.userAgent.IE_DOC_10) { | |
| buttonValueMap[bot.events.EventType.MSPOINTERDOWN] = | |
| buttonValueMap[bot.events.EventType.MOUSEUP]; | |
| buttonValueMap[bot.events.EventType.MSPOINTERUP] = | |
| buttonValueMap[bot.events.EventType.MOUSEUP]; | |
| buttonValueMap[bot.events.EventType.MSPOINTERMOVE] = [-1, -1, -1, -1]; | |
| buttonValueMap[bot.events.EventType.MSPOINTEROUT] = | |
| buttonValueMap[bot.events.EventType.MSPOINTERMOVE]; | |
| buttonValueMap[bot.events.EventType.MSPOINTEROVER] = | |
| buttonValueMap[bot.events.EventType.MSPOINTERMOVE]; | |
| } | |
| buttonValueMap[bot.events.EventType.DBLCLICK] = | |
| buttonValueMap[bot.events.EventType.CLICK]; | |
| buttonValueMap[bot.events.EventType.MOUSEDOWN] = | |
| buttonValueMap[bot.events.EventType.MOUSEUP]; | |
| buttonValueMap[bot.events.EventType.MOUSEOVER] = | |
| buttonValueMap[bot.events.EventType.MOUSEOUT]; | |
| return buttonValueMap; | |
| })(); | |
| /** | |
| * Maps mouse events to corresponding MSPointer event. | |
| * @private {!Object<?, !bot.events.EventFactory_>} | |
| */ | |
| bot.Mouse.MOUSE_EVENT_MAP_ = (function () { | |
| var map = {}; | |
| map[bot.events.EventType.MOUSEDOWN] = bot.events.EventType.MSPOINTERDOWN; | |
| map[bot.events.EventType.MOUSEMOVE] = bot.events.EventType.MSPOINTERMOVE; | |
| map[bot.events.EventType.MOUSEOUT] = bot.events.EventType.MSPOINTEROUT; | |
| map[bot.events.EventType.MOUSEOVER] = bot.events.EventType.MSPOINTEROVER; | |
| map[bot.events.EventType.MOUSEUP] = bot.events.EventType.MSPOINTERUP; | |
| return map; | |
| })(); | |
| /** | |
| * Attempts to fire a mousedown event and then returns whether or not the | |
| * element should receive focus as a result of the mousedown. | |
| * | |
| * @param {?number=} opt_count Number of clicks that have been performed. | |
| * @return {boolean} Whether to focus on the element after the mousedown. | |
| * @private | |
| */ | |
| bot.Mouse.prototype.fireMousedown_ = function (opt_count) { | |
| // On some browsers, a mouse down event on an OPTION or SELECT element cause | |
| // the SELECT to open, blocking further JS execution. This is undesirable, | |
| // and so needs to be detected. We always focus in this case. | |
| // TODO: This is a nasty way to avoid locking the browser | |
| var isFirefox3 = goog.userAgent.GECKO && !bot.userAgent.isProductVersion(4); | |
| var blocksOnMousedown = (goog.userAgent.WEBKIT || isFirefox3) && | |
| (bot.dom.isElement(this.getElement(), goog.dom.TagName.OPTION) || | |
| bot.dom.isElement(this.getElement(), goog.dom.TagName.SELECT)); | |
| if (blocksOnMousedown) { | |
| return true; | |
| } | |
| // On some browsers, if the mousedown event handler makes a focus() call to | |
| // change the active element, this preempts the focus that would happen by | |
| // default on the mousedown, so we should not explicitly focus in this case. | |
| var beforeActiveElement; | |
| var mousedownCanPreemptFocus = goog.userAgent.GECKO || goog.userAgent.IE; | |
| if (mousedownCanPreemptFocus) { | |
| beforeActiveElement = bot.dom.getActiveElement(this.getElement()); | |
| } | |
| var performFocus = this.fireMouseEvent_(bot.events.EventType.MOUSEDOWN, null, null, false, opt_count); | |
| if (performFocus && mousedownCanPreemptFocus && | |
| beforeActiveElement != bot.dom.getActiveElement(this.getElement())) { | |
| return false; | |
| } | |
| return performFocus; | |
| }; | |
| /** | |
| * Press a mouse button on an element that the mouse is interacting with. | |
| * | |
| * @param {!bot.Mouse.Button} button Button. | |
| * @param {?number=} opt_count Number of clicks that have been performed. | |
| */ | |
| bot.Mouse.prototype.pressButton = function (button, opt_count) { | |
| if (this.buttonPressed_ !== null) { | |
| throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR, | |
| 'Cannot press more than one button or an already pressed button.'); | |
| } | |
| this.buttonPressed_ = button; | |
| this.elementPressed_ = this.getElement(); | |
| var performFocus = this.fireMousedown_(opt_count); | |
| if (performFocus) { | |
| if (bot.userAgent.IE_DOC_10 && | |
| this.buttonPressed_ == bot.Mouse.Button.LEFT && | |
| bot.dom.isElement(this.elementPressed_, goog.dom.TagName.OPTION)) { | |
| this.fireMSPointerEvent(bot.events.EventType.MSGOTPOINTERCAPTURE, | |
| this.clientXY_, 0, bot.Device.MOUSE_MS_POINTER_ID, | |
| MSPointerEvent.MSPOINTER_TYPE_MOUSE, true); | |
| } | |
| this.focusOnElement(); | |
| } | |
| }; | |
| /** | |
| * Releases the pressed mouse button. Throws exception if no button pressed. | |
| * | |
| * @param {boolean=} opt_force Whether the event should be fired even if the | |
| * element is not interactable. | |
| * @param {?number=} opt_count Number of clicks that have been performed. | |
| */ | |
| bot.Mouse.prototype.releaseButton = function (opt_force, opt_count) { | |
| if (this.buttonPressed_ === null) { | |
| throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR, | |
| 'Cannot release a button when no button is pressed.'); | |
| } | |
| this.maybeToggleOption(); | |
| // If a mouseup event is dispatched to an interactable event, and that mouseup | |
| // would complete a click, then the click event must be dispatched even if the | |
| // element becomes non-interactable after the mouseup. | |
| var elementInteractableBeforeMouseup = | |
| bot.dom.isInteractable(this.getElement()); | |
| this.fireMouseEvent_(bot.events.EventType.MOUSEUP, null, null, opt_force, opt_count); | |
| try { // https://github.com/SeleniumHQ/selenium/issues/1509 | |
| // TODO: Middle button can also trigger click. | |
| if (this.buttonPressed_ == bot.Mouse.Button.LEFT && | |
| this.getElement() == this.elementPressed_) { | |
| if (!(bot.userAgent.WINDOWS_PHONE && | |
| bot.dom.isElement(this.elementPressed_, goog.dom.TagName.OPTION))) { | |
| this.clickElement(this.clientXY_, | |
| this.getButtonValue_(bot.events.EventType.CLICK), | |
| /* opt_force */ elementInteractableBeforeMouseup); | |
| } | |
| this.maybeDoubleClickElement_(); | |
| if (bot.userAgent.IE_DOC_10 && | |
| this.buttonPressed_ == bot.Mouse.Button.LEFT && | |
| bot.dom.isElement(this.elementPressed_, goog.dom.TagName.OPTION)) { | |
| this.fireMSPointerEvent(bot.events.EventType.MSLOSTPOINTERCAPTURE, | |
| new goog.math.Coordinate(0, 0), 0, bot.Device.MOUSE_MS_POINTER_ID, | |
| MSPointerEvent.MSPOINTER_TYPE_MOUSE, false); | |
| } | |
| // TODO: In Linux, this fires after mousedown event. | |
| } else if (this.buttonPressed_ == bot.Mouse.Button.RIGHT) { | |
| this.fireMouseEvent_(bot.events.EventType.CONTEXTMENU); | |
| } | |
| } catch (ignored) { | |
| } | |
| bot.Device.clearPointerMap(); | |
| this.buttonPressed_ = null; | |
| this.elementPressed_ = null; | |
| }; | |
| /** | |
| * A helper function to fire mouse double click events. | |
| * | |
| * @private | |
| */ | |
| bot.Mouse.prototype.maybeDoubleClickElement_ = function () { | |
| // Trigger an additional double click event if it is the second click. | |
| if (this.nextClickIsDoubleClick_) { | |
| this.fireMouseEvent_(bot.events.EventType.DBLCLICK); | |
| } | |
| this.nextClickIsDoubleClick_ = !this.nextClickIsDoubleClick_; | |
| }; | |
| /** | |
| * Given a coordinates (x,y) related to an element, move mouse to (x,y) of the | |
| * element. The top-left point of the element is (0,0). | |
| * | |
| * @param {!Element} element The destination element. | |
| * @param {!goog.math.Coordinate} coords Mouse position related to the target. | |
| */ | |
| bot.Mouse.prototype.move = function (element, coords) { | |
| // If the element is interactable at the start of the move, it receives the | |
| // full event sequence, even if hidden by an element mid sequence. | |
| var toElemWasInteractable = bot.dom.isInteractable(element); | |
| var rect = bot.dom.getClientRect(element); | |
| this.clientXY_.x = coords.x + rect.left; | |
| this.clientXY_.y = coords.y + rect.top; | |
| var fromElement = this.getElement(); | |
| if (element != fromElement) { | |
| // If the window of fromElement is closed, set fromElement to null as a flag | |
| // to skip the mouseout event and so relatedTarget of the mouseover is null. | |
| try { | |
| if (goog.dom.getWindow(goog.dom.getOwnerDocument(fromElement)).closed) { | |
| fromElement = null; | |
| } | |
| } catch (ignore) { | |
| // Sometimes accessing a window that no longer exists causes an error. | |
| fromElement = null; | |
| } | |
| if (fromElement) { | |
| // For the first mouse interaction on a page, if the mouse was over the | |
| // browser window, the browser will pass null as the relatedTarget for the | |
| // mouseover event. For subsequent interactions, it will pass the | |
| // last-focused element. Unfortunately, we don't have anywhere to keep the | |
| // state of which elements have been focused across Mouse instances, so we | |
| // treat every Mouse initially positioned over the documentElement or body | |
| // as if it's on a new page. Accordingly, for complex actions (e.g. | |
| // drag-and-drop), a single Mouse instance should be used for the whole | |
| // action, to ensure the correct relatedTargets are fired for any events. | |
| var isRoot = fromElement === bot.getDocument().documentElement || | |
| fromElement === bot.getDocument().body; | |
| fromElement = (!this.hasEverInteracted_ && isRoot) ? null : fromElement; | |
| this.fireMouseEvent_(bot.events.EventType.MOUSEOUT, element); | |
| } | |
| this.setElement(element); | |
| // All browsers except IE fire the mouseover before the mousemove. | |
| if (!goog.userAgent.IE) { | |
| this.fireMouseEvent_(bot.events.EventType.MOUSEOVER, fromElement, null, | |
| toElemWasInteractable); | |
| } | |
| } | |
| this.fireMouseEvent_(bot.events.EventType.MOUSEMOVE, null, null, | |
| toElemWasInteractable); | |
| // IE fires the mouseover event after the mousemove. | |
| if (goog.userAgent.IE && element != fromElement) { | |
| this.fireMouseEvent_(bot.events.EventType.MOUSEOVER, fromElement, null, | |
| toElemWasInteractable); | |
| } | |
| this.nextClickIsDoubleClick_ = false; | |
| }; | |
| /** | |
| * Scrolls the wheel of the mouse by the given number of ticks, where a positive | |
| * number indicates a downward scroll and a negative is upward scroll. | |
| * | |
| * @param {number} ticks Number of ticks to scroll the mouse wheel. | |
| */ | |
| bot.Mouse.prototype.scroll = function (ticks) { | |
| if (ticks == 0) { | |
| throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR, | |
| 'Must scroll a non-zero number of ticks.'); | |
| } | |
| // The wheelDelta value for a single up-tick of the mouse wheel is 120, and | |
| // a single down-tick is -120. The deltas in pixels (which is only relevant | |
| // for Firefox) appears to be -57 and 57, respectively. | |
| var wheelDelta = ticks > 0 ? -120 : 120; | |
| var pixelDelta = ticks > 0 ? 57 : -57; | |
| // Browsers fire a separate event (or pair of events in Gecko) for each tick. | |
| for (var i = 0; i < Math.abs(ticks); i++) { | |
| this.fireMouseEvent_(bot.events.EventType.MOUSEWHEEL, null, wheelDelta); | |
| if (goog.userAgent.GECKO) { | |
| this.fireMouseEvent_(bot.events.EventType.MOUSEPIXELSCROLL, null, | |
| pixelDelta); | |
| } | |
| } | |
| }; | |
| /** | |
| * A helper function to fire mouse events. | |
| * | |
| * @param {!bot.events.EventFactory_} type Event type. | |
| * @param {Element=} opt_related The related element of this event. | |
| * @param {?number=} opt_wheelDelta The wheel delta value for the event. | |
| * @param {boolean=} opt_force Whether the event should be fired even if the | |
| * element is not interactable. | |
| * @param {?number=} opt_count Number of clicks that have been performed. | |
| * @return {boolean} Whether the event fired successfully or was cancelled. | |
| * @private | |
| */ | |
| bot.Mouse.prototype.fireMouseEvent_ = function (type, opt_related, | |
| opt_wheelDelta, opt_force, opt_count) { | |
| this.hasEverInteracted_ = true; | |
| if (bot.userAgent.IE_DOC_10) { | |
| var msPointerEvent = bot.Mouse.MOUSE_EVENT_MAP_[type]; | |
| if (msPointerEvent) { | |
| // The pointerId for mouse events is always 1 and the mouse event is never | |
| // fired if the MSPointer event fails. | |
| if (!this.fireMSPointerEvent(msPointerEvent, this.clientXY_, | |
| this.getButtonValue_(msPointerEvent), bot.Device.MOUSE_MS_POINTER_ID, | |
| MSPointerEvent.MSPOINTER_TYPE_MOUSE, /* isPrimary */ true, | |
| opt_related, opt_force)) { | |
| return false; | |
| } | |
| } | |
| } | |
| return this.fireMouseEvent(type, this.clientXY_, | |
| this.getButtonValue_(type), opt_related, opt_wheelDelta, opt_force, null, opt_count); | |
| }; | |
| /** | |
| * Given an event type and a mouse button, sets the mouse button value used | |
| * for that event on the current browser. The mouse button value is 0 for any | |
| * event not covered by bot.Mouse.MOUSE_BUTTON_VALUE_MAP_. | |
| * | |
| * @param {!bot.events.EventFactory_} eventType Type of mouse event. | |
| * @return {number} The mouse button ID value to the current browser. | |
| * @private | |
| */ | |
| bot.Mouse.prototype.getButtonValue_ = function (eventType) { | |
| if (!(eventType in bot.Mouse.MOUSE_BUTTON_VALUE_MAP_)) { | |
| return 0; | |
| } | |
| var buttonIndex = this.buttonPressed_ === null ? | |
| bot.Mouse.NO_BUTTON_VALUE_INDEX_ : this.buttonPressed_; | |
| var buttonValue = bot.Mouse.MOUSE_BUTTON_VALUE_MAP_[eventType][buttonIndex]; | |
| if (buttonValue === null) { | |
| throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR, | |
| 'Event does not permit the specified mouse button.'); | |
| } | |
| return buttonValue; | |
| }; | |
| /** | |
| * Serialize the current state of the mouse. | |
| * @return {!bot.Mouse.State} The current mouse state. | |
| */ | |
| bot.Mouse.prototype.getState = function () { | |
| // Need to use quoted literals here, so the compiler will not rename the | |
| // properties of the emitted object. When the object is created via the | |
| // "constructor", we will look for these *specific* properties. Everywhere | |
| // else internally, we use the dot-notation, so it's okay if the compiler | |
| // renames the internal variable name. | |
| return { | |
| 'buttonPressed': this.buttonPressed_, | |
| 'elementPressed': this.elementPressed_, | |
| 'clientXY': { 'x': this.clientXY_.x, 'y': this.clientXY_.y }, | |
| 'nextClickIsDoubleClick': this.nextClickIsDoubleClick_, | |
| 'hasEverInteracted': this.hasEverInteracted_, | |
| 'element': this.getElement() | |
| }; | |
| }; |