src/dd/DragTracker.js

   1 /*!
   2  * Ext JS Library 3.3.1
   3  * Copyright(c) 2006-2010 Sencha Inc.
   4  * licensing@sencha.com
   5  * http://www.sencha.com/license
   6  */
   7 /**
   8  * @class Ext.dd.DragTracker
   9  * @extends Ext.util.Observable
  10  * A DragTracker listens for drag events on an Element and fires events at the start and end of the drag,
  11  * as well as during the drag. This is useful for components such as {@link Ext.slider.MultiSlider}, where there is
  12  * an element that can be dragged around to change the Slider's value.
  13  * DragTracker provides a series of template methods that should be overridden to provide functionality
  14  * in response to detected drag operations. These are onBeforeStart, onStart, onDrag and onEnd.
  15  * See {@link Ext.slider.MultiSlider}'s initEvents function for an example implementation.
  16  */
  17 Ext.dd.DragTracker = Ext.extend(Ext.util.Observable,  {
  18     /**
  19      * @cfg {Boolean} active
  20          * Defaults to <tt>false</tt>.
  21          */
  22     active: false,
  23     /**
  24      * @cfg {Number} tolerance
  25          * Number of pixels the drag target must be moved before dragging is considered to have started. Defaults to <tt>5</tt>.
  26          */
  27     tolerance: 5,
  28     /**
  29      * @cfg {Boolean/Number} autoStart
  30          * Defaults to <tt>false</tt>. Specify <tt>true</tt> to defer trigger start by 1000 ms.
  31          * Specify a Number for the number of milliseconds to defer trigger start.
  32          */
  33     autoStart: false,
  34
  35     constructor : function(config){
  36         Ext.apply(this, config);
  37             this.addEvents(
  38                 /**
  39                  * @event mousedown
  40                  * @param {Object} this
  41                  * @param {Object} e event object
  42                  */
  43                 'mousedown',
  44                 /**
  45                  * @event mouseup
  46                  * @param {Object} this
  47                  * @param {Object} e event object
  48                  */
  49                 'mouseup',
  50                 /**
  51                  * @event mousemove
  52                  * @param {Object} this
  53                  * @param {Object} e event object
  54                  */
  55                 'mousemove',
  56                 /**
  57                  * @event dragstart
  58                  * @param {Object} this
  59                  * @param {Object} e event object
  60                  */
  61                 'dragstart',
  62                 /**
  63                  * @event dragend
  64                  * @param {Object} this
  65                  * @param {Object} e event object
  66                  */
  67                 'dragend',
  68                 /**
  69                  * @event drag
  70                  * @param {Object} this
  71                  * @param {Object} e event object
  72                  */
  73                 'drag'
  74             );
  75
  76             this.dragRegion = new Ext.lib.Region(0,0,0,0);
  77
  78             if(this.el){
  79                 this.initEl(this.el);
  80             }
  81         Ext.dd.DragTracker.superclass.constructor.call(this, config);
  82     },
  83
  84     initEl: function(el){
  85         this.el = Ext.get(el);
  86         el.on('mousedown', this.onMouseDown, this,
  87                 this.delegate ? {delegate: this.delegate} : undefined);
  88     },
  89
  90     destroy : function(){
  91         this.el.un('mousedown', this.onMouseDown, this);
  92         delete this.el;
  93     },
  94
  95     onMouseDown: function(e, target){
  96         if(this.fireEvent('mousedown', this, e) !== false && this.onBeforeStart(e) !== false){
  97             this.startXY = this.lastXY = e.getXY();
  98             this.dragTarget = this.delegate ? target : this.el.dom;
  99             if(this.preventDefault !== false){
 100                 e.preventDefault();
 101             }
 102             Ext.getDoc().on({
 103                 scope: this,
 104                 mouseup: this.onMouseUp,
 105                 mousemove: this.onMouseMove,
 106                 selectstart: this.stopSelect
 107             });
 108             if(this.autoStart){
 109                 this.timer = this.triggerStart.defer(this.autoStart === true ? 1000 : this.autoStart, this, [e]);
 110             }
 111         }
 112     },
 113
 114     onMouseMove: function(e, target){
 115         // HACK: IE hack to see if button was released outside of window. */
 116         if(this.active && Ext.isIE && !e.browserEvent.button){
 117             e.preventDefault();
 118             this.onMouseUp(e);
 119             return;
 120         }
 121
 122         e.preventDefault();
 123         var xy = e.getXY(), s = this.startXY;
 124         this.lastXY = xy;
 125         if(!this.active){
 126             if(Math.abs(s[0]-xy[0]) > this.tolerance || Math.abs(s[1]-xy[1]) > this.tolerance){
 127                 this.triggerStart(e);
 128             }else{
 129                 return;
 130             }
 131         }
 132         this.fireEvent('mousemove', this, e);
 133         this.onDrag(e);
 134         this.fireEvent('drag', this, e);
 135     },
 136
 137     onMouseUp: function(e) {
 138         var doc = Ext.getDoc(),
 139             wasActive = this.active;
 140
 141         doc.un('mousemove', this.onMouseMove, this);
 142         doc.un('mouseup', this.onMouseUp, this);
 143         doc.un('selectstart', this.stopSelect, this);
 144         e.preventDefault();
 145         this.clearStart();
 146         this.active = false;
 147         delete this.elRegion;
 148         this.fireEvent('mouseup', this, e);
 149         if(wasActive){
 150             this.onEnd(e);
 151             this.fireEvent('dragend', this, e);
 152         }
 153     },
 154
 155     triggerStart: function(e) {
 156         this.clearStart();
 157         this.active = true;
 158         this.onStart(e);
 159         this.fireEvent('dragstart', this, e);
 160     },
 161
 162     clearStart : function() {
 163         if(this.timer){
 164             clearTimeout(this.timer);
 165             delete this.timer;
 166         }
 167     },
 168
 169     stopSelect : function(e) {
 170         e.stopEvent();
 171         return false;
 172     },
 173
 174     /**
 175      * Template method which should be overridden by each DragTracker instance. Called when the user first clicks and
 176      * holds the mouse button down. Return false to disallow the drag
 177      * @param {Ext.EventObject} e The event object
 178      */
 179     onBeforeStart : function(e) {
 180
 181     },
 182
 183     /**
 184      * Template method which should be overridden by each DragTracker instance. Called when a drag operation starts
 185      * (e.g. the user has moved the tracked element beyond the specified tolerance)
 186      * @param {Ext.EventObject} e The event object
 187      */
 188     onStart : function(xy) {
 189
 190     },
 191
 192     /**
 193      * Template method which should be overridden by each DragTracker instance. Called whenever a drag has been detected.
 194      * @param {Ext.EventObject} e The event object
 195      */
 196     onDrag : function(e) {
 197
 198     },
 199
 200     /**
 201      * Template method which should be overridden by each DragTracker instance. Called when a drag operation has been completed
 202      * (e.g. the user clicked and held the mouse down, dragged the element and then released the mouse button)
 203      * @param {Ext.EventObject} e The event object
 204      */
 205     onEnd : function(e) {
 206
 207     },
 208
 209     /**
 210      * Returns the drag target
 211      * @return {Ext.Element} The element currently being tracked
 212      */
 213     getDragTarget : function(){
 214         return this.dragTarget;
 215     },
 216
 217     getDragCt : function(){
 218         return this.el;
 219     },
 220
 221     getXY : function(constrain){
 222         return constrain ?
 223                this.constrainModes[constrain].call(this, this.lastXY) : this.lastXY;
 224     },
 225
 226     getOffset : function(constrain){
 227         var xy = this.getXY(constrain),
 228             s = this.startXY;
 229         return [s[0]-xy[0], s[1]-xy[1]];
 230     },
 231
 232     constrainModes: {
 233         'point' : function(xy){
 234
 235             if(!this.elRegion){
 236                 this.elRegion = this.getDragCt().getRegion();
 237             }
 238
 239             var dr = this.dragRegion;
 240
 241             dr.left = xy[0];
 242             dr.top = xy[1];
 243             dr.right = xy[0];
 244             dr.bottom = xy[1];
 245
 246             dr.constrainTo(this.elRegion);
 247
 248             return [dr.left, dr.top];
 249         }
 250     }
 251 });