Upgrade to ExtJS 3.3.0 - Released 10/06/2010
[extjs.git] / docs / source / DragZone.html
index 79801a2..b572754 100644 (file)
 <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>
 </head>
 <body  onload="prettyPrint();">
     <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.0.3
- * Copyright(c) 2006-2009 Ext JS, LLC
+ * Ext JS Library 3.3.0
+ * Copyright(c) 2006-2010 Ext JS, Inc.
  * licensing@extjs.com
  * http://www.extjs.com/license
  */
-<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() {\r
-    myDataView.dragZone = new Ext.dd.DragZone(myDataView.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(myDataView.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: myDataView.store,\r
-                    draggedRecord: v.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>
+<div id="cls-Ext.dd.DragZone"></div>/**
+ * @class Ext.dd.DragZone
+ * @extends Ext.dd.DragSource
+ * <p>This class provides a container DD instance that allows dragging of multiple child source nodes.</p>
+ * <p>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}</p>
+ * <p>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.DataView DataView}) then use of this class
+ * is the most efficient way to "activate" those nodes.</p>
+ * <p>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:</p><pre><code>
+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.DataView#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;
+        }
+    });
+});</code></pre>
+ * See the {@link Ext.dd.DropZone DropZone} documentation for details about building a DropZone which
+ * cooperates with this DragZone.
+ * @constructor
+ * @param {Mixed} el The container element
+ * @param {Object} config
+ */
+Ext.dd.DragZone = Ext.extend(Ext.dd.DragSource, {
+    
+    constructor : function(el, config){
+        Ext.dd.DragZone.superclass.constructor.call(this, el, config);
+        if(this.containerScroll){
+            Ext.dd.ScrollManager.register(this.el);
+        }
+    },
+    
+    <div id="prop-Ext.dd.DragZone-dragData"></div>/**
+     * 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 <tt>ddel</tt> property, but can contain
+     * any other data according to the application's needs.
+     * @type Object
+     * @property dragData
+     */
+    <div id="cfg-Ext.dd.DragZone-containerScroll"></div>/**
+     * @cfg {Boolean} containerScroll True to register this container with the Scrollmanager
+     * for auto scrolling during drag operations.
+     */
+    <div id="cfg-Ext.dd.DragZone-hlColor"></div>/**
+     * @cfg {String} hlColor The color to use when visually highlighting the drag source in the afterRepair
+     * method after a failed drop (defaults to "c3daf9" - light blue)
+     */
+
+    <div id="method-Ext.dd.DragZone-getDragData"></div>/**
+     * 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 "ddel" 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);
+    },
+    
+    <div id="method-Ext.dd.DragZone-onInitDrag"></div>/**
+     * 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;
+    },
+    
+    <div id="method-Ext.dd.DragZone-afterRepair"></div>/**
+     * Called after a repair of an invalid drop. By default, highlights this.dragData.ddel 
+     */
+    afterRepair : function(){
+        if(Ext.enableFx){
+            Ext.Element.fly(this.dragData.ddel).highlight(this.hlColor || "c3daf9");
+        }
+        this.dragging = false;
+    },
+
+    <div id="method-Ext.dd.DragZone-getRepairXY"></div>/**
+     * 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.Element.fly(this.dragData.ddel).getXY();  
+    },
+    
+    destroy : function(){
+        Ext.dd.DragZone.superclass.destroy.call(this);
+        if(this.containerScroll){
+            Ext.dd.ScrollManager.unregister(this.el);
+        }
+    }
+});</pre>    
 </body>
 </html>
\ No newline at end of file