├── package.json ├── .gitignore ├── LICENSE ├── index.js └── README.md /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "key-event-to-string", 3 | "version": "1.1.1", 4 | "description": " Converts a JavaScript key event object into a humanly readable format", 5 | "main": "index.js", 6 | "scripts": { 7 | "test": "standard" 8 | }, 9 | "repository": { 10 | "type": "git", 11 | "url": "git+https://github.com/florian/key-event-to-string.git" 12 | }, 13 | "keywords": [ 14 | "events" 15 | ], 16 | "author": "Florian Hartmann", 17 | "license": "MIT", 18 | "bugs": { 19 | "url": "https://github.com/florian/key-event-to-string/issues" 20 | }, 21 | "homepage": "https://github.com/florian/key-event-to-string#readme" 22 | } 23 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | 6 | # Runtime data 7 | pids 8 | *.pid 9 | *.seed 10 | 11 | # Directory for instrumented libs generated by jscoverage/JSCover 12 | lib-cov 13 | 14 | # Coverage directory used by tools like istanbul 15 | coverage 16 | 17 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 18 | .grunt 19 | 20 | # node-waf configuration 21 | .lock-wscript 22 | 23 | # Compiled binary addons (http://nodejs.org/api/addons.html) 24 | build/Release 25 | 26 | # Dependency directory 27 | node_modules 28 | 29 | # Optional npm cache directory 30 | .npm 31 | 32 | # Optional REPL history 33 | .node_repl_history 34 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 Florian Hartmann 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | var defaultOptions = { 2 | cmd: 'Cmd', 3 | ctrl: 'Ctrl', 4 | alt: 'Alt', 5 | shift: 'Shift', 6 | joinWith: ' + ' 7 | } 8 | 9 | var options = {} 10 | 11 | var keyMap = { 12 | 8: 'Backspace', 13 | 9: 'Tab', 14 | 13: 'Enter', 15 | 27: 'Escape', 16 | 32: 'Space', 17 | 36: 'Home', 18 | 33: 'Page Up', 19 | 34: 'Page Down', 20 | 35: 'End', 21 | 37: 'Left', 22 | 38: 'Up', 23 | 39: 'Right', 24 | 40: 'Down', 25 | 46: 'Delete', 26 | 112: 'F1', 27 | 113: 'F2', 28 | 114: 'F3', 29 | 115: 'F4', 30 | 116: 'F5', 31 | 117: 'F6', 32 | 118: 'F7', 33 | 119: 'F8', 34 | 120: 'F9', 35 | 121: 'F10', 36 | 122: 'F11', 37 | 123: 'F12', 38 | 186: ';', 39 | 187: '=', 40 | 188: ',', 41 | 189: '-', 42 | 190: '.', 43 | 192: '`', 44 | 222: "'" 45 | } 46 | 47 | function buildKeyMap (e) { 48 | var isOnlyModifier = [16, 17, 18, 91, 93, 224].indexOf(e.keyCode) !== -1 49 | var character = isOnlyModifier ? null : keyMap[e.keyCode] || String.fromCharCode(e.keyCode) 50 | 51 | return { 52 | character: character, 53 | modifiers: { 54 | cmd: e.metaKey, 55 | ctrl: e.ctrlKey, 56 | alt: e.altKey, 57 | shift: e.shiftKey 58 | } 59 | } 60 | } 61 | 62 | function buildKeyArray (e) { 63 | var map = buildKeyMap(e) 64 | var modifiers = map.modifiers 65 | 66 | var result = [] 67 | 68 | if (modifiers.cmd) result.push(options.cmd) 69 | if (modifiers.ctrl) result.push(options.ctrl) 70 | if (modifiers.alt) result.push(options.alt) 71 | if (modifiers.shift) result.push(options.shift) 72 | if (map.character) result.push(map.character) 73 | 74 | return result 75 | } 76 | 77 | function event2string (e) { 78 | return buildKeyArray(e).join(options.joinWith) 79 | } 80 | 81 | function details (e) { 82 | var map = buildKeyMap(e) 83 | var mods = map.modifiers 84 | 85 | var hasModifier = mods.cmd || mods.ctrl || mods.alt || mods.shift 86 | 87 | var result = { 88 | hasKey: map.character != null, 89 | hasModifier: hasModifier, 90 | map: map 91 | } 92 | 93 | return result 94 | } 95 | 96 | module.exports = function (userOptions) { 97 | options = Object.assign(defaultOptions, userOptions) 98 | return event2string 99 | } 100 | 101 | module.exports.details = details 102 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # JavaScript keyboard events to strings 2 | 3 | This library helps converting the event object of a JavaScript keydown event 4 | into a humanly readable format. 5 | The idea is to use this for UI components that let the user choose keyboard 6 | shortcuts. 7 | 8 | In other words: This library provides the inverse functionality to common keyboard shortcut binding libraries like [keymaster](https://github.com/madrobby/keymaster) or [Mousetrap](https://craig.is/killing/mice). 9 | 10 | [![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard) 11 | 12 | ## Installation 13 | 14 | ``` 15 | $ npm install --save key-event-to-string 16 | ``` 17 | 18 | ## Usage 19 | 20 | ```js 21 | var event2string = require('key-event-to-string')(options) 22 | 23 | document.body.onkeydown = (e) => { 24 | var keys = event2string(e) 25 | console.log(keys) // e.g. "Ctrl + A" 26 | } 27 | ``` 28 | 29 | ### Options 30 | 31 | `options` is optional and can be an object with the following properties: 32 | 33 | | key | value | default value | 34 | |:--|:--|:--| 35 | | `cmd` | What string to display for the Cmd/Meta modifier | `"Cmd"` | 36 | | `ctrl` | What string to display for the Ctrl modifier | `"Ctrl"` | 37 | | `alt` | What string to display for the Alt/Option modifier | `"Alt"` | 38 | | `shift` | What string to display for the Shift modifier | `"Shift"` | 39 | | `joinWith` | The string that's displayed between all keys | `" + "` 40 | 41 | For example this could be used to get the Mac style keyboard shortcut strings: 42 | 43 | ```js 44 | { 45 | cmd: "⌘", 46 | ctrl: "⌃", 47 | alt: "⌥", 48 | shift: "⇧", 49 | joinWith: "" 50 | } 51 | ``` 52 | 53 | The default settings are compatible with the format that common keyboard shortcut libraries, like [keymaster](https://github.com/madrobby/keymaster) or [Mousetrap](https://craig.is/killing/mice), accept. 54 | 55 | ### Detailed information 56 | 57 | `require('key-event-to-string').details(e)` can be used to get more details. This can be useful for 58 | validating keyboard shortcuts, e.g. for requiring a modifier and a normal key. 59 | It returns an object with this information: 60 | 61 | - `hasModifier`: True iff atleast one of cmd, ctrl, alt or shift was pressed 62 | - `hasKey`: True iff a key other than a modifier is pressed 63 | - `map`: An object containing information which modifier is active and what 64 | other key is pressed 65 | 66 | 67 | ## Disclaimer 68 | 69 | - This library is meant to parse only `keydown` events. `keypress` / `keyup` events have small differences, e..g. `keydown` is needed to capture `Command` on a Mac. So `keydown` is advisible for this anyways. 70 | - I wrote this library for an Electron side project, so I only needed it to run in the Chrome runtime. It probably won't work well in old browsers 71 | - JavaScript keyCodes don't work well with special international characters. E.g. the German umlaut `ö` has the same keyCode as `;`, on a German keyboard. This library doesn't try to fix that and I don't think there's a good fix for all those special cases. Other keyboard shortcut libraries (Mousetrap/keymaster e.g.) have the same problem, so it shouldn't be a big problem since this library is meant to be used as a helper for those libraries 72 | --------------------------------------------------------------------------------