Upgrade to ExtJS 4.0.2 - Released 06/09/2011

[extjs.git] / docs / source / EventObject.html

diff --git a/docs/source/EventObject.html b/docs/source/EventObject.html
index d163da7..4a9037e 100644 (file)
--- a/docs/source/EventObject.html
+++ b/docs/source/EventObject.html
@@ -221,6 +221,54 @@ Ext.define('Ext.EventObjectImpl', {
 </span>    F11: 122,
 <span id='Ext-EventObject-property-F12'>    /** Key constant @type Number */
 </span>    F12: 123,
+<span id='Ext-EventObject-property-WHEEL_SCALE'>    /**
+</span>     * The mouse wheel delta scaling factor. This value depends on browser version and OS and
+     * attempts to produce a similar scrolling experience across all platforms and browsers.
+     * 
+     * To change this value:
+     * 
+     *      Ext.EventObjectImpl.prototype.WHEEL_SCALE = 72;
+     * 
+     * @type Number
+     * @markdown
+     */
+    WHEEL_SCALE: (function () {
+        var scale;
+
+        if (Ext.isGecko) {
+            // Firefox uses 3 on all platforms
+            scale = 3;
+        } else if (Ext.isMac) {
+            // Continuous scrolling devices have momentum and produce much more scroll than
+            // discrete devices on the same OS and browser. To make things exciting, Safari
+            // (and not Chrome) changed from small values to 120 (like IE).
+
+            if (Ext.isSafari &amp;&amp; Ext.webKitVersion &gt;= 532.0) {
+                // Safari changed the scrolling factor to match IE (for details see
+                // https://bugs.webkit.org/show_bug.cgi?id=24368). The WebKit version where this
+                // change was introduced was 532.0
+                //      Detailed discussion:
+                //      https://bugs.webkit.org/show_bug.cgi?id=29601
+                //      http://trac.webkit.org/browser/trunk/WebKit/chromium/src/mac/WebInputEventFactory.mm#L1063
+                scale = 120;
+            } else {
+                // MS optical wheel mouse produces multiples of 12 which is close enough
+                // to help tame the speed of the continuous mice...
+                scale = 12;
+            }
+
+            // Momentum scrolling produces very fast scrolling, so increase the scale factor
+            // to help produce similar results cross platform. This could be even larger and
+            // it would help those mice, but other mice would become almost unusable as a
+            // result (since we cannot tell which device type is in use).
+            scale *= 3;
+        } else {
+            // IE, Opera and other Windows browsers use 120.
+            scale = 120;
+        }
+
+        return scale;
+    })(),
 
 <span id='Ext-EventObject-property-clickRe'>    /**
 </span>     * Simple click regex
@@ -434,20 +482,69 @@ Ext.define('Ext.EventObjectImpl', {
         return returnEl ? Ext.get(this.relatedTarget) : this.relatedTarget;
     },
 
+<span id='Ext-EventObject-method-correctWheelDelta'>    /**
+</span>     * Correctly scales a given wheel delta.
+     * @param {Number} delta The delta value.
+     */
+    correctWheelDelta : function (delta) {
+        var scale = this.WHEEL_SCALE,
+            ret = Math.round(delta / scale + 0.5);
+
+        if (!ret &amp;&amp; delta) {
+            ret = (delta &lt; 0) ? -1 : 1; // don't allow non-zero deltas to go to zero!
+        }
+
+        return ret;
+    },
+
+<span id='Ext-EventObject-method-getWheelDeltas'>    /**
+</span>     * Returns the mouse wheel deltas for this event.
+     * @return {Object} An object with &quot;x&quot; and &quot;y&quot; properties holding the mouse wheel deltas.
+     */
+    getWheelDeltas : function () {
+        var me = this,
+            event = me.browserEvent,
+            dx = 0, dy = 0; // the deltas
+
+        if (Ext.isDefined(event.wheelDeltaX)) { // WebKit has both dimensions
+            dx = event.wheelDeltaX;
+            dy = event.wheelDeltaY;
+        } else if (event.wheelDelta) { // old WebKit and IE
+            dy = event.wheelDelta;
+        } else if (event.detail) { // Gecko
+            dy = -event.detail; // gecko is backwards
+
+            // Gecko sometimes returns really big values if the user changes settings to
+            // scroll a whole page per scroll
+            if (dy &gt; 100) {
+                dy = 3;
+            } else if (dy &lt; -100) {
+                dy = -3;
+            }
+
+            // Firefox 3.1 adds an axis field to the event to indicate direction of
+            // scroll.  See https://developer.mozilla.org/en/Gecko-Specific_DOM_Events
+            if (Ext.isDefined(event.axis) &amp;&amp; event.axis === event.HORIZONTAL_AXIS) {
+                dx = dy;
+                dy = 0;
+            }
+        }
+
+        return {
+            x: me.correctWheelDelta(dx),
+            y: me.correctWheelDelta(dy)
+        };
+    },
+
 <span id='Ext-EventObject-method-getWheelDelta'>    /**
-</span>     * Normalizes mouse wheel delta across browsers
-     * @return {Number} The delta
+</span>     * Normalizes mouse wheel y-delta across browsers. To get x-delta information, use
+     * {@link #getWheelDeltas} instead.
+     * @return {Number} The mouse wheel y-delta
      */
     getWheelDelta : function(){
-        var event = this.browserEvent,
-            delta = 0;
+        var deltas = this.getWheelDeltas();
 
-        if (event.wheelDelta) { /* IE/Opera. */
-            delta = event.wheelDelta / 120;
-        } else if (event.detail){ /* Mozilla case. */
-            delta = -event.detail / 3;
-        }
-        return delta;
+        return deltas.y;
     },
 
 <span id='Ext-EventObject-method-within'>    /**
@@ -637,7 +734,7 @@ Ext.getBody().on('click', function(e,t){
 
                     return target;
                 }
-            }
+            };
         } else if (document.createEventObject) { // else if (IE)
             var crazyIEButtons = { 0: 1, 1: 4, 2: 2 };