Demo
JS is required...
What is KeyboardJS?
A JavaScript library for binding keyboard combos without the pain of key codes and key combo conflicts.
It can be used as both a standalone library or an AMD module (see
RequireJS for details).
Get it Here
Language Support
KeyboardJS can support any locale, however out of the box it just comes with the US locale (for now).
Adding a new locale is easy. Map your keyboard to an object and pass it to
KeyboardJS.locale.register(localeName, localeDefinition) then call KeyboardJS.locale(localeName).
If you create a new locale please consider sending me a pull request or submit it to the issue tracker so I can add it to the library.
If you create a new locale please consider sending me a pull request or submit it to the issue tracker so I can add it to the library.
Methods
KeyboardJS.on
Usage
KeyboardJS.on(keyCombo, onDownCallback, onUpCallback);
Binds any key or key combo. See 'keyCombo' definition below
for details. The onDownCallback is fired once the key or key combo becomes active. The
onUpCallback is fired when the combo no longer active (a single key is released).
Both the onUpCallback and the onUpCallback are passed three arguments. The first is the key event, the second is the keys pressed, and the third is the key combo string.
Both the onUpCallback and the onUpCallback are passed three arguments. The first is the key event, the second is the keys pressed, and the third is the key combo string.
Returned
- clear() - Removes the key or key combo binding.
- on() - Allows you to bind to the keyup and keydown event of the given combo. An alternative to adding the onDownCallback and onUpCallback.
KeyboardJS.activeKeys
Usage
KeyboardJS.activeKeys();
Returns an array of active keys by name.
Returned
Returns an array of key names that are currently being pressed.
KeyboardJS.clear
Usage
KeyboardJS.clear(keyCombo);
Removes all bindings with the given key combo. See 'keyCombo' definition for more details.
Please note that if you are just trying to remove a single binding should use the clear method in the object returned by KeyboardJS.on instead of this. This function is for removing all binding that use a certain key.
Please note that if you are just trying to remove a single binding should use the clear method in the object returned by KeyboardJS.on instead of this. This function is for removing all binding that use a certain key.
KeyboardJS.clear.key
Usage
KeyboardJS.clear.key(key);
Removes all bindings that use the given key.
KeyboardJS.locale
Usage
KeyboardJS.locale(localeName);
Changes the locale keyboardJS uses to map key presses. Out of the box KeyboardJS only supports US keyboards, however
it is possible to add additional locales via KeyboardJS.locale.register()
KeyboardJS.locale.register
Usage
KeyboardJS.locale.register(localeName, localeDefinition);
Adds new locale definitions to KeyboardJS.
Definitions
keyCombo
A string containing key names separated by whitespace, >, +, and ,.
examples
- 'a' - binds to the 'a' key. Pressing 'a' will match this keyCombo.
- 'a, b' - binds to the 'a' and 'b' keys. Pressing either of these keys will match this keyCombo.
- 'a b' - binds to the 'a' and 'b' keys. Pressing either of these keys will match this keyCombo.
- 'a + b' - binds to the 'a' and 'b' keys. Pressing both of these keys will match this keyCombo.
- 'a > b' - binds to the 'a' and 'b' keys. Pressing 'a' then 'b' will match this keyCombo.
- 'a + b, c + d' - binds to the 'a', 'b', 'c' and 'd' keys. Pressing either the 'a' key and the 'b' key, or the 'c' and the 'd' key will match this keyCombo.
- 'a + b > c + d' - binds to the 'a', 'b', 'c' and 'd' keys. Pressing both the 'a' key and the 'b' key, then both the 'c' and the 'd' key will match this keyCombo.
localeDefinitions
An object that maps keyNames to their keycode and stores locale specific macros. Used for mapping keys on different locales.
examples
- { "map": { "65": ["a"], "66": ["b"], ... }, "macros": [ ["shift + `", ["tilde", "~"]], ["shift + 1", ["exclamation", "!"]], .... ] }