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