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.3.1
  11  * Copyright(c) 2006-2010 Sencha Inc.
  12  * licensing@sencha.com
  13  * http://www.sencha.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>