Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / src / dd / DragZone.js
1 /*!
2  * Ext JS Library 3.3.1
3  * Copyright(c) 2006-2010 Sencha Inc.
4  * licensing@sencha.com
5  * http://www.sencha.com/license
6  */
7 /**
8  * @class Ext.dd.DragZone
9  * @extends Ext.dd.DragSource
10  * <p>This class provides a container DD instance that allows dragging of multiple child source nodes.</p>
11  * <p>This class does not move the drag target nodes, but a proxy element which may contain
12  * any DOM structure you wish. The DOM element to show in the proxy is provided by either a
13  * provided implementation of {@link #getDragData}, or by registered draggables registered with {@link Ext.dd.Registry}</p>
14  * <p>If you wish to provide draggability for an arbitrary number of DOM nodes, each of which represent some
15  * application object (For example nodes in a {@link Ext.DataView DataView}) then use of this class
16  * is the most efficient way to "activate" those nodes.</p>
17  * <p>By default, this class requires that draggable child nodes are registered with {@link Ext.dd.Registry}.
18  * However a simpler way to allow a DragZone to manage any number of draggable elements is to configure
19  * the DragZone with  an implementation of the {@link #getDragData} method which interrogates the passed
20  * mouse event to see if it has taken place within an element, or class of elements. This is easily done
21  * by using the event's {@link Ext.EventObject#getTarget getTarget} method to identify a node based on a
22  * {@link Ext.DomQuery} selector. For example, to make the nodes of a DataView draggable, use the following
23  * technique. Knowledge of the use of the DataView is required:</p><pre><code>
24 myDataView.on('render', function(v) {
25     myDataView.dragZone = new Ext.dd.DragZone(v.getEl(), {
26
27 //      On receipt of a mousedown event, see if it is within a DataView node.
28 //      Return a drag data object if so.
29         getDragData: function(e) {
30
31 //          Use the DataView's own itemSelector (a mandatory property) to
32 //          test if the mousedown is within one of the DataView's nodes.
33             var sourceEl = e.getTarget(v.itemSelector, 10);
34
35 //          If the mousedown is within a DataView node, clone the node to produce
36 //          a ddel element for use by the drag proxy. Also add application data
37 //          to the returned data object.
38             if (sourceEl) {
39                 d = sourceEl.cloneNode(true);
40                 d.id = Ext.id();
41                 return {
42                     ddel: d,
43                     sourceEl: sourceEl,
44                     repairXY: Ext.fly(sourceEl).getXY(),
45                     sourceStore: v.store,
46                     draggedRecord: v.{@link Ext.DataView#getRecord getRecord}(sourceEl)
47                 }
48             }
49         },
50
51 //      Provide coordinates for the proxy to slide back to on failed drag.
52 //      This is the original XY coordinates of the draggable element captured
53 //      in the getDragData method.
54         getRepairXY: function() {
55             return this.dragData.repairXY;
56         }
57     });
58 });</code></pre>
59  * See the {@link Ext.dd.DropZone DropZone} documentation for details about building a DropZone which
60  * cooperates with this DragZone.
61  * @constructor
62  * @param {Mixed} el The container element
63  * @param {Object} config
64  */
65 Ext.dd.DragZone = Ext.extend(Ext.dd.DragSource, {
66     
67     constructor : function(el, config){
68         Ext.dd.DragZone.superclass.constructor.call(this, el, config);
69         if(this.containerScroll){
70             Ext.dd.ScrollManager.register(this.el);
71         }
72     },
73     
74     /**
75      * This property contains the data representing the dragged object. This data is set up by the implementation
76      * of the {@link #getDragData} method. It must contain a <tt>ddel</tt> property, but can contain
77      * any other data according to the application's needs.
78      * @type Object
79      * @property dragData
80      */
81     /**
82      * @cfg {Boolean} containerScroll True to register this container with the Scrollmanager
83      * for auto scrolling during drag operations.
84      */
85     /**
86      * @cfg {String} hlColor The color to use when visually highlighting the drag source in the afterRepair
87      * method after a failed drop (defaults to "c3daf9" - light blue)
88      */
89
90     /**
91      * Called when a mousedown occurs in this container. Looks in {@link Ext.dd.Registry}
92      * for a valid target to drag based on the mouse down. Override this method
93      * to provide your own lookup logic (e.g. finding a child by class name). Make sure your returned
94      * object has a "ddel" attribute (with an HTML Element) for other functions to work.
95      * @param {EventObject} e The mouse down event
96      * @return {Object} The dragData
97      */
98     getDragData : function(e){
99         return Ext.dd.Registry.getHandleFromEvent(e);
100     },
101     
102     /**
103      * Called once drag threshold has been reached to initialize the proxy element. By default, it clones the
104      * this.dragData.ddel
105      * @param {Number} x The x position of the click on the dragged object
106      * @param {Number} y The y position of the click on the dragged object
107      * @return {Boolean} true to continue the drag, false to cancel
108      */
109     onInitDrag : function(x, y){
110         this.proxy.update(this.dragData.ddel.cloneNode(true));
111         this.onStartDrag(x, y);
112         return true;
113     },
114     
115     /**
116      * Called after a repair of an invalid drop. By default, highlights this.dragData.ddel 
117      */
118     afterRepair : function(){
119         if(Ext.enableFx){
120             Ext.Element.fly(this.dragData.ddel).highlight(this.hlColor || "c3daf9");
121         }
122         this.dragging = false;
123     },
124
125     /**
126      * Called before a repair of an invalid drop to get the XY to animate to. By default returns
127      * the XY of this.dragData.ddel
128      * @param {EventObject} e The mouse up event
129      * @return {Array} The xy location (e.g. [100, 200])
130      */
131     getRepairXY : function(e){
132         return Ext.Element.fly(this.dragData.ddel).getXY();  
133     },
134     
135     destroy : function(){
136         Ext.dd.DragZone.superclass.destroy.call(this);
137         if(this.containerScroll){
138             Ext.dd.ScrollManager.unregister(this.el);
139         }
140     }
141 });