browserkeymap

Map browser events to key names, and key names to values

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
browserkeymap
2.0.26 years ago7 years agoMinified + gzip package size for browserkeymap in KB

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 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.

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.