File: event/js/key.js

            /**
             * Functionality to listen for one or more specific key combinations.
             * @module event
             * @submodule event-key
             */
            
            var ALT      = "+alt",
                CTRL     = "+ctrl",
                META     = "+meta",
                SHIFT    = "+shift",
            
                trim     = Y.Lang.trim,
            
                eventDef = {
                    KEY_MAP: {
                        enter    : 13,
                        space    : 32,
                        esc      : 27,
                        backspace: 8,
                        tab      : 9,
                        pageup   : 33,
                        pagedown : 34
                    },
            
                    _typeRE: /^(up|down|press):/,
                    _keysRE: /^(?:up|down|press):|\+(alt|ctrl|meta|shift)/g,
            
                    processArgs: function (args) {
                        var spec = args.splice(3,1)[0],
                            mods = Y.Array.hash(spec.match(/\+(?:alt|ctrl|meta|shift)\b/g) || []),
                            config = {
                                type: this._typeRE.test(spec) ? RegExp.$1 : null,
                                mods: mods,
                                keys: null
                            },
                            // strip type and modifiers from spec, leaving only keyCodes
                            bits = spec.replace(this._keysRE, ''),
                            chr, uc, lc, i;
            
                        if (bits) {
                            bits = bits.split(',');
            
                            config.keys = {};
            
                            // FIXME: need to support '65,esc' => keypress, keydown
                            for (i = bits.length - 1; i >= 0; --i) {
                                chr = trim(bits[i]);
            
                                // catch sloppy filters, trailing commas, etc 'a,,'
                                if (!chr) {
                                    continue;
                                }
            
                                // non-numerics are single characters or key names
                                if (+chr == chr) {
                                    config.keys[chr] = mods;
                                } else {
                                    lc = chr.toLowerCase();
            
                                    if (this.KEY_MAP[lc]) {
                                        config.keys[this.KEY_MAP[lc]] = mods;
                                        // FIXME: '65,enter' defaults keydown for both
                                        if (!config.type) {
                                            config.type = "down"; // safest
                                        }
                                    } else {
                                        // FIXME: Character mapping only works for keypress
                                        // events. Otherwise, it uses String.fromCharCode()
                                        // from the keyCode, which is wrong.
                                        chr = chr.charAt(0);
                                        uc  = chr.toUpperCase();
            
                                        if (mods["+shift"]) {
                                            chr = uc;
                                        }
            
                                        // FIXME: stupid assumption that
                                        // the keycode of the lower case == the
                                        // charCode of the upper case
                                        // a (key:65,char:97), A (key:65,char:65)
                                        config.keys[chr.charCodeAt(0)] =
                                            (chr === uc) ?
                                                // upper case chars get +shift free
                                                Y.merge(mods, { "+shift": true }) :
                                                mods;
                                    }
                                }
                            }
                        }
            
                        if (!config.type) {
                            config.type = "press";
                        }
            
                        return config;
                    },
            
                    on: function (node, sub, notifier, filter) {
                        var spec   = sub._extra,
                            type   = "key" + spec.type,
                            keys   = spec.keys,
                            method = (filter) ? "delegate" : "on";
            
                        // Note: without specifying any keyCodes, this becomes a
                        // horribly inefficient alias for 'keydown' (et al), but I
                        // can't abort this subscription for a simple
                        // Y.on('keypress', ...);
                        // Please use keyCodes or just subscribe directly to keydown,
                        // keyup, or keypress
                        sub._detach = node[method](type, function (e) {
                            var key = keys ? keys[e.which] : spec.mods;
            
                            if (key &&
                                (!key[ALT]   || (key[ALT]   && e.altKey)) &&
                                (!key[CTRL]  || (key[CTRL]  && e.ctrlKey)) &&
                                (!key[META]  || (key[META]  && e.metaKey)) &&
                                (!key[SHIFT] || (key[SHIFT] && e.shiftKey)))
                            {
                                notifier.fire(e);
                            }
                        }, filter);
                    },
            
                    detach: function (node, sub, notifier) {
                        sub._detach.detach();
                    }
                };
            
            eventDef.delegate = eventDef.on;
            eventDef.detachDelegate = eventDef.detach;
            
            /**
             * <p>Add a key listener.  The listener will only be notified if the
             * keystroke detected meets the supplied specification.  The
             * specification is a string that is defined as:</p>
             *
             * <dl>
             *   <dt>spec</dt>
             *   <dd><code>[{type}:]{code}[,{code}]*</code></dd>
             *   <dt>type</dt>
             *   <dd><code>"down", "up", or "press"</code></dd>
             *   <dt>code</dt>
             *   <dd><code>{keyCode|character|keyName}[+{modifier}]*</code></dd>
             *   <dt>modifier</dt>
             *   <dd><code>"shift", "ctrl", "alt", or "meta"</code></dd>
             *   <dt>keyName</dt>
             *   <dd><code>"enter", "space", "backspace", "esc", "tab", "pageup", or "pagedown"</code></dd>
             * </dl>
             *
             * <p>Examples:</p>
             * <ul>
             *   <li><code>Y.on("key", callback, "press:12,65+shift+ctrl", "#my-input");</code></li>
             *   <li><code>Y.delegate("key", preventSubmit, "#forms", "enter", "input[type=text]");</code></li>
             *   <li><code>Y.one("doc").on("key", viNav, "j,k,l,;");</code></li>
             * </ul>
             *
             * @event key
             * @for YUI
             * @param type {string} 'key'
             * @param fn {function} the function to execute
             * @param id {string|HTMLElement|collection} the element(s) to bind
             * @param spec {string} the keyCode and modifier specification
             * @param o optional context object
             * @param args 0..n additional arguments to provide to the listener.
             * @return {Event.Handle} the detach handle
             */
            Y.Event.define('key', eventDef, true);