finger-roll v0.1.3
Finger Roll
This goes out to all the people who have fat fingered something on their keyboard.
Finger Roll provides information about keyboard layouts. Specifically, it will let you know
which keys are close to another on the keyboard ('A'
is close to 'S'
on a QWERTY layout, for example).
Example
const FingerRoll = require('finger-roll');
const fingerRoll = new FingerRoll('us-qwerty');
fingerRoll.getAdjacentKeys('F'); // [ 'C', 'D', 'G', 'R', 'T', 'V' ]
fingerRoll.distanceBetween('A', 'L'); // 8
Supported Keyboard Layouts
- US QWERTY
API
Note: All examples are given assuming as US QWERTY layout since that's what I type with.
FingerRoll(string layout = 'us-qwerty') -> FingerRoll
* Creates a new instance of FingerRoll with the designated keyboard layout.toKeyFormat(string key) -> string
Converts a key name obtained from something likeevent.key
in akeypress
event to the internal format. Example:toKeyFormat('a') == 'A'
All other methods use this internally so if you only use the given API then you won't need this. However, it may be useful when working with the results of other methods.getAlternate(string key) -> string?
Returns the equivalent key as if you were holding down Shift Returnsnull
if it doesn't recognize the key Example:getAlternate('1') == '!'
Example:getAlternate('not a key') == null
getAdjacentKeys(string key) -> string[]
Returns an array with all keys surrounding the given one Example:getAdjacentKeys('F') == [ 'C', 'D', 'G', 'R', 'T', 'V' ]
isAdjacent(string keyA, string keyB) -> bool
Reports whether two keys are next to each other or not Example:isAdjacent('G', 'H') == true
* Example:isAdjacent('G', 'J') == false
distanceBetween(string source, string destination) -> number?
Returns the distance between two keys Returnsnull
if it doesn't recognize either thesource
ordestination
Example:distanceBetween('A', 'L') == 8
Example:distanceBetween('not a key', 'L') == null
distanceToAll(string source) -> ({ [key]: number })?
Returns an object indicating the distance from one key to any other key on the keyboard Returnsnull
if it doesn't recognize thesource
key Example:distanceToAll('A')['D'] == 2
Example:distanceToAll('not a key') == null
pathTo(string source, string destination) -> string[]?
Returns an array indicating the path to take to go between two keys. Returnsnull
if it doesn't recognize either thesource
ordestination
Example:pathTo('A', 'F') == ['A', 'S', 'D', 'F']
Example:pathTo('not a key', 'F') == null
pathToAll(string source) -> ({ [key]: string })?
Returns an object indicating which key to follow to return to thesource
Returnsnull
if it doesn't recognize thesource
Example:pathToAll('A')['F'] == 'D'
Example:pathToAll('not a key') == null
Contributing
If you'd like to create a mapping for a different keyboard layout, look in the layouts
folder. I recommend using the us-qwerty.js
file for reference. It basically comes down to stating which keys are neighbors for every other key. Use the names given by a keypress
event in the DOM as reference. The goal is to be able to plug this straight into a keypress
(or similar) event and have it work out-of-the-box.