2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
15 * The Original Code is guacamole-common-js.
17 * The Initial Developer of the Original Code is
19 * Portions created by the Initial Developer are Copyright (C) 2010
20 * the Initial Developer. All Rights Reserved.
24 * Alternatively, the contents of this file may be used under the terms of
25 * either the GNU General Public License Version 2 or later (the "GPL"), or
26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 * in which case the provisions of the GPL or the LGPL are applicable instead
28 * of those above. If you wish to allow use of your version of this file only
29 * under the terms of either the GPL or the LGPL, and not to allow others to
30 * use your version of this file under the terms of the MPL, indicate your
31 * decision by deleting the provisions above and replace them with the notice
32 * and other provisions required by the GPL or the LGPL. If you do not delete
33 * the provisions above, a recipient may use your version of this file under
34 * the terms of any one of the MPL, the GPL or the LGPL.
36 * ***** END LICENSE BLOCK ***** */
38 // Guacamole namespace
39 var Guacamole = Guacamole || {};
42 * Provides cross-browser mouse events for a given element. The events of
43 * the given element are automatically populated with handlers that translate
44 * mouse events into a non-browser-specific event provided by the
45 * Guacamole.Mouse instance.
47 * Touch events are translated into mouse events as if the touches occurred
48 * on a touchpad (drag to push the mouse pointer, tap to click).
51 * @param {Element} element The Element to use to provide mouse events.
53 Guacamole.Mouse = function(element) {
56 * Reference to this Guacamole.Mouse.
59 var guac_mouse = this;
62 * The distance a two-finger touch must move per scrollwheel event, relative
63 * to the distance between the two touches.
65 this.scrollThreshold = 0.5;
68 * The maximum number of milliseconds to wait for a touch to end for the
69 * gesture to be considered a click.
71 this.clickTimingThreshold = 250;
74 * The maximum number of pixels to allow a touch to move for the gesture to
75 * be considered a click.
77 this.clickMoveThreshold = 10 * (window.displayPixelRatio || 1);
80 * The current mouse state. The properties of this state are updated when
81 * mouse events fire. This state object is also passed in as a parameter to
82 * the handler of any mouse events.
84 * @type Guacamole.Mouse.State
86 this.currentState = new Guacamole.Mouse.State(
88 false, false, false, false, false
92 * Fired whenever the user presses a mouse button down over the element
93 * associated with this Guacamole.Mouse.
96 * @param {Guacamole.Mouse.State} state The current mouse state.
98 this.onmousedown = null;
101 * Fired whenever the user releases a mouse button down over the element
102 * associated with this Guacamole.Mouse.
105 * @param {Guacamole.Mouse.State} state The current mouse state.
107 this.onmouseup = null;
110 * Fired whenever the user moves the mouse over the element associated with
111 * this Guacamole.Mouse.
114 * @param {Guacamole.Mouse.State} state The current mouse state.
116 this.onmousemove = null;
118 function cancelEvent(e) {
120 if (e.preventDefault) e.preventDefault();
121 e.returnValue = false;
124 function moveMouse(pageX, pageY) {
126 guac_mouse.currentState.x = pageX - element.offsetLeft;
127 guac_mouse.currentState.y = pageY - element.offsetTop;
129 // This is all JUST so we can get the mouse position within the element
130 var parent = element.offsetParent;
133 if (parent.offsetLeft)
134 guac_mouse.currentState.x -= parent.offsetLeft;
136 if (parent.offsetTop)
137 guac_mouse.currentState.y -= parent.offsetTop;
139 parent = parent.offsetParent;
142 if (guac_mouse.onmousemove)
143 guac_mouse.onmousemove(guac_mouse.currentState);
148 // Block context menu so right-click gets sent properly
149 element.addEventListener("contextmenu", function(e) {
153 element.addEventListener("mousemove", function(e) {
155 // Don't handle if we aren't supposed to
156 if (gesture_in_progress) return;
160 moveMouse(e.pageX, e.pageY);
165 var last_touch_x = 0;
166 var last_touch_y = 0;
167 var last_touch_time = 0;
168 var pixels_moved = 0;
169 var touch_distance = 0;
171 var touch_buttons = {
177 var gesture_in_progress = false;
178 var click_release_timeout = null;
180 element.addEventListener("touchend", function(e) {
182 // If we're handling a gesture AND this is the last touch
183 if (gesture_in_progress && e.touches.length == 0) {
187 var time = new Date().getTime();
189 // Get corresponding mouse button
190 var button = touch_buttons[touch_count];
192 // If mouse already down, release anad clear timeout
193 if (guac_mouse.currentState[button]) {
195 // Fire button up event
196 guac_mouse.currentState[button] = false;
197 if (guac_mouse.onmouseup)
198 guac_mouse.onmouseup(guac_mouse.currentState);
200 // Clear timeout, if set
201 if (click_release_timeout) {
202 window.clearTimeout(click_release_timeout);
203 click_release_timeout = null;
208 // If single tap detected (based on time and distance)
209 if (time - last_touch_time <= guac_mouse.clickTimingThreshold
210 && pixels_moved < guac_mouse.clickMoveThreshold) {
212 // Fire button down event
213 guac_mouse.currentState[button] = true;
214 if (guac_mouse.onmousedown)
215 guac_mouse.onmousedown(guac_mouse.currentState);
217 // Delay mouse up - mouse up should be canceled if
218 // touchstart within timeout.
219 click_release_timeout = window.setTimeout(function() {
221 // Fire button up event
222 guac_mouse.currentState[button] = false;
223 if (guac_mouse.onmouseup)
224 guac_mouse.onmouseup(guac_mouse.currentState);
226 // Allow mouse events now that touching is over
227 gesture_in_progress = false;
229 }, guac_mouse.clickTimingThreshold);
237 element.addEventListener("touchstart", function(e) {
239 // Track number of touches, but no more than three
240 touch_count = Math.min(e.touches.length, 3);
242 // Record initial touch location and time for touch movement
244 if (e.touches.length == 1) {
248 // Stop mouse events while touching
249 gesture_in_progress = true;
251 // Clear timeout, if set
252 if (click_release_timeout) {
253 window.clearTimeout(click_release_timeout);
254 click_release_timeout = null;
257 // Record touch location and time
258 var starting_touch = e.touches[0];
259 last_touch_x = starting_touch.screenX;
260 last_touch_y = starting_touch.screenY;
261 last_touch_time = new Date().getTime();
266 else if (e.touches.length == 2) {
267 var diff_x = e.touches[0].screenX - e.touches[1].screenX;
268 var diff_y = e.touches[0].screenY - e.touches[1].screenY;
269 touch_distance = Math.sqrt(diff_x*diff_x + diff_y*diff_y);
274 element.addEventListener("touchmove", function(e) {
278 // Get change in touch location
279 var touch = e.touches[0];
280 var delta_x = touch.screenX - last_touch_x;
281 var delta_y = touch.screenY - last_touch_y;
283 // Track pixels moved
284 pixels_moved += Math.abs(delta_x) + Math.abs(delta_y);
286 // If only one touch involved, this is mouse move
287 if (touch_count == 1) {
289 // Update mouse location
290 guac_mouse.currentState.x += delta_x;
291 guac_mouse.currentState.y += delta_y;
293 // Prevent mouse from leaving screen
295 if (guac_mouse.currentState.x < 0)
296 guac_mouse.currentState.x = 0;
297 else if (guac_mouse.currentState.x >= element.offsetWidth)
298 guac_mouse.currentState.x = element.offsetWidth - 1;
300 if (guac_mouse.currentState.y < 0)
301 guac_mouse.currentState.y = 0;
302 else if (guac_mouse.currentState.y >= element.offsetHeight)
303 guac_mouse.currentState.y = element.offsetHeight - 1;
305 // Fire movement event, if defined
306 if (guac_mouse.onmousemove)
307 guac_mouse.onmousemove(guac_mouse.currentState);
309 // Update touch location
310 last_touch_x = touch.screenX;
311 last_touch_y = touch.screenY;
315 // Interpret two-finger touch as scrollwheel
316 else if (touch_count == 2) {
318 // If change in location passes threshold for scroll
319 if (Math.abs(delta_y) >= touch_distance * guac_mouse.scrollThreshold) {
321 // Decide button based on Y movement direction
323 if (delta_y > 0) button = "down";
326 // Fire button down event
327 guac_mouse.currentState[button] = true;
328 if (guac_mouse.onmousedown)
329 guac_mouse.onmousedown(guac_mouse.currentState);
331 // Fire button up event
332 guac_mouse.currentState[button] = false;
333 if (guac_mouse.onmouseup)
334 guac_mouse.onmouseup(guac_mouse.currentState);
336 // Only update touch location after a scroll has been
338 last_touch_x = touch.screenX;
339 last_touch_y = touch.screenY;
348 element.addEventListener("mousedown", function(e) {
350 // Don't handle if we aren't supposed to
351 if (gesture_in_progress) return;
357 guac_mouse.currentState.left = true;
360 guac_mouse.currentState.middle = true;
363 guac_mouse.currentState.right = true;
367 if (guac_mouse.onmousedown)
368 guac_mouse.onmousedown(guac_mouse.currentState);
373 element.addEventListener("mouseup", function(e) {
375 // Don't handle if we aren't supposed to
376 if (gesture_in_progress) return;
382 guac_mouse.currentState.left = false;
385 guac_mouse.currentState.middle = false;
388 guac_mouse.currentState.right = false;
392 if (guac_mouse.onmouseup)
393 guac_mouse.onmouseup(guac_mouse.currentState);
397 element.addEventListener("mouseout", function(e) {
399 // Don't handle if we aren't supposed to
400 if (gesture_in_progress) return;
402 // Get parent of the element the mouse pointer is leaving
403 if (!e) e = window.event;
405 // Check that mouseout is due to actually LEAVING the element
406 var target = e.relatedTarget || e.toElement;
407 while (target != null) {
408 if (target === element)
410 target = target.parentNode;
415 // Release all buttons
416 if (guac_mouse.currentState.left
417 || guac_mouse.currentState.middle
418 || guac_mouse.currentState.right) {
420 guac_mouse.currentState.left = false;
421 guac_mouse.currentState.middle = false;
422 guac_mouse.currentState.right = false;
424 if (guac_mouse.onmouseup)
425 guac_mouse.onmouseup(guac_mouse.currentState);
430 // Override selection on mouse event element.
431 element.addEventListener("selectstart", function(e) {
435 // Scroll wheel support
436 function mousewheel_handler(e) {
438 // Don't handle if we aren't supposed to
439 if (gesture_in_progress) return;
444 else if (e.wheelDelta)
445 delta = -event.wheelDelta;
449 if (guac_mouse.onmousedown) {
450 guac_mouse.currentState.up = true;
451 guac_mouse.onmousedown(guac_mouse.currentState);
454 if (guac_mouse.onmouseup) {
455 guac_mouse.currentState.up = false;
456 guac_mouse.onmouseup(guac_mouse.currentState);
462 if (guac_mouse.onmousedown) {
463 guac_mouse.currentState.down = true;
464 guac_mouse.onmousedown(guac_mouse.currentState);
467 if (guac_mouse.onmouseup) {
468 guac_mouse.currentState.down = false;
469 guac_mouse.onmouseup(guac_mouse.currentState);
476 element.addEventListener('DOMMouseScroll', mousewheel_handler, false);
477 element.addEventListener('mousewheel', mousewheel_handler, false);
482 * Simple container for properties describing the state of a mouse.
485 * @param {Number} x The X position of the mouse pointer in pixels.
486 * @param {Number} y The Y position of the mouse pointer in pixels.
487 * @param {Boolean} left Whether the left mouse button is pressed.
488 * @param {Boolean} middle Whether the middle mouse button is pressed.
489 * @param {Boolean} right Whether the right mouse button is pressed.
490 * @param {Boolean} up Whether the up mouse button is pressed (the fourth
491 * button, usually part of a scroll wheel).
492 * @param {Boolean} down Whether the down mouse button is pressed (the fifth
493 * button, usually part of a scroll wheel).
495 Guacamole.Mouse.State = function(x, y, left, middle, right, up, down) {
498 * The current X position of the mouse pointer.
504 * The current Y position of the mouse pointer.
510 * Whether the left mouse button is currently pressed.
516 * Whether the middle mouse button is currently pressed.
522 * Whether the right mouse button is currently pressed.
528 * Whether the up mouse button is currently pressed. This is the fourth
529 * mouse button, associated with upward scrolling of the mouse scroll
536 * Whether the down mouse button is currently pressed. This is the fifth
537 * mouse button, associated with downward scrolling of the mouse scroll