src/dd/DropZone.js

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