Maptool: Horizontal Scrolling on macOS

[mrkwnzl]

Describe the bug
A follow-up to #413 so that it’s tracked here. On macOS, horizontal scrolling on the trackpad or Apple mice seems to be mapped to vertical scrolling (i.e., scrolling right scrolls up, scrolling left scrolls down).

On the map, this results in conflicting behavior when scrolling diagonally (even slightly) right-up (as scrolling right zooms in while scrolling up zooms out) or left down (vice versa).

In frames with scroll bars (every kind of window with scroll bars, actually), this also leads to conflicting behavior analogous to zooming. I cannot scroll left and right with the mouse wheel in frames, only up and down. I need to use the scroll bar.

Expected behavior
Scrolling left and right should not be mapped to scrolling up and down, respectively. On the map, scrolling left and right should do nothing. In windows with scroll bars, I should be able to scroll left or right by scrolling left or right.

MapTool Info

• Version: 1.5.13
• Install: Upgrade 1.5.12

Desktop (please complete the following information):

• OS: macOS
• Version 10.15.3

[Azhrei]

The macOS JRE implements horizontal scrolling by holding down the Shift key for you and then generating normal wheel up/down events. The patch/solution for #413 was to filter out the Shift key in MapTool's top-level event queue dispatcher so that wheel events _never_ included them, then add the Shift back in if the user was _actually holding down the Shift key_. (This means horizontal scrolling still works if the user holds down the Shift key; also, MapTool can accurately determine if the Shift key is, in fact, being held down rather than being "faked".)

I don't have a solution. Perhaps someone else can give this some thought?

Note: BasicScrollPaneUI.Handler normally does the actual event handling for frames and it checks to see if the Shift key is down to determine whether to perform horizontal scrolling (MouseWheelEvent doesn't intrinsically support horizontal scrolling, hence the use of a modifier to indicate it).

[mrkwnzl]

A less confusing way at least for me as a user, would be to deactivate horizontal scrolling completely, if at all possible. We wouldn’t lose much (as horizontal scrolling doesn’t work as expected right now anyway), and the conflicts would be resolved. Most Windows users don’t have horizontal scrolling, so there aren’t that many actual useful functions for horizontal scrolling in MapTool.

Holding the shift key also maps vertical scrolling to horizontal scrolling, so there the problem also occurs, just in a different direction.

[Azhrei]

I'd be fine with that (I don't use it much), and it would be simple to do.

[mrkwnzl]

Would it be similarly easy to just deactivate the fake shift press? I could see a horizontal scrolling by pressing shift and scrolling up and down (much like with a regular mouse wheel) as still being useful in some situations.

[Azhrei]

So you want horizontal wheels events removed, but only when the physical Shift key isn't actually down? And when the physical key _is_ down, allow the horizontal wheel event to be processed normally?

That should work (I think) and won't be difficult.

Any other macOS users with input on this issue?

[mrkwnzl]

Depends on what you mean by “processed normally.”

If I understood correctly, the JRE doesn’t support horizontal scrolling. So to avoid weird workarounds, MapTool could ignore horizontal scrolling altogether and could be controlled just like it would be with a mouse which doesn’t allow horizontal scrolling (the average mouse wheel).

Functionally, this would be the same as using a mouse without horizontal mouse wheel. If one wants to scroll horizontally, one needs to physically press the shift key and scroll up or down.

I think it would be a bit weird (and probably not as easy to implement) if pressing shift would allow actually scrolling horizontally on the trackpad. In this case, you’d need to deactivate vertical scrolling, or you’d end up with the same conflict between scrolling horizontally and vertically.

This isn’t easy to describe. Sorry about that. Take away message: I would be satisfied if MapTool behaved just like it would if it was controlled with a mouse which doesn’t support horizontal scrolling. That would include pressing the shift key to scroll horizontally by moving the fingers vertically on the trackpad or mouse.

[mrkwnzl]

I just found a feature breaking bug, which I believe is related to this. The size of the token layout in “Edit Token > Config > Layout” is controlled via mouse wheel. On macOS, I can zoom in but not zoom out reliably. Thus, I can make the token bigger but not smaller, most of the time. There’s the same glitchiness as there is when zooming on the map, which is why I believe that this is related to this issue.

If so, removing horizontal scrolling via mouse wheel should fix that.

[Azhrei]

Thanks for the input. I’ll test this myself and then make the change and see what effect it has. I should get to this today.

[mrkwnzl]

