<div class="intro">
<p>The `event-key` module adds the "key" event for subscribing to keyboard
events triggered by users entering specific keys. The subscription
signature includes a filter configuration that can be used to limit event
triggering based on key codes, shift, ctrl, alt, or meta keys pressed, as
well as specifying the keyboard event (`keydown`, `keyup`, or
`keypress`).</p>
</div>
<h2>The filtering spec</h2>
<p>Example subscriptions might look like this:</p>
```
// certain keys can be referenced by name
input.on('key', saveAndClose, 'enter');
// require modifier keys with +(modifier)
Y.one('doc').on('key', composeMail, 'n+ctrl');
// specify the event and key codes
datatable.get('contentBox')
.delegate('key', moveAround, 'down:37,38,39,40', '.yui3-datatable-liner');
```
<p>The third argument is the filtering spec. Similar to using the
`node.delegate()` method, the callback is only executed if the key event
matches the filter. The supported filter syntax is a string defined like
this:</p>
{{>key-railroad-style}}
<ol>
<li>(0..1) <span class="token">type</span> followed by a colon</li>
<li>(0..n) comma separated <span class="token">code</span>s</li>
<li>(0..n) <span class="token">modifier</span>s, each preceded by "+"</li>
</ol>
<h4>Choo choo!</h4>
<p>If you're into railroad diagrams, the filter spec looks like this:</p>
<ul class="railroad yui3-g">
<li class="yui3-u">
<p>"</p>
</li>
<li class="yui3-u">
<div class="branch">
<p><span class="token">type</span> :</p>
</div>
</li>
<li class="yui3-u" id="code-branch">
<div class="branch">
<p><span class="token">code</span></p>
</div>
<div class="loop">
<p>,</p>
</div>
</li>
<li class="yui3-u" id="mod-branch">
<div class="branch">
<p>+<span class="token">modifier</span></p>
</div>
<div class="loop"></div>
</li>
<li class="yui3-u">
<p>"</p>
</li>
</ul>
<h4>Filter tokens</h4>
<dl>
<dt><span class="token">type</span></dt>
<dd>"down", "up", or "press" for `keydown`, `keyup`, and `keypress`.
The default is `keypress`.</dd>
<dt><span class="token">code</span><dt>
<dd>Any numeric `keyCode`, unicode character, or <a
href="#common">common key name</a>.</dd>
<dt><span class="token">modifier</span></dt>
<dd>"shift", "alt", "ctrl", or "meta". "meta" is the Windows key on
Windows-friendly keyboards or the Command key on Apple keyboards.
Remember each must be prefixed with "+".</dd>
</dl>
<h2 id="common">Common keys by name</h2>
<p>Certain keys are common enough that referring to them by name is just easier
and makes the code more readable. The supported key names are:</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>`e.keyCode`</th>
</tr>
</thead>
<tbody>
<tr>
<td>enter</td>
<td>13</td>
</tr>
<tr>
<td>esc</td>
<td>27</td>
</tr>
<tr>
<td>backspace</td>
<td>8</td>
</tr>
<tr>
<td>tab</td>
<td>9</td>
</tr>
<tr>
<td>pageup</td>
<td>33</td>
</tr>
<tr>
<td>pagedown</td>
<td>34</td>
</tr>
</tbody>
</table>
<p>If any of these are found in the spec, the default <span
class="token">type</span> becomes `keydown`.</p>
<p>If you have a mind to extend this map, it's stored in
`Y.Node.DOM_EVENTS.key.eventDef.KEY_MAP`. For example, to add support for
`node.on('key', callback, 'arrowup')`, you'd do:</p>
```
```
<h2>Caveats</h2>
<ol>
<li>
You can't yet indicate that <span class="token">modifier</span>s must
<em>not</em> be in effect or key combinations must <em>only</em>
include those <span class="token">modifier</span>s.
</li>
<li>
You can't yet specify <span class="token">type</span>s or <span
class="token">modifier</span>s on a per-<span class="token">code</span>
basis.
</li>
<li>
Though you can specify keys by their common name, the event is not yet
decorated in any way with that common name, so you still have to refer
to the `keyCode` in callback code.
</li>
</ol>