browserkeymap

2.0.2 • Public • Published

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.

Readme

Keywords

Package Sidebar

Install

npm i browserkeymap

Weekly Downloads

6,771

Version

2.0.2

License

MIT

Last publish

Collaborators

  • marijn