Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / DragDrop2.html
index a58c654..413acb6 100644 (file)
@@ -1,24 +1,80 @@
-<!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-grid.plugin.DragDrop'>/**
-</span> * @class Ext.grid.plugin.DragDrop
- * &lt;p&gt;This plugin provides drag and/or drop functionality for a GridView.&lt;/p&gt;
- * &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}
- * 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;
- * &lt;li&gt;copy : Boolean
- *  &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
- *  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;
- * &lt;li&gt;view : GridView
- *  &lt;div class=&quot;sub-desc&quot;&gt;The source GridView from which the drag originated.&lt;/div&gt;&lt;/li&gt;
- * &lt;li&gt;ddel : HtmlElement
- *  &lt;div class=&quot;sub-desc&quot;&gt;The drag proxy element which moves with the mouse&lt;/div&gt;&lt;/li&gt;
- * &lt;li&gt;item : HtmlElement
- *  &lt;div class=&quot;sub-desc&quot;&gt;The GridView node upon which the mousedown event was registered.&lt;/div&gt;&lt;/li&gt;
- * &lt;li&gt;records : Array
- *  &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;
- * &lt;/ul&gt;&lt;/p&gt;
- * &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
- * ddGroup which processes such data objects.&lt;/p&gt;
- * &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
- * &lt;code&gt;{@link #event-drop drop}&lt;/code&gt;&lt;/p&gt;
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-grid-plugin-DragDrop'>/**
+</span> * This plugin provides drag and/or drop functionality for a GridView.
+ *
+ * It creates a specialized instance of {@link Ext.dd.DragZone DragZone} which knows how to drag out of a {@link
+ * Ext.grid.View GridView} and loads the data object which is passed to a cooperating {@link Ext.dd.DragZone DragZone}'s
+ * methods with the following properties:
+ *
+ * - `copy` : Boolean
+ *
+ *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` _and_
+ *   the control key was pressed when the drag operation was begun.
+ *
+ * - `view` : GridView
+ *
+ *   The source GridView from which the drag originated.
+ *
+ * - `ddel` : HtmlElement
+ *
+ *   The drag proxy element which moves with the mouse
+ *
+ * - `item` : HtmlElement
+ *
+ *   The GridView node upon which the mousedown event was registered.
+ *
+ * - `records` : Array
+ *
+ *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
+ *
+ * It also creates a specialized instance of {@link Ext.dd.DropZone} which cooperates with other DropZones which are
+ * members of the same ddGroup which processes such data objects.
+ *
+ * Adding this plugin to a view means that two new events may be fired from the client GridView, `{@link #beforedrop
+ * beforedrop}` and `{@link #drop drop}`
+ *
+ *     @example
+ *     Ext.create('Ext.data.Store', {
+ *         storeId:'simpsonsStore',
+ *         fields:['name'],
+ *         data: [[&quot;Lisa&quot;], [&quot;Bart&quot;], [&quot;Homer&quot;], [&quot;Marge&quot;]],
+ *         proxy: {
+ *             type: 'memory',
+ *             reader: 'array'
+ *         }
+ *     });
+ *
+ *     Ext.create('Ext.grid.Panel', {
+ *         store: 'simpsonsStore',
+ *         columns: [
+ *             {header: 'Name',  dataIndex: 'name', flex: true}
+ *         ],
+ *         viewConfig: {
+ *             plugins: {
+ *                 ptype: 'gridviewdragdrop',
+ *                 dragText: 'Drag and drop to reorganize'
+ *             }
+ *         },
+ *         height: 200,
+ *         width: 400,
+ *         renderTo: Ext.getBody()
+ *     });
  */
 Ext.define('Ext.grid.plugin.DragDrop', {
     extend: 'Ext.AbstractPlugin',
@@ -29,96 +85,133 @@ Ext.define('Ext.grid.plugin.DragDrop', {
         'Ext.grid.ViewDropZone'
     ],
 
-<span id='Ext-grid.plugin.DragDrop-event-beforedrop'>    /**
+<span id='Ext-grid-plugin-DragDrop-event-beforedrop'>    /**
 </span>     * @event beforedrop
-     * &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;
-     * &lt;p&gt;Fired when a drop gesture has been triggered by a mouseup event in a valid drop position in the GridView.
-     * @param {HtmlElement} node The GridView node &lt;b&gt;if any&lt;/b&gt; over which the mouse was positioned.&lt;/p&gt;
-     * &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
-     * will animate back to the point from which the drag began.&lt;/p&gt;
-     * &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
-     * that the gesture was valid, and that the repair operation should not take place.&lt;/p&gt;
-     * &lt;p&gt;Any other return value continues with the data transfer operation.&lt;/p&gt;
-     * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone DragZone}'s
-     * {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:&lt;ul&gt;
-     * &lt;li&gt;copy : Boolean
-     *  &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
-     *  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;
-     * &lt;li&gt;view : GridView
-     *  &lt;div class=&quot;sub-desc&quot;&gt;The source GridView from which the drag originated.&lt;/div&gt;&lt;/li&gt;
-     * &lt;li&gt;ddel : HtmlElement
-     *  &lt;div class=&quot;sub-desc&quot;&gt;The drag proxy element which moves with the mouse&lt;/div&gt;&lt;/li&gt;
-     * &lt;li&gt;item : HtmlElement
-     *  &lt;div class=&quot;sub-desc&quot;&gt;The GridView node upon which the mousedown event was registered.&lt;/div&gt;&lt;/li&gt;
-     * &lt;li&gt;records : Array
-     *  &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;
-     * &lt;/ul&gt;
+     * **This event is fired through the GridView. Add listeners to the GridView object**
+     *
+     * Fired when a drop gesture has been triggered by a mouseup event in a valid drop position in the GridView.
+     *
+     * @param {HTMLElement} node The GridView node **if any** over which the mouse was positioned.
+     *
+     * Returning `false` to this event signals that the drop gesture was invalid, and if the drag proxy will animate
+     * back to the point from which the drag began.
+     *
+     * Returning `0` To this event signals that the data transfer operation should not take place, but that the gesture
+     * was valid, and that the repair operation should not take place.
+     *
+     * Any other return value continues with the data transfer operation.
+     *
+     * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone
+     * DragZone}'s {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:
+     *
+     * - copy : Boolean
+     *
+     *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` and
+     *   the control key was pressed when the drag operation was begun
+     *
+     * - view : GridView
+     *
+     *   The source GridView from which the drag originated.
+     *
+     * - ddel : HtmlElement
+     *
+     *   The drag proxy element which moves with the mouse
+     *
+     * - item : HtmlElement
+     *
+     *   The GridView node upon which the mousedown event was registered.
+     *
+     * - records : Array
+     *
+     *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
+     *
      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
-     * @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.
-     * @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
-     * View's Store to the destination View's Store.&lt;/p&gt;
-     * &lt;p&gt;This is useful when you want to perform some kind of asynchronous processing before confirming
-     * the drop, such as an {@link Ext.window.MessageBox#confirm confirm} call, or an Ajax request.&lt;/p&gt;
-     * &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;
+     *
+     * @param {String} dropPosition `&quot;before&quot;` or `&quot;after&quot;` depending on whether the mouse is above or below the midline
+     * of the node.
+     *
+     * @param {Function} dropFunction
+     *
+     * A function to call to complete the data transfer operation and either move or copy Model instances from the
+     * source View's Store to the destination View's Store.
+     *
+     * This is useful when you want to perform some kind of asynchronous processing before confirming the drop, such as
+     * an {@link Ext.window.MessageBox#confirm confirm} call, or an Ajax request.
+     *
+     * Return `0` from this event handler, and call the `dropFunction` at any time to perform the data transfer.
      */
 
-<span id='Ext-grid.plugin.DragDrop-event-drop'>    /**
+<span id='Ext-grid-plugin-DragDrop-event-drop'>    /**
 </span>     * @event drop
-     * &lt;b&gt;This event is fired through the GridView. Add listeners to the GridView object&lt;/b&gt;
-     * Fired when a drop operation has been completed and the data has been moved or copied.
-     * @param {HtmlElement} node The GridView node &lt;b&gt;if any&lt;/b&gt; over which the mouse was positioned.
-     * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone DragZone}'s
-     * {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:&lt;ul&gt;
-     * &lt;li&gt;copy : Boolean
-     *  &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
-     *  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;
-     * &lt;li&gt;view : GridView
-     *  &lt;div class=&quot;sub-desc&quot;&gt;The source GridView from which the drag originated.&lt;/div&gt;&lt;/li&gt;
-     * &lt;li&gt;ddel : HtmlElement
-     *  &lt;div class=&quot;sub-desc&quot;&gt;The drag proxy element which moves with the mouse&lt;/div&gt;&lt;/li&gt;
-     * &lt;li&gt;item : HtmlElement
-     *  &lt;div class=&quot;sub-desc&quot;&gt;The GridView node upon which the mousedown event was registered.&lt;/div&gt;&lt;/li&gt;
-     * &lt;li&gt;records : Array
-     *  &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;
-     * &lt;/ul&gt;
+     * **This event is fired through the GridView. Add listeners to the GridView object** Fired when a drop operation
+     * has been completed and the data has been moved or copied.
+     *
+     * @param {HTMLElement} node The GridView node **if any** over which the mouse was positioned.
+     *
+     * @param {Object} data The data object gathered at mousedown time by the cooperating {@link Ext.dd.DragZone
+     * DragZone}'s {@link Ext.dd.DragZone#getDragData getDragData} method it contains the following properties:
+     *
+     * - copy : Boolean
+     *
+     *   The value of the GridView's `copy` property, or `true` if the GridView was configured with `allowCopy: true` and
+     *   the control key was pressed when the drag operation was begun
+     *
+     * - view : GridView
+     *
+     *   The source GridView from which the drag originated.
+     *
+     * - ddel : HtmlElement
+     *
+     *   The drag proxy element which moves with the mouse
+     *
+     * - item : HtmlElement
+     *
+     *   The GridView node upon which the mousedown event was registered.
+     *
+     * - records : Array
+     *
+     *   An Array of {@link Ext.data.Model Model}s representing the selected data being dragged from the source GridView.
+     *
      * @param {Ext.data.Model} overModel The Model over which the drop gesture took place.
-     * @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.
+     *
+     * @param {String} dropPosition `&quot;before&quot;` or `&quot;after&quot;` depending on whether the mouse is above or below the midline
+     * of the node.
      */
 
     dragText : '{0} selected row{1}',
 
-<span id='Ext-grid.plugin.DragDrop-cfg-ddGroup'>    /**
+<span id='Ext-grid-plugin-DragDrop-cfg-ddGroup'>    /**
 </span>     * @cfg {String} ddGroup
-     * A named drag drop group to which this object belongs.  If a group is specified, then both the DragZones and DropZone
-     * used by this plugin will only interact with other drag drop objects in the same group (defaults to 'TreeDD').
+     * A named drag drop group to which this object belongs. If a group is specified, then both the DragZones and
+     * DropZone used by this plugin will only interact with other drag drop objects in the same group.
      */
     ddGroup : &quot;GridDD&quot;,
 
-<span id='Ext-grid.plugin.DragDrop-cfg-dragGroup'>    /**
+<span id='Ext-grid-plugin-DragDrop-cfg-dragGroup'>    /**
 </span>     * @cfg {String} dragGroup
-     * &lt;p&gt;The ddGroup to which the DragZone will belong.&lt;/p&gt;
-     * &lt;p&gt;This defines which other DropZones the DragZone will interact with. Drag/DropZones only interact with other Drag/DropZones
-     * which are members of the same ddGroup.&lt;/p&gt;
+     * The ddGroup to which the DragZone will belong.
+     *
+     * This defines which other DropZones the DragZone will interact with. Drag/DropZones only interact with other
+     * Drag/DropZones which are members of the same ddGroup.
      */
 
-<span id='Ext-grid.plugin.DragDrop-cfg-dropGroup'>    /**
+<span id='Ext-grid-plugin-DragDrop-cfg-dropGroup'>    /**
 </span>     * @cfg {String} dropGroup
-     * &lt;p&gt;The ddGroup to which the DropZone will belong.&lt;/p&gt;
-     * &lt;p&gt;This defines which other DragZones the DropZone will interact with. Drag/DropZones only interact with other Drag/DropZones
-     * which are members of the same ddGroup.&lt;/p&gt;
+     * The ddGroup to which the DropZone will belong.
+     *
+     * This defines which other DragZones the DropZone will interact with. Drag/DropZones only interact with other
+     * Drag/DropZones which are members of the same ddGroup.
      */
 
-<span id='Ext-grid.plugin.DragDrop-cfg-enableDrop'>    /**
+<span id='Ext-grid-plugin-DragDrop-cfg-enableDrop'>    /**
 </span>     * @cfg {Boolean} enableDrop
-     * &lt;p&gt;Defaults to &lt;code&gt;true&lt;/code&gt;&lt;/p&gt;
-     * &lt;p&gt;Set to &lt;code&gt;false&lt;/code&gt; to disallow the View from accepting drop gestures&lt;/p&gt;
+     * False to disallow the View from accepting drop gestures.
      */
     enableDrop: true,
 
-<span id='Ext-grid.plugin.DragDrop-cfg-enableDrag'>    /**
+<span id='Ext-grid-plugin-DragDrop-cfg-enableDrag'>    /**
 </span>     * @cfg {Boolean} enableDrag
-     * &lt;p&gt;Defaults to &lt;code&gt;true&lt;/code&gt;&lt;/p&gt;
-     * &lt;p&gt;Set to &lt;code&gt;false&lt;/code&gt; to disallow dragging items from the View &lt;/p&gt;
+     * False to disallow dragging items from the View.
      */
     enableDrag: true,
 
@@ -126,7 +219,7 @@ Ext.define('Ext.grid.plugin.DragDrop', {
         view.on('render', this.onViewRender, this, {single: true});
     },
 
-<span id='Ext-grid.plugin.DragDrop-method-destroy'>    /**
+<span id='Ext-grid-plugin-DragDrop-method-destroy'>    /**
 </span>     * @private
      * AbstractComponent calls destroy on all its plugins at destroy time.
      */
@@ -134,6 +227,28 @@ Ext.define('Ext.grid.plugin.DragDrop', {
         Ext.destroy(this.dragZone, this.dropZone);
     },
 
+    enable: function() {
+        var me = this;
+        if (me.dragZone) {
+            me.dragZone.unlock();
+        }
+        if (me.dropZone) {
+            me.dropZone.unlock();
+        }
+        me.callParent();
+    },
+
+    disable: function() {
+        var me = this;
+        if (me.dragZone) {
+            me.dragZone.lock();
+        }
+        if (me.dropZone) {
+            me.dropZone.lock();
+        }
+        me.callParent();
+    },
+
     onViewRender : function(view) {
         var me = this;
 
@@ -152,4 +267,6 @@ Ext.define('Ext.grid.plugin.DragDrop', {
             });
         }
     }
-});</pre></pre></body></html>
\ No newline at end of file
+});</pre>
+</body>
+</html>