key-bindings.jade

include ../_util-fns

a( id='top' )

:marked
  With Angular's powerful event-binding syntax, we can bind to any native DOM 
  (Document Object Model) event by wrapping the **event type** in parentheses. 
  For example, if we wanted to bind to the `focus` or `click` event, we would 
  add an element binding for `(focus)` or `(click)`, respectively. The same can
  be done for `(keydown)`, `(keyup)`, and `(keypress)` events. However, with 
  key events, we generally want to do more than _just_ bind to the event 
  — we want to respond to specific key combinations. Luckily, Angular's
  event-binding system can help us accomplish this as well.

:marked
  When defining a `keydown` or `keyup` event-binding, we can provide additional
  settings that determine which keyboard events will cause our event handler to
  be invoked. In the event-binding syntax, these settings are provided as a 
  dot-delimited suffix to the core event type.

:marked
  So, for example, if we wanted to respond specifically to the `Enter` key in a
  `keydown` event, we would add the following element binding: 
  `(keydown.Enter)`. And, if we wanted to respond to the increasingly-popular 
  `Command+Enter` key combination, we would add the following element binding: 
  `(keydown.Meta.Enter)`. 

:marked
  Any alpha-numeric character can be used in the event-binding as long as it 
  doesn't break the HTML parser (Caution: `>` will break the parser). Special
  characters like the period and the space are made available via `Dot` and 
  `Space`, respectively. In addition, [many control characters](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key#Key_values)
  like `ArrowLeft` and `ArrowRight` can be used as well.

.l-sub-section
  :marked
    Commonly-used control characters include:

    * `Enter`
    * `Escape`
    * `ArrowLeft`, `ArrowUp`, `ArrowRight`, `ArrowDown`
    * `Tab`

:marked
  The following modifier modifiers can be used (either on their own or in 
  combination with other modifiers and characters):

:marked
  * `Alt`
  * `Control`
  * `Meta` (`Command` key on the Mac, `Start` key on Windows)
  * `Shift`

:marked
  None of the event-binding settings are case-sensitive. `Tab` is the same as
  `tab` and `A` is the same as `a`. However, the event settings have to match 
  on all event conditions. This means that our event-bindings have to account 
  for modifier keys if modifier keys are required in order to render the target
  character. For example:

:marked
  * `keydown.a` codes for `a`.
  * `keydown.Shift.a` codes for `A` _(if the Shift key was depressed)_.
  * `keydown.Shift.?` codes for the question mark.

:marked
  In the following code, we're attaching multiple key combination events to a
  single `input` and then logging the key values to a list:

:marked
  **See the [live example](/resources/live-examples/cb-key-bindings/ts/plnkr.html)**.

+makeExample( 'cb-key-bindings/ts/app/app.component.ts', 'component', 'app/app.component.ts' )(format='.')

:marked
  When we run this demo and try some of the key combination bindings, we get
  the following output:

figure.image-display
   img(src='/resources/images/cookbooks/key-bindings/key-bindings.gif' alt='Key Bindings')

:marked
  When we use these key bindings, Angular doesn't alter the behavior of the 
  keys in any way. As such, if we want to override the default behavior 
  (such as preventing the `Tab` key from removing focus from an input), we 
  have to call the `.preventDefault()` method on the associated event object.

:marked
  At the time of this writing, these special key combination settings are only 
  supported at the element level and only for the `keydown` and `keyup` events.
  Meaning, these cannot be used with the global `window:` or `document:` 
  targets; and, they cannot be used with the `keypress` event.

:marked
  [Back to top](#top)