Enable Multi-MouseButton Support for dragPan

[gottesman]

trafficstars

This PR enhances the functionality of dragPan in MapLibre GL JS, addressing feature request #5341. It introduces the ability to configure one or multiple mouse buttons for the dragPan interaction using the MouseEvent.button property.

Previously, dragPan was limited to left mouse button, restricting user interaction and personalization. This improvement provides greater flexibility for users who want to customize the drag behavior of the map.

Examples

1. Configuring on Map Initialization:

const map = maplibregl.Map({
    container: 'map',
    dragPan: {
        buttons: [0,1]  // Enable left button (0) and middle button (1)
    }
});

2. Updating on DragPan Enable:

map.dragPan.enable({
    buttons: [1]  // Enable only middle button (1)
})

Launch Checklist

• [x] Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
• [x] Briefly describe the changes in this PR.
• [x] Link to related issues.
• [ ] Include before/after visuals or gifs if this PR includes visual changes.
• [ ] Write tests for all new functionality.
• [ ] Document any changes to public APIs.
• [ ] Post benchmark scores.
• [ ] Add an entry to CHANGELOG.md under the ## main section.

[codecov[bot]]

Codecov Report

:x: Patch coverage is 86.11111% with 5 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 91.83%. Comparing base (f1d58f2) to head (921a48c). :warning: Report is 569 commits behind head on main.

Files with missing lines	Patch %	Lines
src/ui/handler/drag_handler.ts	62.50%	3 Missing :warning:
src/ui/handler/drag_move_state_manager.ts	91.66%	1 Missing :warning:
src/ui/handler/mouse.ts	92.30%	1 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5354      +/-   ##
==========================================
- Coverage   91.84%   91.83%   -0.02%     
==========================================
  Files         282      282              
  Lines       38908    38930      +22     
  Branches     6827     6831       +4     
==========================================
+ Hits        35735    35750      +15     
- Misses       3046     3052       +6     
- Partials      127      128       +1     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[HarelM]

How will this behave when rotating with right click (default behavior) and setting drag pan to right click?

[HarelM]

Any updates on the feedback and questions I asked?

[jiacona]

Hi @HarelM, I also need this functionality and am most of the way to an implementation that addresses your comments here. Should I just open a new PR?

[HarelM]

My main concern about this feature is button collision when you override one gesture and "cancel" other gesture.

[jiacona]

Yes, I can see how you could run into problems if the predicate you use conflicts with another handler. Is it rotate, pitch, and roll you are concerned about?

I was thinking it would be simple enough to allow specifying a checkCorrectEvent predicate for each of the different handlers. That way if you want to customise one, you can also customise any others that might conflict with your new predicate.

[HarelM]

There's a few more handlers: zoom, context menu, scroll, two finger gesture/block. I think adding configuration for all of those might be complicated, but it's possible to add a map from handler to predicate as part of the map options, similar to localization (to some extent). I'm not sure it would be very useful, but I guess it's an option...

[jiacona]

I'm wondering if we're making this all more complicated than it needs to be. I really only need dragPan on middle mouse (in addition to the existing buttons), and I suspect that is all the original issue author wanted as well. What would you think about dropping the idea of button configuration and just make dragPan handled on middle-mouse by default?

[HarelM]

I think that you can hack the following in theory (I haven't fully tested it): (map.dragPan._mousePan as any)._moveStateManager._correctEvent =... It is very specific to how maplibre is currently structured, but it might just work. Making a patch that only support this use case without defining a proper API to support this will introduce backward compatibility issues in the future I believe.

[jiacona]

I think that you can hack the following in theory (I haven't fully tested it): (map.dragPan._mousePan as any)._moveStateManager._correctEvent =... It is very specific to how maplibre is currently structured, but it might just work.

Ah yes, interesting. I would be pretty hesitant to reach into the internals like that without a proper API.

Making a patch that only support this use case without defining a proper API to support this will introduce backward compatibility issues in the future I believe.

This is the minimal change I am proposing. Are there reasons not to want to support drag pan with middle mouse by default?

diff --git a/src/ui/handler/drag_move_state_manager.ts b/src/ui/handler/drag_move_state_manager.ts
index 5ef48fb72..a8b5b0097 100644
--- a/src/ui/handler/drag_move_state_manager.ts
+++ b/src/ui/handler/drag_move_state_manager.ts
@@ -1,12 +1,14 @@
 import {DOM} from '../../util/dom';

 const LEFT_BUTTON = 0;
+const MIDDLE_BUTTON = 1;
 const RIGHT_BUTTON = 2;

 // the values for each button in MouseEvent.buttons
 const BUTTONS_FLAGS = {
     [LEFT_BUTTON]: 1,
-    [RIGHT_BUTTON]: 2
+    [RIGHT_BUTTON]: 2,
+    [MIDDLE_BUTTON]: 4,
 };

 function buttonNoLongerPressed(e: MouseEvent, button: number) {
diff --git a/src/ui/handler/mouse.ts b/src/ui/handler/mouse.ts
index 30dd66471..1e712a6cd 100644
--- a/src/ui/handler/mouse.ts
+++ b/src/ui/handler/mouse.ts
@@ -23,6 +23,7 @@ export interface MousePitchHandler extends DragMoveHandler<DragPitchResult, Mous
 export interface MouseRollHandler extends DragMoveHandler<DragRollResult, MouseEvent> {}

 const LEFT_BUTTON = 0;
+const MIDDLE_BUTTON = 1;
 const RIGHT_BUTTON = 2;

 const assignEvents = (handler: DragHandler<DragPanResult, MouseEvent>) => {
@@ -39,7 +40,9 @@ export function generateMousePanHandler({enable, clickTolerance}: {
     enable?: boolean;
 }): MousePanHandler {
     const mouseMoveStateManager = new MouseMoveStateManager({
-        checkCorrectEvent: (e: MouseEvent) => DOM.mouseButton(e) === LEFT_BUTTON && !e.ctrlKey,
+        checkCorrectEvent: (e: MouseEvent) =>
+            (DOM.mouseButton(e) === LEFT_BUTTON && !e.ctrlKey) ||
+            (DOM.mouseButton(e) === MIDDLE_BUTTON),
     });
     return new DragHandler<DragPanResult, MouseEvent>({
         clickTolerance,

[HarelM]

I don't think this is the same as the original issue, I'm also not sure why you'd need to support both left click and middle click to drag...