KeyStateTracker¶

Overview¶

A type that will manage the state of the keyboard. This will track which keys are being held down and for how long. It also offers convenience methods to determine whether or not specific keys are down like shift or enter using KeyboardUtils' key schema.

@author Michael Kauzmann (PhET Interactive Simulations) @author Jesse Greenberg (PhET Interactive Simulations) @author Michael Barlow

Class KeyStateTracker¶

import { KeyStateTracker } from 'scenerystack/scenery';

Constructor¶

new KeyStateTracker( options? : KeyStateTrackerOptions )¶

Instance Methods¶

keydownUpdate( domEvent : KeyboardEvent )¶

Implements keyboard dragging when listener is attached to the Node, public so listener is attached with addInputListener(). Only updated when enabled.

Note that this event is assigned in the constructor, and not to the prototype. As of writing this, Node.addInputListener only supports type properties as event listeners, and not the event keys as prototype methods. Please see https://github.com/phetsims/scenery/issues/851 for more information.

keyupUpdate( domEvent : KeyboardEvent )¶

Behavior for keyboard 'up' DOM event. Public so it can be attached with addInputListener(). Only updated when enabled.

Note that this event is assigned in the constructor, and not to the prototype. As of writing this, Node.addInputListener only supports type properties as event listeners, and not the event keys as prototype methods. Please see https://github.com/phetsims/scenery/issues/851 for more information.

getLastKeyDown() : string | null¶

Returns the KeyboardEvent.code from the last key down that updated the keystate.

isKeyDown( key : string ) : boolean¶

Returns true if a key with the KeyboardEvent.code is currently down.

isEnglishKeyDown( key : EnglishKey ) : boolean¶

Returns true if the key with the KeyboardEvent.code is currently down.

getKeysDown() : string[]¶

Returns the set of keys that are currently down.

NOTE: Always returns a new array, so a defensive copy is not needed.

getEnglishKeysDown() : Set<EnglishKeyString>¶

Returns the set of EnglishKeys that are currently down.

NOTE: Always returns a new Set, so a defensive copy is not needed.

isAnyKeyInListDown( keyList : string[] ) : boolean¶

Returns true if any of the keys in the list are currently down. Keys are the KeyboardEvent.code strings.

areKeysDown( keyList : string[] ) : boolean¶

Returns true if ALL of the keys in the list are currently down. Values of the keyList array are the KeyboardEvent.code for the keys you are interested in.

areKeysDownWithoutExtraModifiers( keyList : string[] ) : boolean¶

Returns true if every key in the list is down but no other modifier keys are down, unless the modifier key is in the list. For example areKeysDownWithoutModifiers( [ 'ShiftLeft', 'ArrowLeft' ] ) -> true if left shift and left arrow keys are down. areKeysDownWithoutModifiers( [ 'ShiftLeft', 'ArrowLeft' ] ) -> true if left shift, left arrow, and J keys are down. areKeysDownWithoutModifiers( [ 'ArrowLeft' ] ) -> false if left shift and arrow left keys are down. areKeysDownWithoutModifiers( [ 'ArrowLeft' ] ) -> true if the left arrow key is down. areKeysDownWithoutModifiers( [ 'ArrowLeft' ] ) -> true if the left arrow and R keys are down.

This is important for determining when keyboard events should fire listeners. Say you have two KeyboardListeners - One fires from key 'c' and another fires from 'shift-c'. If the user presses 'shift-c', you do NOT want both to fire.

@param keyList - List of KeyboardEvent.code strings for keys you are interested in.

keysAreDown() : boolean¶

Returns true if any keys are down according to teh keyState.

timeDownForKey( key : string ) : number¶

Returns the amount of time that the provided key has been held down. Error if the key is not currently down. @param key - KeyboardEvent.code for the key you are inspecting.

clearState( skipNotify? : boolean )¶

Clear the entire state of the key tracker, basically restarting the tracker.

attachToWindow()¶

Add this KeyStateTracker to the self so that it updates whenever the document receives key events. This is useful if you want to observe key presses while DOM focus not within the PDOM root.

setEnabled( enabled : boolean )¶

The KeyState is cleared when the tracker is disabled.

isEnabled() : boolean¶

detachFromDocument()¶

Detach listeners from the document that would update the state of this KeyStateTracker on key presses.

dispose()¶

Instance Properties¶

keydownEmitter : TEmitter<[ KeyboardEvent ]>¶

(readonly)

Emits events when keyup/keydown updates are received. These will emit after any updates to the keyState so that keyState is correct in time for listeners. Note the valueType is a native KeyboardEvent event.

keyupEmitter : TEmitter<[ KeyboardEvent ]>¶

(readonly)

keyDownStateChangedEmitter : TEmitter<[ KeyboardEvent | null ]>¶

(readonly)

Emits when any key "down" state changes. This is useful for when you want to know if any key is down or up. Does NOT change for timeDown changes. DOES fire if the browser sends fire-on-hold down.

keydownUpdateAction : PhetioAction<[ KeyboardEvent ]>¶

(readonly)

Action which updates the KeyStateTracker, when it is time to do so - the update is wrapped by an Action so that the KeyStateTracker state is captured for PhET-iO.

keyupUpdateAction : PhetioAction<[ KeyboardEvent ]>¶

(readonly)

Action which updates the state of the KeyStateTracker on key release. This is wrapped in an Action so that state is captured for PhET-iO.

Source Code¶

See the source for KeyStateTracker.ts in the scenery repository.