Home

Awesome

Ember Keyboard Service

npm version Build Status Ember Observer Score Code Climate

The keyboard service helps you let your app respond to keyboard input.

You can either do this declaratively with a DSL mixin, or use the lower level service, that gives you more control.

NO LONGER BEING MAINTAINED

I'd recommend using ember-keyboard

Installation

ember install ember-keyboard-service

Specifying keyboard combos

You can specify normal key characters by using the literal value. Examples: 'a', '$', ' '.

You can add modifier keys using 'ctrl', 'alt', 'shift' or 'meta'. 'cmd' is an alias for 'meta', 'option' is an alias for 'alt'.

An example of a combo with modifiers: 'ctrl+v'.

There is also a special modifier: 'nctrl', on OS X this modifier is an alias for 'cmd', on any other system it is just 'ctrl'.

DSL Mixin Usage

Use it do declare shortcuts in a simple manner.

import KeyboardMixin from 'ember-keyboard-service/mixins/keyboard';

Ember.Object.extend(KeyboardMixin, {
  keyboardHandlers: [
    { key: 'ctrl+x', handler: 'cut'   }
    { key: 'ctrl+c', handler: 'copy'  }
    { key: 'ctrl+v', handler: 'paste' }
  ],

  cut() {
    console.log("every day i'm cuttin");
  },

  copy() {
    console.log("every day i'm copyin");
  },

  paste() {
    console.log("every day i'm pastin");
  }
});

You can also specify static arguments for keyboard handlers:

Ember.Object.extend(KeyboardMixin, {
  keyboardHandlers: [
    { key: 'ctrl+g', handler: 'goto', arguments: [42] }
  ],

  goto(e, line) {
    console.log(`going to line ${line}`);
  }
});

You can choose to bind multiple key shortcuts to the same handler:

keyboardHandlers: [
  { key: ['a', 'b'], handler: 'doStuff' }
]

You can use some of the Ember run loop features:

keyboardHandlers: [
  // debounces key handlers by 30ms
  { key: 'a', handler: 'debouncedHandler', debounce: 30 },

  // throttles key handlers by 30ms
  { key: 'b', handler: 'throttledHandler', throttle: 30 },

  // only calls the handler once every run loop
  { key: 'c', handler: 'scheduleOnceHandler', scheduleOnce: true }
]

For more usage examples you can check out the tests

Service Usage

Use Ember.inject.service to inject the service onto your Ember object.

Ember.Object.extend({
  keyboard: service()
});

Then use listenFor to start listening for keyboard events: (The key names are equal to those used for KeyboardEvent.key.)

this.get('keyboard').listenFor('x', this, eventHandler);

You can alternatively pass a function name instead of an eventHandler:

this.get('keyboard').listenFor('x', this, 'xEventHandler');

You can optionally specify modifier keys:

// possible modifiers are: ctrl, cmd, alt, shift
this.get('keyboard').listenFor('ctrl+alt+Delete', this, eventHandler);

You can listen for a key stroke once:

this.get('keyboard').listenForOnce('x', this, eventHandler);

You can stop listening for key strokes, you must supply the exact same arguments as you did to listenFor.

this.get('keyboard').stopListeningFor('x', this, eventHandler);

The service will not handle the event if the even target was an input or similar element. To override this you can do:

this.get('keyboard').listenFor('x', this, eventHandler, {
  actOnInputElement: true
});

For more usage examples you can check out the tests