Keydrown

A JavaScript key state handler for web apps

When building games or any application that requires quick reactions from the user, a system to track key states is needed. You might say "Silly developer! There are events for that! They're called keydown and keyup!" This is correct, but the problem that Keydrown solves is more subtle: When you press and hold any key on the keyboard, there is a brief delay between the initial firing of the keydown event handler and the subsequent firings of that event for every tick. Here's an approximate ASCII visualization:

TIME (seconds)           KEYDOWN HANDLER FIRING STATE
-----------------------------------------------------

0                        Firing
0.25                     Not firing
0.50                     Not firing
0.75                     Not firing
1                        Firing
1.25                     Firing
1.50                     Firing
1.75                     Firing
2                        Firing

...And the handler will just keep firing until the button is released. The expectation from the user is that the key handler would be firing for the entire duration of time that the key is held down - the early ticks where the keydown state is not handled creates a feeling of sluggishness and noticeably worsens the User Experience. A way around this delay is to only listen for one keydown event for a button, and execute the key handler on every tick until the corresponding keyup event is detected for that button.

Keydrown makes this super easy.

API

All Keydrown functionality exists under the kd namespace.

Key Objects

Every letter key, as well as some other keys on the keyboard are represented in a map of kd.Key instances with uppercase key names:

kd.A instanceof kd.Key; // true
kd.SPACE instanceof kd.Key; // true
kd.UP instanceof kd.Key; // true

You can see the full list of supported keys in kd.map.js (more key codes can easily be added, please submit a Pull Request if you add more). kd.Key has the following API:

/**
 * @param {function=} opt_handler
 */
kd.Key.prototype.down = function (opt_handler)

opt_handler fires for every tick where the key is held down. There is no early delay, as described in the ASCII graph above. Calling this method for a key again will overwrite the previous opt_handler - only one handler function is allowed per key.

If opt_handler is omitted, this function invokes whatever handler function was previously bound with kd.Key#down.

/**
 * @param {function=} opt_handler
 */
kd.Key.prototype.up = function (opt_handler)

opt_handler fires when the key is released by the user. As with kd.Key#down, only one handler function is allowed. Unlike kd.Key#down, opt_handler does not fire continuously — only once when the key is released.

If opt_handler is omitted, this function invokes whatever handler function was previously bound with kd.Key#up.

/**
 * @param {function=} opt_handler
 */
kd.Key.prototype.press = function (opt_handler)

opt_handler fires once when the key is pressed by the user. Only one handler function is allowed. This is not a repeating state — it only fires once until the user releases the key and presses it again.

If opt_handler is omitted, this function invokes whatever handler function was previously bound with kd.Key#press.

kd.Key.prototype.isDown = function()

Returns true if the key is currently pressed, otherwise returns false.

Example

kd.B.down(function () {
  console.log('The "B" key is being held down!');
});

kd.B.up(function () {
  console.log('The "B" key was released!');
});

kd.SPACE.press(function () {
  console.log('The space bar was pressed!');
});

if (kd.LEFT.isDown()) {
  console.log('The left arrow key is being held down!')
}

---

down, up, and press functions also provide the raw Keyboard event Object created by the corresponding browser event. The schema of this Object may differ across browsers, particularly older ones.

kd.A.down(function (evt) {
  if (evt.shiftKey) {
    console.log('The shift key is being held down!');
  }

  if (evt.ctrlKey) {
    console.log('The ctrl key is being held down!');
  }
});

---

kd.Key.prototype.unbindDown = function ()

Unbinds the function handler that was bound with kd.Key#down.

kd.Key.prototype.unbindUp = function ()

Unbinds the function handler that was bound with kd.Key#up.

kd.Key.prototype.unbindPress = function ()

Unbinds the function handler that was bound with kd.Key#press.

Example

kd.B.down(function () {
  console.log('The "B" key is being held down!');
});

// Now pressing the "B" key won't do anything
kd.B.unbindDown();

---

Helper methods

The kd Object has helper methods attached to it, and they are represented by camelCase property names.

kd.tick = function ()

Check the states of all of the keys and invoke the necessary key handlers. You should call this once and only once somewhere in your run loop. If you don't call tick somewhere in your run loop, Keydrown won't do anything.

/**
 * @param {function} handler
 */
kd.run = function (handler)

A basic run loop. If your application already has a run loop, you don't need this. kd.run uses requestAnimationFrame if it is available, and falls back to a setTimeout loop if it is not.

kd.stop = function ()

Cancels the run loop started by kd.run.

Example

kd.run(function () {
  kd.tick();
});

kd.SPACE.down(function () {
  console.log('The space bar is being held down!');
});

kd.ESC.down(function () {
  console.log('Canceling the loop.');
  kd.stop();
});

---

Getting the code

If you want to keep things simple, all you need is either dist/keydrown.js or dist/keydrown.min.js from this Git repo. Alternatively, you can install Keydrown via NPM:

$: npm install keydrown

Module compatibility

If loaded directly (without a script loader), Keydrown creates the kd browser global. However, it can also be loaded as an AMD module or as a CommonJS module (through a tool like Webpack).

// Loaded as a CommonJS module with Webpack
var kd = require('keydrown');

kd.run(function () {
  kd.tick();
});

// Loaded with an AMD loader (such as Require.js)
require(['./path/to/keydrown'], function (kd) {
  kd.run(function () {
    kd.tick();
  });
});

Browser compatibility

Keydrown supports all modern browsers, as well as Internet Explorer 7 and up (please see the note below about IE compatibility).

Limitations

Keydrown has a feature where when the user blurs the browser window (for example, switching to another application or tab), the key state is reset and "down" handlers stop firing. On other words, keys aren't considered "down" if the user is not focused on the browser window. This functionality is not supported in IE 7 and 8, as there doesn't seem to be a way to bind to the window's blur event correctly in those browsers. You can assign a function to window.onblur, but that function will only fire once IE regains focus, which is not sufficient for Keydrown's reset-on-blur functionality.

Keydrown in the wild

Keydrown has been used in several interesting projects:

• A Node-powered helicopter
• PeepsQuest, a game development tutorial
• A role playing game
• A WebRTC controlled car
• A Javascript Port of Super Mario 64

License

Keydrown is distibuted under the MIT license. You are encouraged to use and modify the code to suit your needs, as well as redistribute it.