browserkeymap
v2.0.2
Published
Map browser events to key names, and key names to values
Downloads
11,624
Readme
Browser Keymap
A small library for doing sane key binding in the browser. It defines two things:
A string notation for key events
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 tokeypress
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 namesAlt
,Backspace
,CapsLock
,Ctrl
,Delete
,Down
,End
,Enter
,Esc
,Home
,Insert
,Left
,Mod
,PageDown
,PageUp
,Pause
,PrintScrn
,Right
,Shift
,Space
,Tab
, orUp
.
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.
An object type for keymaps
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).
License
This module is released under an MIT license.