Allow the new TapCallbacks API to recognize secondary mouse button clicks

[filiph]

Problem to solve

Allow desktop and web games to use the second mouse button. The right-click is a common input method for some games. Think deselecting in a city builder, issuing commands in an RTS, or secondary weapon fire in a top-down shooter.

Background

Flame is currently in transition from the TapDetector-Tappable API to the newer HasTappableComponents -TapCallbacks API. The old TapDetector API doesn't seem to work with the new CameraComponent API (at least I can't make it work - I always get screen coords, never game coords). The new API is better in every way, except that its callbacks don't give info about the button (primary / secondary / tertiary).

The new API's main workhorse class is HasTappableComponents (a mixin on Game). This class implements MultiTapListener, and that class is a facade to Flutter framework's MultiTapGestureRecognizer (code here).

The problem: Flutter's MultiTapGestureRecognizer doesn't have a concept of the right click. If Flame uses MultiTapGestureRecognizer as the underlying API, it cannot support secondary mouse button action.

Proposal

I'm not sure where the new API is heading, so I can only offer a newcomer's view. I'm guessing I would add a new class, SingleTapListener, that closely follows MultiTapListener in functionality. This class would be "the new TapDetector" — it would forward events from Flutter's TapGestureRecognizer, but in the new way that respects the CameraComponent.

The old TapDetector and the new SingleTapListener would likely have to be exclusive (you either implement from one or the other).

HasTappableComponents would then implement the new SingleTapListener alongside the MultiTapListener, and would send the event down (like so).

The TapDownEvent class would gain a new member, pointerEvent, which would just copy Flutter's PointerEvent. This const class has everything anyone could need, including pressure, tilt, kind, buttons, etc. The primary / secondary / tertiary button is easily extracted from PointerEvent.buttons.

More information

• This has been discussed on Discord here and here
• I'm very new to the codebase but I'm willing to have a stab at it. I do need someone to give me the blessing. As I mentioned, I have no idea where the new API is heading. I might be misreading the direction.

[filiph]

Actually, since MultiTapListener already takes care of so much, maybe all we need is a SecondaryTapListener? Basically just keeping MultiTapListener to be the hero, just adding the extra case for secondary / tertiary buttons.

[filiph]

Just saving the Discord discussion with @st-pasha for posterity, as I'm sure it will come in handy, and Discord eats older messages AFAIK.

As far as I can see (https://docs.flame-engine.org/main/flame/inputs/tap_events.html), the MultiTouchTapDetector already detects right-click events (though it doesn't stop the browser's context menu, so maybe there is something we can do about that). However, the information about which mouse button was clicked is not propagated to the end user. So perhaps we should fix that. They do have that information, but it's in the private map, so not accessible. What we can do though is to drive from MTGR, leaving all implementation as is, but storing the event in a public map. Then the event handler can pull that info from the map and store it in the Tap*Event that we pass to the end user. The class has addAllowedPointer method (https://api.flutter.dev/flutter/gestures/MultiTapGestureRecognizer-class.html), which receives an event that has this info in event.buttons field. So overriding that method and storing the event will give you access to that info & more