Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
briarsweetbriar committed Aug 24, 2016
1 parent 26d9c05 commit 1def7ee
Show file tree
Hide file tree
Showing 5 changed files with 24 additions and 21 deletions.
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
"ember-cli": "^2.6.2",
"ember-cli-app-version": "^1.0.0",
"ember-cli-dependency-checker": "^1.2.0",
"ember-cli-github-pages": "0.1.2",
"ember-cli-htmlbars": "^1.0.3",
"ember-cli-htmlbars-inline-precompile": "^0.3.1",
"ember-cli-inject-live-reload": "^1.4.0",
Expand Down
4 changes: 2 additions & 2 deletions tests/dummy/app/components/key-down-counter.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,11 @@ export default Component.extend(EKMixin, {
this.incrementProperty('counter');
}),

decrementCounter10: on(keyDown('ctrl+ArrowLeft'), function() {
decrementCounter10: on(keyDown('shift+ArrowLeft'), function() {
this.decrementProperty('counter', 10);
}),

incrementCounter10: on(keyDown('ctrl+ArrowRight'), function() {
incrementCounter10: on(keyDown('shift+ArrowRight'), function() {
this.incrementProperty('counter', 10);
}),

Expand Down
2 changes: 1 addition & 1 deletion tests/dummy/app/templates/priority.hbs
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Controls:
* `LeftArrow`: decrement counter by 1
* `RightArrow`: increment counter by 1
* `ctrl`+ArrowKey: increment/decrement x10
* `shift`+ArrowKey: increment/decrement x10
* `ctrl+shift`+ArrowKey: increment/decrement x100
* `r`: resets counter to 0
"}}
Expand Down
36 changes: 18 additions & 18 deletions tests/dummy/app/templates/usage.hbs
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{{formatMarkdown "
## Usage
First, add `EKMixin` to your component:
First, add `EKMixin` to a component or route:
```js
import Ember from 'ember';
Expand All @@ -12,7 +12,7 @@ export default Ember.Component.extend(EKMixin, {
});
```
Now your 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:
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() {
Expand All @@ -26,7 +26,7 @@ Or simply activate the component from your template:
{{my-component keyboardActivated=true}}
```
Once it's activated, your component will start listening for key events. Let's say you want your component to respond to the key `s` as well as `ctrl+shift+a`. You could do so with:
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';
Expand All @@ -42,6 +42,20 @@ anotherFunction: Ember.on(keyDown('ctrl+shift+KeyA'), function() {
})
```
### 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:
Expand Down Expand Up @@ -78,7 +92,7 @@ Note that if you want `preventDefault` to prevent `window` level events, you'll
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 { getKey } from 'ember-keyboard';
import { getCode } from 'ember-keyboard';
. . . .
Expand Down Expand Up @@ -120,20 +134,6 @@ triggerOnAlphaNumeric: Ember.on(keyUp(), function(event) {
})
```
### `cmd` keycode
It is very common for macOS users to expect to use key combinations such as
Command(⌘)+Key vs. Ctrl+Key. Therefore, we provide a special key definiton,
`cmd` to allow handling 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.
### `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`.
Expand Down
2 changes: 2 additions & 0 deletions tests/dummy/config/environment.js
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ module.exports = function(environment) {
}

if (environment === 'production') {
ENV.locationType = 'hash';
ENV.rootURL = '/ember-keyboard/';

}

Expand Down

0 comments on commit 1def7ee

Please sign in to comment.