add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / plugin / AbstractClipboard.js

/**\r
 * This base class manages clipboard data transfer for a component. As an abstract class,\r
 * applications use derived classes such as `{@link Ext.grid.plugin.Clipboard}` instead\r
 * and seldom use this class directly.\r
 *\r
 * ## Operation\r
 *\r
 * Components that interact with the clipboard do so in two directions: copy and paste.\r
 * When copying to the clipboard, a component will often provide multiple data formats.\r
 * On paste, the consumer of the data can then decide what format it prefers and ignore\r
 * the others.\r
 *\r
 * ### Copy (and Cut)\r
 *\r
 * There are two storage locations provided for holding copied data:\r
 *\r
 *  * The system clipboard, used to exchange data with other applications running\r
 *    outside the browser.\r
 *  * A memory space in the browser page that can hold data for use only by other\r
 *    components on the page. This allows for richer formats to be transferred.\r
 *\r
 * A component can copy (or cut) data in multiple formats as controlled by the\r
 * `{@link #cfg-memory}` and `{@link #cfg-system}` configs.\r
 *\r
 * ### Paste\r
 *\r
 * While there may be many formats available, when a component is ready to paste, only\r
 * one format can ultimately be used. This is specified by the `{@link #cfg-source}`\r
 * config.\r
 *\r
 * ## Browser Limitations\r
 *\r
 * At the current time, browsers have only a limited ability to interact with the system\r
 * clipboard. The only reliable, cross-browser, plugin-in-free technique for doing so is\r
 * to use invisible elements and focus tricks **during** the processing of clipboard key\r
 * presses like CTRL+C (on Windows/Linux) or CMD+C (on Mac).\r
 *\r
 * @protected\r
 * @since 5.1.0\r
 */\r
