GitHub - RobertWHurst/KeyboardJS: A JavaScript library for binding keyboard combos without the pain of key codes and key combo conflicts. (original) (raw)

KeyboardJS

NotePlease Note: I've create a new libary calledKeystrokes which serves the same purpose as KeyboardJS, but is more refined, and takes full advantage of modern browsers. If you are considering using KeyboardJS in a new project, I recommend checking outKeystrokes first.

KeyboardJS is a library for use in the browser (node.js compatible). It Allows developers to easily setup key bindings. Use key combos to setup complex bindings. KeyboardJS also provides contexts. Contexts are great for single page applications. They allow you to scope your bindings to various parts of your application. Out of the box keyboardJS uses a US keyboard locale. If you need support for a different type of keyboard KeyboardJS provides custom locale support so you can create with a locale that better matches your needs.

KeyboardJS is available as a NPM module. If you're not using a build system like webpack, simply addkeyboard.jsorkeyboard.min.jsfrom the dist folder in this repo to your project via a script tag.

Note that all key names can be found in ./locales/us.js.

Setting up bindings is easy

keyboardJS.bind('a', (e) => { console.log('a is pressed'); }); keyboardJS.bind('a + b', (e) => { console.log('a and b is pressed'); }); keyboardJS.bind('a + b > c', (e) => { console.log('a and b then c is pressed'); }); keyboardJS.bind(['a + b > c', 'z + y > z'], (e) => { console.log('a and b then c or z and y then z is pressed'); }); keyboardJS.bind('', (e) => { console.log('any key was pressed'); }); //alt, shift, ctrl, etc must be lowercase keyboardJS.bind('alt + shift > a', (e) => { console.log('alt, shift and a is pressed'); });

// keyboardJS.bind === keyboardJS.on === keyboardJS.addListener

keydown vs a keyup

keyboardJS.bind('a', (e) => { console.log('a is pressed'); }, (e) => { console.log('a is released'); }); keyboardJS.bind('a', null, (e) => { console.log('a is released'); });

Prevent keydown repeat

keyboardJS.bind('a', (e) => { // this will run once even if a is held e.preventRepeat(); console.log('a is pressed'); });

Unbind things

keyboardJS.unbind('a', previouslyBoundHandler); // keyboardJS.unbind === keyboardJS.off === keyboardJS.removeListener

Using contexts

// these will execute in all contexts keyboardJS.bind('a', (e) => {}); keyboardJS.bind('b', (e) => {}); keyboardJS.bind('c', (e) => {});

// these will execute in the index context keyboardJS.setContext('index'); keyboardJS.bind('1', (e) => {}); keyboardJS.bind('2', (e) => {}); keyboardJS.bind('3', (e) => {});

// these will execute in the foo context keyboardJS.setContext('foo'); keyboardJS.bind('x', (e) => {}); keyboardJS.bind('y', (e) => {}); keyboardJS.bind('z', (e) => {});

// if we have a router we can activate these contexts when appropriate myRouter.on('/', (e) => { keyboardJS.setContext('index'); }); myRouter.on('/foo', (e) => { keyboardJS.setContext('foo'); });

// you can always figure out your context too const contextName = keyboardJS.getContext();

// you can also set up handlers for a context without losing the current context keyboardJS.withContext('bar', () =>{ // these will execute in the bar context keyboardJS.bind('7', (e) => {}); keyboardJS.bind('8', (e) => {}); keyboardJS.bind('9', (e) => {}); });

pause, resume, and reset

// the keyboard will no longer trigger bindings keyboardJS.pause();

// the keyboard will once again trigger bindings keyboardJS.resume();

// all active bindings will released and unbound, // pressed keys will be cleared keyboardJS.reset();

pressKey, releaseKey, and releaseAllKeys

// pressKey keyboardJS.pressKey('a'); // or keyboardJS.pressKey(65);

// releaseKey keyboardJS.releaseKey('a'); // or keyboardJS.releaseKey(65);

// releaseAllKeys keyboardJS.releaseAllKeys();

watch and stop

// bind to the window and document in the current window keyboardJS.watch();

// or pass your own window and document keyboardJS.watch(myDoc); keyboardJS.watch(myWin, myDoc);

// or scope to a specific element keyboardJS.watch(myForm); keyboardJS.watch(myWin, myForm);

// detach KeyboardJS from the window and document/element keyboardJS.stop();