third_party/polymer/components-chromium/core-a11y-keys/core-a11y-keys.html

   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://polymer.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/CONTRIBUTORS.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/PATENTS.txt
   9 --><!--
  10 `core-a11y-keys` provides a normalized interface for processing keyboard commands that pertain to [WAI-ARIA best
  11 practices](http://www.w3.org/TR/wai-aria-practices/#kbd_general_binding). The element takes care of browser differences
  12 with respect to Keyboard events and uses an expressive syntax to filter key presses.
  13
  14 Use the `keys` attribute to express what combination of keys will trigger the event to fire.
  15
  16 Use the `target` attribute to set up event handlers on a specific node.
  17 The `keys-pressed` event will fire when one of the key combinations set with the `keys` attribute is pressed.
  18
  19 Example:
  20
  21 This element will call `arrowHandler` on all arrow keys:
  22
  23     <core-a11y-keys target="{{}}" keys="up down left right" on-keys-pressed="{{arrowHandler}}"></core-a11y-keys>
  24
  25 Keys Syntax:
  26
  27 The `keys` attribute can accepts a space seprated, `+` concatenated set of modifier keys and some common keyboard keys.
  28
  29 The common keys are `a-z`, `0-9` (top row and number pad), `*` (shift 8 and number pad), `F1-F12`, `Page Up`, `Page
  30 Down`, `Left Arrow`, `Right Arrow`, `Down Arrow`, `Up Arrow`, `Home`, `End`, `Escape`, `Space`, `Tab`, and `Enter` keys.
  31
  32 The modifier keys are `Shift`, `Control`, and `Alt`.
  33
  34 All keys are expected to be lowercase and shortened:
  35 `Left Arrow` is `left`, `Page Down` is `pagedown`, `Control` is `ctrl`, `F1` is `f1`, `Escape` is `esc` etc.
  36
  37 Keys Syntax Example:
  38
  39 Given the `keys` attribute value "ctrl+shift+f7 up pagedown esc space alt+m", the `<core-a11y-keys>` element will send
  40 the `keys-pressed` event if any of the follow key combos are pressed: Control and Shift and F7 keys, Up Arrow key, Page
  41 Down key, Escape key, Space key, Alt and M key.
  42
  43 Slider Example:
  44
  45 The following is an example of the set of keys that fulfil the WAI-ARIA "slider" role [best
  46 practices](http://www.w3.org/TR/wai-aria-practices/#slider):
  47
  48     <core-a11y-keys target="{{}}" keys="left pagedown down" on-keys-pressed="{{decrement}}"></core-a11y-keys>
  49     <core-a11y-keys target="{{}}" keys="right pageup up" on-keys-pressed="{{increment}}"></core-a11y-keys>
  50     <core-a11y-keys target="{{}}" keys="home" on-keys-pressed="{{setMin}}"></core-a11y-keys>
  51     <core-a11y-keys target="{{}}" keys="end" on-keys-pressed="{{setMax}}"></core-a11y-keys>
  52
  53 The `increment` function will move the slider a set amount toward the maximum value.
  54 The `decrement` function will move the slider a set amount toward the minimum value.
  55 The `setMin` function will move the slider to the minimum value.
  56 The `setMax` function will move the slider to the maximum value.
  57
  58 Keys Syntax Grammar:
  59
  60 [EBNF](http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form) Grammar of the `keys` attribute.
  61
  62     modifier = "shift" | "ctrl" | "alt";
  63     ascii = ? /[a-z0-9]/ ? ;
  64     fnkey = ? f1 through f12 ? ;
  65     arrow = "up" | "down" | "left" | "right" ;
  66     key = "tab" | "esc" | "space" | "*" | "pageup" | "pagedown" | "home" | "end" | arrow | ascii | fnkey ;
  67     keycombo = { modifier, "+" }, key ;
  68     keys = keycombo, { " ", keycombo } ;
  69
  70 @group Core Elements
  71 @element core-a11y-keys
  72 @homepage github.io
  73 --><html><head><link rel="import" href="../polymer/polymer.html">
  74
  75 <style shim-shadowdom="">
  76   html /deep/ core-a11y-keys {
  77     display: none;
  78   }
  79 </style>
  80
  81 </head><body><polymer-element name="core-a11y-keys" assetpath="">
  82
  83 </polymer-element>
  84 <script src="core-a11y-keys-extracted.js"></script></body></html>