| 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 [](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 |