Ext.define('Ext.plugin.AbstractClipboard', {\r
    extend: 'Ext.plugin.Abstract',\r
    requires: [\r
        'Ext.util.KeyMap'\r
    ],\r
\r
    cachedConfig: {\r
        /**\r
         * @cfg {Object} formats\r
         * This object is keyed by the names of the data formats supported by this plugin.\r
         * The property values of this object are objects with `get` and `put` properties\r
         * that name the methods for getting data from (copy) and putting to into (paste)\r
         * the associated component.\r
         *\r
         * For example:\r
         *\r
         *      formats: {\r
         *          html: {\r
         *              get: 'getHtmlData',\r
         *              put: 'putHtmlData'\r
         *          }\r
         *      }\r
         *\r
         * This declares support for the "html" data format and indicates that the\r
         * `getHtmlData` method should be called to copy HTML data from the component,\r
         * while the `putHtmlData` should be called to paste HTML data into the component.\r
         *\r
         * By default, all derived classes must support a "text" format:\r
         *\r
         *      formats: {\r
         *          text: {\r
         *              get: 'getTextData',\r
         *              put: 'putTextData'\r
         *          }\r
         *      }\r
         *\r
         * To understand the method signatures required to implement a data format, see the\r
         * documentation for `{@link #getTextData}` and  `{@link #putTextData}`.\r
         *\r
         * The format name "system" is not allowed.\r
         *\r
         * @protected\r
         */\r
        formats: {\r
            text: {\r
                get: 'getTextData',\r
                put: 'putTextData'\r
            }\r
        }\r
    },\r
\r
    config: {\r
        /**\r
         * @cfg {String/String[]} [memory]\r
         * The data format(s) to copy to the private, memory clipboard. By default, data\r
         * is not saved to the memory clipboard. Specify `true` to include all formats\r
         * of data, or a string to copy a single format, or an array of strings to copy\r
         * multiple formats.\r
         */\r
        memory: null,\r
\r
        /**\r
         * @cfg {String/String[]} [source="system"]\r
         * The format or formats in order of preference when pasting data. This list can\r
         * be any of the valid formats, plus the name "system". When a paste occurs, this\r
         * config is consulted. The first format specified by this config that has data\r
         * available in the private memory space is used. If "system" is encountered in\r
         * the list, whatever data is available on the system clipboard is chosen. At\r
         * that point, no further source formats will be considered.\r
         */\r
        source: 'system',\r
\r
        /**\r
         * @cfg {String} [system="text"]\r
         * The data format to set in the system clipboard. By default, the "text"\r
         * format is used. Based on the type of derived class, other formats may be\r
         * possible.\r
         */\r
        system: 'text'\r
    },\r
\r
    destroy: function () {\r
        var me = this,\r
            keyMap = me.keyMap,\r
            shared = me.shared;\r
\r
        if (keyMap) {\r
            // If we have a keyMap then we have incremented the shared usage counter\r
            // and now need to remove ourselves.\r
            me.keyMap = Ext.destroy(keyMap);\r
            if (! --shared.counter) {\r
                shared.textArea = Ext.destroy(shared.textArea);\r
            }\r
        } else {\r
            // If we don't have a keyMap it is because we are waiting for the render\r
            // event and haven't connected to the shared context.\r
            me.renderListener = Ext.destroy(me.renderListener);\r
        }\r
\r
        me.callParent();\r
    },\r
\r
    init: function (comp) {\r
        var me = this;\r
\r
        if (comp.rendered) {\r
            this.finishInit(comp);\r
        } else {\r
            me.renderListener = comp.on({\r
                render: function () {\r
                    me.renderListener = null;\r
                    me.finishInit(comp);\r
                },\r
                destroyable: true,\r
                single: true\r
            });\r
        }\r
    },\r
\r
    /**\r
     * Returns the element target to listen to copy/paste.\r
     *\r
     * @param {Ext.Component} comp The component this plugin is initialized on.\r
     * @return {Ext.dom.Element} The element target.\r
     */\r
    getTarget: function(comp) {\r
        return comp.el;\r
    },\r
\r
    /**\r
     * This method returns the selected data in text format.\r
     * @method getTextData\r
     * @param {String} format The name of the format (i.e., "text").\r
     * @param {Boolean} erase Pass `true` to erase (cut) the data, `false` to just copy.\r
     * @return {String} The data in text format.\r
     */\r
\r
    /**\r
     * This method pastes the given text data.\r
     * @method putTextData\r
     * @param {Object} data The data in the indicated `format`.\r
     * @param {String} format The name of the format (i.e., "text").\r
     */\r
\r
    privates: {\r
        /**\r
         * @property {Object} shared\r
         * The shared state for all clipboard-enabled components.\r
         * @property {Number} shared.counter The number of clipboard-enabled components\r
         * currently using this object.\r
         * @property {Object} shared.data The clipboard data for intra-page copy/paste. The\r
         * properties of the object are keyed by format.\r
         * @property {Ext.dom.Element} textArea The shared textarea used to polyfill the\r
         * lack of HTML5 clipboard API.\r
         * @private\r
         */\r
        shared: {\r
            counter: 0,\r
\r
            data: null,\r
\r
            textArea: null\r
        },\r
\r
        applyMemory: function (value) {\r
            // Same as "source" config but that allows "system" as a format.\r
            value = this.applySource(value);\r
\r
            //<debug>\r
            if (value) {\r
                for (var i = value.length; i-- > 0; ) {\r
                    if (value[i] === 'system') {\r
                        Ext.raise('Invalid clipboard format "' + value[i] + '"');\r
                    }\r
                }\r
            }\r
            //</debug>\r
\r
            return value;\r
        },\r
\r
        applySource: function (value) {\r
            // Make sure we have a non-empty String[] or null\r
            if (value) {\r
                if (Ext.isString(value)) {\r
                    value = [value];\r
                } else if (value.length === 0) {\r
                    value = null;\r
                }\r
            }\r
\r
            //<debug>\r
            if (value) {\r
                var formats = this.getFormats();\r
\r
                for (var i = value.length; i-- > 0; ) {\r
                    if (value[i] !== 'system' && !formats[value[i]]) {\r
                        Ext.raise('Invalid clipboard format "' + value[i] + '"');\r
                    }\r
                }\r
            }\r
            //</debug>\r
\r
            return value || null;\r
        },\r
\r
        //<debug>\r
        applySystem: function (value) {\r
            var formats = this.getFormats();\r
\r
            if (!formats[value]) {\r
                Ext.raise('Invalid clipboard format "' + value + '"');\r
            }\r
\r
            return value;\r
        },\r
        //</debug>\r
\r
        doCutCopy: function (event, erase) {\r
            var me = this,\r
                formats = me.allFormats || me.syncFormats(),\r
                data = me.getData(erase, formats),\r
                memory = me.getMemory(),\r
                system = me.getSystem(),\r
                sys;\r
\r
            me.shared.data = memory && data;\r
\r
            if (system) {\r
                sys = data[system];\r
                if (formats[system] < 3) {\r
                    delete data[system];\r
                }\r
                me.setClipboardData(sys);\r
            }\r
        },\r
\r
        doPaste: function (format, data) {\r
            var formats = this.getFormats();\r
\r
            this[formats[format].put](data, format);\r
        },\r
\r
        finishInit: function (comp) {\r
            var me = this;\r
\r
            me.keyMap = new Ext.util.KeyMap({\r
                target: me.getTarget(comp),\r
\r
                binding: [{\r
                    ctrl: true, key: 'x', fn: me.onCut, scope: me\r
                }, {\r
                    ctrl: true, key: 'c', fn: me.onCopy, scope: me\r
                }, {\r
                    ctrl: true, key: 'v', fn: me.onPaste, scope: me\r
                }]\r
            });\r
\r
            ++me.shared.counter;\r
\r
            comp.on({\r
                destroy: 'destroy',\r
                scope: me\r
            });\r
        },\r
\r
        getData: function (erase, format) {\r
            var me = this,\r
                formats = me.getFormats(),\r
                data, i, name, names;\r
\r
            if (Ext.isString(format)) {\r
                //<debug>\r
                if (!formats[format]) {\r
                    Ext.raise('Invalid clipboard format "' + format + '"');\r
                }\r
                //</debug>\r
                data = me[formats[format].get](format, erase);\r
            } else {\r
                data = {};\r
                names = [];\r
\r
                if (format) {\r
                    for (name in format) {\r
                        //<debug>\r
                        if (!formats[name]) {\r
                            Ext.raise('Invalid clipboard format "' + name + '"');\r
                        }\r
                        //</debug>\r
                        names.push(name);\r
                    }\r
                } else {\r
                    names = Ext.Object.getAllKeys(formats);\r
                }\r
\r
                for (i = names.length; i-- > 0; ) {\r
                    data[name] = me[formats[name].get](name, erase && !i);\r
                }\r
            }\r
\r
            return data;\r
        },\r
\r
        /**\r
         * @private\r
         * @return {Ext.dom.Element}\r
         */\r
        getHiddenTextArea: function () {\r
            var shared = this.shared,\r
                el;\r
            \r
            el = shared.textArea;\r
            \r
            if (!el) {\r
                el = shared.textArea = Ext.getBody().createChild({\r
                    tag: 'textarea',\r
                    tabIndex: -1, // don't tab through this fellow\r
                    style: {\r
                        position: 'absolute',\r
                        top: '-1000px',\r
                        width: '1px',\r
                        height: '1px'\r
                    }\r
                });\r
                \r
                // We don't want this element to fire focus events ever\r
                el.suspendFocusEvents();\r
            }\r
            \r
            return el;\r
        },\r
\r
        onCopy: function (keyCode, event) {\r
            this.doCutCopy(event, false);\r
        },\r
\r
        onCut: function (keyCode, event) {\r
            this.doCutCopy(event, true);\r
        },\r
\r
        onPaste: function (keyCode, event) {\r
            var me = this,\r
                sharedData = me.shared.data,\r
                source = me.getSource(),\r
                i, n, s;\r
\r
            if (source) {\r
                for (i = 0, n = source.length; i < n; ++i) {\r
                    s = source[i];\r
\r
                    if (s === 'system') {\r
                        // get the format used by the system clipboard.\r
                        s = me.getSystem();\r
                        me.pasteClipboardData(s);\r
                        break;\r
                    } else if (sharedData && (s in sharedData)) {\r
                        me.doPaste(s, sharedData[s]);\r
                        break;\r
                    }\r
                }\r
            }\r
        },\r
\r
        pasteClipboardData: function(format) {\r
            var me = this,\r
                clippy = window.clipboardData,\r
                area, focusEl;\r
\r
            if (clippy && clippy.getData) {\r
                 me.doPaste(format, clippy.getData("text"));\r
            }\r
            else {\r
                focusEl = Ext.Element.getActiveElement(true);\r
                area = me.getHiddenTextArea().dom;\r
                area.value = '';\r
\r
                // We must not disturb application state by doing this focus\r
                if (focusEl) {\r
                    focusEl.suspendFocusEvents();\r
                }\r
                \r
                area.focus();\r
\r
                // Between now and the deferred function, the CTRL+V hotkey will have\r
                // its default action processed which will paste the clipboard content\r
                // into the textarea.\r
                Ext.defer(function() {\r
                    // Focus back to the real destination\r
                    if (focusEl) {\r
                        focusEl.focus();\r
                        \r
                        // Restore framework focus handling\r
                        focusEl.resumeFocusEvents();\r
                    }\r
                    \r
                    me.doPaste(format, area.value);\r
                    area.value = '';\r
                }, 100, me);\r
            }\r
        },\r
\r
        setClipboardData: function(data) {\r
            var clippy = window.clipboardData;\r
\r
            if (clippy && clippy.setData) {\r
                clippy.setData("text", data);\r
            }\r
            else {\r
                var me = this,\r
                    area = me.getHiddenTextArea().dom,\r
                    focusEl = Ext.Element.getActiveElement(true);\r
\r
                area.value = data;\r
\r
                // We must not disturb application state by doing this focus\r
                if (focusEl) {\r
                    focusEl.suspendFocusEvents();\r
                }\r
                \r
                area.focus();\r
                area.select();\r
\r
                // Between now and the deferred function, the CTRL+C/X hotkey will have\r
                // its default action processed which will update the clipboard from the\r
                // textarea.\r
                Ext.defer(function() {\r
                    area.value = '';\r
                    \r
                    if (focusEl) {\r
                        focusEl.focus();\r
                        \r
                        // Restore framework focus handling\r
                        focusEl.resumeFocusEvents();\r
                    }\r
                }, 50);\r
            }\r
        },\r
\r
        syncFormats: function () {\r
            var me = this,\r
                map = {},\r
                memory = me.getMemory(),\r
                system = me.getSystem(),\r
                i, s;\r
\r
            if (system) {\r
                map[system] = 1;\r
            }\r
\r
            if (memory) {\r
                for (i = memory.length; i-- > 0; ) {\r
                    s = memory[i];\r
                    map[s] = map[s] ? 3 : 2;\r
                }\r
            }\r
\r
            // 1: memory\r
            // 2: system\r
            // 3: both\r
            return me.allFormats = map; // jshint ignore:line\r
        },\r
\r
        updateMemory: function () {\r
            this.allFormats = null;\r
        },\r
\r
        updateSystem: function () {\r
            this.allFormats = null;\r
        }\r
    }\r
});\r