docs/source/DragTracker.html

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