X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..HEAD:/docs/source/DragTracker.html diff --git a/docs/source/DragTracker.html b/docs/source/DragTracker.html index 2e834a26..ccd84a0e 100644 --- a/docs/source/DragTracker.html +++ b/docs/source/DragTracker.html @@ -1,4 +1,21 @@ -Sencha Documentation Project
/**
+
+
+
+  
+  The source code
+  
+  
+  
+  
+
+
+  
/**
  * @class Ext.dd.DragTracker
  * A DragTracker listens for drag events on an Element and fires events at the start and end of the drag,
  * as well as during the drag. This is useful for components such as {@link Ext.slider.Multi}, where there is
@@ -15,23 +32,21 @@ Ext.define('Ext.dd.DragTracker', {
         observable: 'Ext.util.Observable'
     },
 
-    /**
-     * @property active
-     * @type Boolean
+    /**
+     * @property {Boolean} active
      * Read-only property indicated whether the user is currently dragging this
      * tracker.
      */
     active: false,
 
-    /**
-     * @property dragTarget
-     * @type HtmlElement
+    /**
+     * @property {HTMLElement} dragTarget
      * <p><b>Only valid during drag operations. Read-only.</b></p>
      * <p>The element being dragged.</p>
      * <p>If the {@link #delegate} option is used, this will be the delegate element which was mousedowned.</p>
      */
 
-    /**
+    /**
      * @cfg {Boolean} trackOver
      * <p>Defaults to <code>false</code>. Set to true to fire mouseover and mouseout events when the mouse enters or leaves the target element.</p>
      * <p>This is implicitly set when an {@link #overCls} is specified.</p>
@@ -39,47 +54,47 @@ Ext.define('Ext.dd.DragTracker', {
      */
     trackOver: false,
 
-    /**
+    /**
      * @cfg {String} overCls
      * <p>A CSS class to add to the DragTracker's target element when the element (or, if the {@link #delegate} option is used,
      * when a delegate element) is mouseovered.</p>
      * <b>If the {@link #delegate} option is used, these events fire only when a delegate element is entered of left.</b>.
      */
 
-    /**
-     * @cfg {Ext.util.Region/Element} constrainTo
+    /**
+     * @cfg {Ext.util.Region/Ext.Element} constrainTo
      * <p>A {@link Ext.util.Region Region} (Or an element from which a Region measurement will be read) which is used to constrain
      * the result of the {@link #getOffset} call.</p>
      * <p>This may be set any time during the DragTracker's lifecycle to set a dynamic constraining region.</p>
      */
 
-    /**
+    /**
      * @cfg {Number} tolerance
      * Number of pixels the drag target must be moved before dragging is
      * considered to have started. Defaults to <code>5</code>.
      */
     tolerance: 5,
 
-    /**
+    /**
      * @cfg {Boolean/Number} autoStart
      * Defaults to <code>false</code>. Specify <code>true</code> to defer trigger start by 1000 ms.
      * Specify a Number for the number of milliseconds to defer trigger start.
      */
     autoStart: false,
 
-    /**
+    /**
      * @cfg {String} delegate
      * Optional. <p>A {@link Ext.DomQuery DomQuery} selector which identifies child elements within the DragTracker's encapsulating
      * Element which are the tracked elements. This limits tracking to only begin when the matching elements are mousedowned.</p>
      * <p>This may also be a specific child element within the DragTracker's encapsulating element to use as the tracked element.</p>
      */
 
-    /**
+    /**
      * @cfg {Boolean} preventDefault
      * Specify <code>false</code> to enable default actions on onMouseDown events. Defaults to <code>true</code>.
      */
 
-    /**
+    /**
      * @cfg {Boolean} stopEvent
      * Specify <code>true</code> to stop the <code>mousedown</code> event from bubbling to outer listeners from the target element (or its delegates). Defaults to <code>false</code>.
      */
