mmk.keyboard
MaulingMonkey's typescript keyboard API for consistent cross-browser keybinding, polling input for games, etc.
- GitHub: github.com/MaulingMonkey/mmk.keyboard
- Demo: maulingmonkey.com/mmk.keyboard/demo/
- Docs: maulingmonkey.com/mmk.keyboard/docs/
- NPM: @maulingmonkey/keyboard
- License: Apache 2.0
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