Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / DragZone.html
index b40153e..031ad8a 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.dd.DragZone"></div>/**\r
- * @class Ext.dd.DragZone\r
- * @extends Ext.dd.DragSource\r
- * <p>This class provides a container DD instance that allows dragging of multiple child source nodes.</p>\r
- * <p>This class does not move the drag target nodes, but a proxy element which may contain\r
- * any DOM structure you wish. The DOM element to show in the proxy is provided by either a\r
- * provided implementation of {@link #getDragData}, or by registered draggables registered with {@link Ext.dd.Registry}</p>\r
- * <p>If you wish to provide draggability for an arbitrary number of DOM nodes, each of which represent some\r
- * application object (For example nodes in a {@link Ext.DataView DataView}) then use of this class\r
- * is the most efficient way to "activate" those nodes.</p>\r
- * <p>By default, this class requires that draggable child nodes are registered with {@link Ext.dd.Registry}.\r
- * However a simpler way to allow a DragZone to manage any number of draggable elements is to configure\r
- * the DragZone with  an implementation of the {@link #getDragData} method which interrogates the passed\r
- * mouse event to see if it has taken place within an element, or class of elements. This is easily done\r
- * by using the event's {@link Ext.EventObject#getTarget getTarget} method to identify a node based on a\r
- * {@link Ext.DomQuery} selector. For example, to make the nodes of a DataView draggable, use the following\r
- * technique. Knowledge of the use of the DataView is required:</p><pre><code>\r
-myDataView.on('render', function(v) {\r
-    myDataView.dragZone = new Ext.dd.DragZone(v.getEl(), {\r
-\r
-//      On receipt of a mousedown event, see if it is within a DataView node.\r
-//      Return a drag data object if so.\r
-        getDragData: function(e) {\r
-\r
-//          Use the DataView's own itemSelector (a mandatory property) to\r
-//          test if the mousedown is within one of the DataView's nodes.\r
-            var sourceEl = e.getTarget(v.itemSelector, 10);\r
-\r
-//          If the mousedown is within a DataView node, clone the node to produce\r
-//          a ddel element for use by the drag proxy. Also add application data\r
-//          to the returned data object.\r
-            if (sourceEl) {\r
-                d = sourceEl.cloneNode(true);\r
-                d.id = Ext.id();\r
-                return {\r
-                    ddel: d,\r
-                    sourceEl: sourceEl,\r
-                    repairXY: Ext.fly(sourceEl).getXY(),\r
-                    sourceStore: v.store,\r
-                    draggedRecord: v.{@link Ext.DataView#getRecord getRecord}(sourceEl)\r
-                }\r
-            }\r
-        },\r
-\r
-//      Provide coordinates for the proxy to slide back to on failed drag.\r
-//      This is the original XY coordinates of the draggable element captured\r
-//      in the getDragData method.\r
-        getRepairXY: function() {\r
-            return this.dragData.repairXY;\r
-        }\r
-    });\r
-});</code></pre>\r
- * See the {@link Ext.dd.DropZone DropZone} documentation for details about building a DropZone which\r
- * cooperates with this DragZone.\r
- * @constructor\r
- * @param {Mixed} el The container element\r
- * @param {Object} config\r
- */\r
-Ext.dd.DragZone = function(el, config){\r
-    Ext.dd.DragZone.superclass.constructor.call(this, el, config);\r
-    if(this.containerScroll){\r
-        Ext.dd.ScrollManager.register(this.el);\r
-    }\r
-};\r
-\r
-Ext.extend(Ext.dd.DragZone, Ext.dd.DragSource, {\r
-    <div id="prop-Ext.dd.DragZone-dragData"></div>/**\r
-     * This property contains the data representing the dragged object. This data is set up by the implementation\r
-     * of the {@link #getDragData} method. It must contain a <tt>ddel</tt> property, but can contain\r
-     * any other data according to the application's needs.\r
-     * @type Object\r
-     * @property dragData\r
-     */\r
-    <div id="cfg-Ext.dd.DragZone-containerScroll"></div>/**\r
-     * @cfg {Boolean} containerScroll True to register this container with the Scrollmanager\r
-     * for auto scrolling during drag operations.\r
-     */\r
-    <div id="cfg-Ext.dd.DragZone-hlColor"></div>/**\r
-     * @cfg {String} hlColor The color to use when visually highlighting the drag source in the afterRepair\r
-     * method after a failed drop (defaults to "c3daf9" - light blue)\r
-     */\r
-\r
-    <div id="method-Ext.dd.DragZone-getDragData"></div>/**\r
-     * Called when a mousedown occurs in this container. Looks in {@link Ext.dd.Registry}\r
-     * for a valid target to drag based on the mouse down. Override this method\r
-     * to provide your own lookup logic (e.g. finding a child by class name). Make sure your returned\r
-     * object has a "ddel" attribute (with an HTML Element) for other functions to work.\r
-     * @param {EventObject} e The mouse down event\r
-     * @return {Object} The dragData\r
-     */\r
-    getDragData : function(e){\r
-        return Ext.dd.Registry.getHandleFromEvent(e);\r
-    },\r
-    \r
-    <div id="method-Ext.dd.DragZone-onInitDrag"></div>/**\r
-     * Called once drag threshold has been reached to initialize the proxy element. By default, it clones the\r
-     * this.dragData.ddel\r
-     * @param {Number} x The x position of the click on the dragged object\r
-     * @param {Number} y The y position of the click on the dragged object\r
-     * @return {Boolean} true to continue the drag, false to cancel\r
-     */\r
-    onInitDrag : function(x, y){\r
-        this.proxy.update(this.dragData.ddel.cloneNode(true));\r
-        this.onStartDrag(x, y);\r
-        return true;\r
-    },\r
-    \r
-    <div id="method-Ext.dd.DragZone-afterRepair"></div>/**\r
-     * Called after a repair of an invalid drop. By default, highlights this.dragData.ddel \r
-     */\r
-    afterRepair : function(){\r
-        if(Ext.enableFx){\r
-            Ext.Element.fly(this.dragData.ddel).highlight(this.hlColor || "c3daf9");\r
-        }\r
-        this.dragging = false;\r
-    },\r
-\r
-    <div id="method-Ext.dd.DragZone-getRepairXY"></div>/**\r
-     * Called before a repair of an invalid drop to get the XY to animate to. By default returns\r
-     * the XY of this.dragData.ddel\r
-     * @param {EventObject} e The mouse up event\r
-     * @return {Array} The xy location (e.g. [100, 200])\r
-     */\r
-    getRepairXY : function(e){\r
-        return Ext.Element.fly(this.dragData.ddel).getXY();  \r
-    }\r
-});</pre>    \r
-</body>\r
-</html>
\ No newline at end of file
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../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-dd-DragZone'>/**
+</span> * @class Ext.dd.DragZone
+ * @extends Ext.dd.DragSource
+ * &lt;p&gt;This class provides a container DD instance that allows dragging of multiple child source nodes.&lt;/p&gt;
+ * &lt;p&gt;This class does not move the drag target nodes, but a proxy element which may contain
+ * any DOM structure you wish. The DOM element to show in the proxy is provided by either a
+ * provided implementation of {@link #getDragData}, or by registered draggables registered with {@link Ext.dd.Registry}&lt;/p&gt;
+ * &lt;p&gt;If you wish to provide draggability for an arbitrary number of DOM nodes, each of which represent some
+ * application object (For example nodes in a {@link Ext.view.View DataView}) then use of this class
+ * is the most efficient way to &quot;activate&quot; those nodes.&lt;/p&gt;
+ * &lt;p&gt;By default, this class requires that draggable child nodes are registered with {@link Ext.dd.Registry}.
+ * However a simpler way to allow a DragZone to manage any number of draggable elements is to configure
+ * the DragZone with  an implementation of the {@link #getDragData} method which interrogates the passed
+ * mouse event to see if it has taken place within an element, or class of elements. This is easily done
+ * by using the event's {@link Ext.EventObject#getTarget getTarget} method to identify a node based on a
+ * {@link Ext.DomQuery} selector. For example, to make the nodes of a DataView draggable, use the following
+ * technique. Knowledge of the use of the DataView is required:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
+myDataView.on('render', function(v) {
+    myDataView.dragZone = new Ext.dd.DragZone(v.getEl(), {
+
+//      On receipt of a mousedown event, see if it is within a DataView node.
+//      Return a drag data object if so.
+        getDragData: function(e) {
+
+//          Use the DataView's own itemSelector (a mandatory property) to
+//          test if the mousedown is within one of the DataView's nodes.
+            var sourceEl = e.getTarget(v.itemSelector, 10);
+
+//          If the mousedown is within a DataView node, clone the node to produce
+//          a ddel element for use by the drag proxy. Also add application data
+//          to the returned data object.
+            if (sourceEl) {
+                d = sourceEl.cloneNode(true);
+                d.id = Ext.id();
+                return {
+                    ddel: d,
+                    sourceEl: sourceEl,
+                    repairXY: Ext.fly(sourceEl).getXY(),
+                    sourceStore: v.store,
+                    draggedRecord: v.{@link Ext.view.View#getRecord getRecord}(sourceEl)
+                }
+            }
+        },
+
+//      Provide coordinates for the proxy to slide back to on failed drag.
+//      This is the original XY coordinates of the draggable element captured
+//      in the getDragData method.
+        getRepairXY: function() {
+            return this.dragData.repairXY;
+        }
+    });
+});&lt;/code&gt;&lt;/pre&gt;
+ * See the {@link Ext.dd.DropZone DropZone} documentation for details about building a DropZone which
+ * cooperates with this DragZone.
+ */
+Ext.define('Ext.dd.DragZone', {
+
+    extend: 'Ext.dd.DragSource',
+
+<span id='Ext-dd-DragZone-method-constructor'>    /**
+</span>     * Creates new DragZone.
+     * @param {Mixed} el The container element
+     * @param {Object} config
+     */
+    constructor : function(el, config){
+        this.callParent([el, config]);
+        if (this.containerScroll) {
+            Ext.dd.ScrollManager.register(this.el);
+        }
+    },
+
+<span id='Ext-dd-DragZone-property-dragData'>    /**
+</span>     * This property contains the data representing the dragged object. This data is set up by the implementation
+     * of the {@link #getDragData} method. It must contain a &lt;tt&gt;ddel&lt;/tt&gt; property, but can contain
+     * any other data according to the application's needs.
+     * @type Object
+     * @property dragData
+     */
+
+<span id='Ext-dd-DragZone-cfg-containerScroll'>    /**
+</span>     * @cfg {Boolean} containerScroll True to register this container with the Scrollmanager
+     * for auto scrolling during drag operations.
+     */
+
+<span id='Ext-dd-DragZone-method-getDragData'>    /**
+</span>     * Called when a mousedown occurs in this container. Looks in {@link Ext.dd.Registry}
+     * for a valid target to drag based on the mouse down. Override this method
+     * to provide your own lookup logic (e.g. finding a child by class name). Make sure your returned
+     * object has a &quot;ddel&quot; attribute (with an HTML Element) for other functions to work.
+     * @param {EventObject} e The mouse down event
+     * @return {Object} The dragData
+     */
+    getDragData : function(e){
+        return Ext.dd.Registry.getHandleFromEvent(e);
+    },
+
+<span id='Ext-dd-DragZone-method-onInitDrag'>    /**
+</span>     * Called once drag threshold has been reached to initialize the proxy element. By default, it clones the
+     * this.dragData.ddel
+     * @param {Number} x The x position of the click on the dragged object
+     * @param {Number} y The y position of the click on the dragged object
+     * @return {Boolean} true to continue the drag, false to cancel
+     */
+    onInitDrag : function(x, y){
+        this.proxy.update(this.dragData.ddel.cloneNode(true));
+        this.onStartDrag(x, y);
+        return true;
+    },
+
+<span id='Ext-dd-DragZone-method-afterRepair'>    /**
+</span>     * Called after a repair of an invalid drop. By default, highlights this.dragData.ddel
+     */
+    afterRepair : function(){
+        var me = this;
+        if (Ext.enableFx) {
+            Ext.fly(me.dragData.ddel).highlight(me.repairHighlightColor);
+        }
+        me.dragging = false;
+    },
+
+<span id='Ext-dd-DragZone-method-getRepairXY'>    /**
+</span>     * Called before a repair of an invalid drop to get the XY to animate to. By default returns
+     * the XY of this.dragData.ddel
+     * @param {EventObject} e The mouse up event
+     * @return {Array} The xy location (e.g. [100, 200])
+     */
+    getRepairXY : function(e){
+        return Ext.core.Element.fly(this.dragData.ddel).getXY();
+    },
+
+    destroy : function(){
+        this.callParent();
+        if (this.containerScroll) {
+            Ext.dd.ScrollManager.unregister(this.el);
+        }
+    }
+});
+</pre>
+</body>
+</html>