extjs-rails 4.1.0.alpha1

data/app/assets/javascripts/extjs-rails/src/util/KeyMap.js

@@ -0,0 +1,427 @@
+/**
+ * Handles mapping key events to handling functions for an element or a Component. One KeyMap can be used for multiple
+ * actions.
+ *
+ * A KeyMap must be configured with a {@link #target} as an event source which may be an Element or a Component.
+ *
+ * If the target is an element, then the `keydown` event will trigger the invocation of {@link #binding}s.
+ *
+ * It is possible to configure the KeyMap with a custom {@link #eventName} to listen for. This may be useful when the
+ * {@link #target} is a Component.
+ *
+ * The KeyMap's event handling requires that the first parameter passed is a key event. So if the Component's event
+ * signature is different, specify a {@link #processEvent} configuration which accepts the event's parameters and
+ * returns a key event.
+ *
+ * Functions specified in {@link #binding}s are called with this signature : `(String key, Ext.EventObject e)` (if the
+ * match is a multi-key combination the callback will still be called only once). A KeyMap can also handle a string
+ * representation of keys. By default KeyMap starts enabled.
+ *
+ * Usage:
+ *
+ *     // map one key by key code
+ *     var map = new Ext.util.KeyMap({
+ *         target: "my-element",
+ *         key: 13, // or Ext.EventObject.ENTER
+ *         fn: myHandler,
+ *         scope: myObject
+ *     });
+ *
+ *     // map multiple keys to one action by string
+ *     var map = new Ext.util.KeyMap({
+ *         target: "my-element",
+ *         key: "a\r\n\t",
+ *         fn: myHandler,
+ *         scope: myObject
+ *     });
+ *
+ *     // map multiple keys to multiple actions by strings and array of codes
+ *     var map = new Ext.util.KeyMap({
+ *         target: "my-element",
+ *         binding: [{
+ *             key: [10,13],
+ *             fn: function(){ alert("Return was pressed"); }
+ *         }, {
+ *             key: "abc",
+ *             fn: function(){ alert('a, b or c was pressed'); }
+ *         }, {
+ *             key: "\t",
+ *             ctrl:true,
+ *             shift:true,
+ *             fn: function(){ alert('Control + shift + tab was pressed.'); }
+ *         }]
+ *     });
+ *
+ * Since 4.1.0, KeyMaps can bind to Components and process key-based events fired by Components.
+ *
+ * To bind to a Component, use the single parameter form of constructor:
+ *
+ *     var map = new Ext.util.KeyMap({
+ *         target: myGridView,
+ *         eventName: 'itemkeydown',
+ *         processEvent: function(view, record, node, index, event) {
+ *
+ *             // Load the event with the extra information needed by the mappings
+ *             event.view = view;
+ *             event.store = view.getStore();
+ *             event.record = record;
+ *             event.index = index;
+ *             return event;
+ *         },
+ *         binding: {
+ *             key: Ext.EventObject.DELETE,
+ *             fn: function(keyCode, e) {
+ *                 e.store.remove(e.record);
+ *
+ *                 // Attempt to select the record that's now in its place
+ *                 e.view.getSelectionModel().select(e,index);
+ *                 e.view.el.focus();
+ *             }
+ *         }
+ *     });
+ */
+Ext.define('Ext.util.KeyMap', {
+    alternateClassName: 'Ext.KeyMap',
+
+    /**
+     * @cfg {Ext.Component/Ext.Element/HTMLElement/String} target
+     * The object on which to listen for the event specified by the {@link #eventName} config option.
+     */
+
+    /**
+     * @cfg {Object/Object[][]} binding
+     * Either a single object describing a handling function for s specified key (or set of keys), or
+     * an array of such objects.
+     * @cfg {String/String[]} binding.key A single keycode or an array of keycodes to handle
+     * @cfg {Boolean}  binding.shift True to handle key only when shift is pressed, False to handle the
+     *  key only when shift is not pressed (defaults to undefined)
+     * @cfg {Boolean}  binding.ctrl True to handle key only when ctrl is pressed, False to handle the
+     *  key only when ctrl is not pressed (defaults to undefined)
+     * @cfg {Boolean}  binding.alt True to handle key only when alt is pressed, False to handle the key
+     *  only when alt is not pressed (defaults to undefined)
+     * @cfg {Function} binding.handler The function to call when KeyMap finds the expected key combination
+     * @cfg {Function} binding.fn Alias of handler (for backwards-compatibility)
+     * @cfg {Object}   binding.scope The scope of the callback function
+     * @cfg {String}   binding.defaultEventAction A default action to apply to the event. Possible values
+     *  are: stopEvent, stopPropagation, preventDefault. If no value is set no action is performed.
+     */
+
+    /**
+     * @cfg {Object} [processEventScope=this]
+     * The scope (`this` context) in which the {@link #processEvent} method is executed.
+     */
+
+    /**
+     * @cfg {String} eventName
+     * The event to listen for to pick up key events.
+     */
+    eventName: 'keydown',
+
+    constructor: function(config) {
+        var me = this;
+
+        // Handle legacy arg list in which the first argument is the target.
+        // TODO: Deprecate in V5
+        if ((arguments.length !== 1) || (typeof config === 'string') || config.dom || config.tagName || config === document || config.isComponent) {
+            me.legacyConstructor.apply(me, arguments);
+            return;
+        }
+
+        Ext.apply(me, config);
+        me.bindings = [];
+
+        if (!me.target.isComponent) {
+            me.target = Ext.get(me.target);
+        }
+
+        if (me.binding) {
+            me.addBinding(me.binding);
+        } else if (config.key) {
+            me.addBinding(config);
+        }
+        me.enable();
+    },
+
+    /**
+     * @private
+     * Old constructor signature
+     * @param {String/HTMLElement/Ext.Element/Ext.Component} el The element or its ID, or Component to bind to
+     * @param {Object} binding The binding (see {@link #addBinding})
+     * @param {String} [eventName="keydown"] The event to bind to
+     */
+    legacyConstructor: function(el, binding, eventName){
+        var me = this;
+
+        Ext.apply(me, {
+            target: Ext.get(el),
+            eventName: eventName || me.eventName,
+            bindings: []
+        });
+        if (binding) {
+            me.addBinding(binding);
+        }
+        me.enable();
+    },
+
+    /**
+     * Add a new binding to this KeyMap.
+     *
+     * Usage:
+     *
+     *     // Create a KeyMap
+     *     var map = new Ext.util.KeyMap(document, {
+     *         key: Ext.EventObject.ENTER,
+     *         fn: handleKey,
+     *         scope: this
+     *     });
+     *
+     *     //Add a new binding to the existing KeyMap later
+     *     map.addBinding({
+     *         key: 'abc',
+     *         shift: true,
+     *         fn: handleKey,
+     *         scope: this
+     *     });
+     *
+     * @param {Object/Object[]} binding A single KeyMap config or an array of configs.
+     * The following config object properties are supported:
+     * @param {String/Array} binding.key A single keycode or an array of keycodes to handle.
+     * @param {Boolean} binding.shift True to handle key only when shift is pressed,
+     * False to handle the keyonly when shift is not pressed (defaults to undefined).
+     * @param {Boolean} binding.ctrl True to handle key only when ctrl is pressed,
+     * False to handle the key only when ctrl is not pressed (defaults to undefined).
+     * @param {Boolean} binding.alt True to handle key only when alt is pressed,
+     * False to handle the key only when alt is not pressed (defaults to undefined).
+     * @param {Function} binding.handler The function to call when KeyMap finds the
+     * expected key combination.
+     * @param {Function} binding.fn Alias of handler (for backwards-compatibility).
+     * @param {Object} binding.scope The scope of the callback function.
+     * @param {String} binding.defaultEventAction A default action to apply to the event.
+     * Possible values are: stopEvent, stopPropagation, preventDefault. If no value is
+     * set no action is performed..
+     */
+    addBinding : function(binding){
+        var keyCode = binding.key,
+            processed = false,
+            key,
+            keys,
+            keyString,
+            i,
+            len;
+
+        if (Ext.isArray(binding)) {
+            for (i = 0, len = binding.length; i < len; i++) {
+                this.addBinding(binding[i]);
+            }
+            return;
+        }
+
+        if (Ext.isString(keyCode)) {
+            keys = [];
+            keyString = keyCode.toUpperCase();
+
+            for (i = 0, len = keyString.length; i < len; ++i){
+                keys.push(keyString.charCodeAt(i));
+            }
+            keyCode = keys;
+            processed = true;
+        }
+
+        if (!Ext.isArray(keyCode)) {
+            keyCode = [keyCode];
+        }
+
+        if (!processed) {
+            for (i = 0, len = keyCode.length; i < len; ++i) {
+                key = keyCode[i];
+                if (Ext.isString(key)) {
+                    keyCode[i] = key.toUpperCase().charCodeAt(0);
+                }
+            }
+        }
+
+        this.bindings.push(Ext.apply({
+            keyCode: keyCode
+        }, binding));
+    },
+
+    /**
+     * Process any keydown events on the element
+     * @private
+     * @param {Ext.EventObject} event
+     */
+    handleKeyDown: function(event) {
+        var me = this,
+            bindings, i, len;
+
+        if (this.enabled) { //just in case
+            bindings = this.bindings;
+            i = 0;
+            len = bindings.length;
+
+            // Process the event
+            event = me.processEvent.apply(me||me.processEventScope, arguments);
+
+            // If the processor does not return a keyEvent, we can't process it.
+            // Allow them to return false to cancel processing of the event
+            if (!event.getKey) {
+                return event;
+            }
+            for(; i < len; ++i){
+                this.processBinding(bindings[i], event);
+            }
+        }
+    },
+
+    /**
+     * @cfg {Function} processEvent
+     * An optional event processor function which accepts the argument list provided by the
+     * {@link #eventName configured event} of the {@link #target}, and returns a keyEvent for processing by the KeyMap.
+     *
+     * This may be useful when the {@link #target} is a Component with s complex event signature. Extra information from
+     * the event arguments may be injected into the event for use by the handler functions before returning it.
+     */
+    processEvent: function(event){
+        return event;
+    },
+
+    /**
+     * Process a particular binding and fire the handler if necessary.
+     * @private
+     * @param {Object} binding The binding information
+     * @param {Ext.EventObject} event
+     */
+    processBinding: function(binding, event){
+        if (this.checkModifiers(binding, event)) {
+            var key = event.getKey(),
+                handler = binding.fn || binding.handler,
+                scope = binding.scope || this,
+                keyCode = binding.keyCode,
+                defaultEventAction = binding.defaultEventAction,
+                i,
+                len,
+                keydownEvent = new Ext.EventObjectImpl(event);
+
+
+            for (i = 0, len = keyCode.length; i < len; ++i) {
+                if (key === keyCode[i]) {
+                    if (handler.call(scope, key, event) !== true && defaultEventAction) {
+                        keydownEvent[defaultEventAction]();
+                    }
+                    break;
+                }
+            }
+        }
+    },
+
+    /**
+     * Check if the modifiers on the event match those on the binding
+     * @private
+     * @param {Object} binding
+     * @param {Ext.EventObject} event
+     * @return {Boolean} True if the event matches the binding
+     */
+    checkModifiers: function(binding, e) {
+        var keys = ['shift', 'ctrl', 'alt'],
+            i = 0,
+            len = keys.length,
+            val, key;
+
+        for (; i < len; ++i){
+            key = keys[i];
+            val = binding[key];
+            if (!(val === undefined || (val === e[key + 'Key']))) {
+                return false;
+            }
+        }
+        return true;
+    },
+
+    /**
+     * Shorthand for adding a single key listener.
+     *
+     * @param {Number/Number[]/Object} key Either the numeric key code, array of key codes or an object with the
+     * following options: `{key: (number or array), shift: (true/false), ctrl: (true/false), alt: (true/false)}`
+     * @param {Function} fn The function to call
+     * @param {Object} [scope] The scope (`this` reference) in which the function is executed.
+     * Defaults to the browser window.
+     */
+    on: function(key, fn, scope) {
+        var keyCode, shift, ctrl, alt;
+        if (Ext.isObject(key) && !Ext.isArray(key)) {
+            keyCode = key.key;
+            shift = key.shift;
+            ctrl = key.ctrl;
+            alt = key.alt;
+        } else {
+            keyCode = key;
+        }
+        this.addBinding({
+            key: keyCode,
+            shift: shift,
+            ctrl: ctrl,
+            alt: alt,
+            fn: fn,
+            scope: scope
+        });
+    },
+
+    /**
+     * Returns true if this KeyMap is enabled
+     * @return {Boolean}
+     */
+    isEnabled : function() {
+        return this.enabled;
+    },
+
+    /**
+     * Enables this KeyMap
+     */
+    enable: function() {
+        var me = this;
+        
+        if (!me.enabled) {
+            me.target.on(me.eventName, me.handleKeyDown, me);
+            me.enabled = true;
+        }
+    },
+
+    /**
+     * Disable this KeyMap
+     */
+    disable: function() {
+        var me = this;
+        
+        if (me.enabled) {
+            me.target.removeListener(me.eventName, me.handleKeyDown, me);
+            me.enabled = false;
+        }
+    },
+
+    /**
+     * Convenience function for setting disabled/enabled by boolean.
+     * @param {Boolean} disabled
+     */
+    setDisabled : function(disabled) {
+        if (disabled) {
+            this.disable();
+        } else {
+            this.enable();
+        }
+    },
+
+    /**
+     * Destroys the KeyMap instance and removes all handlers.
+     * @param {Boolean} removeTarget True to also remove the {@link #target}
+     */
+    destroy: function(removeTarget) {
+        var me = this;
+
+        me.bindings = [];
+        me.disable();
+        if (removeTarget === true) {
+            me.target.isComponent ? me.target.destroy() : me.target.remove();
+        }
+        delete me.target;
+    }
+});

