touchscreen.js

// 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 touch screen
 * for simulating atomic touchscreen actions.
 */

goog.provide('bot.Touchscreen');

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.TagName');
goog.require('goog.math.Coordinate');
goog.require('goog.userAgent.product');
goog.require('goog.utils');



/**
 * A TouchScreen that provides atomic touch actions.  The metaphor
 * for this abstraction is a finger moving above the touchscreen that
 * can press and then release the touchscreen when specified.
 *
 * The touchscreen supports three actions: press, release, and move.
 *
 * @constructor
 * @extends {bot.Device}
 */
bot.Touchscreen = function () {
  bot.Device.call(this);

  /** @private {!goog.math.Coordinate} */
  this.clientXY_ = new goog.math.Coordinate(0, 0);

  /** @private {!goog.math.Coordinate} */
  this.clientXY2_ = new goog.math.Coordinate(0, 0);
};
goog.utils.inherits(bot.Touchscreen, bot.Device);


/** @private {boolean} */
bot.Touchscreen.prototype.fireMouseEventsOnRelease_ = true;


/** @private {boolean} */
bot.Touchscreen.prototype.cancelled_ = false;


/** @private {number} */
bot.Touchscreen.prototype.touchIdentifier_ = 0;


/** @private {number} */
bot.Touchscreen.prototype.touchIdentifier2_ = 0;


/** @private {number} */
bot.Touchscreen.prototype.touchCounter_ = 2;


/**
 * Press the touch screen.  Pressing before moving results in an exception.
 * Pressing while already pressed also results in an exception.
 *
 * @param {boolean=} opt_press2 Whether or not press the second finger during
 *     the press.  If not defined or false, only the primary finger will be
 *     pressed.
 */
bot.Touchscreen.prototype.press = function (opt_press2) {
  if (this.isPressed()) {
    throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR,
      'Cannot press touchscreen when already pressed.');
  }

  this.touchIdentifier_ = this.touchCounter_++;
  if (opt_press2) {
    this.touchIdentifier2_ = this.touchCounter_++;
  }

  if (bot.userAgent.IE_DOC_10) {
    this.fireMouseEventsOnRelease_ = true;
    this.firePointerEvents_(bot.Touchscreen.fireSinglePressPointer_);
  } else {
    this.fireMouseEventsOnRelease_ = this.fireTouchEvent_(
      bot.events.EventType.TOUCHSTART);
  }
};


/**
 * Releases an element on a touchscreen.  Releasing an element that is not
 * pressed results in an exception.
 */
bot.Touchscreen.prototype.release = function () {
  if (!this.isPressed()) {
    throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR,
      'Cannot release touchscreen when not already pressed.');
  }

  if (!bot.userAgent.IE_DOC_10) {
    this.fireTouchReleaseEvents_();
  } else if (!this.cancelled_) {
    this.firePointerEvents_(bot.Touchscreen.fireSingleReleasePointer_);
  }
  bot.Device.clearPointerMap();
  this.touchIdentifier_ = 0;
  this.touchIdentifier2_ = 0;
  this.cancelled_ = false;
};


/**
 * Moves finger along the touchscreen.
 *
 * @param {!Element} element Element that is being pressed.
 * @param {!goog.math.Coordinate} coords Coordinates relative to
 *   currentElement.
 * @param {goog.math.Coordinate=} opt_coords2 Coordinates relative to
 *   currentElement.
 */
bot.Touchscreen.prototype.move = function (element, coords, opt_coords2) {
  // The target element for touch actions is the original element. Hence, the
  // element is set only when the touchscreen is not currently being pressed.
  // The exception is IE10 which fire events on the moved to element.
  var originalElement = this.getElement();
  if (!this.isPressed() || bot.userAgent.IE_DOC_10) {
    this.setElement(element);
  }

  var rect = bot.dom.getClientRect(element);
  this.clientXY_.x = coords.x + rect.left;
  this.clientXY_.y = coords.y + rect.top;

  if (opt_coords2 !== undefined) {
    this.clientXY2_.x = opt_coords2.x + rect.left;
    this.clientXY2_.y = opt_coords2.y + rect.top;
  }

  if (this.isPressed()) {
    if (!bot.userAgent.IE_DOC_10) {
      this.fireMouseEventsOnRelease_ = false;
      this.fireTouchEvent_(bot.events.EventType.TOUCHMOVE);
    } else if (!this.cancelled_) {
      if (element != originalElement) {
        this.fireMouseEventsOnRelease_ = false;
      }
      if (bot.Touchscreen.hasMsTouchActionsEnabled_(element)) {
        this.firePointerEvents_(bot.Touchscreen.fireSingleMovePointer_);
      } else {
        this.fireMSPointerEvent(bot.events.EventType.MSPOINTEROUT, coords, -1,
          this.touchIdentifier_, MSPointerEvent.MSPOINTER_TYPE_TOUCH, true);
        this.fireMouseEvent(bot.events.EventType.MOUSEOUT, coords, 0);
        this.fireMSPointerEvent(bot.events.EventType.MSPOINTERCANCEL, coords, 0,
          this.touchIdentifier_, MSPointerEvent.MSPOINTER_TYPE_TOUCH, true);
        this.cancelled_ = true;
        bot.Device.clearPointerMap();
      }
    }
  }
};