Thanks a lot!

[Azhrei]

I've got a fix for this, but I'm going to check for all other locations where similar code appears. (It appears that the mouse wheel code assumes the wheel had to move and doesn't expect the rotation to be zero. But the hi-res mice that Apple uses (and presumably others?) can trigger fractional movements. The existing code assumes _any_ movement is enough to trigger a scale change and that leads to weird results.)

[Phergus]

Tested #1500 under Windows 10. Mouse wheel functions for scrolling in panels and lists, zooming in maps, token config & vbl, rotation of assets on map, setting facing all working as before.

[Phergus]

@mrkwnzl Can you test from source?

[mrkwnzl]

@Phergus I’d be more than happy to, but I’d need someone explain to me how I do that on Mac. It’s been years since I compiled something from source and never a Java application.

EDIT: I’ll ask on Discord. I’m sure there’s someone who can help me a bit with that!

[mrkwnzl]

Craig on Discord provided me with a test build. It works great whenever I use the mouse wheel only, but in instances in which I need to press shift, both horizontal and vertical scrolling still work in partly conflicting behavior.

Zooming on the map, scrolling when only one scroll bar is present, changing the size of the token layout in Edit Token all work really great and as expected. Horizontal scroll movement does nothing, as it should. All the glitchy behavior when I accidentally scrolled just a little bit horizontally in the wrong direction is gone!

Set facing and scrolling horizontally when there’s also a vertical scroll bar (example: long lists for Sight and Light in the Campaign Properties) require the use of the shift key plus mouse wheel. In these instances, it works as before, including glitchy behavior when scrolling to or from the upper right corner of the mouse or trackpad. I would expect that I simply press shift and use the mouse wheel vertically to scroll horizontally or set the facing. Pressing shift and horizontal mouse wheel movement should do nothing.

[Phergus]

(example: long lists for Sight and Light in the Campaign Properties) require the use of the shift key plus mouse wheel.

Has it always been that way? Having to use Shift to to scroll in those panels? The shift key is required under Windows. Or is this still a bug related to the hires mice?

[mrkwnzl]

This is a bit complicated and not macOS default behavior, but as far as I can tell, it’s a bug.

The examples I mentioned require the shift key if there are both horizontal and vertical scroll bars present. If there is either only a horizontal or vertical scroll bar, vertical mouse wheel movement controls it. For example, if the list in Light is short, there’s only a horizontal scroll bar. Vertical mouse wheel movement scrolls that bar horizontally. No shift key required, although this is a bit unconventional (horizontal scrolling with vertical mouse wheels movement).

If the list is longer, a vertical scroll bar appears, so that there are now both horizontal and vertical scroll bars. If I now scroll vertically on my mouse, I scroll the list vertically. If I press shift, I scroll horizontally, no matter the scroll direction on my wheel.

I think that the behavior should be as it is on windows, as that’s more consistent: No horizontal scrolling without pressing shift and you scroll horizontally by pressing shift and use vertical mouse wheel movement. Horizontal mouse wheel movement should do nothing, regardless of whether shift is pressed or not.

[Phergus]

Very helpful. Thanks!

[Azhrei]

Zooming on the map, scrolling when only one scroll bar is present, changing the size of the token layout in Edit Token all work really great and as expected. Horizontal scroll movement does nothing, as it should. All the glitchy behavior when I accidentally scrolled just a little bit horizontally in the wrong direction is gone!

Great.

Set facing and scrolling horizontally when there’s also a vertical scroll bar (example: long lists for Sight and Light in the Campaign Properties) require the use of the shift key plus mouse wheel. In these instances, it works as before, including glitchy behavior when scrolling to or from the upper right corner of the mouse or trackpad.

I didn't see the glitches, but I'll play with it some more.

I would expect that I simply press shift and use the mouse wheel vertically to scroll horizontally or set the facing.

It should still work like that right now — are you saying you observed that it did not?

Pressing shift and horizontal mouse wheel movement should do nothing.

I don't understand this one. For other platforms, as Phergus says, the Shift key is required for horizontal scrolling (which I don't completely understand; I'll need to read some Windows docs, I think). If the user is holding down the Shift key and using vertical scrolling to move horizontally, why not allow horizontal movement to continue to work? That seems more intuitive to me...?

[mrkwnzl]

I didn't see the glitches, but I'll play with it some more.

I’ll try to make a quick screencast of it to show you what I mean.

If the user is holding down the Shift key and using vertical scrolling to move horizontally, why not allow horizontal movement to continue to work? That seems more intuitive to me...?

The problem is that both horizontal and vertical movement work, which results in conflicting behavior. If the vertical movement says right, while the horizontal says left, it starts to glitch. That happens if I scroll from down-left to up-right on the trackpad. On a mouse it’s rather difficult to scroll in such a way that only vertical or horizontal movement is triggered, as the mouse is so sensitive.

For consistency, I’d say that it’s better to ignore horizontal movement altogether. How would you explain that in two instances you have to press shift and scroll left or right when the rest of the time you have to scroll up or down? Saying that horizontal scrolling does not work and you have press shift while scrolling is easy.

[mrkwnzl]

Okay, here’s a screen recording. There are four kinds of scrolling to see.

First: I scrolled on a 45° degree from the upper-left corner to the lower-right corner on my trackpad.

Second: I pressed shift and scrolled on a 45° degree from the upper-left corner to the lower-right corner on my trackpad.

That’s how it’s supposed to look like.

Third: I scrolled on a 45° degree from the upper-right corner to the lower-left corner on my trackpad.

Fourth: I pressed shift and scrolled on a 45° degree from the upper-right corner to the lower-left corner on my trackpad.

Now MapTool received conflicting commands, resulting in the glitched out behavior.

Glitchy Scrolling.mov.zip

[Azhrei]

The problem is that both horizontal and vertical movement work, which results in conflicting behavior. If the vertical movement says right, while the horizontal says left, it starts to glitch. That happens if I scroll from down-left to up-right on the trackpad. On a mouse it’s rather difficult to scroll in such a way that only vertical or horizontal movement is triggered, as the mouse is so sensitive.

You're saying that if all physical horizontal events are turned off and only Shift+vertical is used on the device, the effect you're seeing would disappear...

So, if the event arrives from the OS with Shift+vertical, then it's a physical horizontal event and should be discarded, regardless of the state of the actual Shift key. If instead we detect a manual KeyPress of Shift and vertical movement, treat it as horizontal by allowing it to propagate. Yes, that should be doable. I'll get a new PR submitted shortly.

[Azhrei]

Ah, great job with the screencast, btw. A perfect example. Thanks! 🙂

[mrkwnzl]

Maybe I should have done that much sooner 😄

[Phergus]

@cwisniew Do you want to test this on your end or get @mrkwnzl a build to test?

[Azhrei]

@JamzTheMan also has a Mac to test with...

[mrkwnzl]

If someone could make a test build like the last time, I’ll gladly test it.

[JamzTheMan]

I do but I don't always keep it updated because it is my work laptop.

Kicking off builds are easier. Eventually we will get done nightly builds going...

[Phergus]

@mrkwnzl There is a 1.7.0 alpha build with this fix. Give it a test when you get a chance.
https://github.com/RPTools/maptool/releases/tag/1.7.0-alpha-1

[mrkwnzl]

I just tested it using 1.7.0 Alpha 1. Thanks for the build!

Horizontal mouse wheel movement without pressing shift does not trigger any scrolling. Works as expected.

Horizontal mouse wheel movement while pressing shift (e.g. to scroll horizontally in a frame or to change the facing of a token) still triggers the scrolling, as does vertical mouse wheel movement while pressing shift. The conflicting behavior (as demonstrated in the screencast above) is still present while pressing shift.

[mrkwnzl]

I think figured out why this happens. I’m not a programmer, so I don’t have the right vocabulary. I did however install the JDK and IntelliJ, so that I can play around a bit and test the most recent builds, using my basic Java skills from 12 years ago. I’ll try to explain the best I can. In #1508 there are these lines of code:

if (mwe.isShiftDown() && MapToolEventQueue.shiftState != 1) {
         return;
         }

What this says is to ignore horizontal mouse wheel events as long as the shift key is not pressed. As soon as shift is pressed (physically), it reverts to the old behavior before all these mouse wheel changes (which seems to be the Java default behavior–IntelliJ has the same glitchy scrolling behavior, albeit not as severe). Problem is that Java doesn’t seem to make the distinction between a physical shift press and the virtual shift press that occurs on horizontal mouse wheel events.

If the code is changed to

if (mwe.isShiftDown()) {
         return;
         }

it deactivates mouse wheel events when shift is pressed either physically (in which case it deactivates all mouse wheel events) or virtually (in which case it deactivates only horizontal mouse wheel events, as vertical mouse wheel events don’t press shift virtually). So mwe.isShiftDown does not distinguish between physical shift presses and virtual ones.

I don’t know if there’s a way to make MapTool distinguish between physical and virtual shift presses. In case there isn’t, I propose an accessibility option: “macOS Mouse Wheel Compatibility,” which activates the second code above. What it does is to deactivate horizontal scrolling, period. It has the side effect that the facing can’t be set with the mouse wheel and you can’t scroll horizontally in windows with wider content. But both have alternatives already in place (set facing with right-click and dragging the horizontal scroll bar), and it fixes all conflicting behavior. All other functions of the shift key still work (like resizing tokens with a fixed ratio, selecting multiple tokens) and other functions of the mouse wheel also still work (like zooming and scrolling vertically), as long as you don’t press shift simultaneously.

Because of the side effects, it can’t be made the default as I believe it would also affect Windows and Linux, which is not desired. If setting the facing with the mouse wheel is deemed very important, it could be set to option+mouse wheel if “macOS Mouse Wheel Compatibility” is set.

What do you think?

[Azhrei]

Yep, that’s the line that needs to change.

I’m not sure about the need for an accessibility option. Linux uses BUTTON4 and 5 to indicate horizontal scrolling and Windows does something else (I don’t remember right now).

However, if the shift key is down on those platforms AND the user is attempting hit horizontal scroll, the change you propose would eliminate the event. I don’t think that is correct.

So the event should only be removed if the event says the shift key is down but the keyboard state says it isn’t (hence, the second half of the IF statement). But that means if the shift key IS down, the horizontal scroll event is not thrown away, and that leads to the behavior you’re seeing.

You may be right — I think I just convinced myself that an option is needed. 🤔 I was trying to find a way to do it that didn’t require a setting from the user.

Maybe that’s still possible, though. If the event says there’s a shift key down and the keyboard says there isn’t, then this “macOS compatibility” option you’re talking about could automatically be turned on (since the system must be macOS with a hires mouse). Of course, there’s always the MapTool.isMacOS() function (or whatever it’s called), but as I said, I was trying not to use that. Perhaps it’s time to, though...

[mrkwnzl]

If the event says there’s a shift key down and the keyboard says there isn’t, then this “macOS compatibility” option you’re talking about could automatically be turned on (since the system must be macOS with a hires mouse).

Hm, but the flip side would be that if the event says shift key down and the keyboard also says shift key down, the option would be off, right? Then we have the exact behavior that #1508 produces. What am I missing here?

I’m impartial about whether this is set automatically for macOS via a isMacOS function or via user preference. I assumed that this changes the behavior so drastically that it shouldn’t be the default, but then again, who on a Mac wouldn’t want to set it?

[Azhrei]

If the event says there’s a shift key down and the keyboard says there isn’t, then this “macOS compatibility” option you’re talking about could automatically be turned on (since the system must be macOS with a hires mouse).

Hm, but the flip side would be that if the event says shift key down and the keyboard also says shift key down, the option would be off, right? Then we have the exact behavior that #1508 produces. What am I missing here?

The automated code never turns it off, only on.

I’m impartial about whether this is set automatically for macOS via a isMacOS function or via user preference. I assumed that this changes the behavior so drastically that it shouldn’t be the default, but then again, who on a Mac wouldn’t want to set it?

I think I agree. But I’m still not sure what the IF statement should be.

The condition “macOS && event has shift key” isn’t enough, because the physical shift key could be down. We could do “macOS && event has shift && not physical shift”, but that’s the condition we have now.

Damn, it was stupid of the Apple JVM to turn on the shift key for horizontal scroll events!! And I don’t think we can change that — it'll be buried in the platform code. But it might be informative to see how Obj-C code receives mouse scroll events (to know whether the OS does the this or whether it’s the JVM); or maybe the JVM has a way to change how this works...

[Azhrei]

I've been playing with this... It seems that Apple's own apps can distinguish horizontal scrolling vs. shift key+vertical scrolling. For example, in Safari, I can swipe left/right to scroll horizontally, but if I hold down the shift key and scroll vertically, the shift key is ignored and the vertical scrolling occurs.

This tells me that the app can tell the difference between h.scroll and v.scroll+shift key. I just don't know how yet. I'm currently reading about mouse/trackpad event handling on Apple's web site. I'll post again when I find something definitive.

[mrkwnzl]

The automated code never turns it off, only on.

Ah, I see. I think using a isMacOS function is more elegant, unless there are some downsides to it I don’t know about. And it couldn’t be a user setting as it would be confusing when it turns itself on.

But I’m still not sure what the IF statement should be.

I think ”isMacOS() && mwe.isShiftDown()“ would suffice. I think we can’t find a way to exclude the physical shift press. If we did, the option wouldn’t be needed.

[JamzTheMan]

FWIW it may be worth trying with JDK 14 and see if the latest java maybe fixes or maybe helps?

I have a build on my repo and will be pushing the branch over to rptools today.

[Azhrei]

I have installed OpenJDK 14 and when I'm back to my laptop, I'm going to grab the source code for the macOS port (if I can figure out what the URL is for the mercurial clone).

Trying to find out whether the macOS GUI did something special was not fruitful. It appears that the event that the OS generates has other flags that don't appear in the AWTEvent, such as SystemGenerated. I'm betting those are seen by Obj-C apps but the JVM doesn't use them.

Anyway, I will look at this more over the next few days, but I've got a couple deadlines for this week so it'll be "as time permits". I definitely want a solution, though!
—
Frank Edwards
Edwards & Edwards Consulting, LLC
Hours: 10A-6P ET
Phone: [phone] (office, mobile, and SMS texts)

No electrons were harmed in the creation or transmission of this message.

On Apr 26, 2020, at 11:48 AM, Jamz [e-mail] wrote:


FWIW it may be worth trying with JDK 14 and see if the latest java maybe fixes or maybe helps?

I have a build on my repo and will be puahing the branch over to rptools today.

—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub, or unsubscribe.

[mrkwnzl]

In the meantime, I tested AppUtil.MAC_OS_X && mwe.isShiftDown() and it works as I described above.

Would it be sensible to use this until a better solution is found? I don’t know how the etiquette about this is. Would you want me to push this to the repository for review?

[Phergus]

Fork the repo (which you did), make a branch off of develop and commit your fix to your local repo, push up to your fork and then do a Pull Request from there (Github should prompt you on this) back o develop on the rptools repo.

[Azhrei]

Isn't there a function instead of checking AppUtil directly? If so, please use that.

And what is the IF statement you're using? I don't see how it can work to allow horizontal scrolling at all, since holding down the physical shift key will result in mwe.isShiftDown() returning true...

[mrkwnzl]

Fork the repo (which you did), make a branch off of develop and commit your fix to your local repo, push up to your fork and then do a Pull Request from there (Github should prompt you on this) back o develop on the rptools repo.

Right. Thanks for that.

Isn't there a function instead of checking AppUtil directly? If so, please use that.

I haven’t found a function. Any hint on where I should look?

And what is the IF statement you're using? I don't see how it can work to allow horizontal scrolling at all, since holding down the physical shift key will result in mwe.isShiftDown() returning true...

} else if (event instanceof MouseWheelEvent) {
        MouseWheelEvent mwe = (MouseWheelEvent) event;
        if (AppUtil.MAC_OS_X && mwe.isShiftDown()) {
          return;
        }
      }

