key.js revision cc993d3cace28dec43cfc6f55b41961e90e76ba9
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * Functionality to listen for one or more specific key combinations.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @module event
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @submodule event-key
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp _keysRE: /^(?:up|down|press):|\+(alt|ctrl|meta|shift)/g,
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp mods = Y.Array.hash(spec.match(/\+(?:alt|ctrl|meta|shift)\b/g) || []),
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp // strip type and modifiers from spec, leaving only keyCodes
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp // FIXME: need to support '65,esc' => keypress, keydown
a89ad754cce3cfc8aee71760e10217b54020360dTripp // catch sloppy filters, trailing commas, etc 'a,,'
a89ad754cce3cfc8aee71760e10217b54020360dTripp // non-numerics are single characters or key names
a89ad754cce3cfc8aee71760e10217b54020360dTripp // FIXME: '65,enter' defaults keydown for both
a89ad754cce3cfc8aee71760e10217b54020360dTripp // FIXME: possibly stupid assumption that
7947db4b7d8682ea81598e3a4283e659a8103be6Tripp // the keycode of the lower case == the
a89ad754cce3cfc8aee71760e10217b54020360dTripp // charcode of the upper case
a89ad754cce3cfc8aee71760e10217b54020360dTripp // a (key:65,char:97), A (key:65,char:65)
7947db4b7d8682ea81598e3a4283e659a8103be6Tripp // upper case chars get +shift free
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp // Note: without specifying any keyCodes, this becomes a
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp // horribly inefficient alias for 'keydown' (et al), but I
c093c1aed867e18aa4778708592e1ceb45d18cffTripp // can't abort this subscription for a simple
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp // Y.on('keypress', ...);
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp // Please use keyCodes or just subscribe directly to keydown,
a89ad754cce3cfc8aee71760e10217b54020360dTripp // keyup, or keypress
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <p>Add a key listener. The listener will only be notified if the
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * keystroke detected meets the supplied specification. The
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * specification is a string that is defined as:</p>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>spec</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dd><code>[{type}:]{code}[,{code}]*</code></dd>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>type</dt>
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * <dd><code>"down", "up", or "press"</code></dd>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>code</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dd><code>{keyCode|character|keyName}[+{modifier}]*</code></dd>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>modifier</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dd><code>"shift", "ctrl", "alt", or "meta"</code></dd>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>keyName</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dd><code>"enter", "backspace", "esc", "tab", "pageup", or "pagedown"</code></dd>
bf801d6851ecf7ed14742ef3639a077daecb5cf8Tripp * <p>Examples:</p>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <li><code>Y.on("key", callback, "press:12,65+shift+ctrl", "#my-input");</code></li>
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * <li><code>Y.delegate("key", preventSubmit, "enter", "#forms", "input[type=text]");</code></li>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <li><code>Y.one("doc").on("key", viNav, "j,k,l,;");</code></li>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @event key
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param type {string} 'key'
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param fn {function} the function to execute
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param id {string|HTMLElement|collection} the element(s) to bind
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param spec {string} the keyCode and modifier specification
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param o optional context object
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param args 0..n additional arguments to provide to the listener.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @return {Event.Handle} the detach handle