mouse-buttons doesn't distinguish between click, command-click, & option-click

[rigdern]

Click, command-click, and option-click are currently indistinguishable because mouse-buttons returns 2 for all three cases.

Expected behavior according to docs

This is the expected behavior of mouse-buttons according to page 164 of Boxer Manual V2:

mouse-buttons	Meaning	Unix meaning
0	No buttons	No buttons
1	Option-mouse-click	Left
2	Mouse	Middle
4	Command-mouse-click	Right

(When the documentation says "Unix" what is it contrasting against? Mac? Windows?)

Observed behavior

Here's the behavior I saw in Boxer 3.4.18 2024-05-26 on macOS on a MacBook Air.

Input	Actual mouse-buttons	Expected mouse-buttons
✅ No buttons	0	0
❌ Option-mouse-click	2	1
✅ Mouse click	2	2
❌ Command-mouse-click	2	4
??? Two finger tap on trackpad (right-click)	18	Not sure. 4?

Additionally, shift-click seems to cause the value of mouse-buttons to persist. Is this documented?

Repro file

To try the mouse experiments for yourself:

1. Download mouse buttons demo.box.zip, unzip it, and open mouse buttons demo.box.
2. In Boxer, click the mouse buttons demo box to navigate into it.
3. Run the doit box named go. Now Boxer will monitor your mouse clicks indefinitely.
4. Try different mouse clicks (e.g. click, option-click, command-click). The value of mouse-buttons is shown in the buttons box.

When you're done, stop Boxer's execution by choosing the menu item "Do > Stop" (Ctrl-.)

Here's a screenshot of how this looks:

Impact

This prevents the user from being able to set the velocity and acceleration vectors to zero (via command-click) when flying the Apollo Missions in the Vectors Demo microworld.

[cben]

Comment on documented behavior: mapping regular click on Mac = middle click on Unix is weird. The "regular" button on unix is certainly the left.

Nowdays middle click on most mice is done by depressing the scroll wheel, so it's the least-convenient of the 3 buttons (and tends to emit extra scroll events).

[sgithens]

I need to review the docs still on this one... the terminology in the manual might be a bit old, but the mapping between all three platforms should be the same at this point. I believe we're always mapping regular to left as well, although ideally at some future point in time we'd take into account the OS accessibility settings, which allow you to swap them around. However, but the times the clicks get to us, this remapping may have already taken place in our gui bindings.