docs/source/DragTracker.html

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