README.md
##<iron-a11y-keys>
iron-a11y-keys provides a cross-browser interface for processing
keyboard commands. The interface adheres to WAI-ARIA best
practices.
It uses an expressive syntax to filter key presses.
Basic usage
The sample code below is a portion of a custom element. The goal is to call
the onEnter method whenever the paper-input element is in focus and
the Enter key is pressed.
<iron-a11y-keys id="a11y" target="[[target]]" keys="enter"
on-keys-pressed="onEnter"></iron-a11y-keys>
<paper-input id="input"
placeholder="Type something. Press enter. Check console."
value="{{userInput::input}}"></paper-input>
The custom element declares an iron-a11y-keys element that is bound to a
property called target. The target property
needs to evaluate to the paper-input node. iron-a11y-keys registers
an event handler for the target node using Polymer's annotated event handler
syntax. {{userInput::input}} sets the userInput property to the
user's input on each keystroke.
The last step is to link the two elements within the custom element's registration.
...
properties: {
userInput: {
type: String,
notify: true,
},
target: {
type: Object,
value: function() {
return this.$.input;
}
},
},
onEnter: function() {
console.log(this.userInput);
}
...
The keys attribute
The keys attribute expresses what combination of keys triggers the event.
The attribute accepts a space-separated, plus-sign-concatenated set of modifier keys and some common keyboard keys.
The common keys are: a-z, 0-9 (top row and number pad), * (shift 8 and
number pad), F1-F12, Page Up, Page Down, Left Arrow, Right Arrow,
Down Arrow, Up Arrow, Home, End, Escape, Space, Tab, Enter.
The modifier keys are: Shift, Control, Alt.
All keys are expected to be lowercase and shortened. E.g.
Left Arrow is left, Page Down is pagedown, Control is ctrl,
F1 is f1, Escape is esc, etc.
Grammar
Below is the EBNF
Grammar of the keys attribute.
modifier = "shift" | "ctrl" | "alt";
ascii = ? /[a-z0-9]/ ? ;
fnkey = ? f1 through f12 ? ;
arrow = "up" | "down" | "left" | "right" ;
key = "tab" | "esc" | "space" | "*" | "pageup" | "pagedown" |
"home" | "end" | arrow | ascii | fnkey;
keycombo = { modifier, "+" }, key ;
keys = keycombo, { " ", keycombo } ;
Example
Given the following value for keys:
ctrl+shift+f7 up pagedown esc space alt+m
The event is fired if any of the following key combinations are fired:
Control and Shift and F7 keys, Up Arrow key, Page Down key,
Escape key, Space key, Alt and M keys.
WAI-ARIA Slider Example
The following is an example of the set of keys that fulfills WAI-ARIA's "slider" role best practices:
<iron-a11y-keys target="[[target]]" keys="left pagedown down"
on-keys-pressed="decrement"></iron-a11y-keys>
<iron-a11y-keys target=""[[target]] keys="right pageup up"
on-keys-pressed="increment"></iron-a11y-keys>
<iron-a11y-keys target="[[target]]" keys="home"
on-keys-pressed="setMin"></iron-a11y-keys>
<iron-a11y-keys target=""[[target]] keys="end"
on-keys-pressed="setMax"></iron-a11y-keys>
The target properties must evaluate to a node. See the basic usage
example above.
Each of the values for the on-keys-pressed attributes must evalute
to methods. The increment method should move the slider a set amount
toward the maximum value. decrement should move the slider a set amount
toward the minimum value. setMin should move the slider to the minimum
value. setMax should move the slider to the maximum value.