MouseTracker fixes and tests

Separated event-model/device specific event handling code from
event-model/device agnostic event handling code.
Use enter/leave events instead of over/out events.
Updated unit tests for above changes.
Added unit tests for mouse gestures.
Updated changelog for breaking changes and deprecations.

changelog.txt

@@ -7,9 +7,13 @@ OPENSEADRAGON CHANGELOG
     * The drawer element is no longer accessible via viewer.canvas.firstChild but via viewer.drawersContainer.firstChild or viewer.drawer.canvas.
     * The overlays elements are no longer accessible via viewer.canvas.childNodes but via viewer.overlaysContainer.childNodes or viewer.currentOverlays[i].element.
 * BREAKING CHANGE: Pseudo full screen mode on IE<11 using activex has been dropped. OpenSeadragon will run in full page if full screen mode is requested.
+* BREAKING CHANGE: MouseTracker touch pinch gestures are no longer converted to scroll events. MouseTracker.pinchHandler should be used instead. (#369)
+* BREAKING CHANGE: MouseTracker now uses pointer enter/leave DOM events instead of pointer over/out DOM events for generating enterHandler/exitHandler events and for tracking pointers inside the hit-test bounds of the tracked element. (#369)
 * DEPRECATION: overlay functions have been moved from Drawer to Viewer (#331)
 * DEPRECATION: OpenSeadragon.cancelFullScreen has been renamed OpenSeadragon.exitFullScreen (#358)
-* DEPRECATION: The 'isTouchEvent' property passed in MouseTracker events is deprecated and has been replaced with 'pointerType', which is a String value "mouse", "touch", "pen", or "" to support multiple simultaneous pointing devices (#369)
+* DEPRECATION: The 'isTouchEvent' property passed in MouseTracker events is deprecated and has been replaced with 'pointerType', which is a String value "mouse", "touch", "pen", etc. to support multiple simultaneous pointing devices (#369)
+* DEPRECATION: The 'buttonDownAny' property passed in MouseTracker enter and exit events (enterHandler/exitHandler) is deprecated and has been replaced with 'buttons', which indicates the button(s) currently pressed (#369)
+* DEPRECATION: The 'buttonDownAny' property passed in Viewer's 'container-enter' and 'container-exit' events is deprecated and has been replaced with 'buttons', which indicates the button(s) currently pressed (#369)
 * Added layers support. Multiple images can now been displayed on top of each other with transparency via the Viewer.addLayer method (#298)
 * Improved overlay functions (#331)
 * Fixed: Nav button highlight states aren't quite aligned on Firefox (#303)
@@ -28,7 +32,7 @@ OPENSEADRAGON CHANGELOG
 * Added optimization for large numbers of overlays: `checkResize = false` option for OpenSeadragon.Overlay (#365)
 * Updated full screen API, adding support for Opera and IE11 and allowing keyboard input in Chrome (#358)
 * Enhanced MouseTracker for multi-touch (#369)
-    * Added support for multiple touch-points on multiple/simultaneous pointing devices
+    * Added support for tracking multiple touch-points on multiple/simultaneous pointing devices
     * Added support for the W3C Pointer Events event model. Enables touch/multi-touch on IE10+
     * Added a dragEndHandler event callback, called when a drag gesture ends
     * Added a pinchHandler event callback, called as a pinch gesture (2 touch points) is occurring

src/openseadragon.js

@@ -285,24 +285,32 @@
   * @property {Boolean} [gestureSettingsMouse.scrollToZoom=true] - Zoom on scroll gesture
   * @property {Boolean} [gestureSettingsMouse.clickToZoom=true] - Zoom on click gesture
   * @property {Boolean} [gestureSettingsMouse.flickEnabled=false] - Enable flick gesture
-  * @property {Number} [gestureSettingsMouse.flickMinSpeed=20] - Minimum speed to initiate a flick gesture (pixels-per-second)
+  * @property {Number} [gestureSettingsMouse.flickMinSpeed=20] - If flickEnabled is true, the minimum speed to initiate a flick gesture (pixels-per-second)
-  * @property {Number} [gestureSettingsMouse.flickMomentum=0.35] - Momentum factor for the flick gesture
+  * @property {Number} [gestureSettingsMouse.flickMomentum=0.40] - If flickEnabled is true, the momentum factor for the flick gesture
   *
   * @property {OpenSeadragon.GestureSettings} [gestureSettingsTouch]
   *     Settings for gestures generated by a touch pointer device. (See {@link OpenSeadragon.GestureSettings})
   * @property {Boolean} [gestureSettingsTouch.scrollToZoom=false] - Zoom on scroll gesture
   * @property {Boolean} [gestureSettingsTouch.clickToZoom=false] - Zoom on click gesture
   * @property {Boolean} [gestureSettingsTouch.flickEnabled=true] - Enable flick gesture
-  * @property {Number} [gestureSettingsTouch.flickMinSpeed=20] - Minimum speed to initiate a flick gesture (pixels-per-second)
+  * @property {Number} [gestureSettingsTouch.flickMinSpeed=20] - If flickEnabled is true, the minimum speed to initiate a flick gesture (pixels-per-second)
-  * @property {Number} [gestureSettingsTouch.flickMomentum=0.35] - Momentum factor for the flick gesture
+  * @property {Number} [gestureSettingsTouch.flickMomentum=0.40] - If flickEnabled is true, the momentum factor for the flick gesture
   *
   * @property {OpenSeadragon.GestureSettings} [gestureSettingsPen]
   *     Settings for gestures generated by a pen pointer device. (See {@link OpenSeadragon.GestureSettings})
   * @property {Boolean} [gestureSettingsPen.scrollToZoom=false] - Zoom on scroll gesture
   * @property {Boolean} [gestureSettingsPen.clickToZoom=true] - Zoom on click gesture
   * @property {Boolean} [gestureSettingsPen.flickEnabled=false] - Enable flick gesture
-  * @property {Number} [gestureSettingsPen.flickMinSpeed=20] - Minimum speed to initiate a flick gesture (pixels-per-second)
+  * @property {Number} [gestureSettingsPen.flickMinSpeed=20] - If flickEnabled is true, the minimum speed to initiate a flick gesture (pixels-per-second)
-  * @property {Number} [gestureSettingsPen.flickMomentum=0.35] - Momentum factor for the flick gesture
+  * @property {Number} [gestureSettingsPen.flickMomentum=0.40] - If flickEnabled is true, the momentum factor for the flick gesture
+  *
+  * @property {OpenSeadragon.GestureSettings} [gestureSettingsUnknown]
+  *     Settings for gestures generated by unknown pointer devices. (See {@link OpenSeadragon.GestureSettings})
+  * @property {Boolean} [gestureSettingsUnknown.scrollToZoom=true] - Zoom on scroll gesture
+  * @property {Boolean} [gestureSettingsUnknown.clickToZoom=false] - Zoom on click gesture
+  * @property {Boolean} [gestureSettingsUnknown.flickEnabled=true] - Enable flick gesture
+  * @property {Number} [gestureSettingsUnknown.flickMinSpeed=20] - If flickEnabled is true, the minimum speed to initiate a flick gesture (pixels-per-second)
+  * @property {Number} [gestureSettingsUnknown.flickMomentum=0.40] - If flickEnabled is true, the momentum factor for the flick gesture
   *
   * @property {Number} [zoomPerClick=2.0]
   *     The "zoom distance" per mouse click or touch tap. <em><strong>Note:</strong> Setting this to 1.0 effectively disables the click-to-zoom feature (also see gestureSettings[Mouse|Touch|Pen].clickToZoom).</em>
@@ -455,12 +463,12 @@
   *     Set to false to disable the kinetic panning effect (flick) at the end of a drag gesture.
   *
   * @property {Number} flickMinSpeed
-  *     Minimum speed (in pixels-per-second) required to cause the kinetic panning effect (flick) at the end of a drag gesture.
+  *     If flickEnabled is true, the minimum speed (in pixels-per-second) required to cause the kinetic panning effect (flick) at the end of a drag gesture.
   *
   * @property {Number} flickMomentum
-  *     Constant multiplied by the velocity to determine the distance of the kinetic panning effect (flick) at the end of a drag gesture.
+  *     If flickEnabled is true, a constant multiplied by the velocity to determine the distance of the kinetic panning effect (flick) at the end of a drag gesture.
   *     A larger value will make the flick feel "lighter", while a smaller value will make the flick feel "heavier".
-  *     Also, springStiffness and animationTime affect the "spring" used to stop the flick animation.
+  *     Note: springStiffness and animationTime also affect the "spring" used to stop the flick animation.
   *
   */
 
@@ -798,6 +806,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
             gestureSettingsMouse:   { scrollToZoom: true,  clickToZoom: true,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.40 },
             gestureSettingsTouch:   { scrollToZoom: false, clickToZoom: false, flickEnabled: true,  flickMinSpeed: 20, flickMomentum: 0.40 },
             gestureSettingsPen:     { scrollToZoom: false, clickToZoom: true,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.40 },
+            gestureSettingsUnknown: { scrollToZoom: false, clickToZoom: false, flickEnabled: true,  flickMinSpeed: 20, flickMomentum: 0.40 },
             zoomPerClick:           2,
             zoomPerScroll:          1.2,
             zoomPerSecond:          1.0,

src/viewer.js

@@ -278,8 +278,7 @@ $.Viewer = function( options ) {
         // Disable browser default touch handling
         if (style["touch-action"] !== undefined) {
             style["touch-action"] = "none";
-        }
+        } else if (style["-ms-touch-action"] !== undefined) {
-        else if (style["-ms-touch-action"] !== undefined) {
             style["-ms-touch-action"] = "none";
         }
     }(this.canvas.style));
@@ -1776,21 +1775,19 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     /**
      * Gets this viewer's gesture settings for the given pointer device type.
      * @method
-     * @param {String} type - The pointer device type to get the gesture settings for. "mouse", "touch", "pen", or "".
+     * @param {String} type - The pointer device type to get the gesture settings for ("mouse", "touch", "pen", etc.).
      * @return {OpenSeadragon.GestureSettings}
      */
     gestureSettingsByDeviceType: function ( type ) {
-        if ( type === 'mouse' ) {
+        switch ( type ) {
+            case 'mouse':
                 return this.gestureSettingsMouse;
-        }
+            case 'touch':
-        else if ( type === 'touch' ) {
                 return this.gestureSettingsTouch;
-        }
+            case 'pen':
-        else if ( type === 'pen' ) {
                 return this.gestureSettingsPen;
-        }
+            default:
-        else {
+                return this.gestureSettingsUnknown;
-            return { scrollToZoom: false, clickToZoom: false,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.35 };
         }
     }
 
@@ -2472,14 +2469,16 @@ function onContainerExit( event ) {
      * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
      * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
      * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Number} buttons - Current buttons pressed. A combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
      * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
-     * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event.
+     * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. <span style="color:red;">Deprecated. Use buttons instead.</span>
      * @property {Object} originalEvent - The original DOM event.
      * @property {?Object} userData - Arbitrary subscriber-defined object.
      */
     this.raiseEvent( 'container-exit', {
         tracker: event.eventSource,
         position: event.position,
+        buttons: event.buttons,
         insideElementPressed: event.insideElementPressed,
         buttonDownAny: event.buttonDownAny,
         originalEvent: event.originalEvent
@@ -2528,14 +2527,16 @@ function onContainerEnter( event ) {
      * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
      * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
      * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Number} buttons - Current buttons pressed. A combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
      * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
-     * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event.
+     * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. <span style="color:red;">Deprecated. Use buttons instead.</span>
      * @property {Object} originalEvent - The original DOM event.
      * @property {?Object} userData - Arbitrary subscriber-defined object.
      */
     this.raiseEvent( 'container-enter', {
         tracker: event.eventSource,
         position: event.position,
+        buttons: event.buttons,
         insideElementPressed: event.insideElementPressed,
         buttonDownAny: event.buttonDownAny,
         originalEvent: event.originalEvent

test/events.js

@@ -25,184 +25,365 @@
     } );
 
     // ----------
-    asyncTest( 'addHandler without userData', function () {
+    asyncTest( 'MouseTracker: mouse gestures', function () {
-        var openHandler = function ( event ) {
-            viewer.removeHandler( 'open', openHandler );
-            ok( event, 'Event handler received event data' );
-            if ( event ) {
-                strictEqual( event.eventSource, viewer, 'eventSource sent, eventSource is viewer' );
-                strictEqual( event.userData, null, 'User data defaulted to null' );
-            }
-            viewer.close();
-            start();
-        };
-
-        viewer.addHandler( 'open', openHandler );
-        viewer.open( '/test/data/testpattern.dzi' );
-    } );
-
-    // ----------
-    asyncTest( 'addHandler with userData', function () {
-        var userData = { item1: 'Test user data', item2: Math.random() },
-            originalUserData = { item1: userData.item1, item2: userData.item2 };
-
-        var openHandler = function ( event ) {
-            viewer.removeHandler( 'open', openHandler );
-            ok( event, 'Event handler received event data' );
-            ok( event && event.userData, 'Event handler received user data' );
-            if ( event && event.userData ) {
-                deepEqual( event.userData, originalUserData, 'User data was untouched' );
-            }
-            viewer.close();
-            start();
-        };
-
-        viewer.addHandler( 'open', openHandler, userData );
-        viewer.open( '/test/data/testpattern.dzi' );
-    } );
-
-    // ----------
-    asyncTest( 'MouseTracker, EventSource canvas-drag canvas-release canvas-click', function () {
         var $canvas = $( viewer.element ).find( '.openseadragon-canvas' ).not( '.navigator .openseadragon-canvas' ),
-            mouseTracker = null,
+            offset = $canvas.offset(),
-            userData = { item1: 'Test user data', item2: Math.random() },
+            tracker = viewer.innerTracker,
-            originalUserData = { item1: userData.item1, item2: userData.item2 },
+            origEnterHandler,
-            dragCount = 10,
+            origExitHandler,
-            dragsHandledEventSource = 0,
+            origPressHandler,
-            releasesHandledEventSource = 0,
+            origReleaseHandler,
-            clicksHandledEventSource = 0,
+            origMoveHandler,
-            eventsHandledMouseTracker = 0,
+            origClickHandler,
-            eventSourcePassedMouseTracker = 0,
+            origDragHandler,
-            originalEventsPassedMouseTracker = 0,
+            origDragEndHandler,
-            eventsHandledViewer = 0,
+            enterCount,
-            originalEventsPassedViewer = 0,
+            exitCount,
-            releasesExpected = 1,
+            pressCount,
-            clicksExpected = 1;
+            releaseCount,
+            moveCount,
+            clickCount,
+            dragCount,
+            dragEndCount,
+            insideElementPressed,
+            insideElementReleased,
+            quickClick;
+
+        var hookViewerHandlers = function () {
+            origEnterHandler = tracker.enterHandler;
+            tracker.enterHandler = function ( event ) {
+                enterCount++;
+                if (origEnterHandler) {
+                    return origEnterHandler( event );
+                } else {
+                    return true;
+                }
+            };
+            origExitHandler = tracker.exitHandler;
+            tracker.exitHandler = function ( event ) {
+                exitCount++;
+                if (origExitHandler) {
+                    return origExitHandler( event );
+                } else {
+                    return true;
+                }
+            };
+            origPressHandler = tracker.pressHandler;
+            tracker.pressHandler = function ( event ) {
+                pressCount++;
+                if (origPressHandler) {
+                    return origPressHandler( event );
+                } else {
+                    return true;
+                }
+            };
+            origReleaseHandler = tracker.releaseHandler;
+            tracker.releaseHandler = function ( event ) {
+                releaseCount++;
+                insideElementPressed = event.insideElementPressed;
+                insideElementReleased = event.insideElementReleased;
+                if (origReleaseHandler) {
+                    return origReleaseHandler( event );
+                } else {
+                    return true;
+                }
+            };
+            origMoveHandler = tracker.moveHandler;
+            tracker.moveHandler = function ( event ) {
+                moveCount++;
+                if (origMoveHandler) {
+                    return origMoveHandler( event );
+                } else {
+                    return true;
+                }
+            };
+            origClickHandler = tracker.clickHandler;
+            tracker.clickHandler = function ( event ) {
+                clickCount++;
+                quickClick = event.quick;
+                if (origClickHandler) {
+                    return origClickHandler( event );
+                } else {
+                    return true;
+                }
+            };
+            origDragHandler = tracker.dragHandler;
+            tracker.dragHandler = function ( event ) {
+                dragCount++;
+                if (origDragHandler) {
+                    return origDragHandler( event );
+                } else {
+                    return true;
+                }
+            };
+            origDragEndHandler = tracker.dragEndHandler;
+            tracker.dragEndHandler = function ( event ) {
+                dragEndCount++;
+                if (origDragEndHandler) {
+                    return origDragEndHandler( event );
+                } else {
+                    return true;
+                }
+            };
+        };
+
+        var unhookViewerHandlers = function () {
+            tracker.enterHandler = origEnterHandler;
+            tracker.exitHandler = origExitHandler;
+            tracker.pressHandler = origPressHandler;
+            tracker.releaseHandler = origReleaseHandler;
+            tracker.moveHandler = origMoveHandler;
+            tracker.clickHandler = origClickHandler;
+            tracker.dragHandler = origDragHandler;
+            tracker.dragEndHandler = origDragEndHandler;
+        };
+
+        var simulateEnter = function ($element, event, x, y) {
+            event.clientX = offset.left + x;
+            event.clientY = offset.top  + y;
+            $canvas.simulate( 'mouseenter', event );
+        };
+
+        var simulateLeave = function ($element, event, x, y) {
+            event.clientX = offset.left + x;
+            event.clientY = offset.top  + y;
+            $canvas.simulate( 'mouseleave', event );
+        };
+
+        var simulateMove = function ($element, event, dX, dY, count) {
+            var i;
+            for ( i = 0; i < count; i++ ) {
+                event.clientX += dX;
+                event.clientY += dY;
+                $canvas.simulate( 'mousemove', event );
+            }
+        };
+
+        var simulateDown = function ($element, event, x, y) {
+            event.clientX = offset.left + x;
+            event.clientY = offset.top  + y;
+            $canvas.simulate( 'mousedown', event );
+        };
+
+        var simulateUp = function ($element, event, x, y) {
+            event.clientX = offset.left + x;
+            event.clientY = offset.top  + y;
+            $canvas.simulate( 'mouseup', event );
+        };
+
+        var resetForAssessment = function () {
+            enterCount = 0;
+            exitCount = 0;
+            pressCount = 0;
+            releaseCount = 0;
+            moveCount = 0;
+            clickCount = 0;
+            dragCount = 0;
+            dragEndCount = 0;
+            insideElementPressed = false;
+            insideElementReleased = false;
+            quickClick = false;
+        };
+
+        var assessGestureExpectations = function (expected) {
+            var pointersList = tracker.getActivePointersListByType('mouse');
+            if ('enterCount' in expected) {
+                equal( enterCount, expected.enterCount, expected.description + 'enterHandler event count matches expected (' + expected.enterCount + ')' );
+            }
+            if ('exitCount' in expected) {
+                equal( exitCount, expected.exitCount, expected.description + 'exitHandler event count matches expected (' + expected.exitCount + ')' );
+            }
+            if ('pressCount' in expected) {
+                equal( pressCount, expected.pressCount, expected.description + 'pressHandler event count matches expected (' + expected.pressCount + ')' );
+            }
+            if ('releaseCount' in expected) {
+                equal( releaseCount, expected.releaseCount, expected.description + 'releaseHandler event count matches expected (' + expected.releaseCount + ')' );
+            }
+            if ('moveCount' in expected) {
+                equal( moveCount, expected.moveCount, expected.description + 'moveHandler event count matches expected (' + expected.moveCount + ')' );
+            }
+            if ('clickCount' in expected) {
+                equal( clickCount, expected.clickCount, expected.description + 'clickHandler event count matches expected (' + expected.clickCount + ')' );
+            }
+            if ('dragCount' in expected) {
+                equal( dragCount, expected.dragCount, expected.description + 'dragHandler event count matches expected (' + expected.dragCount + ')' );
+            }
+            if ('dragEndCount' in expected) {
+                equal( dragEndCount, expected.dragEndCount, expected.description + 'dragEndHandler event count matches expected (' + expected.dragEndCount + ')' );
+            }
+            if ('insideElementPressed' in expected) {
+                equal( insideElementPressed, expected.insideElementPressed, expected.description + 'releaseHandler event.insideElementPressed matches expected (' + expected.insideElementPressed + ')' );
+            }
+            if ('insideElementReleased' in expected) {
+                equal( insideElementReleased, expected.insideElementReleased, expected.description + 'releaseHandler event.insideElementReleased matches expected (' + expected.insideElementReleased + ')' );
+            }
+            if ('contacts' in expected) {
+                equal( pointersList.contacts, expected.contacts, expected.description + 'Remaining pointer contact count matches expected (' + expected.contacts + ')' );
+            }
+            if ('trackedPointers' in expected) {
+                equal( pointersList.getLength(), expected.trackedPointers, expected.description + 'Remaining tracked pointer count matches expected (' + expected.trackedPointers + ')' );
+            }
+            if ('quickClick' in expected) {
+                equal( quickClick, expected.quickClick, expected.description + 'clickHandler event.quick matches expected (' + expected.quickClick + ')' );
+            }
+        };
 
         var onOpen = function ( event ) {
             viewer.removeHandler( 'open', onOpen );
 
-            viewer.addHandler( 'canvas-drag', onEventSourceDrag );
+            hookViewerHandlers();
-            viewer.addHandler( 'canvas-release', onEventSourceRelease );
-            viewer.addHandler( 'canvas-click', onEventSourceClick );
 
-            mouseTracker = new OpenSeadragon.MouseTracker( {
+            // enter-move-release (release in tracked element, press in unknown element)
-                element: $canvas[0],
+            //   (Note we also test to see if the pointer is still being tracked by not simulating a leave event until after assessment)
-                userData: userData,
+            resetForAssessment();
-                clickTimeThreshold: OpenSeadragon.DEFAULT_SETTINGS.clickTimeThreshold,
+            var event = {};
-                clickDistThreshold: OpenSeadragon.DEFAULT_SETTINGS.clickDistThreshold,
+            simulateEnter($canvas, event, 0, 0);
-                focusHandler: onMouseTrackerFocus,
+            simulateMove($canvas, event, 1, 1, 10);
-                blurHandler: onMouseTrackerBlur,
+            simulateMove($canvas, event, -1, -1, 10);
-                enterHandler: onMouseTrackerEnter,
+            simulateUp($canvas, event, 0, 0);
-                pressHandler: onMouseTrackerPress,
+            assessGestureExpectations({
-                moveHandler: onMouseTrackerMove,
+                description:           'enter-move-release (release in tracked element, press in unknown element):  ',
-                dragHandler: onMouseTrackerDrag,
+                enterCount:            1,
-                releaseHandler: onMouseTrackerRelease,
+                exitCount:             0,
-                clickHandler: onMouseTrackerClick,
+                pressCount:            0,
-                exitHandler: onMouseTrackerExit
+                releaseCount:          1,
-            } ).setTracking( true );
+                moveCount:             20,
+                clickCount:            0,
+                dragCount:             0,
+                dragEndCount:          0,
+                insideElementPressed:  false,
+                insideElementReleased: true,
+                contacts:              0,
+                trackedPointers:       1
+                //quickClick:            false
+            });
+            simulateLeave($canvas, event, -1, -1); // flush tracked pointer
 
-            var event = {
+            // enter-move-exit (fly-over)
-                clientX:1,
+            resetForAssessment();
-                clientY:1
+            var event = {};
-            };
+            simulateEnter($canvas, event, 0, 0);
+            simulateMove($canvas, event, 1, 1, 10);
+            simulateMove($canvas, event, -1, -1, 10);
+            simulateLeave($canvas, event, -1, -1);
+            assessGestureExpectations({
+                description:           'enter-move-exit (fly-over):  ',
+                enterCount:            1,
+                exitCount:             1,
+                pressCount:            0,
+                releaseCount:          0,
+                moveCount:             20,
+                clickCount:            0,
+                dragCount:             0,
+                dragEndCount:          0,
+                //insideElementPressed:  false,
+                //insideElementReleased: false,
+                contacts:              0,
+                trackedPointers:       0
+                //quickClick:            false
+            });
 
-            $canvas.simulate( 'focus', event );
+            // move-exit (fly-over, no enter event)
-            Util.simulateViewerClickWithDrag( {
+            resetForAssessment();
-                viewer: viewer,
+            var event = {};
-                widthFactor: 0.25,
+            simulateMove($canvas, event, 1, 1, 10);
-                heightFactor: 0.25,
+            simulateMove($canvas, event, -1, -1, 10);
-                dragCount: dragCount,
+            simulateLeave($canvas, event, -1, -1);
-                dragDx: 1,
+            assessGestureExpectations({
-                dragDy: 1
+                description:           'move-exit (fly-over, no enter event):  ',
-            } );
+                enterCount:            0,
-            $canvas.simulate( 'blur', event );
+                exitCount:             1,
-        };
+                pressCount:            0,
+                releaseCount:          0,
+                moveCount:             20,
+                clickCount:            0,
+                dragCount:             0,
+                dragEndCount:          0,
+                //insideElementPressed:  false,
+                //insideElementReleased: false,
+                contacts:              0,
+                trackedPointers:       0
+                //quickClick:            false
+            });
 
-        var checkOriginalEventReceivedViewer = function ( event ) {
+            // enter-press-release-exit
-            eventsHandledViewer++;
+            resetForAssessment();
-            //TODO Provide a better check for the original event...simulate doesn't currently extend the object 
+            var event = {};
-            //   with arbitrary user data.
+            simulateEnter($canvas, event, 0, 0);
-            if ( event && event.originalEvent ) {
+            simulateDown($canvas, event, 0, 0);
-                originalEventsPassedViewer++;
+            simulateUp($canvas, event, 0, 0);
-            }
+            simulateLeave($canvas, event, -1, -1);
-        };
+            assessGestureExpectations({
+                description:           'enter-press-release-exit (click):  ',
+                enterCount:            1,
+                exitCount:             1,
+                pressCount:            1,
+                releaseCount:          1,
+                moveCount:             0,
+                clickCount:            1,
+                dragCount:             0,
+                dragEndCount:          0,
+                insideElementPressed:  true,
+                insideElementReleased: true,
+                contacts:              0,
+                trackedPointers:       0,
+                quickClick:            true
+            });
 
-        var onEventSourceDrag = function ( event ) {
+            // enter-press-move-release-move-exit (drag, release in tracked element)
-            checkOriginalEventReceivedViewer( event );
+            resetForAssessment();
-            dragsHandledEventSource++;
+            var event = {};
-        };
+            simulateEnter($canvas, event, 0, 0);
+            simulateDown($canvas, event, 0, 0);
+            simulateMove($canvas, event, 1, 1, 10);
+            simulateUp($canvas, event, 10, 10);
+            simulateMove($canvas, event, -1, -1, 10);
+            simulateLeave($canvas, event, -1, -1);
+            assessGestureExpectations({
+                description:           'enter-press-move-release-move-exit (drag, release in tracked element):  ',
+                enterCount:            1,
+                exitCount:             1,
+                pressCount:            1,
+                releaseCount:          1,
+                moveCount:             20,
+                clickCount:            1,
+                dragCount:             10,
+                dragEndCount:          1,
+                insideElementPressed:  true,
+                insideElementReleased: true,
+                contacts:              0,
+                trackedPointers:       0,
+                quickClick:            false
+            });
 
-        var onEventSourceRelease = function ( event ) {
+            // enter-press-move-exit-move-release (drag, release outside tracked element)
-            checkOriginalEventReceivedViewer( event );
+            resetForAssessment();
-            releasesHandledEventSource++;
+            var event = {};
-        };
+            simulateEnter($canvas, event, 0, 0);
+            simulateDown($canvas, event, 0, 0);
+            simulateMove($canvas, event, 1, 1, 5);
+            simulateMove($canvas, event, -1, -1, 5);
+            simulateLeave($canvas, event, -1, -1);
+            simulateMove($canvas, event, -1, -1, 5);
+            simulateUp($canvas, event, -5, -5);
+            assessGestureExpectations({
+                description:           'enter-press-move-exit-move-release (drag, release outside tracked element):  ',
+                enterCount:            1,
+                exitCount:             1,
+                pressCount:            1,
+                releaseCount:          1,
+                moveCount:             15,
+                clickCount:            0,
+                dragCount:             15,
+                dragEndCount:          1,
+                insideElementPressed:  true,
+                insideElementReleased: false,
+                contacts:              0,
+                trackedPointers:       0,
+                quickClick:            false
+            });
 
-        var onEventSourceClick = function ( event ) {
+            unhookViewerHandlers();
-            checkOriginalEventReceivedViewer( event );
-            clicksHandledEventSource++;
-        };
-
-        var checkOriginalEventReceived = function ( event ) {
-            eventsHandledMouseTracker++;
-            if ( event && event.eventSource === mouseTracker ) {
-                eventSourcePassedMouseTracker++;
-            }
-            //TODO Provide a better check for the original event...simulate doesn't currently extend the object 
-            //   with arbitrary user data.
-            if ( event && event.originalEvent ) {
-                originalEventsPassedMouseTracker++;
-            }
-        };
-
-        var onMouseTrackerFocus = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerBlur = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerEnter = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerPress = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerMove = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerDrag = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerRelease = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerClick = function ( event ) {
-            checkOriginalEventReceived( event );
-        };
-
-        var onMouseTrackerExit = function ( event ) {
-            checkOriginalEventReceived( event );
-
-            mouseTracker.destroy();
-            viewer.removeHandler( 'canvas-drag', onEventSourceDrag );
-            viewer.removeHandler( 'canvas-release', onEventSourceRelease );
-            viewer.removeHandler( 'canvas-click', onEventSourceClick );
-
-            equal( dragsHandledEventSource, dragCount, "'canvas-drag' event count matches 'mousemove' event count (" + dragCount + ")" );
-            equal( releasesHandledEventSource, releasesExpected, "'canvas-release' event count matches expected (" + releasesExpected + ")" );
-            equal( clicksHandledEventSource, releasesExpected, "'canvas-click' event count matches expected (" + releasesExpected + ")" );
-            equal( originalEventsPassedViewer, eventsHandledViewer, "Original event received count matches expected (" + eventsHandledViewer + ")" );
-
-            equal( eventSourcePassedMouseTracker, eventsHandledMouseTracker, "Event source received count matches expected (" + eventsHandledMouseTracker + ")" );
-            equal( originalEventsPassedMouseTracker, eventsHandledMouseTracker, "Original event received count matches expected (" + eventsHandledMouseTracker + ")" );
-            deepEqual( event.userData, originalUserData, 'MouseTracker userData was untouched' );
 
             viewer.close();
             start();
@@ -213,7 +394,7 @@
     } );
 
     // ----------
-    asyncTest( 'MouseTracker preventDefaultAction', function () {
+    asyncTest( 'MouseTracker: preventDefaultAction', function () {
         var $canvas = $( viewer.element ).find( '.openseadragon-canvas' ).not( '.navigator .openseadragon-canvas' ),
             tracker = viewer.innerTracker,
             origClickHandler,
@@ -281,7 +462,209 @@
     } );
 
     // ----------
-    asyncTest( 'tile-drawing event', function () {
+    asyncTest( 'EventSource/MouseTracker/Viewer: event.originalEvent event.userData canvas-drag canvas-drag-end canvas-release canvas-click', function () {
+        var $canvas = $( viewer.element ).find( '.openseadragon-canvas' ).not( '.navigator .openseadragon-canvas' ),
+            mouseTracker = null,
+            userData = { item1: 'Test user data', item2: Math.random() },
+            originalUserData = { item1: userData.item1, item2: userData.item2 },
+            dragCount = 10,
+            dragsHandledEventSource = 0,
+            dragEndsHandledEventSource = 0,
+            releasesHandledEventSource = 0,
+            clicksHandledEventSource = 0,
+            eventsHandledMouseTracker = 0,
+            eventSourcePassedMouseTracker = 0,
+            originalEventsPassedMouseTracker = 0,
+            eventsHandledViewer = 0,
+            originalEventsPassedViewer = 0,
+            dragEndsExpected = 1,
+            releasesExpected = 1,
+            clicksExpected = 1;
+
+        var onOpen = function ( event ) {
+            viewer.removeHandler( 'open', onOpen );
+
+            viewer.addHandler( 'canvas-drag', onEventSourceDrag );
+            viewer.addHandler( 'canvas-drag-end', onEventSourceDragEnd );
+            viewer.addHandler( 'canvas-release', onEventSourceRelease );
+            viewer.addHandler( 'canvas-click', onEventSourceClick );
+
+            mouseTracker = new OpenSeadragon.MouseTracker( {
+                element: $canvas[0],
+                userData: userData,
+                clickTimeThreshold: OpenSeadragon.DEFAULT_SETTINGS.clickTimeThreshold,
+                clickDistThreshold: OpenSeadragon.DEFAULT_SETTINGS.clickDistThreshold,
+                focusHandler: onMouseTrackerFocus,
+                blurHandler: onMouseTrackerBlur,
+                enterHandler: onMouseTrackerEnter,
+                pressHandler: onMouseTrackerPress,
+                moveHandler: onMouseTrackerMove,
+                dragHandler: onMouseTrackerDrag,
+                dragEndHandler: onMouseTrackerDragEnd,
+                releaseHandler: onMouseTrackerRelease,
+                clickHandler: onMouseTrackerClick,
+                exitHandler: onMouseTrackerExit
+            } ).setTracking( true );
+
+            var event = {
+                clientX:1,
+                clientY:1
+            };
+
+            $canvas.simulate( 'focus', event );
+            Util.simulateViewerClickWithDrag( {
+                viewer: viewer,
+                widthFactor: 0.25,
+                heightFactor: 0.25,
+                dragCount: dragCount,
+                dragDx: 1,
+                dragDy: 1
+            } );
+            $canvas.simulate( 'blur', event );
+        };
+
+        var checkOriginalEventReceivedViewer = function ( event ) {
+            eventsHandledViewer++;
+            //TODO Provide a better check for the original event...simulate doesn't currently extend the object 
+            //   with arbitrary user data.
+            if ( event && event.originalEvent ) {
+                originalEventsPassedViewer++;
+            }
+        };
+
+        var onEventSourceDrag = function ( event ) {
+            checkOriginalEventReceivedViewer( event );
+            dragsHandledEventSource++;
+        };
+
+        var onEventSourceDragEnd = function ( event ) {
+            checkOriginalEventReceivedViewer( event );
+            dragEndsHandledEventSource++;
+        };
+
+        var onEventSourceRelease = function ( event ) {
+            checkOriginalEventReceivedViewer( event );
+            releasesHandledEventSource++;
+        };
+
+        var onEventSourceClick = function ( event ) {
+            checkOriginalEventReceivedViewer( event );
+            clicksHandledEventSource++;
+        };
+
+        var checkOriginalEventReceived = function ( event ) {
+            eventsHandledMouseTracker++;
+            if ( event && event.eventSource === mouseTracker ) {
+                eventSourcePassedMouseTracker++;
+            }
+            //TODO Provide a better check for the original event...simulate doesn't currently extend the object 
+            //   with arbitrary user data.
+            if ( event && event.originalEvent ) {
+                originalEventsPassedMouseTracker++;
+            }
+        };
+
+        var onMouseTrackerFocus = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerBlur = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerEnter = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerPress = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerMove = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerDrag = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerDragEnd = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerRelease = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerClick = function ( event ) {
+            checkOriginalEventReceived( event );
+        };
+
+        var onMouseTrackerExit = function ( event ) {
+            checkOriginalEventReceived( event );
+
+            mouseTracker.destroy();
+            viewer.removeHandler( 'canvas-drag', onEventSourceDrag );
+            viewer.removeHandler( 'canvas-release', onEventSourceRelease );
+            viewer.removeHandler( 'canvas-click', onEventSourceClick );
+
+            equal( dragsHandledEventSource, dragCount, "'canvas-drag' event count matches 'mousemove' event count (" + dragCount + ")" );
+            equal( dragEndsHandledEventSource, dragEndsExpected, "'canvas-drag-end' event count matches expected (" + dragEndsExpected + ")" );
+            equal( releasesHandledEventSource, releasesExpected, "'canvas-release' event count matches expected (" + releasesExpected + ")" );
+            equal( clicksHandledEventSource, releasesExpected, "'canvas-click' event count matches expected (" + releasesExpected + ")" );
+            equal( originalEventsPassedViewer, eventsHandledViewer, "Original event received count matches expected (" + eventsHandledViewer + ")" );
+
+            equal( eventSourcePassedMouseTracker, eventsHandledMouseTracker, "Event source received count matches expected (" + eventsHandledMouseTracker + ")" );
+            equal( originalEventsPassedMouseTracker, eventsHandledMouseTracker, "Original event received count matches expected (" + eventsHandledMouseTracker + ")" );
+            deepEqual( event.userData, originalUserData, 'MouseTracker userData was untouched' );
+
+            viewer.close();
+            start();
+        };
+
+        viewer.addHandler( 'open', onOpen );
+        viewer.open( '/test/data/testpattern.dzi' );
+    } );
+
+    // ----------
+    asyncTest( 'Viewer: addHandler without userData', function () {
+        var openHandler = function ( event ) {
+            viewer.removeHandler( 'open', openHandler );
+            ok( event, 'Event handler received event data' );
+            if ( event ) {
+                strictEqual( event.eventSource, viewer, 'eventSource sent, eventSource is viewer' );
+                strictEqual( event.userData, null, 'User data defaulted to null' );
+            }
+            viewer.close();
+            start();
+        };
+
+        viewer.addHandler( 'open', openHandler );
+        viewer.open( '/test/data/testpattern.dzi' );
+    } );
+
+    // ----------
+    asyncTest( 'Viewer: addHandler with userData', function () {
+        var userData = { item1: 'Test user data', item2: Math.random() },
+            originalUserData = { item1: userData.item1, item2: userData.item2 };
+
+        var openHandler = function ( event ) {
+            viewer.removeHandler( 'open', openHandler );
+            ok( event, 'Event handler received event data' );
+            ok( event && event.userData, 'Event handler received user data' );
+            if ( event && event.userData ) {
+                deepEqual( event.userData, originalUserData, 'User data was untouched' );
+            }
+            viewer.close();
+            start();
+        };
+
+        viewer.addHandler( 'open', openHandler, userData );
+        viewer.open( '/test/data/testpattern.dzi' );
+    } );
+
+    // ----------
+    asyncTest( 'Viewer: tile-drawing event', function () {
         var tileDrawing = function ( event ) {
             viewer.removeHandler( 'tile-drawing', tileDrawing );
             ok( event, 'Event handler should be invoked' );

test/legacy.mouse.shim.js

@@ -11,17 +11,18 @@
         $.MouseTracker.subscribeEvents.push( "MozMousePixelScroll" );
     }
 
-    $.MouseTracker.subscribeEvents.push( "mouseover", "mouseout", "mousedown", "mouseup", "mousemove" );
+    $.MouseTracker.subscribeEvents.push( "mouseenter", "mouseleave", "mousedown", "mouseup", "mousemove" );
     if ( 'ontouchstart' in window ) {
         // iOS, Android, and other W3c Touch Event implementations (see http://www.w3.org/TR/2011/WD-touch-events-20110505)
         $.MouseTracker.subscribeEvents.push( "touchstart", "touchend", "touchmove", "touchcancel" );
         if ( 'ontouchenter' in window ) {
             $.MouseTracker.subscribeEvents.push( "touchenter", "touchleave" );
             $.MouseTracker.haveTouchEnter = true;
-        }
+        } else {
-        else {
             $.MouseTracker.haveTouchEnter = false;
         }
+    } else {
+        $.MouseTracker.haveTouchEnter = false;
     }
     if ( 'ongesturestart' in window ) {
         // iOS (see https://developer.apple.com/library/safari/documentation/UserExperience/Reference/GestureEventClassReference/GestureEvent/GestureEvent.html)

test/navigator.js

@@ -189,7 +189,7 @@ QUnit.config.autostart = false;
                 clientY:offset.top + locationY
             };
         $canvas
-            .simulate('mouseover', event)
+            .simulate('mouseenter', event)
             .simulate('mousedown', event)
             .simulate('mouseup', event);
     };

test/test.js

@@ -37,7 +37,7 @@
             };
 
             $canvas
-                .simulate( 'mouseover', event )
+                .simulate( 'mouseenter', event )
                 .simulate( 'mousedown', event );
             for ( var i = 0; i < args.dragCount; i++ ) {
                 event.clientX += args.dragDx;
@@ -47,7 +47,7 @@
             }
             $canvas
                 .simulate( 'mouseup', event )
-                .simulate( 'mouseout', event );
+                .simulate( 'mouseleave', event );
         },
 
         initializeTestDOM: function () {