Upgrade to ExtJS 4.0.1 - Released 05/18/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="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../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> * @class Ext.grid.plugin.DragDrop
20  * &lt;p&gt;This plugin provides drag and/or drop functionality for a GridView.&lt;/p&gt;
21  * &lt;p&gt;It creates a specialized instance of {@link Ext.dd.DragZone DragZone} which knows how to drag out of a {@link Ext.grid.View GridView}
22  * and loads the data object which is passed to a cooperating {@link Ext.dd.DragZone DragZone}'s methods with the following properties:&lt;ul&gt;
23  * &lt;li&gt;copy : Boolean
24  *  &lt;div class=&quot;sub-desc&quot;&gt;The value of the GridView's &lt;code&gt;copy&lt;/code&gt; property, or &lt;code&gt;true&lt;/code&gt; if the GridView was configured
25  *  with &lt;code&gt;allowCopy: true&lt;/code&gt; &lt;u&gt;and&lt;/u&gt; the control key was pressed when the drag operation was begun.&lt;/div&gt;&lt;/li&gt;
26  * &lt;li&gt;view : GridView
27  *  &lt;div class=&quot;sub-desc&quot;&gt;The source GridView from which the drag originated.&lt;/div&gt;&lt;/li&gt;
28  * &lt;li&gt;ddel : HtmlElement
29  *  &lt;div class=&quot;sub-desc&quot;&gt;The drag proxy element which moves with the mouse&lt;/div&gt;&lt;/li&gt;
30  * &lt;li&gt;item : HtmlElement
31  *  &lt;div class=&quot;sub-desc&quot;&gt;The GridView node upon which the mousedown event was registered.&lt;/div&gt;&lt;/li&gt;
32  * &lt;li&gt;records : Array
33  *  &lt;div class=&quot;sub-desc&quot;&gt;An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.&lt;/div&gt;&lt;/li&gt;
34  * &lt;/ul&gt;&lt;/p&gt;
35  * &lt;p&gt;It also creates a specialized instance of {@link Ext.dd.DropZone} which cooperates with other DropZones which are members of the same
36  * ddGroup which processes such data objects.&lt;/p&gt;
37  * &lt;p&gt;Adding this plugin to a view means that two new events may be fired from the client GridView, &lt;code&gt;{@link #event-beforedrop beforedrop}&lt;/code&gt; and
38  * &lt;code&gt;{@link #event-drop drop}&lt;/code&gt;&lt;/p&gt;
39  */
40 Ext.define('Ext.grid.plugin.DragDrop', {
41     extend: 'Ext.AbstractPlugin',
42     alias: 'plugin.gridviewdragdrop',
43
44     uses: [
45         'Ext.view.DragZone',
46         'Ext.grid.ViewDropZone'
47     ],
48
49 <span id='Ext-grid-plugin-DragDrop-event-beforedrop'>    /**
50 </span>     * @event beforedrop
51      * &lt;p&gt;&lt;b&gt;This event is fired through the GridView. Add listeners to the GridView object&lt;/b&gt;&lt;/p&gt;
52      * &lt;p&gt;Fired when a drop gesture has been triggered by a mouseup event in a valid drop position in the GridView.
53      * @param {HtmlElement} node The GridView node &lt;b&gt;if any&lt;/b&gt; over which the mouse was positioned.&lt;/p&gt;
54      * &lt;p&gt;Returning &lt;code&gt;false&lt;/code&gt; to this event signals that the drop gesture was invalid, and if the drag proxy
55      * will animate back to the point from which the drag began.&lt;/p&gt;
56      * &lt;p&gt;Returning &lt;code&gt;0&lt;/code&gt; To this event signals that the data transfer operation should not take place, but
57      * that the gesture was valid, and that the repair operation should not take place.&lt;/p&gt;
58      * &lt;p&gt;Any other return value continues with the data transfer operation.&lt;/p&gt;
59      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone DragZone}'s
60      * {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:&lt;ul&gt;
61      * &lt;li&gt;copy : Boolean
62      *  &lt;div class=&quot;sub-desc&quot;&gt;The value of the GridView's &lt;code&gt;copy&lt;/code&gt; property, or &lt;code&gt;true&lt;/code&gt; if the GridView was configured
63      *  with &lt;code&gt;allowCopy: true&lt;/code&gt; and the control key was pressed when the drag operation was begun&lt;/div&gt;&lt;/li&gt;
64      * &lt;li&gt;view : GridView
65      *  &lt;div class=&quot;sub-desc&quot;&gt;The source GridView from which the drag originated.&lt;/div&gt;&lt;/li&gt;
66      * &lt;li&gt;ddel : HtmlElement
67      *  &lt;div class=&quot;sub-desc&quot;&gt;The drag proxy element which moves with the mouse&lt;/div&gt;&lt;/li&gt;
68      * &lt;li&gt;item : HtmlElement
69      *  &lt;div class=&quot;sub-desc&quot;&gt;The GridView node upon which the mousedown event was registered.&lt;/div&gt;&lt;/li&gt;
70      * &lt;li&gt;records : Array
71      *  &lt;div class=&quot;sub-desc&quot;&gt;An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.&lt;/div&gt;&lt;/li&gt;
72      * &lt;/ul&gt;
73      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
74      * @param {String} dropPosition &lt;code&gt;&quot;before&quot;&lt;/code&gt; or &lt;code&gt;&quot;after&quot;&lt;/code&gt; depending on whether the mouse is above or below the midline of the node.
75      * @param {Function} dropFunction &lt;p&gt;A function to call to complete the data transfer operation and either move or copy Model instances from the source
76      * View's Store to the destination View's Store.&lt;/p&gt;
77      * &lt;p&gt;This is useful when you want to perform some kind of asynchronous processing before confirming
78      * the drop, such as an {@link Ext.window.MessageBox#confirm confirm} call, or an Ajax request.&lt;/p&gt;
79      * &lt;p&gt;Return &lt;code&gt;0&lt;/code&gt; from this event handler, and call the &lt;code&gt;dropFunction&lt;/code&gt; at any time to perform the data transfer.&lt;/p&gt;
80      */
81
82 <span id='Ext-grid-plugin-DragDrop-event-drop'>    /**
83 </span>     * @event drop
84      * &lt;b&gt;This event is fired through the GridView. Add listeners to the GridView object&lt;/b&gt;
85      * Fired when a drop operation has been completed and the data has been moved or copied.
86      * @param {HtmlElement} node The GridView node &lt;b&gt;if any&lt;/b&gt; over which the mouse was positioned.
87      * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone DragZone}'s
88      * {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:&lt;ul&gt;
89      * &lt;li&gt;copy : Boolean
90      *  &lt;div class=&quot;sub-desc&quot;&gt;The value of the GridView's &lt;code&gt;copy&lt;/code&gt; property, or &lt;code&gt;true&lt;/code&gt; if the GridView was configured
91      *  with &lt;code&gt;allowCopy: true&lt;/code&gt; and the control key was pressed when the drag operation was begun&lt;/div&gt;&lt;/li&gt;
92      * &lt;li&gt;view : GridView
93      *  &lt;div class=&quot;sub-desc&quot;&gt;The source GridView from which the drag originated.&lt;/div&gt;&lt;/li&gt;
94      * &lt;li&gt;ddel : HtmlElement
95      *  &lt;div class=&quot;sub-desc&quot;&gt;The drag proxy element which moves with the mouse&lt;/div&gt;&lt;/li&gt;
96      * &lt;li&gt;item : HtmlElement
97      *  &lt;div class=&quot;sub-desc&quot;&gt;The GridView node upon which the mousedown event was registered.&lt;/div&gt;&lt;/li&gt;
98      * &lt;li&gt;records : Array
99      *  &lt;div class=&quot;sub-desc&quot;&gt;An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.&lt;/div&gt;&lt;/li&gt;
100      * &lt;/ul&gt;
101      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
102      * @param {String} dropPosition &lt;code&gt;&quot;before&quot;&lt;/code&gt; or &lt;code&gt;&quot;after&quot;&lt;/code&gt; depending on whether the mouse is above or below the midline of the node.
103      */
104
105     dragText : '{0} selected row{1}',
106
107 <span id='Ext-grid-plugin-DragDrop-cfg-ddGroup'>    /**
108 </span>     * @cfg {String} ddGroup
109      * A named drag drop group to which this object belongs.  If a group is specified, then both the DragZones and DropZone
110      * used by this plugin will only interact with other drag drop objects in the same group (defaults to 'TreeDD').
111      */
112     ddGroup : &quot;GridDD&quot;,
113
114 <span id='Ext-grid-plugin-DragDrop-cfg-dragGroup'>    /**
115 </span>     * @cfg {String} dragGroup
116      * &lt;p&gt;The ddGroup to which the DragZone will belong.&lt;/p&gt;
117      * &lt;p&gt;This defines which other DropZones the DragZone will interact with. Drag/DropZones only interact with other Drag/DropZones
118      * which are members of the same ddGroup.&lt;/p&gt;
119      */
120
121 <span id='Ext-grid-plugin-DragDrop-cfg-dropGroup'>    /**
122 </span>     * @cfg {String} dropGroup
123      * &lt;p&gt;The ddGroup to which the DropZone will belong.&lt;/p&gt;
124      * &lt;p&gt;This defines which other DragZones the DropZone will interact with. Drag/DropZones only interact with other Drag/DropZones
125      * which are members of the same ddGroup.&lt;/p&gt;
126      */
127
128 <span id='Ext-grid-plugin-DragDrop-cfg-enableDrop'>    /**
129 </span>     * @cfg {Boolean} enableDrop
130      * &lt;p&gt;Defaults to &lt;code&gt;true&lt;/code&gt;&lt;/p&gt;
131      * &lt;p&gt;Set to &lt;code&gt;false&lt;/code&gt; to disallow the View from accepting drop gestures&lt;/p&gt;
132      */
133     enableDrop: true,
134
135 <span id='Ext-grid-plugin-DragDrop-cfg-enableDrag'>    /**
136 </span>     * @cfg {Boolean} enableDrag
137      * &lt;p&gt;Defaults to &lt;code&gt;true&lt;/code&gt;&lt;/p&gt;
138      * &lt;p&gt;Set to &lt;code&gt;false&lt;/code&gt; to disallow dragging items from the View &lt;/p&gt;
139      */
140     enableDrag: true,
141
142     init : function(view) {
143         view.on('render', this.onViewRender, this, {single: true});
144     },
145
146 <span id='Ext-grid-plugin-DragDrop-method-destroy'>    /**
147 </span>     * @private
148      * AbstractComponent calls destroy on all its plugins at destroy time.
149      */
150     destroy: function() {
151         Ext.destroy(this.dragZone, this.dropZone);
152     },
153
154     onViewRender : function(view) {
155         var me = this;
156
157         if (me.enableDrag) {
158             me.dragZone = Ext.create('Ext.view.DragZone', {
159                 view: view,
160                 ddGroup: me.dragGroup || me.ddGroup,
161                 dragText: me.dragText
162             });
163         }
164
165         if (me.enableDrop) {
166             me.dropZone = Ext.create('Ext.grid.ViewDropZone', {
167                 view: view,
168                 ddGroup: me.dropGroup || me.ddGroup
169             });
170         }
171     }
172 });</pre>
173 </body>
174 </html>