Add ScreenSpaceEventHandler support for multiple KeyboardEventModifier keys

[Bob-vdV]

Description

This pull request adds the functionality to add a listener for mouse events with multiple modifier keys, like this:

viewer.screenSpaceEventHandler.setInputAction(
  () => console.log("Hello alt+shift"),
  ScreenSpaceEventType.LEFT_DOWN,
  [KeyboardEventModifier.ALT, KeyboardEventModifier.SHIFT],
);

This allows devs to define complex shortcuts that don't interfere with the default camera controls.

Single modifier keys are also supported as before.

Issue number and link

#13300

Testing plan

Behaviour tested in a simple sandcastle: localhost link

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

[github-actions]

Thank you for the pull request, @Bob-vdV!

✅ We can confirm we have a CLA on file for you.

[javagl]

From very quickly looking over that (I haven't thought it through, just a potential heads-up), it looks like it could make a diference whether someone is using
setInputAction( ... , [KeyboardEventModifier.ALT, KeyboardEventModifier.SHIFT]) or
setInputAction( ... , [KeyboardEventModifier.SHIFT, KeyboardEventModifier.ALT])
(or am I overlooking a place where this is made order-independent?)

[Bob-vdV]

From very quickly looking over that (I haven't thought it through, just a potential heads-up), it looks like it could make a diference whether someone is using setInputAction( ... , [KeyboardEventModifier.ALT, KeyboardEventModifier.SHIFT]) or setInputAction( ... , [KeyboardEventModifier.SHIFT, KeyboardEventModifier.ALT]) (or am I overlooking a place where this is made order-independent?)

In getInputEventKey I added modifiers.sort() to fix the order dependence:
https://github.com/CesiumGS/cesium/pull/13307/changes#diff-8df297d7dad4c6a903f50ff5a01cc7d38d66e66d5dfa1532f983b4be0d36b5adL25-R39

[javagl]

modifiers.sort() to fix the order dependence:

I had indeed overlooked that. That should prevent any issues here. Sorry for the noise.

[jjspace]

Thanks for the PR @Bob-vdV! Overall this seems to be the change I was expecting. However (as I also suspected) an old bug of the camera getting "stuck" moving has cropped back up. (See #11903, #11889 and #2522) I assume the fix is related or the same as #12073 and just needs to account for the mouse up of more modifier types/combos. Please take a look into it and let us know if you need help tracking it down.

Reproduce

• Open your test sandcastle or this one with all modifier combos
• Press mouse down and start dragging
• Press and hold Ctrl+Shift and continue dragging - movement should stop
• Release the mouse
• Release Ctrl+Shift and notice the camera is "stuck" moving with the mouse

[Bob-vdV]

The bug seems to be fixed now by adding a few more listeners in the CameraEventAggregator constructor:

  const modifierCombinations = [
    [KeyboardEventModifier.SHIFT, KeyboardEventModifier.CTRL],
    [KeyboardEventModifier.SHIFT, KeyboardEventModifier.ALT],
    [KeyboardEventModifier.CTRL, KeyboardEventModifier.ALT],
    [
      KeyboardEventModifier.SHIFT,
      KeyboardEventModifier.CTRL,
      KeyboardEventModifier.ALT,
    ],
  ];

  modifierCombinations.forEach((modifiers) => {
    listenToWheel(this, modifiers);
    listenToPinch(this, modifiers, canvas);
    listenMouseButtonDownUp(this, modifiers, CameraEventType.LEFT_DRAG);
    listenMouseButtonDownUp(this, modifiers, CameraEventType.RIGHT_DRAG);
    listenMouseButtonDownUp(this, modifiers, CameraEventType.MIDDLE_DRAG);
    // listenMouseMove(this, modifiers);
  });

link

When // listenMouseMove(this, modifiers); is uncommented it breaks again with the same behavior as before, so I think something goes wrong in listenMouseMove.

@jjspace do you have an idea on what is the cause of this bug?

[Bob-vdV]

@jjspace The bug should be fixed now.

I noticed that getKey in CameraEventAggregator and getInputEventKey in ScreenSpaceEventHandler are the same, could they be refactored to use a single function?