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