add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / util / KeyNav.js

/**\r
 * Provides a convenient wrapper for normalized keyboard navigation. KeyNav allows you to bind navigation keys to\r
 * function calls that will get called when the keys are pressed, providing an easy way to implement custom navigation\r
 * schemes for any UI component.\r
 *\r
 * The following are all of the possible keys that can be implemented: enter, space, left, right, up, down, tab, esc,\r
 * pageUp, pageDown, del, backspace, home, end.\r
 *\r
 * Usage:\r
 *\r
 *     var nav = new Ext.util.KeyNav({\r
 *         target : "my-element",\r
 *         left   : function(e){\r
 *             this.moveLeft(e.ctrlKey);\r
 *         },\r
 *         right  : function(e){\r
 *             this.moveRight(e.ctrlKey);\r
 *         },\r
 *         enter  : function(e){\r
 *             this.save();\r
 *         },\r
 *         \r
 *         // Binding may be a function specifiying fn, scope and defaultEventAction\r
 *         esc: {\r
 *             fn: this.onEsc,\r
 *             defaultEventAction: false\r
 *         },\r
 *\r
 *         // Binding may be keyed by a single character\r
 *         A: {\r
 *             ctrl: true,\r
 *             fn: selectAll\r
 *         },\r
 *\r
 *         // Binding may be keyed by a key code (45 = {@link Ext.event.Event#property-INSERT INSERT})\r
 *         45: {\r
 *             fn: doInsert\r
 *         }\r
 *         scope : this\r
 *     });\r
 */\r
