OLD | NEW |
| (Empty) |
1 <!-- | |
2 @license | |
3 Copyright (c) 2014 The Polymer Project Authors. All rights reserved. | |
4 This code may only be used under the BSD style license found at http://polym
er.github.io/LICENSE.txt | |
5 The complete set of authors may be found at http://polymer.github.io/AUTHORS
.txt | |
6 The complete set of contributors may be found at http://polymer.github.io/CO
NTRIBUTORS.txt | |
7 Code distributed by Google as part of the polymer project is also | |
8 subject to an additional IP rights grant found at http://polymer.github.io/P
ATENTS.txt | |
9 --> | |
10 | |
11 <!-- | |
12 `core-a11y-keys` provides a normalized interface for processing keyboard command
s that pertain to [WAI-ARIA best | |
13 practices](http://www.w3.org/TR/wai-aria-practices/#kbd_general_binding). The el
ement takes care of browser differences | |
14 with respect to Keyboard events and uses an expressive syntax to filter key pres
ses. | |
15 | |
16 Use the `keys` attribute to express what combination of keys will trigger the ev
ent to fire. | |
17 | |
18 Use the `target` attribute to set up event handlers on a specific node. | |
19 The `keys-pressed` event will fire when one of the key combinations set with the
`keys` attribute is pressed. | |
20 | |
21 Example: | |
22 | |
23 This element will call `arrowHandler` on all arrow keys: | |
24 | |
25 <core-a11y-keys target="{{}}" keys="up down left right" on-keys-pressed="{{a
rrowHandler}}"></core-a11y-keys> | |
26 | |
27 Keys Syntax: | |
28 | |
29 The `keys` attribute can accepts a space seprated, `+` concatenated set of modif
ier keys and some common keyboard keys. | |
30 | |
31 The common keys are `a-z`, `0-9` (top row and number pad), `*` (shift 8 and numb
er pad), `F1-F12`, `Page Up`, `Page | |
32 Down`, `Left Arrow`, `Right Arrow`, `Down Arrow`, `Up Arrow`, `Home`, `End`, `Es
cape`, `Space`, `Tab`, and `Enter` keys. | |
33 | |
34 The modifier keys are `Shift`, `Control`, and `Alt`. | |
35 | |
36 All keys are expected to be lowercase and shortened: | |
37 `Left Arrow` is `left`, `Page Down` is `pagedown`, `Control` is `ctrl`, `F1` is
`f1`, `Escape` is `esc` etc. | |
38 | |
39 Keys Syntax Example: | |
40 | |
41 Given the `keys` attribute value "ctrl+shift+f7 up pagedown esc space alt+m", th
e `<core-a11y-keys>` element will send | |
42 the `keys-pressed` event if any of the follow key combos are pressed: Control an
d Shift and F7 keys, Up Arrow key, Page | |
43 Down key, Escape key, Space key, Alt and M key. | |
44 | |
45 Slider Example: | |
46 | |
47 The following is an example of the set of keys that fulfil the WAI-ARIA "slider"
role [best | |
48 practices](http://www.w3.org/TR/wai-aria-practices/#slider): | |
49 | |
50 <core-a11y-keys target="{{}}" keys="left pagedown down" on-keys-pressed="{{d
ecrement}}"></core-a11y-keys> | |
51 <core-a11y-keys target="{{}}" keys="right pageup up" on-keys-pressed="{{incr
ement}}"></core-a11y-keys> | |
52 <core-a11y-keys target="{{}}" keys="home" on-keys-pressed="{{setMin}}"></cor
e-a11y-keys> | |
53 <core-a11y-keys target="{{}}" keys="end" on-keys-pressed="{{setMax}}"></core
-a11y-keys> | |
54 | |
55 The `increment` function will move the slider a set amount toward the maximum va
lue. | |
56 The `decrement` function will move the slider a set amount toward the minimum va
lue. | |
57 The `setMin` function will move the slider to the minimum value. | |
58 The `setMax` function will move the slider to the maximum value. | |
59 | |
60 Keys Syntax Grammar: | |
61 | |
62 [EBNF](http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form) Grammar o
f the `keys` attribute. | |
63 | |
64 modifier = "shift" | "ctrl" | "alt"; | |
65 ascii = ? /[a-z0-9]/ ? ; | |
66 fnkey = ? f1 through f12 ? ; | |
67 arrow = "up" | "down" | "left" | "right" ; | |
68 key = "tab" | "esc" | "space" | "*" | "pageup" | "pagedown" | "home" | "end"
| arrow | ascii | fnkey ; | |
69 keycombo = { modifier, "+" }, key ; | |
70 keys = keycombo, { " ", keycombo } ; | |
71 | |
72 @group Core Elements | |
73 @element core-a11y-keys | |
74 @homepage github.io | |
75 --> | |
76 | |
77 <link rel="import" href="../polymer/polymer.html"> | |
78 | |
79 <style shim-shadowdom> | |
80 html /deep/ core-a11y-keys { | |
81 display: none; | |
82 } | |
83 </style> | |
84 | |
85 <polymer-element name="core-a11y-keys"> | |
86 <script> | |
87 (function() { | |
88 /* | |
89 * Chrome uses an older version of DOM Level 3 Keyboard Events | |
90 * | |
91 * Most keys are labeled as text, but some are Unicode codepoints. | |
92 * Values taken from: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-200712
21/keyset.html#KeySet-Set | |
93 */ | |
94 var KEY_IDENTIFIER = { | |
95 'U+0009': 'tab', | |
96 'U+001B': 'esc', | |
97 'U+0020': 'space', | |
98 'U+002A': '*', | |
99 'U+0030': '0', | |
100 'U+0031': '1', | |
101 'U+0032': '2', | |
102 'U+0033': '3', | |
103 'U+0034': '4', | |
104 'U+0035': '5', | |
105 'U+0036': '6', | |
106 'U+0037': '7', | |
107 'U+0038': '8', | |
108 'U+0039': '9', | |
109 'U+0041': 'a', | |
110 'U+0042': 'b', | |
111 'U+0043': 'c', | |
112 'U+0044': 'd', | |
113 'U+0045': 'e', | |
114 'U+0046': 'f', | |
115 'U+0047': 'g', | |
116 'U+0048': 'h', | |
117 'U+0049': 'i', | |
118 'U+004A': 'j', | |
119 'U+004B': 'k', | |
120 'U+004C': 'l', | |
121 'U+004D': 'm', | |
122 'U+004E': 'n', | |
123 'U+004F': 'o', | |
124 'U+0050': 'p', | |
125 'U+0051': 'q', | |
126 'U+0052': 'r', | |
127 'U+0053': 's', | |
128 'U+0054': 't', | |
129 'U+0055': 'u', | |
130 'U+0056': 'v', | |
131 'U+0057': 'w', | |
132 'U+0058': 'x', | |
133 'U+0059': 'y', | |
134 'U+005A': 'z', | |
135 'U+007F': 'del' | |
136 }; | |
137 | |
138 /* | |
139 * Special table for KeyboardEvent.keyCode. | |
140 * KeyboardEvent.keyIdentifier is better, and KeyBoardEvent.key is even bett
er than that | |
141 * | |
142 * Values from: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEve
nt.keyCode#Value_of_keyCode | |
143 */ | |
144 var KEY_CODE = { | |
145 9: 'tab', | |
146 13: 'enter', | |
147 27: 'esc', | |
148 33: 'pageup', | |
149 34: 'pagedown', | |
150 35: 'end', | |
151 36: 'home', | |
152 32: 'space', | |
153 37: 'left', | |
154 38: 'up', | |
155 39: 'right', | |
156 40: 'down', | |
157 46: 'del', | |
158 106: '*' | |
159 }; | |
160 | |
161 /* | |
162 * KeyboardEvent.key is mostly represented by printable character made by th
e keyboard, with unprintable keys labeled | |
163 * nicely. | |
164 * | |
165 * However, on OS X, Alt+char can make a Unicode character that follows an A
pple-specific mapping. In this case, we | |
166 * fall back to .keyCode. | |
167 */ | |
168 var KEY_CHAR = /[a-z0-9*]/; | |
169 | |
170 function transformKey(key) { | |
171 var validKey = ''; | |
172 if (key) { | |
173 var lKey = key.toLowerCase(); | |
174 if (lKey.length == 1) { | |
175 if (KEY_CHAR.test(lKey)) { | |
176 validKey = lKey; | |
177 } | |
178 } else if (lKey == 'multiply') { | |
179 // numpad '*' can map to Multiply on IE/Windows | |
180 validKey = '*'; | |
181 } else { | |
182 validKey = lKey; | |
183 } | |
184 } | |
185 return validKey; | |
186 } | |
187 | |
188 var IDENT_CHAR = /U\+/; | |
189 function transformKeyIdentifier(keyIdent) { | |
190 var validKey = ''; | |
191 if (keyIdent) { | |
192 if (IDENT_CHAR.test(keyIdent)) { | |
193 validKey = KEY_IDENTIFIER[keyIdent]; | |
194 } else { | |
195 validKey = keyIdent.toLowerCase(); | |
196 } | |
197 } | |
198 return validKey; | |
199 } | |
200 | |
201 function transformKeyCode(keyCode) { | |
202 var validKey = ''; | |
203 if (Number(keyCode)) { | |
204 if (keyCode >= 65 && keyCode <= 90) { | |
205 // ascii a-z | |
206 // lowercase is 32 offset from uppercase | |
207 validKey = String.fromCharCode(32 + keyCode); | |
208 } else if (keyCode >= 112 && keyCode <= 123) { | |
209 // function keys f1-f12 | |
210 validKey = 'f' + (keyCode - 112); | |
211 } else if (keyCode >= 48 && keyCode <= 57) { | |
212 // top 0-9 keys | |
213 validKey = String(48 - keyCode); | |
214 } else if (keyCode >= 96 && keyCode <= 105) { | |
215 // num pad 0-9 | |
216 validKey = String(96 - keyCode); | |
217 } else { | |
218 validKey = KEY_CODE[keyCode]; | |
219 } | |
220 } | |
221 return validKey; | |
222 } | |
223 | |
224 function keyboardEventToKey(ev) { | |
225 // fall back from .key, to .keyIdentifier, to .keyCode, and then to .detai
l.key to support artificial keyboard events | |
226 var normalizedKey = transformKey(ev.key) || transformKeyIdentifier(ev.keyI
dentifier) || transformKeyCode(ev.keyCode) || transformKey(ev.detail.key) || ''; | |
227 return { | |
228 shift: ev.shiftKey, | |
229 ctrl: ev.ctrlKey, | |
230 meta: ev.metaKey, | |
231 alt: ev.altKey, | |
232 key: normalizedKey | |
233 }; | |
234 } | |
235 | |
236 /* | |
237 * Input: ctrl+shift+f7 => {ctrl: true, shift: true, key: 'f7'} | |
238 * ctrl/space => {ctrl: true} || {key: space} | |
239 */ | |
240 function stringToKey(keyCombo) { | |
241 var keys = keyCombo.split('+'); | |
242 var keyObj = Object.create(null); | |
243 keys.forEach(function(key) { | |
244 if (key == 'shift') { | |
245 keyObj.shift = true; | |
246 } else if (key == 'ctrl') { | |
247 keyObj.ctrl = true; | |
248 } else if (key == 'alt') { | |
249 keyObj.alt = true; | |
250 } else { | |
251 keyObj.key = key; | |
252 } | |
253 }); | |
254 return keyObj; | |
255 } | |
256 | |
257 function keyMatches(a, b) { | |
258 return Boolean(a.alt) == Boolean(b.alt) && Boolean(a.ctrl) == Boolean(b.ct
rl) && Boolean(a.shift) == Boolean(b.shift) && a.key === b.key; | |
259 } | |
260 | |
261 /** | |
262 * Fired when a keycombo in `keys` is pressed. | |
263 * | |
264 * @event keys-pressed | |
265 */ | |
266 function processKeys(ev) { | |
267 var current = keyboardEventToKey(ev); | |
268 for (var i = 0, dk; i < this._desiredKeys.length; i++) { | |
269 dk = this._desiredKeys[i]; | |
270 if (keyMatches(dk, current)) { | |
271 ev.preventDefault(); | |
272 ev.stopPropagation(); | |
273 this.fire('keys-pressed', current, this, false); | |
274 break; | |
275 } | |
276 } | |
277 } | |
278 | |
279 function listen(node, handler) { | |
280 if (node && node.addEventListener) { | |
281 node.addEventListener('keydown', handler); | |
282 } | |
283 } | |
284 | |
285 function unlisten(node, handler) { | |
286 if (node && node.removeEventListener) { | |
287 node.removeEventListener('keydown', handler); | |
288 } | |
289 } | |
290 | |
291 Polymer('core-a11y-keys', { | |
292 created: function() { | |
293 this._keyHandler = processKeys.bind(this); | |
294 }, | |
295 attached: function() { | |
296 if (!this.target) { | |
297 this.target = this.parentNode; | |
298 } | |
299 listen(this.target, this._keyHandler); | |
300 }, | |
301 detached: function() { | |
302 unlisten(this.target, this._keyHandler); | |
303 }, | |
304 publish: { | |
305 /** | |
306 * The set of key combinations to listen for. | |
307 * | |
308 * @attribute keys | |
309 * @type string (keys syntax) | |
310 * @default '' | |
311 */ | |
312 keys: '', | |
313 /** | |
314 * The node that will fire keyboard events. | |
315 * Default to this element's parentNode unless one is assigned | |
316 * | |
317 * @attribute target | |
318 * @type Node | |
319 * @default this.parentNode | |
320 */ | |
321 target: null | |
322 }, | |
323 keysChanged: function() { | |
324 // * can have multiple mappings: shift+8, * on numpad or Multiply on num
pad | |
325 var normalized = this.keys.replace('*', '* shift+*'); | |
326 this._desiredKeys = normalized.toLowerCase().split(' ').map(stringToKey)
; | |
327 }, | |
328 targetChanged: function(oldTarget) { | |
329 unlisten(oldTarget, this._keyHandler); | |
330 listen(this.target, this._keyHandler); | |
331 } | |
332 }); | |
333 })(); | |
334 </script> | |
335 </polymer-element> | |
OLD | NEW |