Better shortcut key support

[andrew-oc]

Description

Existing shortcut key support falls a bit a short of being useful:

• When shortcutKeysConsumeInput is off, there is basically no shortcut key support at all. Shift+B will trigger bindings to just B and the application has no reasonable way of determining that a different key combination was pressed
• When all action maps are enabled (anecdotally the default for most users) event consumption causes confusion due to unintuitive behaviour. A Vector2 binding to WASD would consume the input of a binding to Ctrl+W when Ctrl+W is pressed.
• The application has no way to override the default event consumption

Changes made

• Composite bindings are now sorted by a priority system that comes from the bindings themselves, rather than as a count of the number of binding parts. In practice this means that for example a Vector2Composite binding does not have a higher priority than a one or two modifier composite binding i.e. pressing W to trigger a WASD action would not by default prevent a binding to Ctrl-W from performing.
• Added several APIs to allow application logic to control event handling/consumption.
  • CallbackContext.eventHandled can be used to check if a higher priority binding has already handled the current event
  • CallbackContext.HandleEvent() allows any 'performed' callback to set an input event as handled
  • InputAction.wasPerformedThisFrame(bool checkConflictingActions) allows polling code to determine if a higher priority binding has performed
  • InputBindingComposite.handleInputEvents allows applications to decide which composite bindings will handle events

Notes

This PR does not change the default behaviour of code that has InputSettings.shortcutKeysConsumeInput turned off i.e. no bindings are blocked due to event consumption. However it is possible that due to the differences in how controls are sorted within the state monitor code that some bindings will now be triggered in a different order than before.

Future work

We can build two interesting features on top of this PR:

• It would be possible to allow users to set the priority of bindings on an instance by instance basis, and hence fully control the order that bindings perform in
• The action grouping that this PR comes with would allow us to detect conflicting bindings that we could display in the input action asset editor as warnings or even detect at runtime for players rebinding controls.

Checklist

Before review:

• [x] Changelog entry added.
  • Explains the change in Changed, Fixed, Added sections.
  • For API change contains an example snippet and/or migration example.
  • FogBugz ticket attached, example ([case %number%](https://issuetracker.unity3d.com/issues/...)).
  • FogBugz is marked as "Resolved" with next release version correctly set.
• [x] Tests added/changed, if applicable.
  • Functional tests Area_CanDoX, Area_CanDoX_EvenIfYIsTheCase, Area_WhenIDoX_AndYHappens_ThisIsTheResult.
  • Performance tests.
  • Integration tests.
• [x] Docs for new/changed API's.
  • Xmldoc cross references are set correctly.
  • Added explanation how the API works.
  • Usage code examples added.
  • The manual is updated, if needed.

[andrew-oc]

There are a couple of suggested changes and I'd like to discuss with design/product before landing on develop as the preference would be to expand further to see what could be done to handle the common case [CTRL/SHIFT/ALT]+KEY overriding KEY (without impacting WASD in two places).

This PR changes things so that WASD is never impacted anywhere. Event consumption is still off by default, so no inputs will go missing, while still allowing users to check for shortcut keys, but even if event consumption is turned on, Vector2 controls (and 1DAxis) don't handle events by default, so they still won't be impacted. The only time you'll see a WASD getting blocked (out of the box) is when event consumption is on and a modifier is used with W A S or D keys.

[unity-cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[jfreire-unity]

Closing as it will not be merged.