OLD | NEW |
| (Empty) |
1 | |
2 <!--- | |
3 | |
4 This README is automatically generated from the comments in these files: | |
5 iron-a11y-keys.html | |
6 | |
7 Edit those files, and our readme bot will duplicate them over here! | |
8 Edit this file, and the bot will squash your changes :) | |
9 | |
10 --> | |
11 | |
12 [![Build Status](https://travis-ci.org/PolymerElements/iron-a11y-keys.svg?branch
=master)](https://travis-ci.org/PolymerElements/iron-a11y-keys) | |
13 | |
14 _[Demo and API Docs](https://elements.polymer-project.org/elements/iron-a11y-key
s)_ | |
15 | |
16 | |
17 ##<iron-a11y-keys> | |
18 | |
19 | |
20 `iron-a11y-keys` provides a cross-browser interface for processing | |
21 keyboard commands. The interface adheres to [WAI-ARIA best | |
22 practices](http://www.w3.org/TR/wai-aria-practices/#kbd_general_binding). | |
23 It uses an expressive syntax to filter key presses. | |
24 | |
25 ## Basic usage | |
26 | |
27 The sample code below is a portion of a custom element. The goal is to call | |
28 the `onEnter` method whenever the `paper-input` element is in focus and | |
29 the `Enter` key is pressed. | |
30 | |
31 <iron-a11y-keys id="a11y" target="[[target]]" keys="enter" | |
32 on-keys-pressed="onEnter"></iron-a11y-keys> | |
33 <paper-input id="input" | |
34 placeholder="Type something. Press enter. Check console." | |
35 value="{{userInput::input}}"></paper-input> | |
36 | |
37 The custom element declares an `iron-a11y-keys` element that is bound to a | |
38 property called `target`. The `target` property | |
39 needs to evaluate to the `paper-input` node. `iron-a11y-keys` registers | |
40 an event handler for the target node using Polymer's [annotated event handler | |
41 syntax](https://www.polymer-project.org/1.0/docs/devguide/events.html#annotated-
listeners). `{{userInput::input}}` sets the `userInput` property to the | |
42 user's input on each keystroke. | |
43 | |
44 The last step is to link the two elements within the custom element's | |
45 registration. | |
46 | |
47 ... | |
48 properties: { | |
49 userInput: { | |
50 type: String, | |
51 notify: true, | |
52 }, | |
53 target: { | |
54 type: Object, | |
55 value: function() { | |
56 return this.$.input; | |
57 } | |
58 }, | |
59 }, | |
60 onEnter: function() { | |
61 console.log(this.userInput); | |
62 } | |
63 ... | |
64 | |
65 ## The `keys` attribute | |
66 | |
67 The `keys` attribute expresses what combination of keys triggers the event. | |
68 | |
69 The attribute accepts a space-separated, plus-sign-concatenated | |
70 set of modifier keys and some common keyboard keys. | |
71 | |
72 The common keys are: `a-z`, `0-9` (top row and number pad), `*` (shift 8 and | |
73 number pad), `F1-F12`, `Page Up`, `Page Down`, `Left Arrow`, `Right Arrow`, | |
74 `Down Arrow`, `Up Arrow`, `Home`, `End`, `Escape`, `Space`, `Tab`, `Enter`. | |
75 | |
76 The modifier keys are: `Shift`, `Control`, `Alt`. | |
77 | |
78 All keys are expected to be lowercase and shortened. E.g. | |
79 `Left Arrow` is `left`, `Page Down` is `pagedown`, `Control` is `ctrl`, | |
80 `F1` is `f1`, `Escape` is `esc`, etc. | |
81 | |
82 ### Grammar | |
83 | |
84 Below is the [EBNF](http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Fo
rm) | |
85 Grammar of the `keys` attribute. | |
86 | |
87 modifier = "shift" | "ctrl" | "alt"; | |
88 ascii = ? /[a-z0-9]/ ? ; | |
89 fnkey = ? f1 through f12 ? ; | |
90 arrow = "up" | "down" | "left" | "right" ; | |
91 key = "tab" | "esc" | "space" | "*" | "pageup" | "pagedown" | | |
92 "home" | "end" | arrow | ascii | fnkey; | |
93 keycombo = { modifier, "+" }, key ; | |
94 keys = keycombo, { " ", keycombo } ; | |
95 | |
96 ### Example | |
97 | |
98 Given the following value for `keys`: | |
99 | |
100 `ctrl+shift+f7 up pagedown esc space alt+m` | |
101 | |
102 The event is fired if any of the following key combinations are fired: | |
103 `Control` and `Shift` and `F7` keys, `Up Arrow` key, `Page Down` key, | |
104 `Escape` key, `Space` key, `Alt` and `M` keys. | |
105 | |
106 ### WAI-ARIA Slider Example | |
107 | |
108 The following is an example of the set of keys that fulfills WAI-ARIA's | |
109 "slider" role [best | |
110 practices](http://www.w3.org/TR/wai-aria-practices/#slider): | |
111 | |
112 <iron-a11y-keys target="[[target]]" keys="left pagedown down" | |
113 on-keys-pressed="decrement"></iron-a11y-keys> | |
114 <iron-a11y-keys target=""[[target]] keys="right pageup up" | |
115 on-keys-pressed="increment"></iron-a11y-keys> | |
116 <iron-a11y-keys target="[[target]]" keys="home" | |
117 on-keys-pressed="setMin"></iron-a11y-keys> | |
118 <iron-a11y-keys target=""[[target]] keys="end" | |
119 on-keys-pressed="setMax"></iron-a11y-keys> | |
120 | |
121 The `target` properties must evaluate to a node. See the basic usage | |
122 example above. | |
123 | |
124 Each of the values for the `on-keys-pressed` attributes must evalute | |
125 to methods. The `increment` method should move the slider a set amount | |
126 toward the maximum value. `decrement` should move the slider a set amount | |
127 toward the minimum value. `setMin` should move the slider to the minimum | |
128 value. `setMax` should move the slider to the maximum value. | |
129 | |
130 | |
OLD | NEW |