Ext.define('Ext.util.KeyNav', {\r
    alternateClassName: 'Ext.KeyNav',\r
\r
    requires: ['Ext.util.KeyMap'],\r
\r
    /**\r
     * @cfg {Boolean} disabled\r
     * True to disable this KeyNav instance.\r
     */\r
    disabled: false,\r
\r
    /**\r
     * @cfg {String} [defaultEventAction=false]\r
     * The method to call on the {@link Ext.event.Event} after this KeyNav intercepts a key.\r
     * Valid values are {@link Ext.event.Event#stopEvent}, {@link Ext.event.Event#preventDefault}\r
     * and {@link Ext.event.Event#stopPropagation}.\r
     *\r
     * If a falsy value is specified, no method is called on the key event.\r
     */\r
    defaultEventAction: false,\r
\r
    /**\r
     * @cfg {Boolean} forceKeyDown\r
     * Handle the keydown event instead of keypress. KeyNav automatically does this for IE since IE does not propagate\r
     * special keys on keypress, but setting this to true will force other browsers to also handle keydown instead of\r
     * keypress.\r
     */\r
    forceKeyDown: false,\r
\r
    /**\r
     * @cfg {Ext.Component/Ext.dom.Element/HTMLElement/String} target\r
     * The object on which to listen for the event specified by the {@link #eventName} config option.\r
     */\r
\r
    /**\r
     * @cfg {String} eventName\r
     * The event to listen for to pick up key events.\r
     */\r
    eventName: 'keypress',\r
\r
    /**\r
     * @cfg {Function} processEvent\r
     * An optional event processor function which accepts the argument list provided by the {@link #eventName configured\r
     * event} of the {@link #target}, and returns a keyEvent for processing by the KeyMap.\r
     *\r
     * This may be useful when the {@link #target} is a Component with s complex event signature. Extra information from\r
     * the event arguments may be injected into the event for use by the handler functions before returning it.\r
     */\r
\r
    /**\r
     * @cfg {Object} [processEventScope=this]\r
     * The scope (`this` context) in which the {@link #processEvent} method is executed.\r
     */\r
\r
    /**\r
     * @cfg {Boolean} [ignoreInputFields=false]\r
     * Configure this as `true` if there are any input fields within the {@link #target}, and this KeyNav\r
     * should not process events from input fields, (`<input>, <textarea> and elements with `contentEditable="true"`)\r
     */\r
\r
    /**\r
     * @cfg {Ext.util.KeyMap} [keyMap]\r
     * An optional pre-existing {@link Ext.util.KeyMap KeyMap} to use to listen for key events. If not specified,\r
     * one is created.\r
     */\r
\r
    /**\r
     * @property {Ext.event.Event} lastKeyEvent\r
     * The last key event that this KeyMap handled.\r
     */\r
\r
    /**\r
     * @cfg {Number} [priority]\r
     * The priority to set on this KeyNav's listener. Listeners with a higher priority are fired before those with\r
     * lower priority.\r
     */\r
\r
    statics: {\r
        keyOptions: {\r
            left: 37,\r
            right: 39,\r
            up: 38,\r
            down: 40,\r
            space: 32,\r
            pageUp: 33,\r
            pageDown: 34,\r
            del: 46,\r
            backspace: 8,\r
            home: 36,\r
            end: 35,\r
            enter: 13,\r
            esc: 27,\r
            tab: 9\r
        }\r
    },\r
\r
    constructor: function(config) {\r
        var me = this;\r
        if (arguments.length === 2) {\r
            me.legacyConstructor.apply(me, arguments);\r
            return;\r
        }\r
        me.doConstruction(config);\r
    },\r
\r
    /**\r
     * @private\r
     * Old constructor signature.\r
     * @param {String/HTMLElement/Ext.dom.Element} el The element or its ID to bind to\r
     * @param {Object} config The config\r
     */\r
    legacyConstructor: function(el, config) {\r
        this.doConstruction(Ext.apply({\r
            target: el\r
        }, config));\r
    },\r
\r
    /**\r
     * Sets up a configuration for the KeyNav.\r
     * @private\r
     * @param {Object} config A configuration object as specified in the constructor.\r
     */\r
    doConstruction: function(config) {\r
        var me = this,\r
            keymapCfg = {\r
                target: config.target,\r
                ignoreInputFields: config.ignoreInputFields,\r
                eventName: me.getKeyEvent('forceKeyDown' in config ? config.forceKeyDown : me.forceKeyDown, config.eventName),\r
                capture: config.capture\r
            },\r
            map;\r
\r
        if (me.map) {\r
            me.map.destroy();\r
        }\r
\r
        // Ensure config system configs are set\r
        me.initConfig(config);\r
\r
        if (config.processEvent) {\r
            keymapCfg.processEvent = config.processEvent;\r
            keymapCfg.processEventScope = config.processEventScope||me;\r
        }\r
        if (config.priority) {\r
            keymapCfg.priority = config.priority;\r
        }\r
\r
        // If they specified a KeyMap to use, use it\r
        if (config.keyMap) {\r
            map = me.map = config.keyMap;\r
        }\r
        // Otherwise, create one, and remember to destroy it on destroy\r
        else {\r
            map = me.map = new Ext.util.KeyMap(keymapCfg);\r
            me.destroyKeyMap = true;\r
        }\r
\r
        this.addBindings(config);\r
\r
        map.disable();\r
        if (!config.disabled) {\r
            map.enable();\r
        }\r
    },\r
\r
    addBindings: function(bindings) {\r
        var me = this,\r
            keyName,\r
            binding,\r
            map = me.map,\r
            keyCodes = Ext.util.KeyNav.keyOptions,\r
            keyCode,\r
            defaultScope = bindings.scope || me;\r
\r
        for (keyName in bindings) {\r
            binding = bindings[keyName];\r
            // There is a property named after a key name.\r
            // It may be a function or an binding spec containing handler, scope and defaultEventAction configs\r
            // Allow {A: { ctrl: true, handler: onCtrlA }}\r
            // Allow {45: doInsert} to use key codes directly\r
            keyCode = keyCodes[keyName];\r
            if (keyCode != null) {\r
                keyName = keyCode;\r
            }\r
            if (binding && (keyName.length === 1 || !isNaN(keyName = parseInt(keyName, 10)))) {\r
                if (typeof binding === 'function') {\r
                    binding = {\r
                        handler: binding,\r
                        defaultEventAction: (bindings.defaultEventAction !== undefined) ? bindings.defaultEventAction : me.defaultEventAction\r
                    };\r
                }\r
                map.addBinding({\r
                    key: keyName,\r
                    ctrl: binding.ctrl,\r
                    shift: binding.shift,\r
                    alt: binding.alt,\r
                    handler: Ext.Function.bind(me.handleEvent, binding.scope||defaultScope, [binding.handler||binding.fn, me], true),\r
                    defaultEventAction: (binding.defaultEventAction !== undefined) ? binding.defaultEventAction : me.defaultEventAction\r
                });\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Method for filtering out the map argument\r
     * @private\r
     * @param {Number} keyCode\r
     * @param {Ext.event.Event} event\r
     * @param {Function} handler The function to call\r
     * @param {Ext.util.KeyNav} keyNav The owning KeyNav\r
     */\r
    handleEvent: function(keyCode, event, handler, keyNav) {\r
        keyNav.lastKeyEvent = event;\r
        return handler.call(this, event);\r
    },\r
\r
    /**\r
     * Destroy this KeyNav.\r
     * @param {Boolean} removeEl Pass `true` to remove the element associated with this KeyNav.\r
     */\r
    destroy: function(removeEl) {\r
        var me = this;\r
        \r
        if (me.destroyKeyMap) {\r
            me.map.destroy(removeEl);\r
        }\r
        delete me.map;\r
        me.callParent();\r
    },\r
\r
    /**\r
     * Enables this KeyNav.\r
     */\r
    enable: function() {\r
        // this.map will be removed if destroyed\r
        if (this.map) {\r
            this.map.enable();\r
            this.disabled = false;\r
        }\r
    },\r
\r
    /**\r
     * Disables this KeyNav.\r
     */\r
    disable: function() {\r
        // this.map will be removed if destroyed\r
        if (this.map) {\r
            this.map.disable();\r
        }\r
        this.disabled = true;\r
    },\r
\r
    /**\r
     * Convenience function for setting disabled/enabled by boolean.\r
     * @param {Boolean} disabled\r
     */\r
    setDisabled : function(disabled) {\r
        this.map.setDisabled(disabled);\r
        this.disabled = disabled;\r
    },\r
\r
    /**\r
     * @private\r
     * Determines the event to bind to listen for keys. Defaults to the {@link #eventName} value, but\r
     * may be overridden the {@link #forceKeyDown} setting.\r
     *\r
     * @return {String} The type of event to listen for.\r
     */\r
    getKeyEvent: function(forceKeyDown, configuredEventName) {\r
        if (forceKeyDown || (Ext.supports.SpecialKeyDownRepeat && !configuredEventName)) {\r
            return 'keydown';\r
        } else {\r
            return configuredEventName||this.eventName;\r
        }\r
    }\r
});