Use KeyboardListener instead of globalKeyStateTracker and custom listeners

[jessegreenberg]

Searching for globalKeyStateTracker. keydown:, and keyup: I found this list of files that might be improved by using KeyboardListener:

• EFACIntroScreenView.js (keydown, keyup) @jbphet
• MagnetAutoSlideKeyboardListener.js (keydown, keyup) @jbphet
• FaradaysLawKeyboardDragListener.js (keyup) @jbphet - (didn't update this one, here's why not).
• PhetMenu.ts @jessegreenberg
• PreferencesDialog.ts @jessegreenberg
• PreferencesTabs.ts @jessegreenberg
• GrabDragInteraction.js @jessegreenberg
• AquaRadioButtonGroup.ts @jessegreenberg
• ComboBoxListBox.ts @jessegreenberg
• Dialog.ts @jessegreenberg
• BothHandsInteractionListener.ts @zepumph
• AccessibleNumberSpinner.ts @jessegreenberg - Not a good candidate for KeyboardListener. Adds other alt input listeners and replacing is more effort than it is worth. People will not go here to look for an example, this is an internal implementation.
• AccessibleValueHandler.ts @jessegreenberg - Same as AccessibleNumberSpinner.
• WaveGameLevelNode.ts @pixelzoom - moved to Replace globalKeyStateTracker with KeyboardListener fourier-making-waves#237
• localeProperty.ts @samreid @zepumph necessary usage of globalKeyStateTracker (no Node close by)
• phetioDevSaveLoad.ts @samreid @zepumph - necessary usage of globalKeyStateTracker (no Node close by)
• Display.ts @jessegreenberg - necessary usage of globalKeyStateTracker
• AnimatedPanZoomListener.js @jessegreenberg - necessary usage of globalKeyStateTracker
• PlayControlButton.ts @jessegreenberg

Important notes:

• Remember to dispose the listener, if you need to.

Examples:

globalKeyStateTracker was often used to add support for global hotkeys. It is better to use KeyboardListener now for this case. Here is an example of the old style an an example switching to KeyboardListener.

Old style

globalKeyStateTracker.keydownEmitter.addListener( event => {

  // Make sure this Node is visible, pdomVisible, and enabled for input.
  if ( this.pdomDisplayed && this.enabledProperty.value ) {
    if ( KeyboardUtils.isKeyEvent( event, KeyboardUtils.KEY_ESCAPE ) ) {
      // Escape
      ...
    }
    else if ( globalKeyStateTracker.altKeyDown && KeyboardUtils.isKeyEvent( event, KeyboardUtils.KEY_C ) ){
      // Alt+C
      ...
    }
  }
} );

Using KeyboardListener

const keyboardListener = new KeyboardListener( {
  keys: [ 'escape', 'alt+c' ],
  callback: ( event, listener ) => {
    if ( listener.keysPressed === 'escape' ) {
      // escape key was pressed
    }
    else if ( listener.keysPressed === 'alt+c' ) {
      // alt+c were pressed
    }
  },
  
  // By making this listener "global" it will fire no matter where focus is in the document as long as
  // myNode is visible and has input enabled. If this is false, callback will only fire when myNode has keyboard focus.
  global: true
} );

myNode.addInputListener( keyboardListener );

Often, a custom input listener was used for keydown and keyup events added to a particular Node. It might be better to use KeyboardListener for these for now.

Old style

    preferencesTabs.addInputListener( {
      keydown: event => {
        if ( KeyboardUtils.isKeyEvent( event.domEvent, KeyboardUtils.KEY_DOWN_ARROW ) ) {
          this.focusSelectedPanel();
        }
      }
    } );

Using KeyboardListener

    preferencesTabs.addInputListener( new KeyboardListener( {
      keys: [ 'arrowDown' ],
      callback: () => {
        this.focusSelectedPanel();
      }
    } ) );

[jessegreenberg]

• localeProperty.ts

This one is for ?keyboardLocaleSwitcher. Since there is no view component to add a listener to, using the global globalKeyStateTracker is probably best but curious if @samreid has an opinion so Ill put his name next to that one. An alternative could be to move this code to a view component, but that is not a big improvement in my opinion.

EDIT: Similar story for phetioDevSaveLoad.ts

[pixelzoom]

I've attempted to follow the example provided, and it's not working in fourier-making-waves WaveGameLevelNode. So I'm moving that conversion to phetsims/fourier-making-waves#237.

[jbphet]

Can a static list of range keys be added that would parallel the functionality we previously got from KeyboardUtils.isRangeKey()?

[jessegreenberg]

Can a static list of range keys be added that would parallel the functionality we previously got from KeyboardUtils.isRangeKey()?

Thanks @jbphet, I added functions for this in the above commit. They are exported from EnglishStringToCodeMap.

[jessegreenberg]

Regarding #1126 (comment), after seeing the usage in phetsims/energy-forms-and-changes@3a708eb, I changed it a little. Functions and constants were moved to EnglishStringKeyUtils.

[jbphet]

I changed the ones assigned to me with the exception of FaradaysLawKeyboardDragListener. This one is a drag listener rather than a general keyboard listener, and it extends KeyboardDragListener, which doesn't appear to be deprecated or anything. In other words, it doesn't seem like an improvement to migrate this one, so I'm not going to.