Upgrade to ExtJS 3.2.0 - Released 03/30/2010
[extjs.git] / docs / source / DragSource.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.0
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.DragSource"></div>/**
16  * @class Ext.dd.DragSource
17  * @extends Ext.dd.DDProxy
18  * A simple class that provides the basic implementation needed to make any element draggable.
19  * @constructor
20  * @param {Mixed} el The container element
21  * @param {Object} config
22  */
23 Ext.dd.DragSource = function(el, config){
24     this.el = Ext.get(el);
25     if(!this.dragData){
26         this.dragData = {};
27     }
28     
29     Ext.apply(this, config);
30     
31     if(!this.proxy){
32         this.proxy = new Ext.dd.StatusProxy();
33     }
34     Ext.dd.DragSource.superclass.constructor.call(this, this.el.dom, this.ddGroup || this.group, 
35           {dragElId : this.proxy.id, resizeFrame: false, isTarget: false, scroll: this.scroll === true});
36     
37     this.dragging = false;
38 };
39
40 Ext.extend(Ext.dd.DragSource, Ext.dd.DDProxy, {
41     <div id="cfg-Ext.dd.DragSource-ddGroup"></div>/**
42      * @cfg {String} ddGroup
43      * A named drag drop group to which this object belongs.  If a group is specified, then this object will only
44      * interact with other drag drop objects in the same group (defaults to undefined).
45      */
46     <div id="cfg-Ext.dd.DragSource-dropAllowed"></div>/**
47      * @cfg {String} dropAllowed
48      * The CSS class returned to the drag source when drop is allowed (defaults to "x-dd-drop-ok").
49      */
50     dropAllowed : "x-dd-drop-ok",
51     <div id="cfg-Ext.dd.DragSource-dropNotAllowed"></div>/**
52      * @cfg {String} dropNotAllowed
53      * The CSS class returned to the drag source when drop is not allowed (defaults to "x-dd-drop-nodrop").
54      */
55     dropNotAllowed : "x-dd-drop-nodrop",
56
57     <div id="method-Ext.dd.DragSource-getDragData"></div>/**
58      * Returns the data object associated with this drag source
59      * @return {Object} data An object containing arbitrary data
60      */
61     getDragData : function(e){
62         return this.dragData;
63     },
64
65     // private
66     onDragEnter : function(e, id){
67         var target = Ext.dd.DragDropMgr.getDDById(id);
68         this.cachedTarget = target;
69         if(this.beforeDragEnter(target, e, id) !== false){
70             if(target.isNotifyTarget){
71                 var status = target.notifyEnter(this, e, this.dragData);
72                 this.proxy.setStatus(status);
73             }else{
74                 this.proxy.setStatus(this.dropAllowed);
75             }
76             
77             if(this.afterDragEnter){
78                 <div id="method-Ext.dd.DragSource-afterDragEnter"></div>/**
79                  * An empty function by default, but provided so that you can perform a custom action
80                  * when the dragged item enters the drop target by providing an implementation.
81                  * @param {Ext.dd.DragDrop} target The drop target
82                  * @param {Event} e The event object
83                  * @param {String} id The id of the dragged element
84                  * @method afterDragEnter
85                  */
86                 this.afterDragEnter(target, e, id);
87             }
88         }
89     },
90
91     <div id="method-Ext.dd.DragSource-beforeDragEnter"></div>/**
92      * An empty function by default, but provided so that you can perform a custom action
93      * before the dragged item enters the drop target and optionally cancel the onDragEnter.
94      * @param {Ext.dd.DragDrop} target The drop target
95      * @param {Event} e The event object
96      * @param {String} id The id of the dragged element
97      * @return {Boolean} isValid True if the drag event is valid, else false to cancel
98      */
99     beforeDragEnter : function(target, e, id){
100         return true;
101     },
102
103     // private
104     alignElWithMouse: function() {
105         Ext.dd.DragSource.superclass.alignElWithMouse.apply(this, arguments);
106         this.proxy.sync();
107     },
108
109     // private
110     onDragOver : function(e, id){
111         var target = this.cachedTarget || Ext.dd.DragDropMgr.getDDById(id);
112         if(this.beforeDragOver(target, e, id) !== false){
113             if(target.isNotifyTarget){
114                 var status = target.notifyOver(this, e, this.dragData);
115                 this.proxy.setStatus(status);
116             }
117
118             if(this.afterDragOver){
119                 <div id="method-Ext.dd.DragSource-afterDragOver"></div>/**
120                  * An empty function by default, but provided so that you can perform a custom action
121                  * while the dragged item is over the drop target by providing an implementation.
122                  * @param {Ext.dd.DragDrop} target The drop target
123                  * @param {Event} e The event object
124                  * @param {String} id The id of the dragged element
125                  * @method afterDragOver
126                  */
127                 this.afterDragOver(target, e, id);
128             }
129         }
130     },
131
132     <div id="method-Ext.dd.DragSource-beforeDragOver"></div>/**
133      * An empty function by default, but provided so that you can perform a custom action
134      * while the dragged item is over the drop target and optionally cancel the onDragOver.
135      * @param {Ext.dd.DragDrop} target The drop target
136      * @param {Event} e The event object
137      * @param {String} id The id of the dragged element
138      * @return {Boolean} isValid True if the drag event is valid, else false to cancel
139      */
140     beforeDragOver : function(target, e, id){
141         return true;
142     },
143
144     // private
145     onDragOut : function(e, id){
146         var target = this.cachedTarget || Ext.dd.DragDropMgr.getDDById(id);
147         if(this.beforeDragOut(target, e, id) !== false){
148             if(target.isNotifyTarget){
149                 target.notifyOut(this, e, this.dragData);
150             }
151             this.proxy.reset();
152             if(this.afterDragOut){
153                 <div id="method-Ext.dd.DragSource-afterDragOut"></div>/**
154                  * An empty function by default, but provided so that you can perform a custom action
155                  * after the dragged item is dragged out of the target without dropping.
156                  * @param {Ext.dd.DragDrop} target The drop target
157                  * @param {Event} e The event object
158                  * @param {String} id The id of the dragged element
159                  * @method afterDragOut
160                  */
161                 this.afterDragOut(target, e, id);
162             }
163         }
164         this.cachedTarget = null;
165     },
166
167     <div id="method-Ext.dd.DragSource-beforeDragOut"></div>/**
168      * An empty function by default, but provided so that you can perform a custom action before the dragged
169      * item is dragged out of the target without dropping, and optionally cancel the onDragOut.
170      * @param {Ext.dd.DragDrop} target The drop target
171      * @param {Event} e The event object
172      * @param {String} id The id of the dragged element
173      * @return {Boolean} isValid True if the drag event is valid, else false to cancel
174      */
175     beforeDragOut : function(target, e, id){
176         return true;
177     },
178     
179     // private
180     onDragDrop : function(e, id){
181         var target = this.cachedTarget || Ext.dd.DragDropMgr.getDDById(id);
182         if(this.beforeDragDrop(target, e, id) !== false){
183             if(target.isNotifyTarget){
184                 if(target.notifyDrop(this, e, this.dragData)){ // valid drop?
185                     this.onValidDrop(target, e, id);
186                 }else{
187                     this.onInvalidDrop(target, e, id);
188                 }
189             }else{
190                 this.onValidDrop(target, e, id);
191             }
192             
193             if(this.afterDragDrop){
194                 <div id="method-Ext.dd.DragSource-afterDragDrop"></div>/**
195                  * An empty function by default, but provided so that you can perform a custom action
196                  * after a valid drag drop has occurred by providing an implementation.
197                  * @param {Ext.dd.DragDrop} target The drop target
198                  * @param {Event} e The event object
199                  * @param {String} id The id of the dropped element
200                  * @method afterDragDrop
201                  */
202                 this.afterDragDrop(target, e, id);
203             }
204         }
205         delete this.cachedTarget;
206     },
207
208     <div id="method-Ext.dd.DragSource-beforeDragDrop"></div>/**
209      * An empty function by default, but provided so that you can perform a custom action before the dragged
210      * item is dropped onto the target and optionally cancel the onDragDrop.
211      * @param {Ext.dd.DragDrop} target The drop target
212      * @param {Event} e The event object
213      * @param {String} id The id of the dragged element
214      * @return {Boolean} isValid True if the drag drop event is valid, else false to cancel
215      */
216     beforeDragDrop : function(target, e, id){
217         return true;
218     },
219
220     // private
221     onValidDrop : function(target, e, id){
222         this.hideProxy();
223         if(this.afterValidDrop){
224             /**
225              * An empty function by default, but provided so that you can perform a custom action
226              * after a valid drop has occurred by providing an implementation.
227              * @param {Object} target The target DD 
228              * @param {Event} e The event object
229              * @param {String} id The id of the dropped element
230              * @method afterInvalidDrop
231              */
232             this.afterValidDrop(target, e, id);
233         }
234     },
235
236     // private
237     getRepairXY : function(e, data){
238         return this.el.getXY();  
239     },
240
241     // private
242     onInvalidDrop : function(target, e, id){
243         this.beforeInvalidDrop(target, e, id);
244         if(this.cachedTarget){
245             if(this.cachedTarget.isNotifyTarget){
246                 this.cachedTarget.notifyOut(this, e, this.dragData);
247             }
248             this.cacheTarget = null;
249         }
250         this.proxy.repair(this.getRepairXY(e, this.dragData), this.afterRepair, this);
251
252         if(this.afterInvalidDrop){
253             <div id="method-Ext.dd.DragSource-afterInvalidDrop"></div>/**
254              * An empty function by default, but provided so that you can perform a custom action
255              * after an invalid drop has occurred by providing an implementation.
256              * @param {Event} e The event object
257              * @param {String} id The id of the dropped element
258              * @method afterInvalidDrop
259              */
260             this.afterInvalidDrop(e, id);
261         }
262     },
263
264     // private
265     afterRepair : function(){
266         if(Ext.enableFx){
267             this.el.highlight(this.hlColor || "c3daf9");
268         }
269         this.dragging = false;
270     },
271
272     <div id="method-Ext.dd.DragSource-beforeInvalidDrop"></div>/**
273      * An empty function by default, but provided so that you can perform a custom action after an invalid
274      * drop has occurred.
275      * @param {Ext.dd.DragDrop} target The drop target
276      * @param {Event} e The event object
277      * @param {String} id The id of the dragged element
278      * @return {Boolean} isValid True if the invalid drop should proceed, else false to cancel
279      */
280     beforeInvalidDrop : function(target, e, id){
281         return true;
282     },
283
284     // private
285     handleMouseDown : function(e){
286         if(this.dragging) {
287             return;
288         }
289         var data = this.getDragData(e);
290         if(data && this.onBeforeDrag(data, e) !== false){
291             this.dragData = data;
292             this.proxy.stop();
293             Ext.dd.DragSource.superclass.handleMouseDown.apply(this, arguments);
294         } 
295     },
296
297     <div id="method-Ext.dd.DragSource-onBeforeDrag"></div>/**
298      * An empty function by default, but provided so that you can perform a custom action before the initial
299      * drag event begins and optionally cancel it.
300      * @param {Object} data An object containing arbitrary data to be shared with drop targets
301      * @param {Event} e The event object
302      * @return {Boolean} isValid True if the drag event is valid, else false to cancel
303      */
304     onBeforeDrag : function(data, e){
305         return true;
306     },
307
308     <div id="method-Ext.dd.DragSource-onStartDrag"></div>/**
309      * An empty function by default, but provided so that you can perform a custom action once the initial
310      * drag event has begun.  The drag cannot be canceled from this function.
311      * @param {Number} x The x position of the click on the dragged object
312      * @param {Number} y The y position of the click on the dragged object
313      */
314     onStartDrag : Ext.emptyFn,
315
316     // private override
317     startDrag : function(x, y){
318         this.proxy.reset();
319         this.dragging = true;
320         this.proxy.update("");
321         this.onInitDrag(x, y);
322         this.proxy.show();
323     },
324
325     // private
326     onInitDrag : function(x, y){
327         var clone = this.el.dom.cloneNode(true);
328         clone.id = Ext.id(); // prevent duplicate ids
329         this.proxy.update(clone);
330         this.onStartDrag(x, y);
331         return true;
332     },
333
334     <div id="method-Ext.dd.DragSource-getProxy"></div>/**
335      * Returns the drag source's underlying {@link Ext.dd.StatusProxy}
336      * @return {Ext.dd.StatusProxy} proxy The StatusProxy
337      */
338     getProxy : function(){
339         return this.proxy;  
340     },
341
342     <div id="method-Ext.dd.DragSource-hideProxy"></div>/**
343      * Hides the drag source's {@link Ext.dd.StatusProxy}
344      */
345     hideProxy : function(){
346         this.proxy.hide();  
347         this.proxy.reset(true);
348         this.dragging = false;
349     },
350
351     // private
352     triggerCacheRefresh : function(){
353         Ext.dd.DDM.refreshCache(this.groups);
354     },
355
356     // private - override to prevent hiding
357     b4EndDrag: function(e) {
358     },
359
360     // private - override to prevent moving
361     endDrag : function(e){
362         this.onEndDrag(this.dragData, e);
363     },
364
365     // private
366     onEndDrag : function(data, e){
367     },
368     
369     // private - pin to cursor
370     autoOffset : function(x, y) {
371         this.setDelta(-12, -20);
372     },
373     
374     destroy: function(){
375         Ext.dd.DragSource.superclass.destroy.call(this);
376         Ext.destroy(this.proxy);
377     }
378 });</pre>    
379 </body>
380 </html>