Skip to content
Typescript keyboard API for consistent cross-browser keybinding, polling input for games, etc.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode
build
demo
src
.gitignore
LICENSE.txt
Readme.md
package.json
tsconfig.common.json

Readme.md

mmk.keyboard

MaulingMonkey's typescript keyboard API for consistent cross-browser keybinding, polling input for games, etc.

What? Why?

The vanilla browser keyboard APIs are pretty inconsistent about a lot of things. IE11's keyboardEvent.repeat lies, .code may or may not be available - and if present, has different names for the same keys across different browsers, vanilla numpad events are annoying to differentiate from other hotkeys (e.g. Shift+Numpad1 maps to key: "End"), etc.) which is annoying for roguelikes...

Additionally, doing "the right thing" with the vanilla API isn't straightforward. A lot of webcomics I read implement page handlers for ArrowLeft / ArrowRight, which is nice. Less nice is that most of them don't think to check event.alt or other modifier keys, so their page handlers interfere with browser history navigation (Alt+ArrowLeft, Alt+ArrowRight in Chrome).

Browser Support

OS Browser U.S. Dvorak[1] mmkCode keypress[2]
Windows 7 Chrome 57
Windows 7 IE 11 ✗ [3]
  • [1] Dvorak "support" means mmkKey reports correctly the logical key pressed.
  • [2] Key press events are only partially implemented: mmkCode should be set, if available. mmkKey is not, period.
  • [3] This browser provides no API to get physical key codes - and thus cannot support mmkCode at all.

Basic API

// APIs for consistent results across multiple browsers
keyboardEvent.mmkRepeat // Workaround IE11 keyboardEvent.repeat lying (always being false)
keyboardEvent.mmkKey    // Logical key pressed               (e.g. by keyboard layout labels)
keyboardEvent.mmkCode   // Physical key pressed if available (e.g. ignoring keyboard layout)

// Combination parsing and testing
combo = mmk.keyboard.parseSimpleKeyCombo("Alt+["); // Won't match "[" or "Ctrl+Alt+["
combo = mmk.keyboard.parseSimpleKeyCombo("?Shift+?Ctrl+Alt+["); // Match "Alt+[" or "Ctrl+Alt+[" but not "Meta+["
if (mmk.keyboard.isSimpleKeyCombo(keyboardEvent, combo)) { ... }
conflicts = mmk.keyboard.systemConflictsWithSimpleKeyCombo(combo).filter(conflict => !conflict.overrideable);

Unstablized API Bits

What Why
mmkRepeat Still mulling over how to handle LCtrl + RCtrl "repeats" in Chrome
mmkKey Digits Still mulling over how to handle Digit0 vs Numpad0
mmkCode Numpad Still mulling over how to handle Shift+Numpad 1
mmkCode IE11 Could add fallback for some keys that doesn't rely on keyboard layout (e.g. arrows, basic numpad)
Conflicts API Some conflict detection depends on mmkKey/mmkCode bits above
Key.CtrlLeft Might drop sided keys if we split off a separate 'Code' field.
Key["0"] Ambiguous - Digit0? Include Numpad0? Key based? Code based? ...
Key["."] Punctuation is very likely to be dropped from the Key namespace at some point - too ambiguous
parseSimpleKeyCombo Naming?
isSimpleKeyCombo Naming?
systemConflictsWithSimpleKeyCombo Naming? Bloody wordy.

(Unstable here means the API is subject to change - it shouldn't crash or anything.)

Project Scope

Perhaps easier to say what's not in scope:

  • No "on screen keyboard" support (I should make one, but it can be a separate module)
  • No/limited automatic keyboard layout detection. Even flash doesn't have an API - I'd need to write my own native plugins? Might be able to partially bodge around it.

Installation

Via npm

  • Grab NPM via node.js
  • Install per project
    npm i @maulingmonkey/keyboard
You can’t perform that action at this time.