@@ -87,17 +102,17 @@ Ext.define('Ext.dd.DragTracker', {
     constructor : function(config){
         Ext.apply(this, config);
         this.addEvents(
-            /**
+            /**
              * @event mouseover <p><b>Only available when {@link #trackOver} is <code>true</code></b></p>
              * <p>Fires when the mouse enters the DragTracker's target element (or if {@link #delegate} is
              * used, when the mouse enters a delegate element).</p>
              * @param {Object} this
              * @param {Object} e event object
-             * @param {HtmlElement} target The element mouseovered.
+             * @param {HTMLElement} target The element mouseovered.
              */
             'mouseover',
 
-            /**
+            /**
              * @event mouseout <p><b>Only available when {@link #trackOver} is <code>true</code></b></p>
              * <p>Fires when the mouse exits the DragTracker's target element (or if {@link #delegate} is
              * used, when the mouse exits a delegate element).</p>
@@ -106,7 +121,7 @@ Ext.define('Ext.dd.DragTracker', {
              */
             'mouseout',
 
-            /**
+            /**
              * @event mousedown <p>Fires when the mouse button is pressed down, but before a drag operation begins. The
              * drag operation begins after either the mouse has been moved by {@link #tolerance} pixels, or after
              * the {@link #autoStart} timer fires.</p>
@@ -116,35 +131,42 @@ Ext.define('Ext.dd.DragTracker', {
              */
             'mousedown',
 
-            /**
+            /**
              * @event mouseup
              * @param {Object} this
              * @param {Object} e event object
              */
             'mouseup',
 
-            /**
+            /**
              * @event mousemove Fired when the mouse is moved. Returning false cancels the drag operation.
              * @param {Object} this
              * @param {Object} e event object
              */
             'mousemove',
 
-            /**
+            /**
+             * @event beforestart
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'beforedragstart',
+
+            /**
              * @event dragstart
              * @param {Object} this
              * @param {Object} e event object
              */
             'dragstart',
 
-            /**
+            /**
              * @event dragend
              * @param {Object} this
              * @param {Object} e event object
              */
             'dragend',
 
-            /**
+            /**
              * @event drag
              * @param {Object} this
              * @param {Object} e event object
@@ -166,9 +188,9 @@ Ext.define('Ext.dd.DragTracker', {
 
     },
 
-    /**
+    /**
      * Initializes the DragTracker on a given element.
-     * @param {Ext.core.Element/HTMLElement} el The element
+     * @param {Ext.Element/HTMLElement} el The element
      */
     initEl: function(el) {
         this.el = Ext.get(el);
@@ -256,27 +278,30 @@ Ext.define('Ext.dd.DragTracker', {
         this.startXY = this.lastXY = e.getXY();
         this.startRegion = Ext.fly(this.dragTarget).getRegion();
 
-        if (this.fireEvent('mousedown', this, e) !== false && this.onBeforeStart(e) !== false) {
+        if (this.fireEvent('mousedown', this, e) === false ||
+            this.fireEvent('beforedragstart', this, e) === false ||
+            this.onBeforeStart(e) === false) {
+            return;
+        }
 
-            // Track when the mouse is down so that mouseouts while the mouse is down are not processed.
-            // The onMouseOut method will only ever be called after mouseup.
-            this.mouseIsDown = true;
+        // Track when the mouse is down so that mouseouts while the mouse is down are not processed.
+        // The onMouseOut method will only ever be called after mouseup.
+        this.mouseIsDown = true;
 
-            // Flag for downstream DragTracker instances that the mouse is being tracked.
-            e.dragTracked = true;
+        // Flag for downstream DragTracker instances that the mouse is being tracked.
+        e.dragTracked = true;
 
-            if (this.preventDefault !== false) {
-                e.preventDefault();
-            }
-            Ext.getDoc().on({
-                scope: this,
-                mouseup: this.onMouseUp,
-                mousemove: this.onMouseMove,
-                selectstart: this.stopSelect
-            });
-            if (this.autoStart) {
-                this.timer =  Ext.defer(this.triggerStart, this.autoStart === true ? 1000 : this.autoStart, this, [e]);
-            }
+        if (this.preventDefault !== false) {
+            e.preventDefault();
+        }
+        Ext.getDoc().on({
+            scope: this,
+            mouseup: this.onMouseUp,
+            mousemove: this.onMouseMove,
+            selectstart: this.stopSelect
+        });
+        if (this.autoStart) {
+            this.timer =  Ext.defer(this.triggerStart, this.autoStart === true ? 1000 : this.autoStart, this, [e]);
         }
     },
 
@@ -302,7 +327,7 @@ Ext.define('Ext.dd.DragTracker', {
             }
         }
 
-        // Returning false from a mousemove listener deactivates 
+        // Returning false from a mousemove listener deactivates
         if (this.fireEvent('mousemove', this, e) === false) {
             this.onMouseUp(e);
         } else {
@@ -316,9 +341,6 @@ Ext.define('Ext.dd.DragTracker', {
         // is lifted if the mouseout happens *during* a drag.
         this.mouseIsDown = false;
 
-        // Remove flag from event singleton
-        delete e.dragTracked;
-
         // If we mouseouted the el *during* the drag, the onMouseOut method will not have fired. Ensure that it gets processed.
         if (this.mouseIsOut) {
             this.mouseIsOut = false;
@@ -329,7 +351,7 @@ Ext.define('Ext.dd.DragTracker', {
         this.endDrag(e);
     },
 
-    /**
+    /**
      * @private
      * Stop the drag operation, and remove active mouse listeners.
      */
@@ -348,6 +370,9 @@ Ext.define('Ext.dd.DragTracker', {
         }
         // Private property calculated when first required and only cached during a drag
         delete this._constrainRegion;
+
+        // Remove flag from event singleton.  Using "Ext.EventObject" here since "endDrag" is called directly in some cases without an "e" param
+        delete Ext.EventObject.dragTracked;
     },
 
     triggerStart: function(e) {
@@ -369,60 +394,64 @@ Ext.define('Ext.dd.DragTracker', {
         return false;
     },
 
-    /**
+    /**
      * Template method which should be overridden by each DragTracker instance. Called when the user first clicks and
      * holds the mouse button down. Return false to disallow the drag
      * @param {Ext.EventObject} e The event object
+     * @template
      */
     onBeforeStart : function(e) {
 
     },
 
-    /**
+    /**
      * Template method which should be overridden by each DragTracker instance. Called when a drag operation starts
      * (e.g. the user has moved the tracked element beyond the specified tolerance)
      * @param {Ext.EventObject} e The event object
+     * @template
      */
     onStart : function(xy) {
 
     },
 
-    /**
+    /**
      * Template method which should be overridden by each DragTracker instance. Called whenever a drag has been detected.
      * @param {Ext.EventObject} e The event object
+     * @template
      */
     onDrag : function(e) {
 
     },
 
-    /**
+    /**
      * Template method which should be overridden by each DragTracker instance. Called when a drag operation has been completed
      * (e.g. the user clicked and held the mouse down, dragged the element and then released the mouse button)
      * @param {Ext.EventObject} e The event object
+     * @template
      */
     onEnd : function(e) {
 
     },
 
-    /**
+    /**
      * </p>Returns the drag target. This is usually the DragTracker's encapsulating element.</p>
      * <p>If the {@link #delegate} option is being used, this may be a child element which matches the
      * {@link #delegate} selector.</p>
-     * @return {Ext.core.Element} The element currently being tracked.
+     * @return {Ext.Element} The element currently being tracked.
      */
     getDragTarget : function(){
         return this.dragTarget;
     },
 
-    /**
+    /**
      * @private
-     * @returns {Element} The DragTracker's encapsulating element.
+     * @returns {Ext.Element} The DragTracker's encapsulating element.
      */
     getDragCt : function(){
         return this.el;
     },
 
-    /**
+    /**
      * @private
      * Return the Region into which the drag operation is constrained.
      * Either the XY pointer itself can be constrained, or the dragTarget element
@@ -445,23 +474,25 @@ Ext.define('Ext.dd.DragTracker', {
     },
 
     getXY : function(constrain){
-        return constrain ? this.constrainModes[constrain].call(this, this.lastXY) : this.lastXY;
+        return constrain ? this.constrainModes[constrain](this, this.lastXY) : this.lastXY;
     },
 
-    /**
-     * <p>Returns the X, Y offset of the current mouse position from the mousedown point.</p>
-     * <p>This method may optionally constrain the real offset values, and returns a point coerced in one
-     * of two modes:</p><ul>
-     * <li><code>point</code><div class="sub-desc">The current mouse position is coerced into the
-     * {@link #constrainRegion}, and the resulting position is returned.</div></li>
-     * <li><code>dragTarget</code><div class="sub-desc">The new {@link Ext.util.Region Region} of the
-     * {@link #getDragTarget dragTarget} is calculated based upon the current mouse position, and then
-     * coerced into the {@link #constrainRegion}. The returned mouse position is then adjusted by the
-     * same delta as was used to coerce the region.</div></li>
-     * </ul>
-     * @param constrainMode {String} Optional. If omitted the true mouse position is returned. May be passed
-     * as <code>'point'</code> or <code>'dragTarget'. See above.</code>.
-     * @returns {Array} The <code>X, Y</code> offset from the mousedown point, optionally constrained.
+    /**
+     * Returns the X, Y offset of the current mouse position from the mousedown point.
+     *
+     * This method may optionally constrain the real offset values, and returns a point coerced in one
+     * of two modes:
+     *
+     *  - `point`
+     *    The current mouse position is coerced into the constrainRegion and the resulting position is returned.
+     *  - `dragTarget`
+     *    The new {@link Ext.util.Region Region} of the {@link #getDragTarget dragTarget} is calculated
+     *    based upon the current mouse position, and then coerced into the constrainRegion. The returned
+     *    mouse position is then adjusted by the same delta as was used to coerce the region.\
+     *
+     * @param constrainMode {String} (Optional) If omitted the true mouse position is returned. May be passed
+     * as `point` or `dragTarget`. See above.
+     * @returns {Number[]} The `X, Y` offset from the mousedown point, optionally constrained.
      */
     getOffset : function(constrain){
         var xy = this.getXY(constrain),
@@ -472,9 +503,9 @@ Ext.define('Ext.dd.DragTracker', {
 
     constrainModes: {
         // Constrain the passed point to within the constrain region
-        point: function(xy) {
-            var dr = this.dragRegion,
-                constrainTo = this.getConstrainRegion();
+        point: function(me, xy) {
+            var dr = me.dragRegion,
+                constrainTo = me.getConstrainRegion();
 
             // No constraint
             if (!constrainTo) {
@@ -489,10 +520,10 @@ Ext.define('Ext.dd.DragTracker', {
         },
 
         // Constrain the dragTarget to within the constrain region. Return the passed xy adjusted by the same delta.
-        dragTarget: function(xy) {
-            var s = this.startXY,
-                dr = this.startRegion.copy(),
-                constrainTo = this.getConstrainRegion(),
+        dragTarget: function(me, xy) {
+            var s = me.startXY,
+                dr = me.startRegion.copy(),
+                constrainTo = me.getConstrainRegion(),
                 adjust;
 
             // No constraint
@@ -503,7 +534,7 @@ Ext.define('Ext.dd.DragTracker', {
             // See where the passed XY would put the dragTarget if translated by the unconstrained offset.
             // If it overflows, we constrain the passed XY to bring the potential
             // region back within the boundary.
-            dr.translateBy.apply(dr, [xy[0]-s[0], xy[1]-s[1]]);
+            dr.translateBy(xy[0]-s[0], xy[1]-s[1]);
 
             // Constrain the X coordinate by however much the dragTarget overflows
             if (dr.right > constrainTo.right) {
@@ -514,7 +545,7 @@ Ext.define('Ext.dd.DragTracker', {
                 xy[0] += (constrainTo.left - dr.left);      // overflowed the left
             }
 
-            // Constrain the X coordinate by however much the dragTarget overflows
+            // Constrain the Y coordinate by however much the dragTarget overflows
             if (dr.bottom > constrainTo.bottom) {
                 xy[1] += adjust = (constrainTo.bottom - dr.bottom);  // overflowed the bottom
                 dr.top += adjust;
@@ -525,4 +556,6 @@ Ext.define('Ext.dd.DragTracker', {
             return xy;
         }
     }
-});
\ No newline at end of file +});
+ +