<commit_before>{{formatMarkdown "
## Usage

First, add `EKMixin` to a component or route:

```js
import Ember from 'ember';
import { EKMixin } from 'ember-keyboard';

export default Ember.Component.extend(EKMixin, {
  . . . .
});
```

Now this component observes several new properties that'll help it determine when and if it should respond to key events. These properties are outlined in greater detail below, but to simply get things started, you'll need to set `keyboardActivated` to true:

```js
  activateKeyboard: Ember.on('init', function() {
    this.set('keyboardActivated', true);
  })
```

Or simply activate the component from your template:

```hbs
{{my-component keyboardActivated=true}}
```

Once it's activated, this component will start listening for key events. Let's say you want this component to respond to the key `s` as well as `ctrl+shift+a`. You could do so with:

```js
import { keyUp, keyDown } from 'ember-keyboard';

. . . .

aFunction: Ember.on(keyUp('KeyS'), function() {
  console.log('`KeyS` was pressed');
}),

anotherFunction: Ember.on(keyDown('ctrl+shift+KeyA'), function() {
  console.log('`ctrl+shift+KeyA` is being held');
})
```

### Modifier Keys

As mentioned above, you can augment your key bindings with modifier keys, including `ctrl`, `shift`, `alt`, and `meta`. In addition, `ember-keyboard` supports a special key definition called `cmd`. It is very common for macOS users to expect to use key combinations such as Command(⌘)+Key, where a PC or Linux user would use Ctrl+Key. `cmd` handles this behavior. For instance this defintion:

```js
triggerSubmit: Ember.on(keyDown('Enter+cmd'), function() {
  this.submit();
});
```

will trigger on Command(⌘)+Enter on macOS or Ctrl+Enter on all other platforms.

Note that `ctrl` should be used with caution, as MacOSs will swollow some `ctrl` events before `ember-keyboard` can observe them.

### `keyUp`, `keyDown`, and `keyPress`

By default, `ember-keyboard` listens to `keydown`, `keyup`, and `keypress` events, and has corresponding functions:

```js
import { keyUp, keyDown, keyPress } from 'ember-keyboard';
```

If you want `ember-keyboard` to listen to fewer events, then you can specify them in your `config/environment.js` file like so:

```js
ENV.emberKeyboard = {
  listeners: ['keyUp', 'keyDown'] // use only `keyUp` and `keyDown`
}
```

Note that `keydown` events fire repeatedly while the key is pressed, while `keyup` events fire only once, after the key has been released.

### `event`

When `ember-keyboard` triggers an event, it passes in the `event` object as its first argument:

```js
saveDocument: Ember.on(keyDown('ctrl+KeyS'), function(event) {
  this.performSave();
  event.preventDefault();
})
```

Note that if you want `preventDefault` to prevent `window` level events, you'll need to use `keyDown`, as the default event will fire before `keyUp`.

### `getCode`

Did you know that 65 was the keycode for 'KeyA'? Or that 37 was the keycode for the right arrow? If you don't want to litter your code with keycode references, you can use `getCode`, which `ember-keyboard` uses internally:

```js
import { getCode } from 'ember-keyboard';

. . . .

keyMapper: Ember.on(keyDown('KeyA'), keyDown('KeyB'), keyDown('KeyC'), function(event) {
  const key = getCode(event);
  switch (key) {
    match 'KeyA': console.log('It\'s an a!'); break;
    . . . .
  }
})
```

### `getKeyCode`

On the other end of things, if you need to convert a code into a keycode, you can use `getKeyCode`. This is particularly useful when testing:

```js
import { getKeyCode } from 'ember-keyboard';

. . . .

keyEvent(document, 'keydown', getKeyCode('KeyA'));
keyEvent(document, 'keydown', getKeyCode('ArrowRight'));
keyEvent(document, 'keydown', getKeyCode('Backspace'));
keyEvent(document, 'keydown', getKeyCode('Space'));
```

Just pass in an `event`, and it'll return a human readable key. Look [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) for a full mapping.

### Key Indifference

If you want an event to fire for every keypress, then simply don't provide a keystring to `keyUp` or `keyDown`. This can be a handy way to trigger events for large ranges of keys, such as on any alphanumeric keypress. For instance:

```js
triggerOnAlphaNumeric: Ember.on(keyUp(), function(event) {
  if (/^Key\w(?!.)/.test(getCode(event))) {
    this.startEditing();
  }
})
```

### `Ember.TextField` && `Ember.TextArea`

To prevent `ember-keyboard` from responding to key strokes while an input/textarea is focused, we've reopened `Ember.TextField` and `Ember.TextArea` and applied the `EKOnInsertMixin` and `EKFirstResponderOnFocusMixin`. This ensures that whenever an input is focused, other key responders will not fire. If you want to have responders associated with an input or textarea (such as a rich text editor with `keyUp('ctrl+i')` bindings), you need to extend these components from `Ember.TextField` or `Ember.TextArea` rather than `Ember.component`.

This applies to `input` and `textarea` helpers:

```hbs
{{input}}
{{textarea}}
```
"}}
<commit_msg>update docs to list unpropogated key events<commit_after>{{formatMarkdown "
## Usage

First, add `EKMixin` to a component or route:

```js
import Ember from 'ember';
import { EKMixin } from 'ember-keyboard';

export default Ember.Component.extend(EKMixin, {
  . . . .
});
```

Now this component observes several new properties that'll help it determine when and if it should respond to key events. These properties are outlined in greater detail below, but to simply get things started, you'll need to set `keyboardActivated` to true:

```js
  activateKeyboard: Ember.on('init', function() {
    this.set('keyboardActivated', true);
  })
```

Or simply activate the component from your template:

```hbs
{{my-component keyboardActivated=true}}
```

Once it's activated, this component will start listening for key events. Let's say you want this component to respond to the key `s` as well as `ctrl+shift+a`. You could do so with:

```js
import { keyUp, keyDown } from 'ember-keyboard';

. . . .

aFunction: Ember.on(keyUp('KeyS'), function() {
  console.log('`KeyS` was pressed');
}),

anotherFunction: Ember.on(keyDown('ctrl+shift+KeyA'), function() {
  console.log('`ctrl+shift+KeyA` is being held');
})
```

### Modifier Keys

As mentioned above, you can augment your key bindings with modifier keys, including `ctrl`, `shift`, `alt`, and `meta`. In addition, `ember-keyboard` supports a special key definition called `cmd`. It is very common for macOS users to expect to use key combinations such as Command(⌘)+Key, where a PC or Linux user would use Ctrl+Key. `cmd` handles this behavior. For instance this defintion:

```js
triggerSubmit: Ember.on(keyDown('Enter+cmd'), function() {
  this.submit();
});
```

will trigger on Command(⌘)+Enter on macOS or Ctrl+Enter on all other platforms.

Note that `ctrl` should be used with caution, as MacOSs will swollow some `ctrl` events before `ember-keyboard` can observe them.

### `keyUp`, `keyDown`, and `keyPress`

By default, `ember-keyboard` listens to `keydown`, `keyup`, and `keypress` events, and has corresponding functions:

```js
import { keyUp, keyDown, keyPress } from 'ember-keyboard';
```

If you want `ember-keyboard` to listen to fewer events, then you can specify them in your `config/environment.js` file like so:

```js
ENV.emberKeyboard = {
  listeners: ['keyUp', 'keyDown'] // use only `keyUp` and `keyDown`
}
```

Note that `keydown` events fire repeatedly while the key is pressed, while `keyup` events fire only once, after the key has been released.

### `event`

When `ember-keyboard` triggers an event, it passes in the `event` object as its first argument:

```js
saveDocument: Ember.on(keyDown('ctrl+KeyS'), function(event) {
  this.performSave();
  event.preventDefault();
})
```

Note that if you want `preventDefault` to prevent `window` level events, you'll need to use `keyDown`, as the default event will fire before `keyUp`.

### `getCode`

Did you know that 65 was the keycode for 'KeyA'? Or that 37 was the keycode for the right arrow? If you don't want to litter your code with keycode references, you can use `getCode`, which `ember-keyboard` uses internally:

```js
import { getCode } from 'ember-keyboard';

. . . .

keyMapper: Ember.on(keyDown('KeyA'), keyDown('KeyB'), keyDown('KeyC'), function(event) {
  const key = getCode(event);
  switch (key) {
    match 'KeyA': console.log('It\'s an a!'); break;
    . . . .
  }
})
```

### `getKeyCode`

On the other end of things, if you need to convert a code into a keycode, you can use `getKeyCode`. This is particularly useful when testing:

```js
import { getKeyCode } from 'ember-keyboard';

. . . .

keyEvent(document, 'keydown', getKeyCode('KeyA'));
keyEvent(document, 'keydown', getKeyCode('ArrowRight'));
keyEvent(document, 'keydown', getKeyCode('Backspace'));
keyEvent(document, 'keydown', getKeyCode('Space'));
```

Just pass in an `event`, and it'll return a human readable key. Look [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) for a full mapping.

### Key Indifference

If you want an event to fire for every keypress, then simply don't provide a keystring to `keyUp` or `keyDown`. This can be a handy way to trigger events for large ranges of keys, such as on any alphanumeric keypress. For instance:

```js
triggerOnAlphaNumeric: Ember.on(keyUp(), function(event) {
  if (/^Key\w(?!.)/.test(getCode(event))) {
    this.startEditing();
  }
})
```

### `Ember.TextField` && `Ember.TextArea`

To prevent `ember-keyboard` from responding to key strokes while an input/textarea is focused, we've reopened `Ember.TextField` and `Ember.TextArea` and applied the `EKOnInsertMixin` and `EKFirstResponderOnFocusMixin`. This ensures that whenever an input is focused, other key responders will not fire. If you want to have responders associated with an input or textarea (such as a rich text editor with `keyUp('ctrl+i')` bindings), you need to extend these components from `Ember.TextField` or `Ember.TextArea` rather than `Ember.component`.

This applies to `input` and `textarea` helpers:

```hbs
{{input}}
{{textarea}}
```

### Unpropogated Key Events

Some key events get swollowed by the browser well before they reach `ember-keyboard`. Here is a growing (aka incomplete) list of such events:

* Enter: keyUp (keyDown works)
"}}

{'fraction_non_alphanumeric': 0.1293551491819057, 'fraction_numerical': 0.0007699711260827719, 'mean_word_length': 4.766370699223086, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6628514', 'n_tokens_mistral': 3246, 'n_tokens_neox': 3139, 'n_words': 1262}