Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / DragDrop2.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-grid-plugin-DragDrop'>/**
19 </span> * This plugin provides drag and/or drop functionality for a GridView.
20  *
21  * It creates a specialized instance of {@link Ext.dd.DragZone DragZone} which knows how to drag out of a {@link
22  * Ext.grid.View GridView} and loads the data object which is passed to a cooperating {@link Ext.dd.DragZone DragZone}'s
23  * methods with the following properties:
24  *
25  * - `copy` : Boolean
26  *
27  *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` _and_
28  *   the control key was pressed when the drag operation was begun.
29  *
30  * - `view` : GridView
31  *
32  *   The source GridView from which the drag originated.
33  *
34  * - `ddel` : HtmlElement
35  *
36  *   The drag proxy element which moves with the mouse
37  *
38  * - `item` : HtmlElement
39  *
40  *   The GridView node upon which the mousedown event was registered.
41  *
42  * - `records` : Array
43  *
44  *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
45  *
46  * It also creates a specialized instance of {@link Ext.dd.DropZone} which cooperates with other DropZones which are
47  * members of the same ddGroup which processes such data objects.
48  *
49  * Adding this plugin to a view means that two new events may be fired from the client GridView, `{@link #beforedrop
50  * beforedrop}` and `{@link #drop drop}`
51  *
52  *     @example
53  *     Ext.create('Ext.data.Store', {
54  *         storeId:'simpsonsStore',
55  *         fields:['name'],
56  *         data: [[&quot;Lisa&quot;], [&quot;Bart&quot;], [&quot;Homer&quot;], [&quot;Marge&quot;]],
57  *         proxy: {
58  *             type: 'memory',
59  *             reader: 'array'
60  *         }
61  *     });
62  *
63  *     Ext.create('Ext.grid.Panel', {
64  *         store: 'simpsonsStore',
65  *         columns: [
66  *             {header: 'Name',  dataIndex: 'name', flex: true}
67  *         ],
68  *         viewConfig: {
69  *             plugins: {
70  *                 ptype: 'gridviewdragdrop',
71  *                 dragText: 'Drag and drop to reorganize'
72  *             }
73  *         },
74  *         height: 200,
75  *         width: 400,
76  *         renderTo: Ext.getBody()
77  *     });
78  */
79 Ext.define('Ext.grid.plugin.DragDrop', {
80     extend: 'Ext.AbstractPlugin',
81     alias: 'plugin.gridviewdragdrop',
82
83     uses: [
84         'Ext.view.DragZone',
85         'Ext.grid.ViewDropZone'
86     ],
87
88 <span id='Ext-grid-plugin-DragDrop-event-beforedrop'>    /**
89 </span>     * @event beforedrop
90      * **This event is fired through the GridView. Add listeners to the GridView object**
91      *
92      * Fired when a drop gesture has been triggered by a mouseup event in a valid drop position in the GridView.
93      *
94      * @param {HTMLElement} node The GridView node **if any** over which the mouse was positioned.
95      *
96      * Returning `false` to this event signals that the drop gesture was invalid, and if the drag proxy will animate
97      * back to the point from which the drag began.
98      *
99      * Returning `0` To this event signals that the data transfer operation should not take place, but that the gesture
100      * was valid, and that the repair operation should not take place.
101      *
102      * Any other return value continues with the data transfer operation.
103      *
104      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone
105      * DragZone}'s {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:
106      *
107      * - copy : Boolean
108      *
109      *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` and
110      *   the control key was pressed when the drag operation was begun
111      *
112      * - view : GridView
113      *
114      *   The source GridView from which the drag originated.
115      *
116      * - ddel : HtmlElement
117      *
118      *   The drag proxy element which moves with the mouse
119      *
120      * - item : HtmlElement
121      *
122      *   The GridView node upon which the mousedown event was registered.
123      *
124      * - records : Array
125      *
126      *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
127      *
128      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
129      *
130      * @param {String} dropPosition `&quot;before&quot;` or `&quot;after&quot;` depending on whether the mouse is above or below the midline
131      * of the node.
132      *
133      * @param {Function} dropFunction
134      *
135      * A function to call to complete the data transfer operation and either move or copy Model instances from the
136      * source View's Store to the destination View's Store.
137      *
138      * This is useful when you want to perform some kind of asynchronous processing before confirming the drop, such as
139      * an {@link Ext.window.MessageBox#confirm confirm} call, or an Ajax request.
140      *
141      * Return `0` from this event handler, and call the `dropFunction` at any time to perform the data transfer.
142      */
143
144 <span id='Ext-grid-plugin-DragDrop-event-drop'>    /**
145 </span>     * @event drop
146      * **This event is fired through the GridView. Add listeners to the GridView object** Fired when a drop operation
147      * has been completed and the data has been moved or copied.
148      *
149      * @param {HTMLElement} node The GridView node **if any** over which the mouse was positioned.
150      *
151      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone
152      * DragZone}'s {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:
153      *
154      * - copy : Boolean
155      *
156      *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` and
157      *   the control key was pressed when the drag operation was begun
158      *
159      * - view : GridView
160      *
161      *   The source GridView from which the drag originated.
162      *
163      * - ddel : HtmlElement
164      *
165      *   The drag proxy element which moves with the mouse
166      *
167      * - item : HtmlElement
168      *
169      *   The GridView node upon which the mousedown event was registered.
170      *
171      * - records : Array
172      *
173      *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
174      *
175      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
176      *
177      * @param {String} dropPosition `&quot;before&quot;` or `&quot;after&quot;` depending on whether the mouse is above or below the midline
178      * of the node.
179      */
180
181     dragText : '{0} selected row{1}',
182
183 <span id='Ext-grid-plugin-DragDrop-cfg-ddGroup'>    /**
184 </span>     * @cfg {String} ddGroup
185      * A named drag drop group to which this object belongs. If a group is specified, then both the DragZones and
186      * DropZone used by this plugin will only interact with other drag drop objects in the same group.
187      */
188     ddGroup : &quot;GridDD&quot;,
189
190 <span id='Ext-grid-plugin-DragDrop-cfg-dragGroup'>    /**
191 </span>     * @cfg {String} dragGroup
192      * The ddGroup to which the DragZone will belong.
193      *
194      * This defines which other DropZones the DragZone will interact with. Drag/DropZones only interact with other
195      * Drag/DropZones which are members of the same ddGroup.
196      */
197
198 <span id='Ext-grid-plugin-DragDrop-cfg-dropGroup'>    /**
199 </span>     * @cfg {String} dropGroup
200      * The ddGroup to which the DropZone will belong.
201      *
202      * This defines which other DragZones the DropZone will interact with. Drag/DropZones only interact with other
203      * Drag/DropZones which are members of the same ddGroup.
204      */
205
206 <span id='Ext-grid-plugin-DragDrop-cfg-enableDrop'>    /**
207 </span>     * @cfg {Boolean} enableDrop
208      * False to disallow the View from accepting drop gestures.
209      */
210     enableDrop: true,
211
212 <span id='Ext-grid-plugin-DragDrop-cfg-enableDrag'>    /**
213 </span>     * @cfg {Boolean} enableDrag
214      * False to disallow dragging items from the View.
215      */
216     enableDrag: true,
217
218     init : function(view) {
219         view.on('render', this.onViewRender, this, {single: true});
220     },
221
222 <span id='Ext-grid-plugin-DragDrop-method-destroy'>    /**
223 </span>     * @private
224      * AbstractComponent calls destroy on all its plugins at destroy time.
225      */
226     destroy: function() {
227         Ext.destroy(this.dragZone, this.dropZone);
228     },
229
230     enable: function() {
231         var me = this;
232         if (me.dragZone) {
233             me.dragZone.unlock();
234         }
235         if (me.dropZone) {
236             me.dropZone.unlock();
237         }
238         me.callParent();
239     },
240
241     disable: function() {
242         var me = this;
243         if (me.dragZone) {
244             me.dragZone.lock();
245         }
246         if (me.dropZone) {
247             me.dropZone.lock();
248         }
249         me.callParent();
250     },
251
252     onViewRender : function(view) {
253         var me = this;
254
255         if (me.enableDrag) {
256             me.dragZone = Ext.create('Ext.view.DragZone', {
257                 view: view,
258                 ddGroup: me.dragGroup || me.ddGroup,
259                 dragText: me.dragText
260             });
261         }
262
263         if (me.enableDrop) {
264             me.dropZone = Ext.create('Ext.grid.ViewDropZone', {
265                 view: view,
266                 ddGroup: me.dropGroup || me.ddGroup
267             });
268         }
269     }
270 });</pre>
271 </body>
272 </html>