Hotkey¶

Overview¶

Represents a single hotkey (keyboard shortcut) that can be either:

1. Added to globalHotkeyRegistry (to be available regardless of keyboard focus)
2. Added to a node's inputListeners (to be available only when that node is part of the focused trail)

For example:

globalHotkeyRegistry.add( new Hotkey( { keyStringProperty: new Property( 'y' ), fire: () => console.log( 'fire: y' ) } ) );

myNode.addInputListener( { hotkeys: [ new Hotkey( { keyStringProperty: new Property( 'x' ), fire: () => console.log( 'fire: x' ) } ) ] } );

Also supports modifier keys that must be pressed in addition to the Key. See options for a description of how they behave.

Hotkeys are managed by hotkeyManager, which determines which hotkeys are active based on the globalHotkeyRegistry and what Node has focus. See that class for information about how hotkeys work.

@author Jesse Greenberg (PhET Interactive Simulations) @author Jonathan Olson <jonathan.olson@colorado.edu>

Class Hotkey¶

import { Hotkey } from 'scenerystack/scenery';

Constructor¶

new Hotkey( providedOptions : HotkeyOptions )¶

Instance Methods¶

onRelease( event : KeyboardEvent | null, interrupted : boolean, shouldFire : boolean )¶

On "release" of a Hotkey. All keys are released while the Hotkey is inactive. May also fire depending on events. See hotkeyManager.

interrupt()¶

Manually interrupt this hotkey, releasing it and setting a flag so that it will not fire until the next time keys are pressed.

dispose()¶

Instance Properties¶

keyStringProperty : TReadOnlyProperty<OneKeyStroke>¶

(readonly)

Straight from options

fire : ( event: KeyboardEvent | null ) => void¶

(readonly)

press : ( event: KeyboardEvent | null ) => void¶

(readonly)

release : ( event: KeyboardEvent | null ) => void¶

(readonly)

fireOnDown : boolean¶

(readonly)

fireOnHold : boolean¶

(readonly)

fireOnHoldTiming : HotkeyFireOnHoldTiming¶

(readonly)

allowOverlap : boolean¶

(readonly)

override : boolean¶

(readonly)

keyDescriptorProperty : TReadOnlyProperty<KeyDescriptor>¶

(readonly)

A Property for the KeyDescriptor describing the key and modifier keys for this hotkey from the keyStringProperty.

keysProperty : TReadOnlyProperty<AllowedKeysString[]>¶

All keys that are part of this hotkey (key + modifierKeys) as defined by the current KeyDescriptor.

isPressedProperty : TProperty<boolean>¶

(readonly)

A Property that tracks whether the hotkey is currently pressed. Will be true if it meets the following conditions:

1. Main key pressed
2. All modifier keys in the hotkey's modifierKeys are pressed
3. All modifier keys not in the hotkey's modifierKeys (but in the other enabled hotkeys) are not pressed

interrupted¶

(read-only for client code) Whether the last release (value during isPressedProperty => false) was due to an interruption (e.g. focus changed). If false, the hotkey was released due to the key being released.

Type HotkeyFireOnHoldTiming¶

import type { HotkeyFireOnHoldTiming } from 'scenerystack/scenery';

"browser" | "custom"

Type HotkeyOptions¶

import type { HotkeyOptions } from 'scenerystack/scenery';

• keyStringProperty: TReadOnlyProperty<OneKeyStroke>
  Describes the keys, modifier keys, and ignored modifier keys for this hotkey. This is a Property to support dynamic behavior. This will be useful for i18n or creating new keymaps. See KeyDescriptor for documentation about the key and modifierKeys.
• fire?: ( event: KeyboardEvent | null ) => void
  Called as fire() when the hotkey is fired (see fireOnDown/fireOnHold for when that happens). The event will be null if the hotkey was fired due to fire-on-hold.
• press?: ( event: KeyboardEvent | null ) => void
  Called as press() when the hotkey is pressed. Note that the Hotkey may be pressed before firing depending on fireOnDown. And press is not called with fire-on-hold. The event may be null if there is a press due to the hotkey becoming active due to change in state without a key press.
• release?: ( event: KeyboardEvent | null ) => void
  Called as release() when the Hotkey is released. Note that the Hotkey may release without calling fire() depending on fireOnDown. Event may be null in cases of interrupt or if the hotkey is released due to change in state without a key release.
• fireOnDown?: boolean
  If true, the hotkey will fire when the hotkey is initially pressed. If false, the hotkey will fire when the hotkey is finally released.
• fireOnHold?: boolean
  Whether the fire-on-hold feature is enabled
• fireOnHoldTiming?: HotkeyFireOnHoldTiming
  Whether we should listen to the browser's fire-on-hold timing, or use our own.
• fireOnHoldCustomDelay?: number
  Start to fire continuously after pressing for this long (milliseconds)
• fireOnHoldCustomInterval?: number
  Fire continuously at this interval (milliseconds)
• allowOverlap?: boolean
  For each main key, the hotkey system will only allow one hotkey with allowOverlap:false to be active at any time. This is provided to allow multiple hotkeys with the same keys to fire. Default is false.
• override?: boolean
  If true, any overlapping hotkeys (either added to an ancestor's inputListener or later in the local/global order) will be ignored.
• & EnabledComponentOptions

Source Code¶

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