That’s the relevant portion. You’re right, it prevents horizontal scrolling. With this, there is no horizontal scrolling in MapTool ever on Macs.

[Azhrei]

You’re right, it prevents horizontal scrolling. With this, there is no horizontal scrolling in MapTool ever on Macs.

Ah. And you must be alright with that or you wouldn't have suggested it. You also can't change facing using the mouse wheel at all with this patch. The arrow keys would still work, though.

I was trying to still preserve horizontal scrolling. But this is a fine interim solution because a true solution may never be found. 😐

[mrkwnzl]

Yeah, I’m alright with this. As mentioned above, the two only instances in which horizontal mouse wheels are important are facing and scrolling, both can be achieved without the mouse wheel. I prefer to avoid the glitches, but that’s why I initially proposed a user setting, in case anyone preferred the current behavior.

[mrkwnzl]

Submitted pull request #1707. That was the first time I did that. Let me know if I did something wrong there, please.

[Phergus]

Not seeing any impact on Windows so far. Facing working as expected. Locked aspect when resizing working.

[Phergus]

Calling this good. Corrections can be made if alpha/beta testing reveals new issues.

[Phergus]

@mrkwnzl Can you test the UI changes in the i1635-fix-ui-decorations branch under MacOS?

Alternatively there is also a test build here but Travis didn't like the tag name and so you'll have to use the JAR version.

[mrkwnzl]

@Phergus Sure thing.