src/dd/DragTracker.js

   1 /**
   2  * @class Ext.dd.DragTracker
   3  * A DragTracker listens for drag events on an Element and fires events at the start and end of the drag,
   4  * as well as during the drag. This is useful for components such as {@link Ext.slider.Multi}, where there is
   5  * an element that can be dragged around to change the Slider's value.
   6  * DragTracker provides a series of template methods that should be overridden to provide functionality
   7  * in response to detected drag operations. These are onBeforeStart, onStart, onDrag and onEnd.
   8  * See {@link Ext.slider.Multi}'s initEvents function for an example implementation.
   9  */
  10 Ext.define('Ext.dd.DragTracker', {
  11
  12     uses: ['Ext.util.Region'],
  13
  14     mixins: {
  15         observable: 'Ext.util.Observable'
  16     },
  17
  18     /**
  19      * @property active
  20      * @type Boolean
  21      * Read-only property indicated whether the user is currently dragging this
  22      * tracker.
  23      */
  24     active: false,
  25
  26     /**
  27      * @property dragTarget
  28      * @type HtmlElement
  29      * <p><b>Only valid during drag operations. Read-only.</b></p>
  30      * <p>The element being dragged.</p>
  31      * <p>If the {@link #delegate} option is used, this will be the delegate element which was mousedowned.</p>
  32      */
  33
  34     /**
  35      * @cfg {Boolean} trackOver
  36      * <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>
  37      * <p>This is implicitly set when an {@link #overCls} is specified.</p>
  38      * <b>If the {@link #delegate} option is used, these events fire only when a delegate element is entered of left.</b>.
  39      */
  40     trackOver: false,
  41
  42     /**
  43      * @cfg {String} overCls
  44      * <p>A CSS class to add to the DragTracker's target element when the element (or, if the {@link #delegate} option is used,
  45      * when a delegate element) is mouseovered.</p>
  46      * <b>If the {@link #delegate} option is used, these events fire only when a delegate element is entered of left.</b>.
  47      */
  48
  49     /**
  50      * @cfg {Ext.util.Region/Element} constrainTo
  51      * <p>A {@link Ext.util.Region Region} (Or an element from which a Region measurement will be read) which is used to constrain
  52      * the result of the {@link #getOffset} call.</p>
  53      * <p>This may be set any time during the DragTracker's lifecycle to set a dynamic constraining region.</p>
  54      */
  55
  56     /**
  57      * @cfg {Number} tolerance
  58      * Number of pixels the drag target must be moved before dragging is
  59      * considered to have started. Defaults to <code>5</code>.
  60      */
  61     tolerance: 5,
  62
  63     /**
  64      * @cfg {Boolean/Number} autoStart
  65      * Defaults to <code>false</code>. Specify <code>true</code> to defer trigger start by 1000 ms.
  66      * Specify a Number for the number of milliseconds to defer trigger start.
  67      */
  68     autoStart: false,
  69
  70     /**
  71      * @cfg {String} delegate
  72      * Optional. <p>A {@link Ext.DomQuery DomQuery} selector which identifies child elements within the DragTracker's encapsulating
  73      * Element which are the tracked elements. This limits tracking to only begin when the matching elements are mousedowned.</p>
  74      * <p>This may also be a specific child element within the DragTracker's encapsulating element to use as the tracked element.</p>
  75      */
  76
  77     /**
  78      * @cfg {Boolean} preventDefault
  79      * Specify <code>false</code> to enable default actions on onMouseDown events. Defaults to <code>true</code>.
  80      */
  81
  82     /**
  83      * @cfg {Boolean} stopEvent
  84      * 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>.
  85      */
  86
  87     constructor : function(config){
  88         Ext.apply(this, config);
  89         this.addEvents(
  90             /**
  91              * @event mouseover <p><b>Only available when {@link #trackOver} is <code>true</code></b></p>
  92              * <p>Fires when the mouse enters the DragTracker's target element (or if {@link #delegate} is
  93              * used, when the mouse enters a delegate element).</p>
  94              * @param {Object} this
  95              * @param {Object} e event object
  96              * @param {HtmlElement} target The element mouseovered.
  97              */
  98             'mouseover',
  99
 100             /**
 101              * @event mouseout <p><b>Only available when {@link #trackOver} is <code>true</code></b></p>
 102              * <p>Fires when the mouse exits the DragTracker's target element (or if {@link #delegate} is
 103              * used, when the mouse exits a delegate element).</p>
 104              * @param {Object} this
 105              * @param {Object} e event object
 106              */
 107             'mouseout',
 108
 109             /**
 110              * @event mousedown <p>Fires when the mouse button is pressed down, but before a drag operation begins. The
 111              * drag operation begins after either the mouse has been moved by {@link #tolerance} pixels, or after
 112              * the {@link #autoStart} timer fires.</p>
 113              * <p>Return false to veto the drag operation.</p>
 114              * @param {Object} this
 115              * @param {Object} e event object
 116              */
 117             'mousedown',
 118
 119             /**
 120              * @event mouseup
 121              * @param {Object} this
 122              * @param {Object} e event object
 123              */
 124             'mouseup',
 125
 126             /**
 127              * @event mousemove Fired when the mouse is moved. Returning false cancels the drag operation.
 128              * @param {Object} this
 129              * @param {Object} e event object
 130              */
 131             'mousemove',
 132
 133             /**
 134              * @event beforestart
 135              * @param {Object} this
 136              * @param {Object} e event object
 137              */
 138             'beforedragstart',
 139
 140             /**
 141              * @event dragstart
 142              * @param {Object} this
 143              * @param {Object} e event object
 144              */
 145             'dragstart',
 146
 147             /**
 148              * @event dragend
 149              * @param {Object} this
 150              * @param {Object} e event object
 151              */
 152             'dragend',
 153
 154             /**
 155              * @event drag
 156              * @param {Object} this
 157              * @param {Object} e event object
 158              */
 159             'drag'
 160         );
 161
 162         this.dragRegion = Ext.create('Ext.util.Region', 0,0,0,0);
 163
 164         if (this.el) {
 165             this.initEl(this.el);
 166         }
 167
 168         // Dont pass the config so that it is not applied to 'this' again
 169         this.mixins.observable.constructor.call(this);
 170         if (this.disabled) {
 171             this.disable();
 172         }
 173
 174     },
 175
 176     /**
 177      * Initializes the DragTracker on a given element.
 178      * @param {Ext.core.Element/HTMLElement} el The element
 179      */
 180     initEl: function(el) {
 181         this.el = Ext.get(el);
 182
 183         // The delegate option may also be an element on which to listen
 184         this.handle = Ext.get(this.delegate);
 185
 186         // If delegate specified an actual element to listen on, we do not use the delegate listener option
 187         this.delegate = this.handle ? undefined : this.delegate;
 188
 189         if (!this.handle) {
 190             this.handle = this.el;
 191         }
 192
 193         // Add a mousedown listener which reacts only on the elements targeted by the delegate config.
 194         // We process mousedown to begin tracking.
 195         this.mon(this.handle, {
 196             mousedown: this.onMouseDown,
 197             delegate: this.delegate,
 198             scope: this
 199         });
 200
 201         // If configured to do so, track mouse entry and exit into the target (or delegate).
 202         // The mouseover and mouseout CANNOT be replaced with mouseenter and mouseleave
 203         // because delegate cannot work with those pseudoevents. Entry/exit checking is done in the handler.
 204         if (this.trackOver || this.overCls) {
 205             this.mon(this.handle, {
 206                 mouseover: this.onMouseOver,
 207                 mouseout: this.onMouseOut,
 208                 delegate: this.delegate,
 209                 scope: this
 210             });
 211         }
 212     },
 213
 214     disable: function() {
 215         this.disabled = true;
 216     },
 217
 218     enable: function() {
 219         this.disabled = false;
 220     },
 221
 222     destroy : function() {
 223         this.clearListeners();
 224         delete this.el;
 225     },
 226
 227     // When the pointer enters a tracking element, fire a mouseover if the mouse entered from outside.
 228     // This is mouseenter functionality, but we cannot use mouseenter because we are using "delegate" to filter mouse targets
 229     onMouseOver: function(e, target) {
 230         var me = this;
 231         if (!me.disabled) {
 232             if (Ext.EventManager.contains(e) || me.delegate) {
 233                 me.mouseIsOut = false;
 234                 if (me.overCls) {
 235                     me.el.addCls(me.overCls);
 236                 }
 237                 me.fireEvent('mouseover', me, e, me.delegate ? e.getTarget(me.delegate, target) : me.handle);
 238             }
 239         }
 240     },
 241
 242     // When the pointer exits a tracking element, fire a mouseout.
 243     // This is mouseleave functionality, but we cannot use mouseleave because we are using "delegate" to filter mouse targets
 244     onMouseOut: function(e) {
 245         if (this.mouseIsDown) {
 246             this.mouseIsOut = true;
 247         } else {
 248             if (this.overCls) {
 249                 this.el.removeCls(this.overCls);
 250             }
 251             this.fireEvent('mouseout', this, e);
 252         }
 253     },
 254
 255     onMouseDown: function(e, target){
 256         // If this is disabled, or the mousedown has been processed by an upstream DragTracker, return
 257         if (this.disabled ||e.dragTracked) {
 258             return;
 259         }
 260
 261         // This information should be available in mousedown listener and onBeforeStart implementations
 262         this.dragTarget = this.delegate ? target : this.handle.dom;
 263         this.startXY = this.lastXY = e.getXY();
 264         this.startRegion = Ext.fly(this.dragTarget).getRegion();
 265
 266         if (this.fireEvent('mousedown', this, e) === false ||
 267             this.fireEvent('beforedragstart', this, e) === false ||
 268             this.onBeforeStart(e) === false) {
 269             return;
 270         }
 271
 272         // Track when the mouse is down so that mouseouts while the mouse is down are not processed.
 273         // The onMouseOut method will only ever be called after mouseup.
 274         this.mouseIsDown = true;
 275
 276         // Flag for downstream DragTracker instances that the mouse is being tracked.
 277         e.dragTracked = true;
 278
 279         if (this.preventDefault !== false) {
 280             e.preventDefault();
 281         }
 282         Ext.getDoc().on({
 283             scope: this,
 284             mouseup: this.onMouseUp,
 285             mousemove: this.onMouseMove,
 286             selectstart: this.stopSelect
 287         });
 288         if (this.autoStart) {
 289             this.timer =  Ext.defer(this.triggerStart, this.autoStart === true ? 1000 : this.autoStart, this, [e]);
 290         }
 291     },
 292
 293     onMouseMove: function(e, target){
 294         // BrowserBug: IE hack to see if button was released outside of window.
 295         // Needed in IE6-9 in quirks and strictmode
 296         if (this.active && Ext.isIE && !e.browserEvent.button) {
 297             e.preventDefault();
 298             this.onMouseUp(e);
 299             return;
 300         }
 301
 302         e.preventDefault();
 303         var xy = e.getXY(),
 304             s = this.startXY;
 305
 306         this.lastXY = xy;
 307         if (!this.active) {
 308             if (Math.max(Math.abs(s[0]-xy[0]), Math.abs(s[1]-xy[1])) > this.tolerance) {
 309                 this.triggerStart(e);
 310             } else {
 311                 return;
 312             }
 313         }
 314
 315         // Returning false from a mousemove listener deactivates
 316         if (this.fireEvent('mousemove', this, e) === false) {
 317             this.onMouseUp(e);
 318         } else {
 319             this.onDrag(e);
 320             this.fireEvent('drag', this, e);
 321         }
 322     },
 323
 324     onMouseUp: function(e) {
 325         // Clear the flag which ensures onMouseOut fires only after the mouse button
 326         // is lifted if the mouseout happens *during* a drag.
 327         this.mouseIsDown = false;
 328
 329         // Remove flag from event singleton
 330         delete e.dragTracked;
 331
 332         // If we mouseouted the el *during* the drag, the onMouseOut method will not have fired. Ensure that it gets processed.
 333         if (this.mouseIsOut) {
 334             this.mouseIsOut = false;
 335             this.onMouseOut(e);
 336         }
 337         e.preventDefault();
 338         this.fireEvent('mouseup', this, e);
 339         this.endDrag(e);
 340     },
 341
 342     /**
 343      * @private
 344      * Stop the drag operation, and remove active mouse listeners.
 345      */
 346     endDrag: function(e) {
 347         var doc = Ext.getDoc(),
 348         wasActive = this.active;
 349
 350         doc.un('mousemove', this.onMouseMove, this);
 351         doc.un('mouseup', this.onMouseUp, this);
 352         doc.un('selectstart', this.stopSelect, this);
 353         this.clearStart();
 354         this.active = false;
 355         if (wasActive) {
 356             this.onEnd(e);
 357             this.fireEvent('dragend', this, e);
 358         }
 359         // Private property calculated when first required and only cached during a drag
 360         delete this._constrainRegion;
 361     },
 362
 363     triggerStart: function(e) {
 364         this.clearStart();
 365         this.active = true;
 366         this.onStart(e);
 367         this.fireEvent('dragstart', this, e);
 368     },
 369
 370     clearStart : function() {
 371         if (this.timer) {
 372             clearTimeout(this.timer);
 373             delete this.timer;
 374         }
 375     },
 376
 377     stopSelect : function(e) {
 378         e.stopEvent();
 379         return false;
 380     },
 381
 382     /**
 383      * Template method which should be overridden by each DragTracker instance. Called when the user first clicks and
 384      * holds the mouse button down. Return false to disallow the drag
 385      * @param {Ext.EventObject} e The event object
 386      */
 387     onBeforeStart : function(e) {
 388
 389     },
 390
 391     /**
 392      * Template method which should be overridden by each DragTracker instance. Called when a drag operation starts
 393      * (e.g. the user has moved the tracked element beyond the specified tolerance)
 394      * @param {Ext.EventObject} e The event object
 395      */
 396     onStart : function(xy) {
 397
 398     },
 399
 400     /**
 401      * Template method which should be overridden by each DragTracker instance. Called whenever a drag has been detected.
 402      * @param {Ext.EventObject} e The event object
 403      */
 404     onDrag : function(e) {
 405
 406     },
 407
 408     /**
 409      * Template method which should be overridden by each DragTracker instance. Called when a drag operation has been completed
 410      * (e.g. the user clicked and held the mouse down, dragged the element and then released the mouse button)
 411      * @param {Ext.EventObject} e The event object
 412      */
 413     onEnd : function(e) {
 414
 415     },
 416
 417     /**
 418      * </p>Returns the drag target. This is usually the DragTracker's encapsulating element.</p>
 419      * <p>If the {@link #delegate} option is being used, this may be a child element which matches the
 420      * {@link #delegate} selector.</p>
 421      * @return {Ext.core.Element} The element currently being tracked.
 422      */
 423     getDragTarget : function(){
 424         return this.dragTarget;
 425     },
 426
 427     /**
 428      * @private
 429      * @returns {Element} The DragTracker's encapsulating element.
 430      */
 431     getDragCt : function(){
 432         return this.el;
 433     },
 434
 435     /**
 436      * @private
 437      * Return the Region into which the drag operation is constrained.
 438      * Either the XY pointer itself can be constrained, or the dragTarget element
 439      * The private property _constrainRegion is cached until onMouseUp
 440      */
 441     getConstrainRegion: function() {
 442         if (this.constrainTo) {
 443             if (this.constrainTo instanceof Ext.util.Region) {
 444                 return this.constrainTo;
 445             }
 446             if (!this._constrainRegion) {
 447                 this._constrainRegion = Ext.fly(this.constrainTo).getViewRegion();
 448             }
 449         } else {
 450             if (!this._constrainRegion) {
 451                 this._constrainRegion = this.getDragCt().getViewRegion();
 452             }
 453         }
 454         return this._constrainRegion;
 455     },
 456
 457     getXY : function(constrain){
 458         return constrain ? this.constrainModes[constrain](this, this.lastXY) : this.lastXY;
 459     },
 460
 461     /**
 462      * <p>Returns the X, Y offset of the current mouse position from the mousedown point.</p>
 463      * <p>This method may optionally constrain the real offset values, and returns a point coerced in one
 464      * of two modes:</p><ul>
 465      * <li><code>point</code><div class="sub-desc">The current mouse position is coerced into the
 466      * {@link #constrainRegion}, and the resulting position is returned.</div></li>
 467      * <li><code>dragTarget</code><div class="sub-desc">The new {@link Ext.util.Region Region} of the
 468      * {@link #getDragTarget dragTarget} is calculated based upon the current mouse position, and then
 469      * coerced into the {@link #constrainRegion}. The returned mouse position is then adjusted by the
 470      * same delta as was used to coerce the region.</div></li>
 471      * </ul>
 472      * @param constrainMode {String} Optional. If omitted the true mouse position is returned. May be passed
 473      * as <code>'point'</code> or <code>'dragTarget'. See above.</code>.
 474      * @returns {Array} The <code>X, Y</code> offset from the mousedown point, optionally constrained.
 475      */
 476     getOffset : function(constrain){
 477         var xy = this.getXY(constrain),
 478             s = this.startXY;
 479
 480         return [xy[0]-s[0], xy[1]-s[1]];
 481     },
 482
 483     constrainModes: {
 484         // Constrain the passed point to within the constrain region
 485         point: function(me, xy) {
 486             var dr = me.dragRegion,
 487                 constrainTo = me.getConstrainRegion();
 488
 489             // No constraint
 490             if (!constrainTo) {
 491                 return xy;
 492             }
 493
 494             dr.x = dr.left = dr[0] = dr.right = xy[0];
 495             dr.y = dr.top = dr[1] = dr.bottom = xy[1];
 496             dr.constrainTo(constrainTo);
 497
 498             return [dr.left, dr.top];
 499         },
 500
 501         // Constrain the dragTarget to within the constrain region. Return the passed xy adjusted by the same delta.
 502         dragTarget: function(me, xy) {
 503             var s = me.startXY,
 504                 dr = me.startRegion.copy(),
 505                 constrainTo = me.getConstrainRegion(),
 506                 adjust;
 507
 508             // No constraint
 509             if (!constrainTo) {
 510                 return xy;
 511             }
 512
 513             // See where the passed XY would put the dragTarget if translated by the unconstrained offset.
 514             // If it overflows, we constrain the passed XY to bring the potential
 515             // region back within the boundary.
 516             dr.translateBy(xy[0]-s[0], xy[1]-s[1]);
 517
 518             // Constrain the X coordinate by however much the dragTarget overflows
 519             if (dr.right > constrainTo.right) {
 520                 xy[0] += adjust = (constrainTo.right - dr.right);    // overflowed the right
 521                 dr.left += adjust;
 522             }
 523             if (dr.left < constrainTo.left) {
 524                 xy[0] += (constrainTo.left - dr.left);      // overflowed the left
 525             }
 526
 527             // Constrain the Y coordinate by however much the dragTarget overflows
 528             if (dr.bottom > constrainTo.bottom) {
 529                 xy[1] += adjust = (constrainTo.bottom - dr.bottom);  // overflowed the bottom
 530                 dr.top += adjust;
 531             }
 532             if (dr.top < constrainTo.top) {
 533                 xy[1] += (constrainTo.top - dr.top);        // overflowed the top
 534             }
 535             return xy;
 536         }
 537     }
 538 });