Source: main/webapp/modules/Touch.js

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one
  3.  * or more contributor license agreements.  See the NOTICE file
  4.  * distributed with this work for additional information
  5.  * regarding copyright ownership.  The ASF licenses this file
  6.  * to you under the Apache License, Version 2.0 (the
  7.  * "License"); you may not use this file except in compliance
  8.  * with the License.  You may obtain a copy of the License at
  9.  *
  10.  *   http://www.apache.org/licenses/LICENSE-2.0
  11.  *
  12.  * Unless required by applicable law or agreed to in writing,
  13.  * software distributed under the License is distributed on an
  14.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15.  * KIND, either express or implied.  See the License for the
  16.  * specific language governing permissions and limitations
  17.  * under the License.
  18.  */
  20. var Guacamole = Guacamole || {};
  22. /**
  23.  * Provides cross-browser multi-touch events for a given element. The events of
  24.  * the given element are automatically populated with handlers that translate
  25.  * touch events into a non-browser-specific event provided by the
  26.  * Guacamole.Touch instance.
  27.  * 
  28.  * @constructor
  29.  * @augments Guacamole.Event.Target
  30.  * @param {!Element} element
  31.  *     The Element to use to provide touch events.
  32.  */
  33. Guacamole.Touch = function Touch(element) {
  35.     Guacamole.Event.Target.call(this);
  37.     /**
  38.      * Reference to this Guacamole.Touch.
  39.      *
  40.      * @private
  41.      * @type {!Guacamole.Touch}
  42.      */
  43.     var guacTouch = this;
  45.     /**
  46.      * The default X/Y radius of each touch if the device or browser does not
  47.      * expose the size of the contact area.
  48.      *
  49.      * @private
  50.      * @constant
  51.      * @type {!number}
  52.      */
  53.     var DEFAULT_CONTACT_RADIUS = Math.floor(16 * window.devicePixelRatio);
  55.     /**
  56.      * The set of all active touches, stored by their unique identifiers.
  57.      *
  58.      * @type {!Object.<Number, Guacamole.Touch.State>}
  59.      */
  60.     this.touches = {};
  62.     /**
  63.      * The number of active touches currently stored within
  64.      * {@link Guacamole.Touch#touches touches}.
  65.      */
  66.     this.activeTouches = 0;
  68.     /**
  69.      * Fired whenever a new touch contact is initiated on the element
  70.      * associated with this Guacamole.Touch.
  71.      * 
  72.      * @event Guacamole.Touch#touchstart
  73.      * @param {!Guacamole.Touch.Event} event
  74.      *     A {@link Guacamole.Touch.Event} object representing the "touchstart"
  75.      *     event.
  76.      */
  78.     /**
  79.      * Fired whenever an established touch contact moves within the element
  80.      * associated with this Guacamole.Touch.
  81.      * 
  82.      * @event Guacamole.Touch#touchmove
  83.      * @param {!Guacamole.Touch.Event} event
  84.      *     A {@link Guacamole.Touch.Event} object representing the "touchmove"
  85.      *     event.
  86.      */
  88.     /**
  89.      * Fired whenever an established touch contact is lifted from the element
  90.      * associated with this Guacamole.Touch.
  91.      * 
  92.      * @event Guacamole.Touch#touchend
  93.      * @param {!Guacamole.Touch.Event} event
  94.      *     A {@link Guacamole.Touch.Event} object representing the "touchend"
  95.      *     event.
  96.      */
  98.     element.addEventListener('touchstart', function touchstart(e) {
  100.         // Fire "ontouchstart" events for all new touches
  101.         for (var i = 0; i < e.changedTouches.length; i++) {
  103.             var changedTouch = e.changedTouches[i];
  104.             var identifier = changedTouch.identifier;
  106.             // Ignore duplicated touches
  107.             if (guacTouch.touches[identifier])
  108.                 continue;
  110.             var touch = guacTouch.touches[identifier] = new Guacamole.Touch.State({
  111.                 id      : identifier,
  112.                 radiusX : changedTouch.radiusX || DEFAULT_CONTACT_RADIUS,
  113.                 radiusY : changedTouch.radiusY || DEFAULT_CONTACT_RADIUS,
  114.                 angle   : changedTouch.angle || 0.0,
  115.                 force   : changedTouch.force || 1.0 /* Within JavaScript changedTouch events, a force of 0.0 indicates the device does not support reporting changedTouch force */
  116.             });
  118.             guacTouch.activeTouches++;
  120.             touch.fromClientPosition(element, changedTouch.clientX, changedTouch.clientY);
  121.             guacTouch.dispatch(new Guacamole.Touch.Event('touchmove', e, touch));
  123.         }
  125.     }, false);
  127.     element.addEventListener('touchmove', function touchstart(e) {
  129.         // Fire "ontouchmove" events for all updated touches
  130.         for (var i = 0; i < e.changedTouches.length; i++) {
  132.             var changedTouch = e.changedTouches[i];
  133.             var identifier = changedTouch.identifier;
  135.             // Ignore any unrecognized touches
  136.             var touch = guacTouch.touches[identifier];
  137.             if (!touch)
  138.                 continue;
  140.             // Update force only if supported by browser (otherwise, assume
  141.             // force is unchanged)
  142.             if (changedTouch.force)
  143.                 touch.force = changedTouch.force;
  145.             // Update touch area, if supported by browser and device
  146.             touch.angle = changedTouch.angle || 0.0;
  147.             touch.radiusX = changedTouch.radiusX || DEFAULT_CONTACT_RADIUS;
  148.             touch.radiusY = changedTouch.radiusY || DEFAULT_CONTACT_RADIUS;
  150.             // Update with any change in position
  151.             touch.fromClientPosition(element, changedTouch.clientX, changedTouch.clientY);
  152.             guacTouch.dispatch(new Guacamole.Touch.Event('touchmove', e, touch));
  154.         }
  156.     }, false);
  158.     element.addEventListener('touchend', function touchstart(e) {
  160.         // Fire "ontouchend" events for all updated touches
  161.         for (var i = 0; i < e.changedTouches.length; i++) {
  163.             var changedTouch = e.changedTouches[i];
  164.             var identifier = changedTouch.identifier;
  166.             // Ignore any unrecognized touches
  167.             var touch = guacTouch.touches[identifier];
  168.             if (!touch)
  169.                 continue;
  171.             // Stop tracking this particular touch
  172.             delete guacTouch.touches[identifier];
  173.             guacTouch.activeTouches--;
  175.             // Touch has ended
  176.             touch.force = 0.0;
  178.             // Update with final position
  179.             touch.fromClientPosition(element, changedTouch.clientX, changedTouch.clientY);
  180.             guacTouch.dispatch(new Guacamole.Touch.Event('touchend', e, touch));
  182.         }
  184.     }, false);
  186. };
  188. /**
  189.  * The current state of a touch contact.
  190.  *
  191.  * @constructor
  192.  * @augments Guacamole.Position
  193.  * @param {Guacamole.Touch.State|object} [template={}]
  194.  *     The object whose properties should be copied within the new
  195.  *     Guacamole.Touch.State.
  196.  */
  197. Guacamole.Touch.State = function State(template) {
  199.     template = template || {};
  201.     Guacamole.Position.call(this, template);
  203.     /**
  204.      * An arbitrary integer ID which uniquely identifies this contact relative
  205.      * to other active contacts.
  206.      *
  207.      * @type {!number}
  208.      * @default 0
  209.      */
  210.     this.id = template.id || 0;
  212.     /**
  213.      * The Y radius of the ellipse covering the general area of the touch
  214.      * contact, in pixels.
  215.      *
  216.      * @type {!number}
  217.      * @default 0
  218.      */
  219.     this.radiusX = template.radiusX || 0;
  221.     /**
  222.      * The X radius of the ellipse covering the general area of the touch
  223.      * contact, in pixels.
  224.      *
  225.      * @type {!number}
  226.      * @default 0
  227.      */
  228.     this.radiusY = template.radiusY || 0;
  230.     /**
  231.      * The rough angle of clockwise rotation of the general area of the touch
  232.      * contact, in degrees.
  233.      *
  234.      * @type {!number}
  235.      * @default 0.0
  236.      */
  237.     this.angle = template.angle || 0.0;
  239.     /**
  240.      * The relative force exerted by the touch contact, where 0 is no force
  241.      * (the touch has been lifted) and 1 is maximum force (the maximum amount
  242.      * of force representable by the device).
  243.      *
  244.      * @type {!number}
  245.      * @default 1.0
  246.      */
  247.     this.force = template.force || 1.0;
  249. };
  251. /**
  252.  * An event which represents a change in state of a single touch contact,
  253.  * including the creation or removal of that contact. If multiple contacts are
  254.  * involved in a touch interaction, each contact will be associated with its
  255.  * own event.
  256.  *
  257.  * @constructor
  258.  * @augments Guacamole.Event.DOMEvent
  259.  * @param {!string} type
  260.  *     The name of the touch event type. Possible values are "touchstart",
  261.  *     "touchmove", and "touchend".
  262.  *
  263.  * @param {!TouchEvent} event
  264.  *     The DOM touch event that produced this Guacamole.Touch.Event.
  265.  *
  266.  * @param {!Guacamole.Touch.State} state
  267.  *     The state of the touch contact associated with this event.
  268.  */
  269. Guacamole.Touch.Event = function TouchEvent(type, event, state) {
  271.     Guacamole.Event.DOMEvent.call(this, type, [ event ]);
  273.     /**
  274.      * The state of the touch contact associated with this event.
  275.      *
  276.      * @type {!Guacamole.Touch.State}
  277.      */
  278.     this.state = state;
  280. };