Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / DropZone.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.1
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.DropZone"></div>/**
16  * @class Ext.dd.DropZone
17  * @extends Ext.dd.DropTarget
18  * <p>This class provides a container DD instance that allows dropping on multiple child target nodes.</p>
19  * <p>By default, this class requires that child nodes accepting drop are registered with {@link Ext.dd.Registry}.
20  * However a simpler way to allow a DropZone to manage any number of target elements is to configure the
21  * DropZone with an implementation of {@link #getTargetFromEvent} which interrogates the passed
22  * mouse event to see if it has taken place within an element, or class of elements. This is easily done
23  * by using the event's {@link Ext.EventObject#getTarget getTarget} method to identify a node based on a
24  * {@link Ext.DomQuery} selector.</p>
25  * <p>Once the DropZone has detected through calling getTargetFromEvent, that the mouse is over
26  * a drop target, that target is passed as the first parameter to {@link #onNodeEnter}, {@link #onNodeOver},
27  * {@link #onNodeOut}, {@link #onNodeDrop}. You may configure the instance of DropZone with implementations
28  * of these methods to provide application-specific behaviour for these events to update both
29  * application state, and UI state.</p>
30  * <p>For example to make a GridPanel a cooperating target with the example illustrated in
31  * {@link Ext.dd.DragZone DragZone}, the following technique might be used:</p><pre><code>
32 myGridPanel.on('render', function() {
33     myGridPanel.dropZone = new Ext.dd.DropZone(myGridPanel.getView().scroller, {
34
35 //      If the mouse is over a grid row, return that node. This is
36 //      provided as the "target" parameter in all "onNodeXXXX" node event handling functions
37         getTargetFromEvent: function(e) {
38             return e.getTarget(myGridPanel.getView().rowSelector);
39         },
40
41 //      On entry into a target node, highlight that node.
42         onNodeEnter : function(target, dd, e, data){ 
43             Ext.fly(target).addClass('my-row-highlight-class');
44         },
45
46 //      On exit from a target node, unhighlight that node.
47         onNodeOut : function(target, dd, e, data){ 
48             Ext.fly(target).removeClass('my-row-highlight-class');
49         },
50
51 //      While over a target node, return the default drop allowed class which
52 //      places a "tick" icon into the drag proxy.
53         onNodeOver : function(target, dd, e, data){ 
54             return Ext.dd.DropZone.prototype.dropAllowed;
55         },
56
57 //      On node drop we can interrogate the target to find the underlying
58 //      application object that is the real target of the dragged data.
59 //      In this case, it is a Record in the GridPanel's Store.
60 //      We can use the data set up by the DragZone's getDragData method to read
61 //      any data we decided to attach in the DragZone's getDragData method.
62         onNodeDrop : function(target, dd, e, data){
63             var rowIndex = myGridPanel.getView().findRowIndex(target);
64             var r = myGridPanel.getStore().getAt(rowIndex);
65             Ext.Msg.alert('Drop gesture', 'Dropped Record id ' + data.draggedRecord.id +
66                 ' on Record id ' + r.id);
67             return true;
68         }
69     });
70 }
71 </code></pre>
72  * See the {@link Ext.dd.DragZone DragZone} documentation for details about building a DragZone which
73  * cooperates with this DropZone.
74  * @constructor
75  * @param {Mixed} el The container element
76  * @param {Object} config
77  */
78 Ext.dd.DropZone = function(el, config){
79     Ext.dd.DropZone.superclass.constructor.call(this, el, config);
80 };
81
82 Ext.extend(Ext.dd.DropZone, Ext.dd.DropTarget, {
83     <div id="method-Ext.dd.DropZone-getTargetFromEvent"></div>/**
84      * Returns a custom data object associated with the DOM node that is the target of the event.  By default
85      * this looks up the event target in the {@link Ext.dd.Registry}, although you can override this method to
86      * provide your own custom lookup.
87      * @param {Event} e The event
88      * @return {Object} data The custom data
89      */
90     getTargetFromEvent : function(e){
91         return Ext.dd.Registry.getTargetFromEvent(e);
92     },
93
94     <div id="method-Ext.dd.DropZone-onNodeEnter"></div>/**
95      * Called when the DropZone determines that a {@link Ext.dd.DragSource} has entered a drop node
96      * that has either been registered or detected by a configured implementation of {@link #getTargetFromEvent}.
97      * This method has no default implementation and should be overridden to provide
98      * node-specific processing if necessary.
99      * @param {Object} nodeData The custom data associated with the drop node (this is the same value returned from 
100      * {@link #getTargetFromEvent} for this node)
101      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
102      * @param {Event} e The event
103      * @param {Object} data An object containing arbitrary data supplied by the drag source
104      */
105     onNodeEnter : function(n, dd, e, data){
106         
107     },
108
109     <div id="method-Ext.dd.DropZone-onNodeOver"></div>/**
110      * Called while the DropZone determines that a {@link Ext.dd.DragSource} is over a drop node
111      * that has either been registered or detected by a configured implementation of {@link #getTargetFromEvent}.
112      * The default implementation returns this.dropNotAllowed, so it should be
113      * overridden to provide the proper feedback.
114      * @param {Object} nodeData The custom data associated with the drop node (this is the same value returned from
115      * {@link #getTargetFromEvent} for this node)
116      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
117      * @param {Event} e The event
118      * @param {Object} data An object containing arbitrary data supplied by the drag source
119      * @return {String} status The CSS class that communicates the drop status back to the source so that the
120      * underlying {@link Ext.dd.StatusProxy} can be updated
121      */
122     onNodeOver : function(n, dd, e, data){
123         return this.dropAllowed;
124     },
125
126     <div id="method-Ext.dd.DropZone-onNodeOut"></div>/**
127      * Called when the DropZone determines that a {@link Ext.dd.DragSource} has been dragged out of
128      * the drop node without dropping.  This method has no default implementation and should be overridden to provide
129      * node-specific processing if necessary.
130      * @param {Object} nodeData The custom data associated with the drop node (this is the same value returned from
131      * {@link #getTargetFromEvent} for this node)
132      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
133      * @param {Event} e The event
134      * @param {Object} data An object containing arbitrary data supplied by the drag source
135      */
136     onNodeOut : function(n, dd, e, data){
137         
138     },
139
140     <div id="method-Ext.dd.DropZone-onNodeDrop"></div>/**
141      * Called when the DropZone determines that a {@link Ext.dd.DragSource} has been dropped onto
142      * the drop node.  The default implementation returns false, so it should be overridden to provide the
143      * appropriate processing of the drop event and return true so that the drag source's repair action does not run.
144      * @param {Object} nodeData The custom data associated with the drop node (this is the same value returned from
145      * {@link #getTargetFromEvent} for this node)
146      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
147      * @param {Event} e The event
148      * @param {Object} data An object containing arbitrary data supplied by the drag source
149      * @return {Boolean} True if the drop was valid, else false
150      */
151     onNodeDrop : function(n, dd, e, data){
152         return false;
153     },
154
155     <div id="method-Ext.dd.DropZone-onContainerOver"></div>/**
156      * Called while the DropZone determines that a {@link Ext.dd.DragSource} is being dragged over it,
157      * but not over any of its registered drop nodes.  The default implementation returns this.dropNotAllowed, so
158      * it should be overridden to provide the proper feedback if necessary.
159      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
160      * @param {Event} e The event
161      * @param {Object} data An object containing arbitrary data supplied by the drag source
162      * @return {String} status The CSS class that communicates the drop status back to the source so that the
163      * underlying {@link Ext.dd.StatusProxy} can be updated
164      */
165     onContainerOver : function(dd, e, data){
166         return this.dropNotAllowed;
167     },
168
169     <div id="method-Ext.dd.DropZone-onContainerDrop"></div>/**
170      * Called when the DropZone determines that a {@link Ext.dd.DragSource} has been dropped on it,
171      * but not on any of its registered drop nodes.  The default implementation returns false, so it should be
172      * overridden to provide the appropriate processing of the drop event if you need the drop zone itself to
173      * be able to accept drops.  It should return true when valid so that the drag source's repair action does not run.
174      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
175      * @param {Event} e The event
176      * @param {Object} data An object containing arbitrary data supplied by the drag source
177      * @return {Boolean} True if the drop was valid, else false
178      */
179     onContainerDrop : function(dd, e, data){
180         return false;
181     },
182
183     <div id="method-Ext.dd.DropZone-notifyEnter"></div>/**
184      * The function a {@link Ext.dd.DragSource} calls once to notify this drop zone that the source is now over
185      * the zone.  The default implementation returns this.dropNotAllowed and expects that only registered drop
186      * nodes can process drag drop operations, so if you need the drop zone itself to be able to process drops
187      * you should override this method and provide a custom implementation.
188      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
189      * @param {Event} e The event
190      * @param {Object} data An object containing arbitrary data supplied by the drag source
191      * @return {String} status The CSS class that communicates the drop status back to the source so that the
192      * underlying {@link Ext.dd.StatusProxy} can be updated
193      */
194     notifyEnter : function(dd, e, data){
195         return this.dropNotAllowed;
196     },
197
198     <div id="method-Ext.dd.DropZone-notifyOver"></div>/**
199      * The function a {@link Ext.dd.DragSource} calls continuously while it is being dragged over the drop zone.
200      * This method will be called on every mouse movement while the drag source is over the drop zone.
201      * It will call {@link #onNodeOver} while the drag source is over a registered node, and will also automatically
202      * delegate to the appropriate node-specific methods as necessary when the drag source enters and exits
203      * registered nodes ({@link #onNodeEnter}, {@link #onNodeOut}). If the drag source is not currently over a
204      * registered node, it will call {@link #onContainerOver}.
205      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
206      * @param {Event} e The event
207      * @param {Object} data An object containing arbitrary data supplied by the drag source
208      * @return {String} status The CSS class that communicates the drop status back to the source so that the
209      * underlying {@link Ext.dd.StatusProxy} can be updated
210      */
211     notifyOver : function(dd, e, data){
212         var n = this.getTargetFromEvent(e);
213         if(!n){ // not over valid drop target
214             if(this.lastOverNode){
215                 this.onNodeOut(this.lastOverNode, dd, e, data);
216                 this.lastOverNode = null;
217             }
218             return this.onContainerOver(dd, e, data);
219         }
220         if(this.lastOverNode != n){
221             if(this.lastOverNode){
222                 this.onNodeOut(this.lastOverNode, dd, e, data);
223             }
224             this.onNodeEnter(n, dd, e, data);
225             this.lastOverNode = n;
226         }
227         return this.onNodeOver(n, dd, e, data);
228     },
229
230     <div id="method-Ext.dd.DropZone-notifyOut"></div>/**
231      * The function a {@link Ext.dd.DragSource} calls once to notify this drop zone that the source has been dragged
232      * out of the zone without dropping.  If the drag source is currently over a registered node, the notification
233      * will be delegated to {@link #onNodeOut} for node-specific handling, otherwise it will be ignored.
234      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop target
235      * @param {Event} e The event
236      * @param {Object} data An object containing arbitrary data supplied by the drag zone
237      */
238     notifyOut : function(dd, e, data){
239         if(this.lastOverNode){
240             this.onNodeOut(this.lastOverNode, dd, e, data);
241             this.lastOverNode = null;
242         }
243     },
244
245     <div id="method-Ext.dd.DropZone-notifyDrop"></div>/**
246      * The function a {@link Ext.dd.DragSource} calls once to notify this drop zone that the dragged item has
247      * been dropped on it.  The drag zone will look up the target node based on the event passed in, and if there
248      * is a node registered for that event, it will delegate to {@link #onNodeDrop} for node-specific handling,
249      * otherwise it will call {@link #onContainerDrop}.
250      * @param {Ext.dd.DragSource} source The drag source that was dragged over this drop zone
251      * @param {Event} e The event
252      * @param {Object} data An object containing arbitrary data supplied by the drag source
253      * @return {Boolean} True if the drop was valid, else false
254      */
255     notifyDrop : function(dd, e, data){
256         if(this.lastOverNode){
257             this.onNodeOut(this.lastOverNode, dd, e, data);
258             this.lastOverNode = null;
259         }
260         var n = this.getTargetFromEvent(e);
261         return n ?
262             this.onNodeDrop(n, dd, e, data) :
263             this.onContainerDrop(dd, e, data);
264     },
265
266     // private
267     triggerCacheRefresh : function(){
268         Ext.dd.DDM.refreshCache(this.groups);
269     }  
270 });</pre>    
271 </body>
272 </html>