/**
+ * Add a key listener. The listener will only be notified if the
+ * keystroke detected meets the supplied specification. The
+ * spec consists of the key event type, followed by a colon,
+ * followed by zero or more comma separated key codes, followed
+ * by zero or more modifiers delimited by a plus sign. Ex:
+ * press:12,65+shift+ctrl
+ * @event key
+ * @for YUI
+ * @param type {string} 'key'
+ * @param fn {string} the function to execute
+ * @param id {string} the element(s) to bind
+ * @param spec {string} the keyCode and modifier specification
+ * @param o optional context object
+ * @param args 0..n additional arguments that should be provided
+ * to the listener.
+ * @return {Event.Handle} the detach handle
+ */
+Y.Env.evt.plugins.key = {
+
+ on: function(type, fn, id, spec, o) {
+ var a = Y.Array(arguments, 0, true),
+ parsed, etype, criteria, ename;
+
+
+ if (!spec || spec.indexOf(':') == -1) {
+Y.log('Illegal key spec, creating a regular keypress listener instead.', 'info', 'event');
+ a[0] = 'keypress';
+ return Y.on.apply(Y, a);
+ }
+
+ parsed = spec.split(':');
+
+ // key event type: 'down', 'up', or 'press'
+ etype = parsed[0];
+
+ // list of key codes optionally followed by modifiers
+ criteria = (parsed[1]) ? parsed[1].split(/,|\+/) : null;
+
+ // the name of the custom event that will be created for the spec
+ ename = (Y.Lang.isString(id) ? id : Y.stamp(id)) + spec;
+
+ ename = ename.replace(/,/g, '_');
+
+ if (!Y.getEvent(ename)) {
+
+ // subscribe spec validator to the DOM event
+ Y.on(type + etype, function(e) {
+
+ // Y.log('keylistener: ' + e.keyCode);
+
+ var passed = false, failed = false, i, crit, critInt;
+
+ for (i=0; i<criteria.length; i=i+1) {
+ crit = criteria[i];
+ critInt = parseInt(crit, 10);
+
+ // pass this section if any supplied keyCode
+ // is found
+ if (Y.Lang.isNumber(critInt)) {
+
+ if (e.charCode === critInt) {
+ // Y.log('passed: ' + crit);
+ passed = true;
+ } else {
+ failed = true;
+ // Y.log('failed: ' + crit);
+ }
+
+ // only check modifier if no keyCode was specified
+ // or the keyCode check was successful. pass only
+ // if every modifier passes
+ } else if (passed || !failed) {
+ passed = (e[crit + 'Key']);
+ failed = !passed;
+ // Y.log(crit + ": " + passed);
+ }
+ }
+
+ // fire spec custom event if spec if met
+ if (passed) {
+ Y.fire(ename, e);
+ }
+
+ }, id);
+
+ }
+
+ // subscribe supplied listener to custom event for spec validator
+ // remove element and spec.
+ a.splice(2, 2);
+ a[0] = ename;
+
+ return Y.on.apply(Y, a);
+ }
+};
+