/**
 * Returns whether the touchscreen is currently pressed.
 *
 * @return {boolean} Whether the touchscreen is pressed.
 */
bot.Touchscreen.prototype.isPressed = function () {
  return !!this.touchIdentifier_;
};


/**
 * A helper function to fire touch events.
 *
 * @param {!bot.events.EventFactory_} type Event type.
 * @return {boolean} Whether the event fired successfully or was cancelled.
 * @private
 */
bot.Touchscreen.prototype.fireTouchEvent_ = function (type) {
  if (!this.isPressed()) {
    throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR,
      'Should never fire event when touchscreen is not pressed.');
  }
  var touchIdentifier2;
  var coords2;
  if (this.touchIdentifier2_) {
    touchIdentifier2 = this.touchIdentifier2_;
    coords2 = this.clientXY2_;
  }
  return this.fireTouchEvent(type, this.touchIdentifier_, this.clientXY_,
    touchIdentifier2, coords2);
};


/**
 * A helper function to fire touch events that occur on a release.
 *
 * @private
 */
bot.Touchscreen.prototype.fireTouchReleaseEvents_ = function () {
  var touchendSuccess = this.fireTouchEvent_(bot.events.EventType.TOUCHEND);

  // In general, TouchScreen.Release will fire the legacy mouse events:
  // mousemove, mousedown, mouseup, and click after the touch events have been
  // fired. The click button should be zero and only one mousemove should fire.
  // Under the following cases, mouse events should not be fired:
  // 1. Movement has occurred since press.
  // 2. Any event handler for touchstart has called preventDefault().
  // 3. Any event handler for touchend has called preventDefault(), and browser
  // is Mobile Safari or Chrome.
  var fireMouseEvents =
    this.fireMouseEventsOnRelease_ &&
    (touchendSuccess || !(bot.userAgent.IOS ||
      goog.userAgent.product.CHROME));

  if (fireMouseEvents) {
    this.fireMouseEvent(bot.events.EventType.MOUSEMOVE, this.clientXY_, 0);
    var performFocus = this.fireMouseEvent(bot.events.EventType.MOUSEDOWN,
      this.clientXY_, 0);
    // Element gets focus after the mousedown event only if the mousedown was
    // not cancelled.
    if (performFocus) {
      this.focusOnElement();
    }
    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, this.clientXY_, 0);

    // Special click logic to follow links and to perform form actions.
    if (!(bot.userAgent.WINDOWS_PHONE &&
      bot.dom.isElement(this.getElement(), goog.dom.TagName.OPTION))) {
      this.clickElement(this.clientXY_,
                         /* button */ 0,
                         /* opt_force */ elementInteractableBeforeMouseup);
    }
  }
};


/**
 * A helper function to fire a sequence of Pointer events.
 * @param {function(!bot.Touchscreen, !Element, !goog.math.Coordinate, number,
 *     boolean)} fireSinglePointer A function that fires a set of events for one
 *     finger.
 * @private
 */
bot.Touchscreen.prototype.firePointerEvents_ = function (fireSinglePointer) {
  fireSinglePointer(this, this.getElement(), this.clientXY_,
    this.touchIdentifier_, true);
  if (this.touchIdentifier2_ &&
    bot.Touchscreen.hasMsTouchActionsEnabled_(this.getElement())) {
    fireSinglePointer(this, this.getElement(),
      this.clientXY2_, this.touchIdentifier2_, false);
  }
};


/**
 * A helper function to fire Pointer events related to a press.
 *
 * @param {!bot.Touchscreen} ts A touchscreen object.
 * @param {!Element} element Element that is being pressed.
 * @param {!goog.math.Coordinate} coords Coordinates relative to
 *   currentElement.
 * @param {number} id The touch identifier.
 * @param {boolean} isPrimary Whether the pointer represents the primary point
 *     of contact.
 * @private
 */
