3 * Copyright(c) 2006-2010 Ext JS, Inc.
5 * http://www.extjs.com/license
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}, 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}'s initEvents function for an example implementation.
17 Ext.dd.DragTracker = Ext.extend(Ext.util.Observable, {
19 * @cfg {Boolean} active
20 * Defaults to <tt>false</tt>.
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>.
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.
35 constructor : function(config){
36 Ext.apply(this, config);
40 * @param {Object} this
41 * @param {Object} e event object
46 * @param {Object} this
47 * @param {Object} e event object
52 * @param {Object} this
53 * @param {Object} e event object
58 * @param {Object} this
59 * @param {Object} startXY the page coordinates of the event
64 * @param {Object} this
65 * @param {Object} e event object
70 * @param {Object} this
71 * @param {Object} e event object
76 this.dragRegion = new Ext.lib.Region(0,0,0,0);
81 Ext.dd.DragTracker.superclass.constructor.call(this, config);
85 this.el = Ext.get(el);
86 el.on('mousedown', this.onMouseDown, this,
87 this.delegate ? {delegate: this.delegate} : undefined);
91 this.el.un('mousedown', this.onMouseDown, this);
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){
102 var doc = Ext.getDoc();
103 doc.on('mouseup', this.onMouseUp, this);
104 doc.on('mousemove', this.onMouseMove, this);
105 doc.on('selectstart', this.stopSelect, this);
107 this.timer = this.triggerStart.defer(this.autoStart === true ? 1000 : this.autoStart, this);
112 onMouseMove: function(e, target){
113 // HACK: IE hack to see if button was released outside of window. */
114 if(this.active && Ext.isIE && !e.browserEvent.button){
121 var xy = e.getXY(), s = this.startXY;
124 if(Math.abs(s[0]-xy[0]) > this.tolerance || Math.abs(s[1]-xy[1]) > this.tolerance){
130 this.fireEvent('mousemove', this, e);
132 this.fireEvent('drag', this, e);
135 onMouseUp: function(e) {
136 var doc = Ext.getDoc();
137 doc.un('mousemove', this.onMouseMove, this);
138 doc.un('mouseup', this.onMouseUp, this);
139 doc.un('selectstart', this.stopSelect, this);
142 var wasActive = this.active;
144 delete this.elRegion;
145 this.fireEvent('mouseup', this, e);
148 this.fireEvent('dragend', this, e);
152 triggerStart: function(isTimer) {
155 this.onStart(this.startXY);
156 this.fireEvent('dragstart', this, this.startXY);
159 clearStart : function() {
161 clearTimeout(this.timer);
166 stopSelect : function(e) {
172 * Template method which should be overridden by each DragTracker instance. Called when the user first clicks and
173 * holds the mouse button down. Return false to disallow the drag
174 * @param {Ext.EventObject} e The event object
176 onBeforeStart : function(e) {
181 * Template method which should be overridden by each DragTracker instance. Called when a drag operation starts
182 * (e.g. the user has moved the tracked element beyond the specified tolerance)
183 * @param {Array} xy x and y co-ordinates of the original location of the tracked element
185 onStart : function(xy) {
190 * Template method which should be overridden by each DragTracker instance. Called whenever a drag has been detected.
191 * @param {Ext.EventObject} e The event object
193 onDrag : function(e) {
198 * Template method which should be overridden by each DragTracker instance. Called when a drag operation has been completed
199 * (e.g. the user clicked and held the mouse down, dragged the element and then released the mouse button)
200 * @param {Ext.EventObject} e The event object
202 onEnd : function(e) {
207 * Returns the drag target
208 * @return {Ext.Element} The element currently being tracked
210 getDragTarget : function(){
211 return this.dragTarget;
214 getDragCt : function(){
218 getXY : function(constrain){
220 this.constrainModes[constrain].call(this, this.lastXY) : this.lastXY;
223 getOffset : function(constrain){
224 var xy = this.getXY(constrain);
225 var s = this.startXY;
226 return [s[0]-xy[0], s[1]-xy[1]];
230 'point' : function(xy){
233 this.elRegion = this.getDragCt().getRegion();
236 var dr = this.dragRegion;
243 dr.constrainTo(this.elRegion);
245 return [dr.left, dr.top];