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:
-
keyNameStringThe 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!!
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
Accepts a key name and returns the key code defined by the current key layout.
Parameters:
-
keyNameString
getKeyName
-
keyCode
Accepts a key code and returns the key names defined by the current key layout.
Parameters:
-
keyCodeNumber
Returns:
keyNames An array of key names defined for the key code as defined by the current layout.
on
-
keySelector -
[options]
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:
,+>
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:
- the keydown or keyup
Eventobject (as received from the host environment) - the array of currently active keys
- the key selector string
Parameters:
-
keySelectorStringThe 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 optionalThe function to execute when the key(s) or key combination(s) are engaged.
-
[onKeyUp]Function optionalThe function to execute when the key(s) or key combination(s) are disengaged.
-
[preventRepeat=false]Boolean optionalWhether to prevent repeated events from firing when the key is being held down.
-
[preventDefault=false]Boolean optionalWhether to prevent default browser callbacks from being triggered.
-
Returns:
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.
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'.
removeActiveKey
-
keyName
Removes a key from the array of currently active keys.
Parameters:
-
keyNameStringThe name of the key.
removeBindingByKeyName
-
keyName
Clears all bindings attached to key selectors matching the supplied key name.
Parameters:
-
keyNameString
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:
-
keySelectorString
removeMacro
-
combo
Clears all macros bound to the specified key selector. TO COMPLETE!!
Parameters:
-
comboString
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.