bot.Touchscreen.fireSinglePressPointer_ = function (ts, element, coords, id,
  isPrimary) {
  // Fire a mousemove event.
  ts.fireMouseEvent(bot.events.EventType.MOUSEMOVE, coords, 0);

  // Fire a MSPointerOver and mouseover events.
  ts.fireMSPointerEvent(bot.events.EventType.MSPOINTEROVER, coords, 0, id,
    MSPointerEvent.MSPOINTER_TYPE_TOUCH, isPrimary);
  ts.fireMouseEvent(bot.events.EventType.MOUSEOVER, coords, 0);

  // Fire a MSPointerDown and mousedown events.
  ts.fireMSPointerEvent(bot.events.EventType.MSPOINTERDOWN, coords, 0, id,
    MSPointerEvent.MSPOINTER_TYPE_TOUCH, isPrimary);

  // Element gets focus after the mousedown event.
  if (ts.fireMouseEvent(bot.events.EventType.MOUSEDOWN, coords, 0)) {
    // For selectable elements, IE 10 fires a MSGotPointerCapture event.
    if (bot.dom.isSelectable(element)) {
      ts.fireMSPointerEvent(bot.events.EventType.MSGOTPOINTERCAPTURE, coords, 0,
        id, MSPointerEvent.MSPOINTER_TYPE_TOUCH, isPrimary);
    }
    ts.focusOnElement();
  }
};


/**
 * A helper function to fire Pointer events related to a release.
 *
 * @param {!bot.Touchscreen} ts A touchscreen object.
 * @param {!Element} element Element that is being released.
 * @param {!goog.math.Coordinate} coords Coordinates relative to
 *   currentElement.
 * @param {number} id The touch identifier.
 * @param {boolean} isPrimary Whether the pointer represents the primary point
 *     of contact.
 * @private
 */
bot.Touchscreen.fireSingleReleasePointer_ = function (ts, element, coords, id,
  isPrimary) {
  // Fire a MSPointerUp and mouseup events.
  ts.fireMSPointerEvent(bot.events.EventType.MSPOINTERUP, coords, 0, id,
    MSPointerEvent.MSPOINTER_TYPE_TOUCH, isPrimary);

  // 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(ts.getElement());
  ts.fireMouseEvent(bot.events.EventType.MOUSEUP, coords, 0, null, 0, false,
    id);

  // Fire a click.
  if (ts.fireMouseEventsOnRelease_) {
    ts.maybeToggleOption();
    if (!(bot.userAgent.WINDOWS_PHONE &&
      bot.dom.isElement(element, goog.dom.TagName.OPTION))) {
      ts.clickElement(ts.clientXY_,
                      /* button */ 0,
                      /* opt_force */ elementInteractableBeforeMouseup,
        id);
    }
  }

  if (bot.dom.isSelectable(element)) {
    // For selectable elements, IE 10 fires a MSLostPointerCapture event.
    ts.fireMSPointerEvent(bot.events.EventType.MSLOSTPOINTERCAPTURE,
      new goog.math.Coordinate(0, 0), 0, id,
      MSPointerEvent.MSPOINTER_TYPE_TOUCH, false);
  }

  // Fire a MSPointerOut and mouseout events.
  ts.fireMSPointerEvent(bot.events.EventType.MSPOINTEROUT, coords, -1, id,
    MSPointerEvent.MSPOINTER_TYPE_TOUCH, isPrimary);
  ts.fireMouseEvent(bot.events.EventType.MOUSEOUT, coords, 0, null, 0, false,
    id);
};


/**
 * A helper function to fire Pointer events related to a move.
 *
 * @param {!bot.Touchscreen} ts A touchscreen object.
 * @param {!Element} element Element that is being moved.
 * @param {!goog.math.Coordinate} coords Coordinates relative to
 *   currentElement.
 * @param {number} id The touch identifier.
 * @param {boolean} isPrimary Whether the pointer represents the primary point
 *     of contact.
 * @private
 */
bot.Touchscreen.fireSingleMovePointer_ = function (ts, element, coords, id,
  isPrimary) {
  // Fire a MSPointerMove and mousemove events.
  ts.fireMSPointerEvent(bot.events.EventType.MSPOINTERMOVE, coords, -1, id,
    MSPointerEvent.MSPOINTER_TYPE_TOUCH, isPrimary);
  ts.fireMouseEvent(bot.events.EventType.MOUSEMOVE, coords, 0, null, 0, false,
    id);
};


/**
 * A function that determines whether an element can be manipulated by the user.
 * The msTouchAction style is queried and an element can be manipulated if the
 * style value is none. If an element cannot be manipulated, then move gestures
 * will result in a cancellation and multi-touch events will be prevented. Tap
 * gestures will still be allowed. If not on IE 10, the function returns true.
 *
 * @param {!Element} element The element being manipulated.
 * @return {boolean} Whether the element can be manipulated.
 * @private
 */
bot.Touchscreen.hasMsTouchActionsEnabled_ = function (element) {
  if (!bot.userAgent.IE_DOC_10) {
    throw new Error('hasMsTouchActionsEnable should only be called from IE 10');
  }

  // Although this particular element may have a style indicating that it cannot
  // receive javascript events, its parent may indicate otherwise.
  if (bot.dom.getEffectiveStyle(element, 'ms-touch-action') == 'none') {
    return true;
  } else {
    var parent = bot.dom.getParentElement(element);
    return !!parent && bot.Touchscreen.hasMsTouchActionsEnabled_(parent);
  }
};