1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
<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>