Map key events to key names, and key names to values
MIT License
A 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 [\]`'*,-./;=
), or
one of the names Alt
, 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)
. This
function maps the modifier Mod-
to Cmd-
on Mac platforms and to
Ctrl-
on non-Mac platforms. It also accepts a-
for Alt-
, c-
or
Control-
for Ctrl-
, m-
or Meta-
for Cmd-
, and s-
for
Shift-
.
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
,
adding a binding for Alt-F4
, 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.