API Docs for: 1.0.0-beta.2
Show:

TangibleKeyboard Class

Overview

TangibleKeyboard is a a flexible and easy to use keyboard binding library allowing the user to attach events to key presses, key sequences and key combos. It is a spin-off of the nice KeyboardJS library created by Robert Hurst.

This particular version adds layouts for various keyboard emulators often used in physical computing to gather input from switches. It also adds explicit support for key repeat prevention. This means you can, if you so wish, ignore repeated keydown events sent by the OS when a key is being held down. This version also allows you to specify whether browser actions tied to certain key combinations should be triggered or not (preventDefault).

Basic usage

Using TangibleKeyboard is quite simple. Simply link to the JS file and use the on() method to attach a callback. Here's an example that will trigger a user function when the "a" key is pressed:

 <script src="tangiblekeyboard.js"></script>

 <script>
     TangibleKeyboard.on(
         'a',
         {
             onKeyDown: function(e, keys, combo) { console.log(e); }
         }
     );
 </script>

That's it.

if you want to prevent default browser actions from being triggered, set preventDefault to true. If you want to prevent repeated events from being triggered when a key is being held down, set preventRepeat to true:

 <script>
     TangibleKeyboard.on(
         'a',
         {
             onKeyDown: function(e, keys, combo) { console.log(e); },
             preventDefault: true,
             preventRepeat: true
         }
     );
 </script>

Using a different keyboard layout

TangibleKeyboard is, by default, configured to use the basic qwerty keyboard layout. If you want to use another one, such as the bundled IpacVE layout, you need to assign the layout:

 <script src="tangiblekeyboard.js"></script>
 <script src="layouts/tangiblekeyboard.layout.ipacve.js"></script>

 <script>
     TangibleKeyboard.setLayout('ipacve');

     TangibleKeyboard.on(
         '1RGHT',
         {
             onKeyDown: function(e, keys, combo) { console.log(e); }
         }
     );
 </script>

Using it with AMD and CommonJS

TangibleKeyboard is compatible with AMD and CommonJS. Here's an example of using an alternative keyboard layout with AMD:

 define(function (require) {

     var tk = require('tangiblekeyboard');
     var layout = require('layouts/tangiblekeyboard.layout.ipacve');
     tk.registerAndSetLayout("ipacve", layout);

     tk.on(
         '1RGHT',
         {
             onKeyDown: function(e, keys, combo) { console.log(e); }
         }
     );

 });

Methods

addActiveKey

(
  • keyName
)

Adds a key to the array of active keys (if it not there already).

Parameters:

  • keyName String

    The name of the key.

createMacro

(
  • combo
  • injectedKeys
)

Accepts a key selector and an array of key names to inject once the key selector is satisfied. TO COMPLETE!!

Parameters:

disable

()

Removes all active user-defined bindings and completely disables the library. The library can be re-enabled afterwards with the enable() method.

enable

()

Enables the library. It should be noted that the library is enabled by default. This method is only useful if the library has been manually disabled through the disable() method.

Enabling the library basically means attaching the appropriate listeners to the host environment.

getKeyCode

(
  • keyName
)
Number | Boolean

Accepts a key name and returns the key code defined by the current key layout.

Parameters:

Returns:

getKeyName

(
  • keyCode
)
Array

Accepts a key code and returns the key names defined by the current key layout.

Parameters:

Returns:

Array:

keyNames An array of key names defined for the key code as defined by the current layout.

getLayout

() String

Returns the currently-assigned layout.

Returns:

String:

The layout identifier.

on

(
  • keySelector
  • [options]
)
Object

Binds keys or combinations of keys to user-defined callback functions. At least one callback function (keydown or keyup) must be specified. The keys are defined by using a key selector string. This string is simply a list of key names separated by one of the following operators:

  •   (space)
  • ,
  • +
  • >

Here are some examples of valid selectors:

  • 'a' : Pressing the 'a' key will trigger the user-defined callbacks.
  • 'a, b' : Pressing the 'a' key or the 'b' key will trigger the user-defined callbacks.
  • 'a + b' : Simultaneously pressing both the 'a' and 'b' keys will trigger the user-defined callbacks.
  • 'a > b' : Pressing the 'a' key, holding it down and then pressing the 'b' key will trigger the user-defined callbacks.
  • 'a + b, b + c' : Simultaneously pressing the 'a' and 'b' keys or the 'b' and 'c' keys will trigger the user-defined callbacks.

Example

var binding = TangibleKeyboard.on(
    'a',
    {
        keyDownCallback: function(e, keys, combo) { console.log(e); },
        keyUpCallback: function(e, keys, combo) { console.log(e); },
        preventRepeat: true,
        preventDefault: true
    }
);

The onDownCallback is fired once the key or combo becomes active. The onUpCallback is fired when the key or combo is no longer active (as soon as a single key is released).

When triggered, the user-defined callbacks are passed three arguments:

  1. the keydown or keyup Event object (as received from the host environment)
  2. the array of currently active keys
  3. the key selector string

Parameters:

  • keySelector String

    The key selector is a string defining the key(s) or key combination(s) that will trigger the callbacks. See the documentation for the TangibleKeyboard.on() method for full key selector syntax.

  • [options] Object optional
    • [onKeyDown] Function optional

      The function to execute when the key(s) or key combination(s) are engaged.

    • [onKeyUp] Function optional

      The function to execute when the key(s) or key combination(s) are disengaged.

    • [preventRepeat=false] Boolean optional

      Whether to prevent repeated events from firing when the key is being held down.

    • [preventDefault=false] Boolean optional

      Whether to prevent default browser callbacks from being triggered.

Returns:

Object:

This object contains a clear and an on property which are both reference to functions. You can use the clear() function to remove the binding when you are done.

You can use the on() function to add additional callbacks for keyup and keydown events. You simply pass the event name as the first parameter and any number of callbacks that should be fired for that event as the second parameter.

registerAndSetLayout

(
  • layoutName
  • layoutMap
)

Registers a new key layout and immediately assigns it as the currently-active layout.

Parameters:

  • layoutName String

    The name of the new key layout.

  • layoutMap Object

    The layout map.

registerLayout

(
  • layoutName
  • layoutMap
)

Registers a new layout. This is useful if you would like to add support for a new keyboard layout. It could also be useful for alternative key names. For example, if you program games you could create a layout for your key mappings. Instead of key 65 mapped to 'a' you could map it to 'jump'.

Parameters:

  • layoutName String

    The name of the new key layout.

  • layoutMap Object

    The layout map.

removeActiveKey

(
  • keyName
)

Removes a key from the array of currently active keys.

Parameters:

  • keyName String

    The name of the key.

removeBindingByKeyName

(
  • keyName
)

Clears all bindings attached to key selectors matching the supplied key name.

Parameters:

removeBindingByKeySelector

(
  • keySelector
)

Clears all bindings attached to a given key selector string. The key name order does not matter as long as the key selectors equate.

Parameters:

removeMacro

(
  • combo
)

Clears all macros bound to the specified key selector. TO COMPLETE!!

Parameters:

setLayout

(
  • layoutName
)
Object

Assigns a new key layout. The new layout must have been previously registered with the registerLayout() function. By default, only the 'qwerty' layout is registered.

Parameters:

  • layoutName String

    The new layout to use.

Returns:

Properties

activeKeys

Array

[read-only] An array of the names of all the currently active keys (i.e. keydown state). This array will include all the names of all the keys that are currently pressed as long as they are defined in the currently-active layout.

version

String static

Version of this library.