data/app/assets/javascripts/extjs-rails/src/util/KeyNav.js

@@ -0,0 +1,239 @@
+/**
+ * Provides a convenient wrapper for normalized keyboard navigation. KeyNav allows you to bind navigation keys to
+ * function calls that will get called when the keys are pressed, providing an easy way to implement custom navigation
+ * schemes for any UI component.
+ *
+ * The following are all of the possible keys that can be implemented: enter, space, left, right, up, down, tab, esc,
+ * pageUp, pageDown, del, backspace, home, end.
+ *
+ * Usage:
+ *
+ *     var nav = new Ext.util.KeyNav({
+ *         target : "my-element",
+ *         left   : function(e){
+ *             this.moveLeft(e.ctrlKey);
+ *         },
+ *         right  : function(e){
+ *             this.moveRight(e.ctrlKey);
+ *         },
+ *         enter  : function(e){
+ *             this.save();
+ *         },
+ *         
+ *         // Binding may be a function specifiying fn, scope and defaultAction
+ *         esc: {
+ *             fn: this.onEsc,
+ *             defaultEventAction: false
+ *         },
+ *         scope : this
+ *     });
+ */
+Ext.define('Ext.util.KeyNav', {
+    alternateClassName: 'Ext.KeyNav',
+    
+    requires: ['Ext.util.KeyMap'],
+    
+    statics: {
+        keyOptions: {
+            left: 37,
+            right: 39,
+            up: 38,
+            down: 40,
+            space: 32,
+            pageUp: 33,
+            pageDown: 34,
+            del: 46,
+            backspace: 8,
+            home: 36,
+            end: 35,
+            enter: 13,
+            esc: 27,
+            tab: 9
+        }
+    },
+
+    constructor: function(config) {
+        var me = this;
+        if (arguments.length === 2) {
+            me.legacyConstructor.apply(me, arguments);
+            return;
+        }
+        me.setConfig(config);
+    },
+
+    /**
+     * @private
+     * Old constructor signature.
+     * @param {String/HTMLElement/Ext.Element} el The element or its ID to bind to
+     * @param {Object} config The config
+     */
+    legacyConstructor: function(el, config) {
+        this.setConfig(Ext.apply({
+            target: el
+        }, config));
+    },
+    
+    /**
+     * Sets up a configuration for the KeyNav.
+     * @private
+     * @param {String/HTMLElement/Ext.Element} el The element or its ID to bind to
+     * @param {Object} config A configuration object as specified in the constructor.
+     */
+    setConfig: function(config) {
+        var me = this,
+            keymapCfg = {
+                target: config.target,
+                eventName: me.getKeyEvent('forceKeyDown' in config ? config.forceKeyDown : me.forceKeyDown, config.eventName)
+            },
+            map, keyCodes, defaultScope, keyName, binding;
+
+        if (me.map) {
+            me.map.destroy();
+        }
+
+        if (config.processEvent) {
+            keymapCfg.processEvent = config.processEvent;
+            keymapCfg.processEventScope = config.processEventScope||me;
+        }
+        map = me.map = new Ext.util.KeyMap(keymapCfg);
+        keyCodes = Ext.util.KeyNav.keyOptions;
+        defaultScope = config.scope || me;
+        
+        for (keyName in keyCodes) {
+            if (keyCodes.hasOwnProperty(keyName)) {
+
+                // There is a property named after a key name.
+                // It may be a function or an binding spec containing handler, scope and defaultAction configs
+                if (binding = config[keyName]) {
+                    if (typeof binding === 'function') {
+                        binding = {
+                            handler: binding,
+                            defaultAction: (config.defaultEventAction !== undefined) ? config.defaultEventAction : me.defaultEventAction
+                        };
+                    }
+                    map.addBinding({
+                        key: keyCodes[keyName],
+                        handler: Ext.Function.bind(me.handleEvent, binding.scope||defaultScope, binding.handler||binding.fn, true),
+                        defaultEventAction: (binding.defaultEventAction !== undefined) ? binding.defaultAction : me.defaultEventAction
+                    });
+                }
+            }
+        }
+        
+        map.disable();
+        if (!config.disabled) {
+            map.enable();
+        }
+    },
+    
+    /**
+     * Method for filtering out the map argument
+     * @private
+     * @param {Number} keyCode
+     * @param {Ext.EventObject} event
+     * @param {Object} options Contains the handler to call
+     */
+    handleEvent: function(keyCode, event, handler){
+        return handler.call(this, event);
+    },
+    
+    /**
+     * @cfg {Boolean} disabled
+     * True to disable this KeyNav instance.
+     */
+    disabled: false,
+    
+    /**
+     * @cfg {String} defaultEventAction
+     * The method to call on the {@link Ext.EventObject} after this KeyNav intercepts a key. Valid values are {@link
+     * Ext.EventObject#stopEvent}, {@link Ext.EventObject#preventDefault} and {@link Ext.EventObject#stopPropagation}.
+     *
+     * If a falsy value is specified, no method is called on the key event.
+     */
+    defaultEventAction: "stopEvent",
+    
+    /**
+     * @cfg {Boolean} forceKeyDown
+     * Handle the keydown event instead of keypress. KeyNav automatically does this for IE since IE does not propagate
+     * special keys on keypress, but setting this to true will force other browsers to also handle keydown instead of
+     * keypress.
+     */
+    forceKeyDown: false,
+
+    /**
+     * @cfg {Ext.Component/Ext.Element/HTMLElement/String} target
+     * The object on which to listen for the event specified by the {@link #eventName} config option.
+     */
+
+    /**
+     * @cfg {String} eventName
+     * The event to listen for to pick up key events.
+     */
+    eventName: 'keypress',
+
+    /**
+     * @cfg {Function} processEvent
+     * An optional event processor function which accepts the argument list provided by the {@link #eventName configured
+     * event} of the {@link #target}, and returns a keyEvent for processing by the KeyMap.
+     *
+     * This may be useful when the {@link #target} is a Component with s complex event signature. Extra information from
+     * the event arguments may be injected into the event for use by the handler functions before returning it.
+     */
+
+    /**
+     * @cfg {Object} [processEventScope=this]
+     * The scope (`this` context) in which the {@link #processEvent} method is executed.
+     */
+
+    /**
+     * Destroy this KeyNav (this is the same as calling disable).
+     * @param {Boolean} removeEl True to remove the element associated with this KeyNav.
+     */
+    destroy: function(removeEl){
+        this.map.destroy(removeEl);
+        delete this.map;
+    },
+
+    /**
+     * Enables this KeyNav.
+     */
+    enable: function() {
+        this.map.enable();
+        this.disabled = false;
+    },
+
+    /**
+     * Disables this KeyNav.
+     */
+    disable: function() {
+        this.map.disable();
+        this.disabled = true;
+    },
+    
+    /**
+     * Convenience function for setting disabled/enabled by boolean.
+     * @param {Boolean} disabled
+     */
+    setDisabled : function(disabled){
+        this.map.setDisabled(disabled);
+        this.disabled = disabled;
+    },
+    
+    /**
+     * @private
+     * Determines the event to bind to listen for keys. Defaults to the {@link #eventName} value, but
+     * may be overridden the {@link #forceKeyDown} setting.
+     *
+     * The useKeyDown option on the EventManager modifies the default {@link #eventName} to be `keydown`,
+     * but a configured {@link #eventName} takes priority over this.
+     *
+     * @return {String} The type of event to listen for.
+     */
+    getKeyEvent: function(forceKeyDown, configuredEventName){
+        if (forceKeyDown || (Ext.EventManager.useKeyDown && !configuredEventName)) {
+            return 'keydown';
+        } else {
+            return configuredEventName||this.eventName;
+        }
+    }
+});