Keyrelease
Updated on September 20, 2024Source codeTests
createKeyrelease is a factory that returns Recognizeable effects for recognizing one or more keycombos.
A key release is a sequence of keydown and keyup events, with no visibilitychange events in between. All keys in a given combo must go down, and then one key must come up in order for the keyrelease to be recognized.
A keyrelease can be recognized multiple times, as long as the final key in the keycombo is pressed down and then released again. It's not necessary to lift up all keys in the combo before recognizing again. A keyrelease is only recognized when the final key in the combo is released—it does not recognize again when other keys in the combo are released.
A keyrelease is denied by visibilitychange, and by the keydown event of a key that is not part of any of the given keycombos. As soon as a keyrelease is denied, all keys must come up before the keyrelease will start trying to recognize again.
Create keyrelease
Call createKeyrelease with these parameters to create your keydown, keyup, and visibilitychange effects:
keycomboThe keycombo or array of keycombos to recognize.
If you pass an array of keycombos, the keyrelease will recognize whenever the current keyboard state exactly matches any one of those keycombos, and the final key of the combo is then released.
optionskeydown, keyup, and visibilitychange effects. See the Options section for more guidance.Options
minDuration0preventsDefaultUnlessDeniedtrueWhether to call preventDefault on the keydown, keyup, and visibilitychange events, unless the keyrelease is denied.
If the keyrelease has been denied, the default will never be prevented (although you can still prevent it via the hooks listed below).
onDownundefinedA function that is called when any key is pressed down.
onDown receives the keyrelease hook API as its only parameter.
onUpundefinedA function that is called when any key is released.
onUp receives the keyrelease hook API as its only parameter.
onVisibilityChangeundefinedA function that is called when the page visibility changes.
onVisibilityChange receives the keyrelease hook API as its only parameter.
Hook API
The hook API is an object that is passed to the onDown, onUp, and onVisibilityChange options as their only parameter. It contains the following properties:
statusrecognized, denied, or recognizing.sequenceMetadata
Your created keyrelease effects store data in the Recognizeable instance's metadata property.
Keyrelease metadata includes all keyboard metadata.
Using with Listenable
The easiest way to use createKeyrelease with Listenable is to use the Keyrelease class, which is a very minimal subclass of Listenable that handles configuration for you.
Here's an example of how to use Keyrelease to nicely combine createKeyrelease with Listenable:
import { Keyrelease } from '@baleada/logic'
const keyrelease = new Keyrelease(keycomboOrKeycombos, [keyreleaseOptions])
keyrelease.listen(() => {
console.log(keyrelease.metadata.duration)
})
