add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / dd / DragZone.js

/**\r
 * This class provides a container DD instance that allows dragging of multiple child source nodes.\r
 *\r
 * This class does not move the drag target nodes, but a proxy element which may contain any DOM structure you wish. The\r
 * DOM element to show in the proxy is provided by either a provided implementation of {@link #getDragData}, or by\r
 * registered draggables registered with {@link Ext.dd.Registry}\r
 *\r
 * If you wish to provide draggability for an arbitrary number of DOM nodes, each of which represent some application\r
 * object (For example nodes in a {@link Ext.view.View DataView}) then use of this class is the most efficient way to\r
 * "activate" those nodes.\r
 *\r
 * By default, this class requires that draggable child nodes are registered with {@link Ext.dd.Registry}. However a\r
 * simpler way to allow a DragZone to manage any number of draggable elements is to configure the DragZone with an\r
 * implementation of the {@link #getDragData} method which interrogates the passed mouse event to see if it has taken\r
 * place within an element, or class of elements. This is easily done by using the event's {@link\r
 * Ext.event.Event#getTarget getTarget} method to identify a node based on a CSS selector. For example,\r
 * to make the nodes of a DataView draggable, use the following technique. Knowledge of the use of the DataView is\r
 * required:\r
 *\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.view.View#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
 *     });\r
 *\r
 * See the {@link Ext.dd.DropZone DropZone} documentation for details about building a DropZone which cooperates with\r
 * this DragZone.\r
 */\r
Ext.define('Ext.dd.DragZone', {\r
    extend: 'Ext.dd.DragSource',\r
\r
    /**\r
     * Creates new DragZone.\r
     * @param {String/HTMLElement/Ext.dom.Element} el The container element or ID of it.\r
     * @param {Object} config\r
     */\r
    constructor : function(el, config){\r
        var me = this,\r
            scroll = me.containerScroll;\r
        \r
        me.callParent([el, config]);\r
        if (scroll) {\r
            el = me.scrollEl || el;\r
            el = Ext.get(el);\r
            if (Ext.isObject(scroll)) {\r
                el.ddScrollConfig = scroll;\r
            }\r
            Ext.dd.ScrollManager.register(el);\r
        }\r
    },\r
\r
    /**\r
     * @cfg {Object/Boolean} containerScroll\r
     * True to register this container with the Scrollmanager for auto scrolling during drag operations.\r
     * A {@link Ext.dd.ScrollManager} configuration may also be passed.\r
     */\r
    \r
    /**\r
     * @cfg {String/HTMLElement/Ext.dom.Element} scrollEl\r
     * An element to register with the ScrollManager if {@link #containerScroll}\r
     * is set. Defaults to the drag element.\r
     */\r
\r
    /**\r
     * Called when a mousedown occurs in this container. Looks in {@link Ext.dd.Registry} for a valid target to drag\r
     * based on the mouse down. Override this method to provide your own lookup logic (e.g. finding a child by class\r
     * name). Make sure your returned object has a "ddel" attribute (with an HTML Element) for other functions to work.\r
     * @param {Event} 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
    /**\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
     * @template\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
    /**\r
     * Called before a repair of an invalid drop to get the XY to animate to. By default returns the XY of\r
     * this.dragData.ddel\r
     * @param {Event} e The mouse up event\r
     * @return {Number[]} The xy location (e.g. `[100, 200]`)\r
     * @template\r
     */\r
    getRepairXY : function(e){\r
        return Ext.fly(this.dragData.ddel).getXY();\r
    },\r
\r
    destroy : function(){\r
        this.callParent();\r
        if (this.containerScroll) {\r
            Ext.dd.ScrollManager.unregister(this.scrollEl || this.el);\r
        }\r
    }\r
});\r