Map browser events to key names, and key names to values
npm install browserkeymapA small library for doing sane key binding in the browser. It defines two
things:
browserkeymap keys are represented by strings like "Shift-Space","Ctrl-Alt-Delete", or "'x'". The rules are:
* keypress events are represented as the character that was typed
between single quotes. They do not support modifiers because
browsers do not attach modifier information to keypress events.
* keydown events are represented as zero or more modifiers
(Shift-, Cmd-, Alt-, Ctrl-) followed by a key name.
* A key name is a capital letter for a letter key, a digit for a
number key, F plus a number for a function key, the symbol typed
by the key when shift isn't held down (one of `[\]'*,-./;=`), orAlt
one of the names , Backspace, CapsLock, Ctrl, Delete,Down
, End, Enter, Esc, Home, Insert, Left, Mod,PageDown
, PageUp, Pause, PrintScrn, Right, Shift,Space
, Tab, or Up.
You can get a key name from an event by calling
Keymap.keyName(event).
You can normalize a key name string (fixing the order of the
modifiers, and replacing alternative modifier names with their
standard name) by calling Keymap.normalizeKeyName(string). ThisMod-
function maps the modifier to Cmd- on Mac platforms and toCtrl- on non-Mac platforms. It also accepts a- for Alt-, c- orControl- for Ctrl-, m- or Meta- for Cmd-, and s- forShift-.
You can use Keymap.isModifierKey(string) to find out whether the
given key name refers to a modifier key.
The Keymap constructor itself, which is the thing the library
exports, can be used to build keymaps.
var myMap = new Keymap({
"Ctrl-Q": handleQuit,
"Shift-Space": autocomplete
})
A keymap associates keys with values. You can call its lookup method
to look up a key:
myMap.lookup("Ctrl-Q") // → handleQuit
myMap.lookup("Alt-F4") // → undefined
You can create a new map from an existing map with its update
method:
var newMap = myMap.update({
"Alt-F4": handleQuit,
"Ctrl-Q": null
})
That will create a new map, starting with the bindings in myMap,Alt-F4
adding a binding for , and removing the binding for Ctrl-Q.
Multi-stroke keys are supported by providing space-separated names to
a keymap. When a prefix of a multi-stroke key is looked up, the
lookup method will return Keymap.unfinished`. The handler should
then buffer the key name, and on the next key event (possibly with a
timeout to clear buffered keys), try again by prefixing the new key
event's name with the buffered key(s).
This module is released under an MIT license.