Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / EventObject.html
index d163da7..55b2d1c 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
@@ -18,7 +18,7 @@
   <pre class="prettyprint lang-js"><span id='Ext-EventObject'>/**
 </span> * @class Ext.EventObject
 
-Just as {@link Ext.core.Element} wraps around a native DOM node, Ext.EventObject
+Just as {@link Ext.Element} wraps around a native DOM node, Ext.EventObject
 wraps the browser's native event-object normalizing cross-browser differences,
 such as which mouse button is clicked, keys pressed, mechanisms to stop
 event-propagation along with a method to prevent default actions from taking place.
@@ -31,7 +31,7 @@ For example:
         ...
     }
 
-    var myDiv = {@link Ext#get Ext.get}(&quot;myDiv&quot;);  // get reference to an {@link Ext.core.Element}
+    var myDiv = {@link Ext#get Ext.get}(&quot;myDiv&quot;);  // get reference to an {@link Ext.Element}
     myDiv.on(         // 'on' is shorthand for addListener
         &quot;click&quot;,      // perform an action on click of myDiv
         handleClick   // reference to the action handler
@@ -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
@@ -377,15 +425,15 @@ Ext.define('Ext.EventObjectImpl', {
     getPageY: function(){
         return this.getY();
     },
-    
+
 <span id='Ext-EventObject-method-getX'>    /**
 </span>     * Gets the x coordinate of the event.
      * @return {Number}
      */
     getX: function() {
         return this.getXY()[0];
-    },    
-    
+    },
+
 <span id='Ext-EventObject-method-getY'>    /**
 </span>     * Gets the y coordinate of the event.
      * @return {Number}
@@ -393,10 +441,10 @@ Ext.define('Ext.EventObjectImpl', {
     getY: function() {
         return this.getXY()[1];
     },
-        
+
 <span id='Ext-EventObject-method-getXY'>    /**
 </span>     * Gets the page coordinates of the event.
-     * @return {Array} The xy values like [x, y]
+     * @return {Number[]} The xy values like [x, y]
      */
     getXY: function() {
         if (!this.xy) {
@@ -409,9 +457,9 @@ Ext.define('Ext.EventObjectImpl', {
 <span id='Ext-EventObject-method-getTarget'>    /**
 </span>     * Gets the target for the event.
      * @param {String} selector (optional) A simple selector to filter the target or look for an ancestor of the target
-     * @param {Number/Mixed} maxDepth (optional) The max depth to search as a number or element (defaults to 10 || document.body)
-     * @param {Boolean} returnEl (optional) True to return a Ext.core.Element object instead of DOM node
-     * @return {HTMLelement}
+     * @param {Number/HTMLElement} maxDepth (optional) The max depth to search as a number or element (defaults to 10 || document.body)
+     * @param {Boolean} returnEl (optional) True to return a Ext.Element object instead of DOM node
+     * @return {HTMLElement}
      */
     getTarget : function(selector, maxDepth, returnEl){
         if (selector) {
@@ -423,8 +471,8 @@ Ext.define('Ext.EventObjectImpl', {
 <span id='Ext-EventObject-method-getRelatedTarget'>    /**
 </span>     * Gets the related target.
      * @param {String} selector (optional) A simple selector to filter the target or look for an ancestor of the target
-     * @param {Number/Mixed} maxDepth (optional) The max depth to search as a number or element (defaults to 10 || document.body)
-     * @param {Boolean} returnEl (optional) True to return a Ext.core.Element object instead of DOM node
+     * @param {Number/HTMLElement} maxDepth (optional) The max depth to search as a number or element (defaults to 10 || document.body)
+     * @param {Boolean} returnEl (optional) True to return a Ext.Element object instead of DOM node
      * @return {HTMLElement}
      */
     getRelatedTarget : function(selector, maxDepth, returnEl){
@@ -434,25 +482,74 @@ 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);
+
+        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'>    /**
-</span>    * Returns true if the target of this event is a child of el.  Unless the allowEl parameter is set, it will return false if if the target is el.
-    * Example usage:&lt;pre&gt;&lt;code&gt;
+</span>     * Returns true if the target of this event is a child of el.  Unless the allowEl parameter is set, it will return false if if the target is el.
+     * Example usage:&lt;pre&gt;&lt;code&gt;
 // Handle click on any child of an element
 Ext.getBody().on('click', function(e){
     if(e.within('some-el')){
@@ -467,9 +564,9 @@ Ext.getBody().on('click', function(e,t){
     }
 });
 &lt;/code&gt;&lt;/pre&gt;
-     * @param {Mixed} el The id, DOM element or Ext.core.Element to check
+     * @param {String/HTMLElement/Ext.Element} el The id, DOM element or Ext.Element to check
      * @param {Boolean} related (optional) true to test if the related target is within el instead of the target
-     * @param {Boolean} allowEl {optional} true to also check if the passed element is the target or related target
+     * @param {Boolean} allowEl (optional) true to also check if the passed element is the target or related target
      * @return {Boolean}
      */
     within : function(el, related, allowEl){
@@ -565,7 +662,7 @@ Ext.getBody().on('click', function(e,t){
      * &lt;li&gt;focus&lt;/li&gt;
      * &lt;li&gt;blur&lt;/li&gt;
      * &lt;/ul&gt;
-     * @param {Element/HTMLElement} target If specified, the target for the event. This
+     * @param {Ext.Element/HTMLElement} target (optional) If specified, the target for the event. This
      * is likely to be used when relaying a DOM event. If not specified, {@link #getTarget}
      * is used to determine the target.
      */
@@ -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 };