Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / DragTracker.html
index 871c218..ccd84a0 100644 (file)
+<!DOCTYPE html>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/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>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.2.2
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-<div id="cls-Ext.dd.DragTracker"></div>/**
- * @class Ext.dd.DragTracker
- * @extends Ext.util.Observable
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-dd-DragTracker'>/**
+</span> * @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}, where there is
+ * as well as during the drag. This is useful for components such as {@link Ext.slider.Multi}, where there is
  * an element that can be dragged around to change the Slider's value.
  * DragTracker provides a series of template methods that should be overridden to provide functionality
  * in response to detected drag operations. These are onBeforeStart, onStart, onDrag and onEnd.
- * See {@link Ext.Slider}'s initEvents function for an example implementation.
+ * See {@link Ext.slider.Multi}'s initEvents function for an example implementation.
  */
-Ext.dd.DragTracker = Ext.extend(Ext.util.Observable,  {    
-    <div id="cfg-Ext.dd.DragTracker-active"></div>/**
-     * @cfg {Boolean} active
-        * Defaults to <tt>false</tt>.
-        */     
+Ext.define('Ext.dd.DragTracker', {
+
+    uses: ['Ext.util.Region'],
+
+    mixins: {
+        observable: 'Ext.util.Observable'
+    },
+
+<span id='Ext-dd-DragTracker-property-active'>    /**
+</span>     * @property {Boolean} active
+     * Read-only property indicated whether the user is currently dragging this
+     * tracker.
+     */
     active: false,
-    <div id="cfg-Ext.dd.DragTracker-tolerance"></div>/**
-     * @cfg {Number} tolerance
-        * Number of pixels the drag target must be moved before dragging is considered to have started. Defaults to <tt>5</tt>.
-        */     
+
+<span id='Ext-dd-DragTracker-property-dragTarget'>    /**
+</span>     * @property {HTMLElement} dragTarget
+     * &lt;p&gt;&lt;b&gt;Only valid during drag operations. Read-only.&lt;/b&gt;&lt;/p&gt;
+     * &lt;p&gt;The element being dragged.&lt;/p&gt;
+     * &lt;p&gt;If the {@link #delegate} option is used, this will be the delegate element which was mousedowned.&lt;/p&gt;
+     */
+
+<span id='Ext-dd-DragTracker-cfg-trackOver'>    /**
+</span>     * @cfg {Boolean} trackOver
+     * &lt;p&gt;Defaults to &lt;code&gt;false&lt;/code&gt;. Set to true to fire mouseover and mouseout events when the mouse enters or leaves the target element.&lt;/p&gt;
+     * &lt;p&gt;This is implicitly set when an {@link #overCls} is specified.&lt;/p&gt;
+     * &lt;b&gt;If the {@link #delegate} option is used, these events fire only when a delegate element is entered of left.&lt;/b&gt;.
+     */
+    trackOver: false,
+
+<span id='Ext-dd-DragTracker-cfg-overCls'>    /**
+</span>     * @cfg {String} overCls
+     * &lt;p&gt;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.&lt;/p&gt;
+     * &lt;b&gt;If the {@link #delegate} option is used, these events fire only when a delegate element is entered of left.&lt;/b&gt;.
+     */
+
+<span id='Ext-dd-DragTracker-cfg-constrainTo'>    /**
+</span>     * @cfg {Ext.util.Region/Ext.Element} constrainTo
+     * &lt;p&gt;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.&lt;/p&gt;
+     * &lt;p&gt;This may be set any time during the DragTracker's lifecycle to set a dynamic constraining region.&lt;/p&gt;
+     */
+
+<span id='Ext-dd-DragTracker-cfg-tolerance'>    /**
+</span>     * @cfg {Number} tolerance
+     * Number of pixels the drag target must be moved before dragging is
+     * considered to have started. Defaults to &lt;code&gt;5&lt;/code&gt;.
+     */
     tolerance: 5,
-    <div id="cfg-Ext.dd.DragTracker-autoStart"></div>/**
-     * @cfg {Boolean/Number} autoStart
-        * Defaults to <tt>false</tt>. Specify <tt>true</tt> to defer trigger start by 1000 ms.
-        * Specify a Number for the number of milliseconds to defer trigger start.
-        */     
+
+<span id='Ext-dd-DragTracker-cfg-autoStart'>    /**
+</span>     * @cfg {Boolean/Number} autoStart
+     * Defaults to &lt;code&gt;false&lt;/code&gt;. Specify &lt;code&gt;true&lt;/code&gt; to defer trigger start by 1000 ms.
+     * Specify a Number for the number of milliseconds to defer trigger start.
+     */
     autoStart: false,
-    
+
+<span id='Ext-dd-DragTracker-cfg-delegate'>    /**
+</span>     * @cfg {String} delegate
+     * Optional. &lt;p&gt;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.&lt;/p&gt;
+     * &lt;p&gt;This may also be a specific child element within the DragTracker's encapsulating element to use as the tracked element.&lt;/p&gt;
+     */
+
+<span id='Ext-dd-DragTracker-cfg-preventDefault'>    /**
+</span>     * @cfg {Boolean} preventDefault
+     * Specify &lt;code&gt;false&lt;/code&gt; to enable default actions on onMouseDown events. Defaults to &lt;code&gt;true&lt;/code&gt;.
+     */
+
+<span id='Ext-dd-DragTracker-cfg-stopEvent'>    /**
+</span>     * @cfg {Boolean} stopEvent
+     * Specify &lt;code&gt;true&lt;/code&gt; to stop the &lt;code&gt;mousedown&lt;/code&gt; event from bubbling to outer listeners from the target element (or its delegates). Defaults to &lt;code&gt;false&lt;/code&gt;.
+     */
+
     constructor : function(config){
         Ext.apply(this, config);
-           this.addEvents(
-               <div id="event-Ext.dd.DragTracker-mousedown"></div>/**
-                * @event mousedown
-                * @param {Object} this
-                * @param {Object} e event object
-                */
-               'mousedown',
-               <div id="event-Ext.dd.DragTracker-mouseup"></div>/**
-                * @event mouseup
-                * @param {Object} this
-                * @param {Object} e event object
-                */
-               'mouseup',
-               <div id="event-Ext.dd.DragTracker-mousemove"></div>/**
-                * @event mousemove
-                * @param {Object} this
-                * @param {Object} e event object
-                */
-               'mousemove',
-               <div id="event-Ext.dd.DragTracker-dragstart"></div>/**
-                * @event dragstart
-                * @param {Object} this
-                * @param {Object} startXY the page coordinates of the event
-                */
-               'dragstart',
-               <div id="event-Ext.dd.DragTracker-dragend"></div>/**
-                * @event dragend
-                * @param {Object} this
-                * @param {Object} e event object
-                */
-               'dragend',
-               <div id="event-Ext.dd.DragTracker-drag"></div>/**
-                * @event drag
-                * @param {Object} this
-                * @param {Object} e event object
-                */
-               'drag'
-           );
-       
-           this.dragRegion = new Ext.lib.Region(0,0,0,0);
-       
-           if(this.el){
-               this.initEl(this.el);
-           }
-        Ext.dd.DragTracker.superclass.constructor.call(this, config);
+        this.addEvents(
+<span id='Ext-dd-DragTracker-event-mouseover'>            /**
+</span>             * @event mouseover &lt;p&gt;&lt;b&gt;Only available when {@link #trackOver} is &lt;code&gt;true&lt;/code&gt;&lt;/b&gt;&lt;/p&gt;
+             * &lt;p&gt;Fires when the mouse enters the DragTracker's target element (or if {@link #delegate} is
+             * used, when the mouse enters a delegate element).&lt;/p&gt;
+             * @param {Object} this
+             * @param {Object} e event object
+             * @param {HTMLElement} target The element mouseovered.
+             */
+            'mouseover',
+
+<span id='Ext-dd-DragTracker-event-mouseout'>            /**
+</span>             * @event mouseout &lt;p&gt;&lt;b&gt;Only available when {@link #trackOver} is &lt;code&gt;true&lt;/code&gt;&lt;/b&gt;&lt;/p&gt;
+             * &lt;p&gt;Fires when the mouse exits the DragTracker's target element (or if {@link #delegate} is
+             * used, when the mouse exits a delegate element).&lt;/p&gt;
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'mouseout',
+
+<span id='Ext-dd-DragTracker-event-mousedown'>            /**
+</span>             * @event mousedown &lt;p&gt;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.&lt;/p&gt;
+             * &lt;p&gt;Return false to veto the drag operation.&lt;/p&gt;
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'mousedown',
+
+<span id='Ext-dd-DragTracker-event-mouseup'>            /**
+</span>             * @event mouseup
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'mouseup',
+
+<span id='Ext-dd-DragTracker-event-mousemove'>            /**
+</span>             * @event mousemove Fired when the mouse is moved. Returning false cancels the drag operation.
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'mousemove',
+
+<span id='Ext-dd-DragTracker-event-beforestart'>            /**
+</span>             * @event beforestart
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'beforedragstart',
+
+<span id='Ext-dd-DragTracker-event-dragstart'>            /**
+</span>             * @event dragstart
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'dragstart',
+
+<span id='Ext-dd-DragTracker-event-dragend'>            /**
+</span>             * @event dragend
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'dragend',
+
+<span id='Ext-dd-DragTracker-event-drag'>            /**
+</span>             * @event drag
+             * @param {Object} this
+             * @param {Object} e event object
+             */
+            'drag'
+        );
+
+        this.dragRegion = Ext.create('Ext.util.Region', 0,0,0,0);
+
+        if (this.el) {
+            this.initEl(this.el);
+        }
+
+        // Dont pass the config so that it is not applied to 'this' again
+        this.mixins.observable.constructor.call(this);
+        if (this.disabled) {
+            this.disable();
+        }
+
     },
 
-    initEl: function(el){
+<span id='Ext-dd-DragTracker-method-initEl'>    /**
+</span>     * Initializes the DragTracker on a given element.
+     * @param {Ext.Element/HTMLElement} el The element
+     */
+    initEl: function(el) {
         this.el = Ext.get(el);
-        el.on('mousedown', this.onMouseDown, this,
-                this.delegate ? {delegate: this.delegate} : undefined);
+
+        // The delegate option may also be an element on which to listen
+        this.handle = Ext.get(this.delegate);
+
+        // If delegate specified an actual element to listen on, we do not use the delegate listener option
+        this.delegate = this.handle ? undefined : this.delegate;
+
+        if (!this.handle) {
+            this.handle = this.el;
+        }
+
+        // Add a mousedown listener which reacts only on the elements targeted by the delegate config.
+        // We process mousedown to begin tracking.
+        this.mon(this.handle, {
+            mousedown: this.onMouseDown,
+            delegate: this.delegate,
+            scope: this
+        });
+
+        // If configured to do so, track mouse entry and exit into the target (or delegate).
+        // The mouseover and mouseout CANNOT be replaced with mouseenter and mouseleave
+        // because delegate cannot work with those pseudoevents. Entry/exit checking is done in the handler.
+        if (this.trackOver || this.overCls) {
+            this.mon(this.handle, {
+                mouseover: this.onMouseOver,
+                mouseout: this.onMouseOut,
+                delegate: this.delegate,
+                scope: this
+            });
+        }
     },
 
-    destroy : function(){
-        this.el.un('mousedown', this.onMouseDown, this);
+    disable: function() {
+        this.disabled = true;
+    },
+
+    enable: function() {
+        this.disabled = false;
+    },
+
+    destroy : function() {
+        this.clearListeners();
         delete this.el;
     },
 
-    onMouseDown: function(e, target){
-        if(this.fireEvent('mousedown', this, e) !== false && this.onBeforeStart(e) !== false){
-            this.startXY = this.lastXY = e.getXY();
-            this.dragTarget = this.delegate ? target : this.el.dom;
-            if(this.preventDefault !== false){
-                e.preventDefault();
+    // When the pointer enters a tracking element, fire a mouseover if the mouse entered from outside.
+    // This is mouseenter functionality, but we cannot use mouseenter because we are using &quot;delegate&quot; to filter mouse targets
+    onMouseOver: function(e, target) {
+        var me = this;
+        if (!me.disabled) {
+            if (Ext.EventManager.contains(e) || me.delegate) {
+                me.mouseIsOut = false;
+                if (me.overCls) {
+                    me.el.addCls(me.overCls);
+                }
+                me.fireEvent('mouseover', me, e, me.delegate ? e.getTarget(me.delegate, target) : me.handle);
             }
-            var doc = Ext.getDoc();
-            doc.on('mouseup', this.onMouseUp, this);
-            doc.on('mousemove', this.onMouseMove, this);
-            doc.on('selectstart', this.stopSelect, this);
-            if(this.autoStart){
-                this.timer = this.triggerStart.defer(this.autoStart === true ? 1000 : this.autoStart, this);
+        }
+    },
+
+    // When the pointer exits a tracking element, fire a mouseout.
+    // This is mouseleave functionality, but we cannot use mouseleave because we are using &quot;delegate&quot; to filter mouse targets
+    onMouseOut: function(e) {
+        if (this.mouseIsDown) {
+            this.mouseIsOut = true;
+        } else {
+            if (this.overCls) {
+                this.el.removeCls(this.overCls);
             }
+            this.fireEvent('mouseout', this, e);
+        }
+    },
+
+    onMouseDown: function(e, target){
+        // If this is disabled, or the mousedown has been processed by an upstream DragTracker, return
+        if (this.disabled ||e.dragTracked) {
+            return;
+        }
+
+        // This information should be available in mousedown listener and onBeforeStart implementations
+        this.dragTarget = this.delegate ? target : this.handle.dom;
+        this.startXY = this.lastXY = e.getXY();
+        this.startRegion = Ext.fly(this.dragTarget).getRegion();
+
+        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;
+
+        // 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]);
         }
     },
 
     onMouseMove: function(e, target){
-        // HACK: IE hack to see if button was released outside of window. */
-        if(this.active && Ext.isIE && !e.browserEvent.button){
+        // BrowserBug: IE hack to see if button was released outside of window.
+        // Needed in IE6-9 in quirks and strictmode
+        if (this.active &amp;&amp; Ext.isIE &amp;&amp; !e.browserEvent.button) {
             e.preventDefault();
             this.onMouseUp(e);
             return;
         }
 
         e.preventDefault();
-        var xy = e.getXY(), s = this.startXY;
+        var xy = e.getXY(),
+            s = this.startXY;
+
         this.lastXY = xy;
-        if(!this.active){
-            if(Math.abs(s[0]-xy[0]) > this.tolerance || Math.abs(s[1]-xy[1]) > this.tolerance){
-                this.triggerStart();
-            }else{
+        if (!this.active) {
+            if (Math.max(Math.abs(s[0]-xy[0]), Math.abs(s[1]-xy[1])) &gt; this.tolerance) {
+                this.triggerStart(e);
+            } else {
                 return;
             }
         }
-        this.fireEvent('mousemove', this, e);
-        this.onDrag(e);
-        this.fireEvent('drag', this, e);
+
+        // Returning false from a mousemove listener deactivates
+        if (this.fireEvent('mousemove', this, e) === false) {
+            this.onMouseUp(e);
+        } else {
+            this.onDrag(e);
+            this.fireEvent('drag', this, e);
+        }
     },
 
     onMouseUp: function(e) {
-        var doc = Ext.getDoc();
+        // Clear the flag which ensures onMouseOut fires only after the mouse button
+        // is lifted if the mouseout happens *during* a drag.
+        this.mouseIsDown = false;
+
+        // 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;
+            this.onMouseOut(e);
+        }
+        e.preventDefault();
+        this.fireEvent('mouseup', this, e);
+        this.endDrag(e);
+    },
+
+<span id='Ext-dd-DragTracker-method-endDrag'>    /**
+</span>     * @private
+     * Stop the drag operation, and remove active mouse listeners.
+     */
+    endDrag: function(e) {
+        var doc = Ext.getDoc(),
+        wasActive = this.active;
+
         doc.un('mousemove', this.onMouseMove, this);
         doc.un('mouseup', this.onMouseUp, this);
         doc.un('selectstart', this.stopSelect, this);
-        e.preventDefault();
         this.clearStart();
-        var wasActive = this.active;
         this.active = false;
-        delete this.elRegion;
-        this.fireEvent('mouseup', this, e);
-        if(wasActive){
+        if (wasActive) {
             this.onEnd(e);
             this.fireEvent('dragend', this, e);
         }
+        // Private property calculated when first required and only cached during a drag
+        delete this._constrainRegion;
+
+        // Remove flag from event singleton.  Using &quot;Ext.EventObject&quot; here since &quot;endDrag&quot; is called directly in some cases without an &quot;e&quot; param
+        delete Ext.EventObject.dragTracked;
     },
 
-    triggerStart: function(isTimer) {
+    triggerStart: function(e) {
         this.clearStart();
         this.active = true;
-        this.onStart(this.startXY);
-        this.fireEvent('dragstart', this, this.startXY);
+        this.onStart(e);
+        this.fireEvent('dragstart', this, e);
     },
 
     clearStart : function() {
-        if(this.timer){
+        if (this.timer) {
             clearTimeout(this.timer);
             delete this.timer;
         }
@@ -175,84 +393,169 @@ Ext.dd.DragTracker = Ext.extend(Ext.util.Observable,  {
         e.stopEvent();
         return false;
     },
-    
-    <div id="method-Ext.dd.DragTracker-onBeforeStart"></div>/**
-     * Template method which should be overridden by each DragTracker instance. Called when the user first clicks and
+
+<span id='Ext-dd-DragTracker-method-onBeforeStart'>    /**
+</span>     * 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) {
 
     },
 
-    <div id="method-Ext.dd.DragTracker-onStart"></div>/**
-     * Template method which should be overridden by each DragTracker instance. Called when a drag operation starts
+<span id='Ext-dd-DragTracker-method-onStart'>    /**
+</span>     * 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 {Array} xy x and y co-ordinates of the original location of the tracked element
+     * @param {Ext.EventObject} e The event object
+     * @template
      */
     onStart : function(xy) {
 
     },
 
-    <div id="method-Ext.dd.DragTracker-onDrag"></div>/**
-     * Template method which should be overridden by each DragTracker instance. Called whenever a drag has been detected.
+<span id='Ext-dd-DragTracker-method-onDrag'>    /**
+</span>     * 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) {
 
     },
 
-    <div id="method-Ext.dd.DragTracker-onEnd"></div>/**
-     * Template method which should be overridden by each DragTracker instance. Called when a drag operation has been completed
+<span id='Ext-dd-DragTracker-method-onEnd'>    /**
+</span>     * 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) {
 
     },
 
-    <div id="method-Ext.dd.DragTracker-getDragTarget"></div>/**
-     * Returns the drag target
-     * @return {Ext.Element} The element currently being tracked
+<span id='Ext-dd-DragTracker-method-getDragTarget'>    /**
+</span>     * &lt;/p&gt;Returns the drag target. This is usually the DragTracker's encapsulating element.&lt;/p&gt;
+     * &lt;p&gt;If the {@link #delegate} option is being used, this may be a child element which matches the
+     * {@link #delegate} selector.&lt;/p&gt;
+     * @return {Ext.Element} The element currently being tracked.
      */
     getDragTarget : function(){
         return this.dragTarget;
     },
 
+<span id='Ext-dd-DragTracker-method-getDragCt'>    /**
+</span>     * @private
+     * @returns {Ext.Element} The DragTracker's encapsulating element.
+     */
     getDragCt : function(){
         return this.el;
     },
 
+<span id='Ext-dd-DragTracker-method-getConstrainRegion'>    /**
+</span>     * @private
+     * Return the Region into which the drag operation is constrained.
+     * Either the XY pointer itself can be constrained, or the dragTarget element
+     * The private property _constrainRegion is cached until onMouseUp
+     */
+    getConstrainRegion: function() {
+        if (this.constrainTo) {
+            if (this.constrainTo instanceof Ext.util.Region) {
+                return this.constrainTo;
+            }
+            if (!this._constrainRegion) {
+                this._constrainRegion = Ext.fly(this.constrainTo).getViewRegion();
+            }
+        } else {
+            if (!this._constrainRegion) {
+                this._constrainRegion = this.getDragCt().getViewRegion();
+            }
+        }
+        return this._constrainRegion;
+    },
+
     getXY : function(constrain){
-        return constrain ?
-               this.constrainModes[constrain].call(this, this.lastXY) : this.lastXY;
+        return constrain ? this.constrainModes[constrain](this, this.lastXY) : this.lastXY;
     },
 
+<span id='Ext-dd-DragTracker-method-getOffset'>    /**
+</span>     * 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);
-        var s = this.startXY;
-        return [s[0]-xy[0], s[1]-xy[1]];
+        var xy = this.getXY(constrain),
+            s = this.startXY;
+
+        return [xy[0]-s[0], xy[1]-s[1]];
     },
 
     constrainModes: {
-        'point' : function(xy){
+        // Constrain the passed point to within the constrain region
+        point: function(me, xy) {
+            var dr = me.dragRegion,
+                constrainTo = me.getConstrainRegion();
 
-            if(!this.elRegion){
-                this.elRegion = this.getDragCt().getRegion();
+            // No constraint
+            if (!constrainTo) {
+                return xy;
             }
 
-            var dr = this.dragRegion;
+            dr.x = dr.left = dr[0] = dr.right = xy[0];
+            dr.y = dr.top = dr[1] = dr.bottom = xy[1];
+            dr.constrainTo(constrainTo);
 
-            dr.left = xy[0];
-            dr.top = xy[1];
-            dr.right = xy[0];
-            dr.bottom = xy[1];
+            return [dr.left, dr.top];
+        },
 
-            dr.constrainTo(this.elRegion);
+        // Constrain the dragTarget to within the constrain region. Return the passed xy adjusted by the same delta.
+        dragTarget: function(me, xy) {
+            var s = me.startXY,
+                dr = me.startRegion.copy(),
+                constrainTo = me.getConstrainRegion(),
+                adjust;
 
-            return [dr.left, dr.top];
+            // No constraint
+            if (!constrainTo) {
+                return xy;
+            }
+
+            // 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(xy[0]-s[0], xy[1]-s[1]);
+
+            // Constrain the X coordinate by however much the dragTarget overflows
+            if (dr.right &gt; constrainTo.right) {
+                xy[0] += adjust = (constrainTo.right - dr.right);    // overflowed the right
+                dr.left += adjust;
+            }
+            if (dr.left &lt; constrainTo.left) {
+                xy[0] += (constrainTo.left - dr.left);      // overflowed the left
+            }
+
+            // Constrain the Y coordinate by however much the dragTarget overflows
+            if (dr.bottom &gt; constrainTo.bottom) {
+                xy[1] += adjust = (constrainTo.bottom - dr.bottom);  // overflowed the bottom
+                dr.top += adjust;
+            }
+            if (dr.top &lt; constrainTo.top) {
+                xy[1] += (constrainTo.top - dr.top);        // overflowed the top
+            }
+            return xy;
         }
     }
-});</pre>    
+});</pre>
 </body>
-</html>
\ No newline at end of file
+</html>