Source: main/webapp/modules/Mouse.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 mouse events for a given element. The events of
  24.  * the given element are automatically populated with handlers that translate
  25.  * mouse events into a non-browser-specific event provided by the
  26.  * Guacamole.Mouse instance.
  27.  *
  28.  * @example
  29.  * var mouse = new Guacamole.Mouse(client.getDisplay().getElement());
  30.  *
  31.  * // Forward all mouse interaction over Guacamole connection
  32.  * mouse.onEach(['mousedown', 'mousemove', 'mouseup'], function sendMouseEvent(e) {
  33.  *     client.sendMouseState(e.state, true);
  34.  * });
  35.  *
  36.  * @example
  37.  * // Hide software cursor when mouse leaves display
  38.  * mouse.on('mouseout', function hideCursor() {
  39.  *     client.getDisplay().showCursor(false);
  40.  * });
  41.  *
  42.  * @constructor
  43.  * @augments Guacamole.Mouse.Event.Target
  44.  * @param {!Element} element
  45.  *     The Element to use to provide mouse events.
  46.  */
  47. Guacamole.Mouse = function Mouse(element) {
  49.     Guacamole.Mouse.Event.Target.call(this);
  51.     /**
  52.      * Reference to this Guacamole.Mouse.
  53.      *
  54.      * @private
  55.      * @type {!Guacamole.Mouse}
  56.      */
  57.     var guac_mouse = this;
  59.     /**
  60.      * The number of mousemove events to require before re-enabling mouse
  61.      * event handling after receiving a touch event.
  62.      *
  63.      * @type {!number}
  64.      */
  65.     this.touchMouseThreshold = 3;
  67.     /**
  68.      * The minimum amount of pixels scrolled required for a single scroll button
  69.      * click.
  70.      *
  71.      * @type {!number}
  72.      */
  73.     this.scrollThreshold = 53;
  75.     /**
  76.      * The number of pixels to scroll per line.
  77.      *
  78.      * @type {!number}
  79.      */
  80.     this.PIXELS_PER_LINE = 18;
  82.     /**
  83.      * The number of pixels to scroll per page.
  84.      *
  85.      * @type {!number}
  86.      */
  87.     this.PIXELS_PER_PAGE = this.PIXELS_PER_LINE * 16;
  89.     /**
  90.      * Array of {@link Guacamole.Mouse.State} button names corresponding to the
  91.      * mouse button indices used by DOM mouse events.
  92.      *
  93.      * @private
  94.      * @type {!string[]}
  95.      */
  96.     var MOUSE_BUTTONS = [
  97.         Guacamole.Mouse.State.Buttons.LEFT,
  98.         Guacamole.Mouse.State.Buttons.MIDDLE,
  99.         Guacamole.Mouse.State.Buttons.RIGHT
  100.     ];
  102.     /**
  103.      * Counter of mouse events to ignore. This decremented by mousemove, and
  104.      * while non-zero, mouse events will have no effect.
  105.      *
  106.      * @private
  107.      * @type {!number}
  108.      */
  109.     var ignore_mouse = 0;
  111.     /**
  112.      * Cumulative scroll delta amount. This value is accumulated through scroll
  113.      * events and results in scroll button clicks if it exceeds a certain
  114.      * threshold.
  115.      *
  116.      * @private
  117.      * @type {!number}
  118.      */
  119.     var scroll_delta = 0;
  121.     // Block context menu so right-click gets sent properly
  122.     element.addEventListener("contextmenu", function(e) {
  123.         Guacamole.Event.DOMEvent.cancelEvent(e);
  124.     }, false);
  126.     element.addEventListener("mousemove", function(e) {
  128.         // If ignoring events, decrement counter
  129.         if (ignore_mouse) {
  130.             Guacamole.Event.DOMEvent.cancelEvent(e);
  131.             ignore_mouse--;
  132.             return;
  133.         }
  135.         guac_mouse.move(Guacamole.Position.fromClientPosition(element, e.clientX, e.clientY), e);
  137.     }, false);
  139.     element.addEventListener("mousedown", function(e) {
  141.         // Do not handle if ignoring events
  142.         if (ignore_mouse) {
  143.             Guacamole.Event.DOMEvent.cancelEvent(e);
  144.             return;
  145.         }
  147.         var button = MOUSE_BUTTONS[e.button];
  148.         if (button)
  149.             guac_mouse.press(button, e);
  151.     }, false);
  153.     element.addEventListener("mouseup", function(e) {
  155.         // Do not handle if ignoring events
  156.         if (ignore_mouse) {
  157.             Guacamole.Event.DOMEvent.cancelEvent(e);
  158.             return;
  159.         }
  161.         var button = MOUSE_BUTTONS[e.button];
  162.         if (button)
  163.             guac_mouse.release(button, e);
  165.     }, false);
  167.     element.addEventListener("mouseout", function(e) {
  169.         // Get parent of the element the mouse pointer is leaving
  170.        	if (!e) e = window.event;
  172.         // Check that mouseout is due to actually LEAVING the element
  173.         var target = e.relatedTarget || e.toElement;
  174.         while (target) {
  175.             if (target === element)
  176.                 return;
  177.             target = target.parentNode;
  178.         }
  180.         // Release all buttons and fire mouseout
  181.         guac_mouse.reset(e);
  182.         guac_mouse.out(e);
  184.     }, false);
  186.     // Override selection on mouse event element.
  187.     element.addEventListener("selectstart", function(e) {
  188.         Guacamole.Event.DOMEvent.cancelEvent(e);
  189.     }, false);
  191.     // Ignore all pending mouse events when touch events are the apparent source
  192.     function ignorePendingMouseEvents() { ignore_mouse = guac_mouse.touchMouseThreshold; }
  194.     element.addEventListener("touchmove",  ignorePendingMouseEvents, false);
  195.     element.addEventListener("touchstart", ignorePendingMouseEvents, false);
  196.     element.addEventListener("touchend",   ignorePendingMouseEvents, false);
  198.     // Scroll wheel support
  199.     function mousewheel_handler(e) {
  201.         // Determine approximate scroll amount (in pixels)
  202.         var delta = e.deltaY || -e.wheelDeltaY || -e.wheelDelta;
  204.         // If successfully retrieved scroll amount, convert to pixels if not
  205.         // already in pixels
  206.         if (delta) {
  208.             // Convert to pixels if delta was lines
  209.             if (e.deltaMode === 1)
  210.                 delta = e.deltaY * guac_mouse.PIXELS_PER_LINE;
  212.             // Convert to pixels if delta was pages
  213.             else if (e.deltaMode === 2)
  214.                 delta = e.deltaY * guac_mouse.PIXELS_PER_PAGE;
  216.         }
  218.         // Otherwise, assume legacy mousewheel event and line scrolling
  219.         else
  220.             delta = e.detail * guac_mouse.PIXELS_PER_LINE;
  221.         
  222.         // Update overall delta
  223.         scroll_delta += delta;
  225.         // Up
  226.         if (scroll_delta <= -guac_mouse.scrollThreshold) {
  228.             // Repeatedly click the up button until insufficient delta remains
  229.             do {
  230.                 guac_mouse.click(Guacamole.Mouse.State.Buttons.UP);
  231.                 scroll_delta += guac_mouse.scrollThreshold;
  232.             } while (scroll_delta <= -guac_mouse.scrollThreshold);
  234.             // Reset delta
  235.             scroll_delta = 0;
  237.         }
  239.         // Down
  240.         if (scroll_delta >= guac_mouse.scrollThreshold) {
  242.             // Repeatedly click the down button until insufficient delta remains
  243.             do {
  244.                 guac_mouse.click(Guacamole.Mouse.State.Buttons.DOWN);
  245.                 scroll_delta -= guac_mouse.scrollThreshold;
  246.             } while (scroll_delta >= guac_mouse.scrollThreshold);
  248.             // Reset delta
  249.             scroll_delta = 0;
  251.         }
  253.         // All scroll/wheel events must currently be cancelled regardless of
  254.         // whether the dispatched event is cancelled, as there is no Guacamole
  255.         // scroll event and thus no way to cancel scroll events that are
  256.         // smaller than required to produce an up/down click
  257.         Guacamole.Event.DOMEvent.cancelEvent(e);
  259.     }
  261.     element.addEventListener('DOMMouseScroll', mousewheel_handler, false);
  262.     element.addEventListener('mousewheel',     mousewheel_handler, false);
  263.     element.addEventListener('wheel',          mousewheel_handler, false);
  265.     /**
  266.      * Whether the browser supports CSS3 cursor styling, including hotspot
  267.      * coordinates.
  268.      *
  269.      * @private
  270.      * @type {!boolean}
  271.      */
  272.     var CSS3_CURSOR_SUPPORTED = (function() {
  274.         var div = document.createElement("div");
  276.         // If no cursor property at all, then no support
  277.         if (!("cursor" in div.style))
  278.             return false;
  280.         try {
  281.             // Apply simple 1x1 PNG
  282.             div.style.cursor = "url(data:image/png;base64,"
  283.                              + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB"
  284.                              + "AQMAAAAl21bKAAAAA1BMVEX///+nxBvI"
  285.                              + "AAAACklEQVQI12NgAAAAAgAB4iG8MwAA"
  286.                              + "AABJRU5ErkJggg==) 0 0, auto";
  287.         }
  288.         catch (e) {
  289.             return false;
  290.         }
  292.         // Verify cursor property is set to URL with hotspot
  293.         return /\burl\([^()]*\)\s+0\s+0\b/.test(div.style.cursor || "");
  295.     })();
  297.     /**
  298.      * Changes the local mouse cursor to the given canvas, having the given
  299.      * hotspot coordinates. This affects styling of the element backing this
  300.      * Guacamole.Mouse only, and may fail depending on browser support for
  301.      * setting the mouse cursor.
  302.      * 
  303.      * If setting the local cursor is desired, it is up to the implementation
  304.      * to do something else, such as use the software cursor built into
  305.      * Guacamole.Display, if the local cursor cannot be set.
  306.      *
  307.      * @param {!HTMLCanvasElement} canvas
  308.      *     The cursor image.
  309.      *
  310.      * @param {!number} x
  311.      *     The X-coordinate of the cursor hotspot.
  312.      *
  313.      * @param {!number} y
  314.      *     The Y-coordinate of the cursor hotspot.
  315.      *
  316.      * @return {!boolean}
  317.      *     true if the cursor was successfully set, false if the cursor could
  318.      *     not be set for any reason.
  319.      */
  320.     this.setCursor = function(canvas, x, y) {
  322.         // Attempt to set via CSS3 cursor styling
  323.         if (CSS3_CURSOR_SUPPORTED) {
  324.             var dataURL = canvas.toDataURL('image/png');
  325.             element.style.cursor = "url(" + dataURL + ") " + x + " " + y + ", auto";
  326.             return true;
  327.         }
  329.         // Otherwise, setting cursor failed
  330.         return false;
  332.     };
  334. };
  336. /**
  337.  * The current state of a mouse, including position and buttons.
  338.  *
  339.  * @constructor
  340.  * @augments Guacamole.Position
  341.  * @param {Guacamole.Mouse.State|object} [template={}]
  342.  *     The object whose properties should be copied within the new
  343.  *     Guacamole.Mouse.State.
  344.  */
  345. Guacamole.Mouse.State = function State(template) {
  347.     /**
  348.      * Returns the template object that would be provided to the
  349.      * Guacamole.Mouse.State constructor to produce a new Guacamole.Mouse.State
  350.      * object with the properties specified. The order and type of arguments
  351.      * used by this function are identical to those accepted by the
  352.      * Guacamole.Mouse.State constructor of Apache Guacamole 1.3.0 and older.
  353.      *
  354.      * @private
  355.      * @param {!number} x
  356.      *     The X position of the mouse pointer in pixels.
  357.      *
  358.      * @param {!number} y
  359.      *     The Y position of the mouse pointer in pixels.
  360.      *
  361.      * @param {!boolean} left
  362.      *     Whether the left mouse button is pressed.
  363.      *
  364.      * @param {!boolean} middle
  365.      *     Whether the middle mouse button is pressed.
  366.      *
  367.      * @param {!boolean} right
  368.      *     Whether the right mouse button is pressed.
  369.      *
  370.      * @param {!boolean} up
  371.      *     Whether the up mouse button is pressed (the fourth button, usually
  372.      *     part of a scroll wheel).
  373.      *
  374.      * @param {!boolean} down
  375.      *     Whether the down mouse button is pressed (the fifth button, usually
  376.      *     part of a scroll wheel).
  377.      *
  378.      * @return {!object}
  379.      *     The equivalent template object that would be passed to the new
  380.      *     Guacamole.Mouse.State constructor.
  381.      */
  382.     var legacyConstructor = function legacyConstructor(x, y, left, middle, right, up, down) {
  383.         return {
  384.             x      : x,
  385.             y      : y,
  386.             left   : left,
  387.             middle : middle,
  388.             right  : right,
  389.             up     : up,
  390.             down   : down
  391.         };
  392.     };
  394.     // Accept old-style constructor, as well
  395.     if (arguments.length > 1)
  396.         template = legacyConstructor.apply(this, arguments);
  397.     else
  398.         template = template || {};
  400.     Guacamole.Position.call(this, template);
  402.     /**
  403.      * Whether the left mouse button is currently pressed.
  404.      *
  405.      * @type {!boolean}
  406.      * @default false
  407.      */
  408.     this.left = template.left || false;
  410.     /**
  411.      * Whether the middle mouse button is currently pressed.
  412.      *
  413.      * @type {!boolean}
  414.      * @default false
  415.      */
  416.     this.middle = template.middle || false;
  418.     /**
  419.      * Whether the right mouse button is currently pressed.
  420.      *
  421.      * @type {!boolean}
  422.      * @default false
  423.      */
  424.     this.right = template.right || false;
  426.     /**
  427.      * Whether the up mouse button is currently pressed. This is the fourth
  428.      * mouse button, associated with upward scrolling of the mouse scroll
  429.      * wheel.
  430.      *
  431.      * @type {!boolean}
  432.      * @default false
  433.      */
  434.     this.up = template.up || false;
  436.     /**
  437.      * Whether the down mouse button is currently pressed. This is the fifth 
  438.      * mouse button, associated with downward scrolling of the mouse scroll
  439.      * wheel.
  440.      *
  441.      * @type {!boolean}
  442.      * @default false
  443.      */
  444.     this.down = template.down || false;
  446. };
  448. /**
  449.  * All mouse buttons that may be represented by a
  450.  * {@link Guacamole.Mouse.State}. 
  451.  *
  452.  * @readonly
  453.  * @enum
  454.  */
  455. Guacamole.Mouse.State.Buttons = {
  457.     /**
  458.      * The name of the {@link Guacamole.Mouse.State} property representing the
  459.      * left mouse button.
  460.      *
  461.      * @constant
  462.      * @type {!string}
  463.      */
  464.     LEFT : 'left',
  466.     /**
  467.      * The name of the {@link Guacamole.Mouse.State} property representing the
  468.      * middle mouse button.
  469.      *
  470.      * @constant
  471.      * @type {!string}
  472.      */
  473.     MIDDLE : 'middle',
  475.     /**
  476.      * The name of the {@link Guacamole.Mouse.State} property representing the
  477.      * right mouse button.
  478.      *
  479.      * @constant
  480.      * @type {!string}
  481.      */
  482.     RIGHT : 'right',
  484.     /**
  485.      * The name of the {@link Guacamole.Mouse.State} property representing the
  486.      * up mouse button (the fourth mouse button, clicked when the mouse scroll
  487.      * wheel is scrolled up).
  488.      *
  489.      * @constant
  490.      * @type {!string}
  491.      */
  492.     UP : 'up',
  494.     /**
  495.      * The name of the {@link Guacamole.Mouse.State} property representing the
  496.      * down mouse button (the fifth mouse button, clicked when the mouse scroll
  497.      * wheel is scrolled up).
  498.      *
  499.      * @constant
  500.      * @type {!string}
  501.      */
  502.     DOWN : 'down'
  504. };
  506. /**
  507.  * Base event type for all mouse events. The mouse producing the event may be
  508.  * the user's local mouse (as with {@link Guacamole.Mouse}) or an emulated
  509.  * mouse (as with {@link Guacamole.Mouse.Touchpad}).
  510.  *
  511.  * @constructor
  512.  * @augments Guacamole.Event.DOMEvent
  513.  * @param {!string} type
  514.  *     The type name of the event ("mousedown", "mouseup", etc.)
  515.  *
  516.  * @param {!Guacamole.Mouse.State} state
  517.  *     The current mouse state.
  518.  *     
  519.  * @param {Event|Event[]} [events=[]]
  520.  *     The DOM events that are related to this event, if any.
  521.  */
  522. Guacamole.Mouse.Event = function MouseEvent(type, state, events) {
  524.     Guacamole.Event.DOMEvent.call(this, type, events);
  526.     /**
  527.      * The name of the event handler used by the Guacamole JavaScript API for
  528.      * this event prior to the migration to Guacamole.Event.Target.
  529.      *
  530.      * @private
  531.      * @constant
  532.      * @type {!string}
  533.      */
  534.     var legacyHandlerName = 'on' + this.type;
  536.     /**
  537.      * The current mouse state at the time this event was fired.
  538.      *
  539.      * @type {!Guacamole.Mouse.State}
  540.      */
  541.     this.state = state;
  543.     /**
  544.      * @inheritdoc
  545.      */
  546.     this.invokeLegacyHandler = function invokeLegacyHandler(target) {
  547.         if (target[legacyHandlerName]) {
  549.             this.preventDefault();
  550.             this.stopPropagation();
  552.             target[legacyHandlerName](this.state);
  554.         }
  555.     };
  557. };
  559. /**
  560.  * An object which can dispatch {@link Guacamole.Mouse.Event} objects
  561.  * representing mouse events. These mouse events may be produced from an actual
  562.  * mouse device (as with {@link Guacamole.Mouse}), from an emulated mouse
  563.  * device (as with {@link Guacamole.Mouse.Touchpad}, or may be programmatically
  564.  * generated (using functions like [dispatch()]{@link Guacamole.Mouse.Event.Target#dispatch},
  565.  * [press()]{@link Guacamole.Mouse.Event.Target#press}, and
  566.  * [release()]{@link Guacamole.Mouse.Event.Target#release}).
  567.  * 
  568.  * @constructor
  569.  * @augments Guacamole.Event.Target
  570.  */
  571. Guacamole.Mouse.Event.Target = function MouseEventTarget() {
  573.     Guacamole.Event.Target.call(this);
  575.     /**
  576.      * The current mouse state. The properties of this state are updated when
  577.      * mouse events fire. This state object is also passed in as a parameter to
  578.      * the handler of any mouse events.
  579.      *
  580.      * @type {!Guacamole.Mouse.State}
  581.      */
  582.     this.currentState = new Guacamole.Mouse.State();
  584.     /**
  585.      * Fired whenever a mouse button is effectively pressed. Depending on the
  586.      * object dispatching the event, this can be due to a true mouse button
  587.      * press ({@link Guacamole.Mouse}), an emulated mouse button press from a
  588.      * touch gesture ({@link Guacamole.Mouse.Touchpad} and
  589.      * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
  590.      * generated through [dispatch()]{@link Guacamole.Mouse.Event.Target#dispatch},
  591.      * [press()]{@link Guacamole.Mouse.Event.Target#press}, or
  592.      * [click()]{@link Guacamole.Mouse.Event.Target#click}.
  593.      *
  594.      * @event Guacamole.Mouse.Event.Target#mousedown
  595.      * @param {!Guacamole.Mouse.Event} event
  596.      *     The mousedown event that was fired.
  597.      */
  599.     /**
  600.      * Fired whenever a mouse button is effectively released. Depending on the
  601.      * object dispatching the event, this can be due to a true mouse button
  602.      * release ({@link Guacamole.Mouse}), an emulated mouse button release from
  603.      * a touch gesture ({@link Guacamole.Mouse.Touchpad} and
  604.      * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
  605.      * generated through [dispatch()]{@link Guacamole.Mouse.Event.Target#dispatch},
  606.      * [release()]{@link Guacamole.Mouse.Event.Target#release}, or
  607.      * [click()]{@link Guacamole.Mouse.Event.Target#click}.
  608.      *
  609.      * @event Guacamole.Mouse.Event.Target#mouseup
  610.      * @param {!Guacamole.Mouse.Event} event
  611.      *     The mouseup event that was fired.
  612.      */
  614.     /**
  615.      * Fired whenever the mouse pointer is effectively moved. Depending on the
  616.      * object dispatching the event, this can be due to true mouse movement
  617.      * ({@link Guacamole.Mouse}), emulated mouse movement from
  618.      * a touch gesture ({@link Guacamole.Mouse.Touchpad} and
  619.      * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
  620.      * generated through [dispatch()]{@link Guacamole.Mouse.Event.Target#dispatch},
  621.      * or [move()]{@link Guacamole.Mouse.Event.Target#move}.
  622.      *
  623.      * @event Guacamole.Mouse.Event.Target#mousemove
  624.      * @param {!Guacamole.Mouse.Event} event
  625.      *     The mousemove event that was fired.
  626.      */
  628.     /**
  629.      * Fired whenever the mouse pointer leaves the boundaries of the element
  630.      * being monitored for interaction. This will only ever be automatically
  631.      * fired due to movement of an actual mouse device via
  632.      * {@link Guacamole.Mouse} unless programmatically generated through
  633.      * [dispatch()]{@link Guacamole.Mouse.Event.Target#dispatch},
  634.      * or [out()]{@link Guacamole.Mouse.Event.Target#out}.
  635.      *
  636.      * @event Guacamole.Mouse.Event.Target#mouseout
  637.      * @param {!Guacamole.Mouse.Event} event
  638.      *     The mouseout event that was fired.
  639.      */
  641.     /**
  642.      * Presses the given mouse button, if it isn't already pressed. Valid
  643.      * button names are defined by {@link Guacamole.Mouse.State.Buttons} and
  644.      * correspond to the button-related properties of
  645.      * {@link Guacamole.Mouse.State}.
  646.      *
  647.      * @fires Guacamole.Mouse.Event.Target#mousedown
  648.      *
  649.      * @param {!string} button
  650.      *     The name of the mouse button to press, as defined by
  651.      *     {@link Guacamole.Mouse.State.Buttons}.
  652.      *
  653.      * @param {Event|Event[]} [events=[]]
  654.      *     The DOM events that are related to the mouse button press, if any.
  655.      */
  656.     this.press = function press(button, events) {
  657.         if (!this.currentState[button]) {
  658.             this.currentState[button] = true;
  659.             this.dispatch(new Guacamole.Mouse.Event('mousedown', this.currentState, events));
  660.         }
  661.     };
  663.     /**
  664.      * Releases the given mouse button, if it isn't already released. Valid
  665.      * button names are defined by {@link Guacamole.Mouse.State.Buttons} and
  666.      * correspond to the button-related properties of
  667.      * {@link Guacamole.Mouse.State}.
  668.      *
  669.      * @fires Guacamole.Mouse.Event.Target#mouseup
  670.      *
  671.      * @param {!string} button
  672.      *     The name of the mouse button to release, as defined by
  673.      *     {@link Guacamole.Mouse.State.Buttons}.
  674.      *
  675.      * @param {Event|Event[]} [events=[]]
  676.      *     The DOM events related to the mouse button release, if any.
  677.      */
  678.     this.release = function release(button, events) {
  679.         if (this.currentState[button]) {
  680.             this.currentState[button] = false;
  681.             this.dispatch(new Guacamole.Mouse.Event('mouseup', this.currentState, events));
  682.         }
  683.     };
  685.     /**
  686.      * Clicks (presses and releases) the given mouse button. Valid button
  687.      * names are defined by {@link Guacamole.Mouse.State.Buttons} and
  688.      * correspond to the button-related properties of
  689.      * {@link Guacamole.Mouse.State}.
  690.      *
  691.      * @fires Guacamole.Mouse.Event.Target#mousedown
  692.      * @fires Guacamole.Mouse.Event.Target#mouseup
  693.      *
  694.      * @param {!string} button
  695.      *     The name of the mouse button to click, as defined by
  696.      *     {@link Guacamole.Mouse.State.Buttons}.
  697.      *
  698.      * @param {Event|Event[]} [events=[]]
  699.      *     The DOM events related to the click, if any.
  700.      */
  701.     this.click = function click(button, events) {
  702.         this.press(button, events);
  703.         this.release(button, events);
  704.     };
  706.     /**
  707.      * Moves the mouse to the given coordinates.
  708.      *
  709.      * @fires Guacamole.Mouse.Event.Target#mousemove
  710.      *
  711.      * @param {!(Guacamole.Position|object)} position
  712.      *     The new coordinates of the mouse pointer. This object may be a
  713.      *     {@link Guacamole.Position} or any object with "x" and "y"
  714.      *     properties.
  715.      *
  716.      * @param {Event|Event[]} [events=[]]
  717.      *     The DOM events related to the mouse movement, if any.
  718.      */
  719.     this.move = function move(position, events) {
  721.         if (this.currentState.x !== position.x || this.currentState.y !== position.y) {
  722.             this.currentState.x = position.x;
  723.             this.currentState.y = position.y;
  724.             this.dispatch(new Guacamole.Mouse.Event('mousemove', this.currentState, events));
  725.         }
  727.     };
  729.     /**
  730.      * Notifies event listeners that the mouse pointer has left the boundaries
  731.      * of the area being monitored for mouse events.
  732.      *
  733.      * @fires Guacamole.Mouse.Event.Target#mouseout
  734.      *
  735.      * @param {Event|Event[]} [events=[]]
  736.      *     The DOM events related to the mouse leaving the boundaries of the
  737.      *     monitored object, if any.
  738.      */
  739.     this.out = function out(events) {
  740.         this.dispatch(new Guacamole.Mouse.Event('mouseout', this.currentState, events));
  741.     };
  743.     /**
  744.      * Releases all mouse buttons that are currently pressed. If all mouse
  745.      * buttons have already been released, this function has no effect.
  746.      *
  747.      * @fires Guacamole.Mouse.Event.Target#mouseup
  748.      *
  749.      * @param {Event|Event[]} [events=[]]
  750.      *     The DOM event related to all mouse buttons being released, if any.
  751.      */
  752.     this.reset = function reset(events) {
  753.         for (var button in Guacamole.Mouse.State.Buttons) {
  754.             this.release(Guacamole.Mouse.State.Buttons[button], events);
  755.         }
  756.     };
  758. };
  760. /**
  761.  * Provides cross-browser relative touch event translation for a given element.
  762.  * 
  763.  * Touch events are translated into mouse events as if the touches occurred
  764.  * on a touchpad (drag to push the mouse pointer, tap to click).
  765.  * 
  766.  * @example
  767.  * var touchpad = new Guacamole.Mouse.Touchpad(client.getDisplay().getElement());
  768.  *
  769.  * // Emulate a mouse using touchpad-style gestures, forwarding all mouse
  770.  * // interaction over Guacamole connection
  771.  * touchpad.onEach(['mousedown', 'mousemove', 'mouseup'], function sendMouseEvent(e) {
  772.  *
  773.  *     // Re-show software mouse cursor if possibly hidden by a prior call to
  774.  *     // showCursor(), such as a "mouseout" event handler that hides the
  775.  *     // cursor
  776.  *     client.getDisplay().showCursor(true);
  777.  *
  778.  *     client.sendMouseState(e.state, true);
  779.  *
  780.  * });
  781.  *
  782.  * @constructor
  783.  * @augments Guacamole.Mouse.Event.Target
  784.  * @param {!Element} element
  785.  *     The Element to use to provide touch events.
  786.  */
  787. Guacamole.Mouse.Touchpad = function Touchpad(element) {
  789.     Guacamole.Mouse.Event.Target.call(this);
  791.     /**
  792.      * The "mouseout" event will never be fired by Guacamole.Mouse.Touchpad.
  793.      *
  794.      * @ignore
  795.      * @event Guacamole.Mouse.Touchpad#mouseout
  796.      */
  798.     /**
  799.      * Reference to this Guacamole.Mouse.Touchpad.
  800.      *
  801.      * @private
  802.      * @type {!Guacamole.Mouse.Touchpad}
  803.      */
  804.     var guac_touchpad = this;
  806.     /**
  807.      * The distance a two-finger touch must move per scrollwheel event, in
  808.      * pixels.
  809.      *
  810.      * @type {!number}
  811.      */
  812.     this.scrollThreshold = 20 * (window.devicePixelRatio || 1);
  814.     /**
  815.      * The maximum number of milliseconds to wait for a touch to end for the
  816.      * gesture to be considered a click.
  817.      *
  818.      * @type {!number}
  819.      */
  820.     this.clickTimingThreshold = 250;
  822.     /**
  823.      * The maximum number of pixels to allow a touch to move for the gesture to
  824.      * be considered a click.
  825.      *
  826.      * @type {!number}
  827.      */
  828.     this.clickMoveThreshold = 10 * (window.devicePixelRatio || 1);
  830.     /**
  831.      * The current mouse state. The properties of this state are updated when
  832.      * mouse events fire. This state object is also passed in as a parameter to
  833.      * the handler of any mouse events.
  834.      * 
  835.      * @type {!Guacamole.Mouse.State}
  836.      */
  837.     this.currentState = new Guacamole.Mouse.State();
  839.     var touch_count = 0;
  840.     var last_touch_x = 0;
  841.     var last_touch_y = 0;
  842.     var last_touch_time = 0;
  843.     var pixels_moved = 0;
  845.     var touch_buttons = {
  846.         1: "left",
  847.         2: "right",
  848.         3: "middle"
  849.     };
  851.     var gesture_in_progress = false;
  852.     var click_release_timeout = null;
  854.     element.addEventListener("touchend", function(e) {
  855.         
  856.         e.preventDefault();
  857.             
  858.         // If we're handling a gesture AND this is the last touch
  859.         if (gesture_in_progress && e.touches.length === 0) {
  860.             
  861.             var time = new Date().getTime();
  863.             // Get corresponding mouse button
  864.             var button = touch_buttons[touch_count];
  866.             // If mouse already down, release anad clear timeout
  867.             if (guac_touchpad.currentState[button]) {
  869.                 // Fire button up event
  870.                 guac_touchpad.release(button, e);
  872.                 // Clear timeout, if set
  873.                 if (click_release_timeout) {
  874.                     window.clearTimeout(click_release_timeout);
  875.                     click_release_timeout = null;
  876.                 }
  878.             }
  880.             // If single tap detected (based on time and distance)
  881.             if (time - last_touch_time <= guac_touchpad.clickTimingThreshold
  882.                     && pixels_moved < guac_touchpad.clickMoveThreshold) {
  884.                 // Fire button down event
  885.                 guac_touchpad.press(button, e);
  887.                 // Delay mouse up - mouse up should be canceled if
  888.                 // touchstart within timeout.
  889.                 click_release_timeout = window.setTimeout(function() {
  890.                     
  891.                     // Fire button up event
  892.                     guac_touchpad.release(button, e);
  894.                     // Gesture now over
  895.                     gesture_in_progress = false;
  897.                 }, guac_touchpad.clickTimingThreshold);
  899.             }
  901.             // If we're not waiting to see if this is a click, stop gesture
  902.             if (!click_release_timeout)
  903.                 gesture_in_progress = false;
  905.         }
  907.     }, false);
  909.     element.addEventListener("touchstart", function(e) {
  911.         e.preventDefault();
  913.         // Track number of touches, but no more than three
  914.         touch_count = Math.min(e.touches.length, 3);
  916.         // Clear timeout, if set
  917.         if (click_release_timeout) {
  918.             window.clearTimeout(click_release_timeout);
  919.             click_release_timeout = null;
  920.         }
  922.         // Record initial touch location and time for touch movement
  923.         // and tap gestures
  924.         if (!gesture_in_progress) {
  926.             // Stop mouse events while touching
  927.             gesture_in_progress = true;
  929.             // Record touch location and time
  930.             var starting_touch = e.touches[0];
  931.             last_touch_x = starting_touch.clientX;
  932.             last_touch_y = starting_touch.clientY;
  933.             last_touch_time = new Date().getTime();
  934.             pixels_moved = 0;
  936.         }
  938.     }, false);
  940.     element.addEventListener("touchmove", function(e) {
  942.         e.preventDefault();
  944.         // Get change in touch location
  945.         var touch = e.touches[0];
  946.         var delta_x = touch.clientX - last_touch_x;
  947.         var delta_y = touch.clientY - last_touch_y;
  949.         // Track pixels moved
  950.         pixels_moved += Math.abs(delta_x) + Math.abs(delta_y);
  952.         // If only one touch involved, this is mouse move
  953.         if (touch_count === 1) {
  955.             // Calculate average velocity in Manhatten pixels per millisecond
  956.             var velocity = pixels_moved / (new Date().getTime() - last_touch_time);
  958.             // Scale mouse movement relative to velocity
  959.             var scale = 1 + velocity;
  961.             // Update mouse location
  962.             var position = new Guacamole.Position(guac_touchpad.currentState);
  963.             position.x += delta_x*scale;
  964.             position.y += delta_y*scale;
  966.             // Prevent mouse from leaving screen
  967.             position.x = Math.min(Math.max(0, position.x), element.offsetWidth - 1);
  968.             position.y = Math.min(Math.max(0, position.y), element.offsetHeight - 1);
  970.             // Fire movement event, if defined
  971.             guac_touchpad.move(position, e);
  973.             // Update touch location
  974.             last_touch_x = touch.clientX;
  975.             last_touch_y = touch.clientY;
  977.         }
  979.         // Interpret two-finger swipe as scrollwheel
  980.         else if (touch_count === 2) {
  982.             // If change in location passes threshold for scroll
  983.             if (Math.abs(delta_y) >= guac_touchpad.scrollThreshold) {
  985.                 // Decide button based on Y movement direction
  986.                 var button;
  987.                 if (delta_y > 0) button = "down";
  988.                 else             button = "up";
  990.                 guac_touchpad.click(button, e);
  992.                 // Only update touch location after a scroll has been
  993.                 // detected
  994.                 last_touch_x = touch.clientX;
  995.                 last_touch_y = touch.clientY;
  997.             }
  999.         }
  1001.     }, false);
  1003. };
  1005. /**
  1006.  * Provides cross-browser absolute touch event translation for a given element.
  1007.  *
  1008.  * Touch events are translated into mouse events as if the touches occurred
  1009.  * on a touchscreen (tapping anywhere on the screen clicks at that point,
  1010.  * long-press to right-click).
  1011.  *
  1012.  * @example
  1013.  * var touchscreen = new Guacamole.Mouse.Touchscreen(client.getDisplay().getElement());
  1014.  *
  1015.  * // Emulate a mouse using touchscreen-style gestures, forwarding all mouse
  1016.  * // interaction over Guacamole connection
  1017.  * touchscreen.onEach(['mousedown', 'mousemove', 'mouseup'], function sendMouseEvent(e) {
  1018.  *
  1019.  *     // Re-show software mouse cursor if possibly hidden by a prior call to
  1020.  *     // showCursor(), such as a "mouseout" event handler that hides the
  1021.  *     // cursor
  1022.  *     client.getDisplay().showCursor(true);
  1023.  *
  1024.  *     client.sendMouseState(e.state, true);
  1025.  *
  1026.  * });
  1027.  *
  1028.  * @constructor
  1029.  * @augments Guacamole.Mouse.Event.Target
  1030.  * @param {!Element} element
  1031.  *     The Element to use to provide touch events.
  1032.  */
  1033. Guacamole.Mouse.Touchscreen = function Touchscreen(element) {
  1035.     Guacamole.Mouse.Event.Target.call(this);
  1037.     /**
  1038.      * The "mouseout" event will never be fired by Guacamole.Mouse.Touchscreen.
  1039.      *
  1040.      * @ignore
  1041.      * @event Guacamole.Mouse.Touchscreen#mouseout
  1042.      */
  1044.     /**
  1045.      * Reference to this Guacamole.Mouse.Touchscreen.
  1046.      *
  1047.      * @private
  1048.      * @type {!Guacamole.Mouse.Touchscreen}
  1049.      */
  1050.     var guac_touchscreen = this;
  1052.     /**
  1053.      * Whether a gesture is known to be in progress. If false, touch events
  1054.      * will be ignored.
  1055.      *
  1056.      * @private
  1057.      * @type {!boolean}
  1058.      */
  1059.     var gesture_in_progress = false;
  1061.     /**
  1062.      * The start X location of a gesture.
  1063.      *
  1064.      * @private
  1065.      * @type {number}
  1066.      */
  1067.     var gesture_start_x = null;
  1069.     /**
  1070.      * The start Y location of a gesture.
  1071.      *
  1072.      * @private
  1073.      * @type {number}
  1074.      */
  1075.     var gesture_start_y = null;
  1077.     /**
  1078.      * The timeout associated with the delayed, cancellable click release.
  1079.      *
  1080.      * @private
  1081.      * @type {number}
  1082.      */
  1083.     var click_release_timeout = null;
  1085.     /**
  1086.      * The timeout associated with long-press for right click.
  1087.      *
  1088.      * @private
  1089.      * @type {number}
  1090.      */
  1091.     var long_press_timeout = null;
  1093.     /**
  1094.      * The distance a two-finger touch must move per scrollwheel event, in
  1095.      * pixels.
  1096.      *
  1097.      * @type {!number}
  1098.      */
  1099.     this.scrollThreshold = 20 * (window.devicePixelRatio || 1);
  1101.     /**
  1102.      * The maximum number of milliseconds to wait for a touch to end for the
  1103.      * gesture to be considered a click.
  1104.      *
  1105.      * @type {!number}
  1106.      */
  1107.     this.clickTimingThreshold = 250;
  1109.     /**
  1110.      * The maximum number of pixels to allow a touch to move for the gesture to
  1111.      * be considered a click.
  1112.      *
  1113.      * @type {!number}
  1114.      */
  1115.     this.clickMoveThreshold = 16 * (window.devicePixelRatio || 1);
  1117.     /**
  1118.      * The amount of time a press must be held for long press to be
  1119.      * detected.
  1120.      */
  1121.     this.longPressThreshold = 500;
  1123.     /**
  1124.      * Returns whether the given touch event exceeds the movement threshold for
  1125.      * clicking, based on where the touch gesture began.
  1126.      *
  1127.      * @private
  1128.      * @param {!TouchEvent} e
  1129.      *     The touch event to check.
  1130.      *
  1131.      * @return {!boolean}
  1132.      *     true if the movement threshold is exceeded, false otherwise.
  1133.      */
  1134.     function finger_moved(e) {
  1135.         var touch = e.touches[0] || e.changedTouches[0];
  1136.         var delta_x = touch.clientX - gesture_start_x;
  1137.         var delta_y = touch.clientY - gesture_start_y;
  1138.         return Math.sqrt(delta_x*delta_x + delta_y*delta_y) >= guac_touchscreen.clickMoveThreshold;
  1139.     }
  1141.     /**
  1142.      * Begins a new gesture at the location of the first touch in the given
  1143.      * touch event.
  1144.      * 
  1145.      * @private
  1146.      * @param {!TouchEvent} e
  1147.      *     The touch event beginning this new gesture.
  1148.      */
  1149.     function begin_gesture(e) {
  1150.         var touch = e.touches[0];
  1151.         gesture_in_progress = true;
  1152.         gesture_start_x = touch.clientX;
  1153.         gesture_start_y = touch.clientY;
  1154.     }
  1156.     /**
  1157.      * End the current gesture entirely. Wait for all touches to be done before
  1158.      * resuming gesture detection.
  1159.      * 
  1160.      * @private
  1161.      */
  1162.     function end_gesture() {
  1163.         window.clearTimeout(click_release_timeout);
  1164.         window.clearTimeout(long_press_timeout);
  1165.         gesture_in_progress = false;
  1166.     }
  1168.     element.addEventListener("touchend", function(e) {
  1170.         // Do not handle if no gesture
  1171.         if (!gesture_in_progress)
  1172.             return;
  1174.         // Ignore if more than one touch
  1175.         if (e.touches.length !== 0 || e.changedTouches.length !== 1) {
  1176.             end_gesture();
  1177.             return;
  1178.         }
  1180.         // Long-press, if any, is over
  1181.         window.clearTimeout(long_press_timeout);
  1183.         // Always release mouse button if pressed
  1184.         guac_touchscreen.release(Guacamole.Mouse.State.Buttons.LEFT, e);
  1186.         // If finger hasn't moved enough to cancel the click
  1187.         if (!finger_moved(e)) {
  1189.             e.preventDefault();
  1191.             // If not yet pressed, press and start delay release
  1192.             if (!guac_touchscreen.currentState.left) {
  1194.                 var touch = e.changedTouches[0];
  1195.                 guac_touchscreen.move(Guacamole.Position.fromClientPosition(element, touch.clientX, touch.clientY));
  1196.                 guac_touchscreen.press(Guacamole.Mouse.State.Buttons.LEFT, e);
  1198.                 // Release button after a delay, if not canceled
  1199.                 click_release_timeout = window.setTimeout(function() {
  1200.                     guac_touchscreen.release(Guacamole.Mouse.State.Buttons.LEFT, e);
  1201.                     end_gesture();
  1202.                 }, guac_touchscreen.clickTimingThreshold);
  1204.             }
  1206.         } // end if finger not moved
  1208.     }, false);
  1210.     element.addEventListener("touchstart", function(e) {
  1212.         // Ignore if more than one touch
  1213.         if (e.touches.length !== 1) {
  1214.             end_gesture();
  1215.             return;
  1216.         }
  1218.         e.preventDefault();
  1220.         // New touch begins a new gesture
  1221.         begin_gesture(e);
  1223.         // Keep button pressed if tap after left click
  1224.         window.clearTimeout(click_release_timeout);
  1226.         // Click right button if this turns into a long-press
  1227.         long_press_timeout = window.setTimeout(function() {
  1228.             var touch = e.touches[0];
  1229.             guac_touchscreen.move(Guacamole.Position.fromClientPosition(element, touch.clientX, touch.clientY));
  1230.             guac_touchscreen.click(Guacamole.Mouse.State.Buttons.RIGHT, e);
  1231.             end_gesture();
  1232.         }, guac_touchscreen.longPressThreshold);
  1234.     }, false);
  1236.     element.addEventListener("touchmove", function(e) {
  1238.         // Do not handle if no gesture
  1239.         if (!gesture_in_progress)
  1240.             return;
  1242.         // Cancel long press if finger moved
  1243.         if (finger_moved(e))
  1244.             window.clearTimeout(long_press_timeout);
  1246.         // Ignore if more than one touch
  1247.         if (e.touches.length !== 1) {
  1248.             end_gesture();
  1249.             return;
  1250.         }
  1252.         // Update mouse position if dragging
  1253.         if (guac_touchscreen.currentState.left) {
  1255.             e.preventDefault();
  1257.             // Update state
  1258.             var touch = e.touches[0];
  1259.             guac_touchscreen.move(Guacamole.Position.fromClientPosition(element, touch.clientX, touch.clientY), e);
  1261.         }
  1263.     }, false);
  1265. };