/**
* @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;
}
}
-});