Changelog, documentation, options update

changelog.txt

@@ -33,6 +33,14 @@ OPENSEADRAGON CHANGELOG
     * 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
     * Added real-time velocity (speed and direction) tracking to drag operations. 'speed' and 'direction' values are passed in the dragHandler and dragEndHandler event data
+* Enhanced Viewer for multi-touch (#369)
+    * Added pinch zoom with the new MouseTracker pinchHandler
+    * Added a "canvas-pinch" event fired by the pinch event handler
+    * Added flick gesture with the new MouseTracker dragEndHandler
+    * Added a "canvas-drag-end" event fired by the drag-end event handler
+    * Added a GestureSettings class for per-device gesture options. Currently has settings to enable/disable zoom-on-scroll, zoom-on-click, and flick gesture settings.
+    * Added GestureSettings objects for mouse, touch, and pen devices to the Viewer options giving users the ability to customize gesture handling in the viewer
+    * Added velocity (speed and direction) properties to the "canvas-drag" event
 
 1.0.0:
 

src/openseadragon.js

@@ -282,6 +282,7 @@
   *
   * @property {OpenSeadragon.GestureSettings} [gestureSettingsMouse]
   *     Settings for gestures generated by a mouse pointer device. (See {@link OpenSeadragon.GestureSettings})
+  * @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)
@@ -289,6 +290,7 @@
   *
   * @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)
@@ -296,16 +298,17 @@
   *
   * @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.flickMomentum=0.35] - 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 {@link OpenSeadragon.GestureSettings.clickToZoom}).</em>
+  *     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>
   *
   * @property {Number} [zoomPerScroll=1.2]
-  *     The "zoom distance" per mouse scroll or touch pinch. <em><strong>Note:</strong> Setting this to 1.0 effectively disables the mouse-wheel zoom feature.</em>
+  *     The "zoom distance" per mouse scroll or touch pinch. <em><strong>Note:</strong> Setting this to 1.0 effectively disables the mouse-wheel zoom feature (also see gestureSettings[Mouse|Touch|Pen].scrollToZoom}).</em>
   *
   * @property {Number} [zoomPerSecond=1.0]
   *     The number of seconds to animate a single zoom event over.
@@ -442,6 +445,9 @@
   * @typedef {Object} GestureSettings
   * @memberof OpenSeadragon
   *
+  * @property {Boolean} scrollToZoom
+  *     Set to false to disable zooming on scroll gestures.
+  *
   * @property {Boolean} clickToZoom
   *     Set to false to disable zooming on click gestures.
   *
@@ -789,9 +795,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
             clickDistThreshold:     5,
             springStiffness:        5.0,
             animationTime:          1.2,
-            gestureSettingsMouse:   { clickToZoom: true,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.40 },
+            gestureSettingsMouse:   { scrollToZoom: true,  clickToZoom: true,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.40 },
-            gestureSettingsTouch:   { clickToZoom: false, flickEnabled: true,  flickMinSpeed: 20, flickMomentum: 0.40 },
+            gestureSettingsTouch:   { scrollToZoom: false, clickToZoom: false, flickEnabled: true,  flickMinSpeed: 20, flickMomentum: 0.40 },
-            gestureSettingsPen:     { clickToZoom: true,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.40 },
+            gestureSettingsPen:     { scrollToZoom: false, clickToZoom: true,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.40 },
             zoomPerClick:           2,
             zoomPerScroll:          1.2,
             zoomPerSecond:          1.0,

src/viewer.js

@@ -1790,7 +1790,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
             return this.gestureSettingsPen;
         }
         else {
-            return { clickToZoom: false,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.35 };
+            return { scrollToZoom: false, clickToZoom: false,  flickEnabled: false, flickMinSpeed: 20, flickMomentum: 0.35 };
         }
     }
 
@@ -2417,14 +2417,19 @@ function onCanvasPinch( event ) {
 }
 
 function onCanvasScroll( event ) {
-    var factor;
+    var gestureSettings,
+        factor;
+
     if ( !event.preventDefaultAction && this.viewport ) {
-        factor = Math.pow( this.zoomPerScroll, event.scroll );
+        gestureSettings = this.gestureSettingsByDeviceType( event.pointerType );
-        this.viewport.zoomBy(
+        if ( gestureSettings.scrollToZoom ) {
-            factor,
+            factor = Math.pow( this.zoomPerScroll, event.scroll );
-            this.viewport.pointFromPixel( event.position, true )
+            this.viewport.zoomBy(
-        );
+                factor,
-        this.viewport.applyConstraints();
+                this.viewport.pointFromPixel( event.position, true )
+            );
+            this.viewport.applyConstraints();
+        }
     }
     /**
      * Raised when a scroll event occurs on the {@link OpenSeadragon.Viewer#canvas} element (mouse wheel).