matplotlib · QuLogic · Oct 30, 2024 · Jun 23, 2024 · tacaswell · Jun 25, 2024
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -1324,6 +1324,28 @@
         If this is unset, *name* is "scroll_event", and *step* is nonzero, then
         this will be set to "up" or "down" depending on the sign of *step*.
 
+    buttons : None or frozenset
+        For 'motion_notify_event', the mouse buttons currently being pressed
+        (a set of zero or more MouseButtons);
+        for other events, None.
+
+        .. note::
+           For 'motion_notify_event', this attribute is more accurate than
+           the ``button`` (singular) attribute, which is obtained from the last
+           'button_press_event' or 'button_release_event' that occurred within
+           the canvas (and thus 1. be wrong if the last change in mouse state
+           occurred when the canvas did not have focus, and 2. cannot report
+           when multiple buttons are pressed).
+
+           This attribute is not set for 'button_press_event' and
+           'button_release_event' because GUI toolkits are inconsistent as to
+           whether they report the button state *before* or *after* the
+           press/release occurred.
+
+        .. warning::
+           On macOS, the Tk backends only report a single button even if
+           multiple buttons are pressed.
+
     key : None or str
         The key pressed when the mouse event triggered, e.g. 'shift'.
         See `KeyEvent`.
@@ -1356,7 +1378,8 @@
     """
 
     def __init__(self, name, canvas, x, y, button=None, key=None,
-                 step=0, dblclick=False, guiEvent=None, *, modifiers=None):
+                 step=0, dblclick=False, guiEvent=None, *,
+                 buttons=None, modifiers=None):
         super().__init__(
             name, canvas, x, y, guiEvent=guiEvent, modifiers=modifiers)
         if button in MouseButton.__members__.values():
@@ -1367,6 +1390,16 @@
             elif step < 0:
                 button = "down"
         self.button = button
+        if name == "motion_notify_event":
+            self.buttons = frozenset(buttons if buttons is not None else [])
+        else:
+            # We don't support 'buttons' for button_press/release_event because
+            # toolkits are inconsistent as to whether they report the state
+            # before or after the event.
+            if buttons:
+                raise ValueError(
+                    "'buttons' is only supported for 'motion_notify_event'")
+            self.buttons = None
         self.key = key
         self.step = step
         self.dblclick = dblclick

diff --git a/lib/matplotlib/backend_bases.pyi b/lib/matplotlib/backend_bases.pyi
@@ -258,6 +258,7 @@ class MouseEvent(LocationEvent):
         dblclick: bool = ...,
         guiEvent: Any | None = ...,
         *,
+        buttons: Iterable[MouseButton] | None = ...,
         modifiers: Iterable[str] | None = ...,
     ) -> None: ...
 

diff --git a/lib/matplotlib/backends/_backend_tk.py b/lib/matplotlib/backends/_backend_tk.py
@@ -19,7 +19,7 @@
 from matplotlib import _api, backend_tools, cbook, _c_internal_utils
 from matplotlib.backend_bases import (
     _Backend, FigureCanvasBase, FigureManagerBase, NavigationToolbar2,
-    TimerBase, ToolContainerBase, cursors, _Mode,
+    TimerBase, ToolContainerBase, cursors, _Mode, MouseButton,
     CloseEvent, KeyEvent, LocationEvent, MouseEvent, ResizeEvent)
 from matplotlib._pylab_helpers import Gcf
 from . import _tkagg
@@ -296,6 +296,7 @@
     def motion_notify_event(self, event):
         MouseEvent("motion_notify_event", self,
                    *self._event_mpl_coords(event),
+                   buttons=self._mpl_buttons(event),
                    modifiers=self._mpl_modifiers(event),
                    guiEvent=event)._process()
 
@@ -357,13 +358,33 @@
                    x, y, step=step, modifiers=self._mpl_modifiers(event),
                    guiEvent=event)._process()
 
+    @staticmethod
+    def _mpl_buttons(event):  # See _mpl_modifiers.
+        # NOTE: This fails to report multiclicks on macOS; only one button is
+        # reported (multiclicks work correctly on Linux & Windows).
+        modifiers = [
+            # macOS appears to swap right and middle (look for "Swap buttons
+            # 2/3" in tk/macosx/tkMacOSXMouseEvent.c).
+            (MouseButton.LEFT, 1 << 8),
+            (MouseButton.RIGHT, 1 << 9),
+            (MouseButton.MIDDLE, 1 << 10),
+            (MouseButton.BACK, 1 << 11),
+            (MouseButton.FORWARD, 1 << 12),
+        ] if sys.platform == "darwin" else [
+            (MouseButton.LEFT, 1 << 8),
+            (MouseButton.MIDDLE, 1 << 9),
+            (MouseButton.RIGHT, 1 << 10),
+            (MouseButton.BACK, 1 << 11),
+            (MouseButton.FORWARD, 1 << 12),
+        ]
+        # State *before* press/release.
+        return [name for name, mask in modifiers if event.state & mask]
+
     @staticmethod
     def _mpl_modifiers(event, *, exclude=None):
-        # add modifier keys to the key string. Bit details originate from
-        # http://effbot.org/tkinterbook/tkinter-events-and-bindings.htm
-        # BIT_SHIFT = 0x001; BIT_CAPSLOCK = 0x002; BIT_CONTROL = 0x004;
-        # BIT_LEFT_ALT = 0x008; BIT_NUMLOCK = 0x010; BIT_RIGHT_ALT = 0x080;
-        # BIT_MB_1 = 0x100; BIT_MB_2 = 0x200; BIT_MB_3 = 0x400;
+        # Add modifier keys to the key string. Bit values are inferred from
+        # the implementation of tkinter.Event.__repr__ (1, 2, 4, 8, ... =
+        # Shift, Lock, Control, Mod1, ..., Mod5, Button1, ..., Button5)
         # In general, the modifier key is excluded from the modifier flag,
         # however this is not the case on "darwin", so double check that
         # we aren't adding repeat modifier flags to a modifier key.

diff --git a/lib/matplotlib/backends/backend_gtk3.py b/lib/matplotlib/backends/backend_gtk3.py
@@ -6,8 +6,8 @@
 import matplotlib as mpl
 from matplotlib import _api, backend_tools, cbook
 from matplotlib.backend_bases import (
-    ToolContainerBase, CloseEvent, KeyEvent, LocationEvent, MouseEvent,
-    ResizeEvent)
+    ToolContainerBase, MouseButton,
+    CloseEvent, KeyEvent, LocationEvent, MouseEvent, ResizeEvent)
 
 try:
     import gi
@@ -156,6 +156,7 @@
 
     def motion_notify_event(self, widget, event):
         MouseEvent("motion_notify_event", self, *self._mpl_coords(event),
+                   buttons=self._mpl_buttons(event.state),
                    modifiers=self._mpl_modifiers(event.state),
                    guiEvent=event)._process()
         return False  # finish event propagation?
@@ -182,6 +183,18 @@
         ResizeEvent("resize_event", self)._process()
         self.draw_idle()
 
+    @staticmethod
+    def _mpl_buttons(event_state):
+        modifiers = [
+            (MouseButton.LEFT, Gdk.ModifierType.BUTTON1_MASK),
+            (MouseButton.MIDDLE, Gdk.ModifierType.BUTTON2_MASK),
+            (MouseButton.RIGHT, Gdk.ModifierType.BUTTON3_MASK),
+            (MouseButton.BACK, Gdk.ModifierType.BUTTON4_MASK),
+            (MouseButton.FORWARD, Gdk.ModifierType.BUTTON5_MASK),
+        ]
+        # State *before* press/release.
+        return [name for name, mask in modifiers if event_state & mask]
+
     @staticmethod
     def _mpl_modifiers(event_state, *, exclude=None):
         modifiers = [

diff --git a/lib/matplotlib/backends/backend_gtk4.py b/lib/matplotlib/backends/backend_gtk4.py
@@ -5,8 +5,8 @@
 import matplotlib as mpl
 from matplotlib import _api, backend_tools, cbook
 from matplotlib.backend_bases import (
-    ToolContainerBase, KeyEvent, LocationEvent, MouseEvent, ResizeEvent,
-    CloseEvent)
+    ToolContainerBase, MouseButton,
+    KeyEvent, LocationEvent, MouseEvent, ResizeEvent, CloseEvent)
 
 try:
     import gi
@@ -155,6 +155,7 @@
     def motion_notify_event(self, controller, x, y):
         MouseEvent(
             "motion_notify_event", self, *self._mpl_coords((x, y)),
+            buttons=self._mpl_buttons(controller),
             modifiers=self._mpl_modifiers(controller),
             guiEvent=controller.get_current_event(),
         )._process()
@@ -182,6 +183,26 @@
         ResizeEvent("resize_event", self)._process()
         self.draw_idle()
 
+    def _mpl_buttons(self, controller):
+        # NOTE: This spews "Broken accounting of active state" warnings on
+        # right click on macOS.
+        surface = self.get_native().get_surface()
+        is_over, x, y, event_state = surface.get_device_position(
+            self.get_display().get_default_seat().get_pointer())
+        # NOTE: alternatively we could use
+        #   event_state = controller.get_current_event_state()
+        # but for button_press/button_release this would report the state
+        # *prior* to the event rather than after it; the above reports the
+        # state *after* it.
+        mod_table = [
+            (MouseButton.LEFT, Gdk.ModifierType.BUTTON1_MASK),
+            (MouseButton.MIDDLE, Gdk.ModifierType.BUTTON2_MASK),
+            (MouseButton.RIGHT, Gdk.ModifierType.BUTTON3_MASK),
+            (MouseButton.BACK, Gdk.ModifierType.BUTTON4_MASK),
+            (MouseButton.FORWARD, Gdk.ModifierType.BUTTON5_MASK),
+        ]
+        return {name for name, mask in mod_table if event_state & mask}
+
     def _mpl_modifiers(self, controller=None):
         if controller is None:
             surface = self.get_native().get_surface()

diff --git a/lib/matplotlib/backends/backend_qt.py b/lib/matplotlib/backends/backend_qt.py
@@ -329,6 +329,7 @@
             return
         MouseEvent("motion_notify_event", self,
                    *self.mouseEventCoords(event),
+                   buttons=self._mpl_buttons(event.buttons()),
                    modifiers=self._mpl_modifiers(),
                    guiEvent=event)._process()
 
@@ -396,6 +397,13 @@
     def minimumSizeHint(self):
         return QtCore.QSize(10, 10)
 
+    @staticmethod
+    def _mpl_buttons(buttons):
+        buttons = _to_int(buttons)
+        # State *after* press/release.
+        return {button for mask, button in FigureCanvasQT.buttond.items()
+                if _to_int(mask) & buttons}
+
     @staticmethod
     def _mpl_modifiers(modifiers=None, *, exclude=None):
         if modifiers is None:

diff --git a/lib/matplotlib/backends/backend_webagg_core.py b/lib/matplotlib/backends/backend_webagg_core.py
@@ -22,7 +22,7 @@
 from matplotlib import _api, backend_bases, backend_tools
 from matplotlib.backends import backend_agg
 from matplotlib.backend_bases import (
-    _Backend, KeyEvent, LocationEvent, MouseEvent, ResizeEvent)
+    _Backend, MouseButton, KeyEvent, LocationEvent, MouseEvent, ResizeEvent)
 
 _log = logging.getLogger(__name__)
 
@@ -283,10 +283,17 @@
         y = event['y']
         y = self.get_renderer().height - y
         self._last_mouse_xy = x, y
-        # JavaScript button numbers and Matplotlib button numbers are off by 1.
-        button = event['button'] + 1
-
         e_type = event['type']
+        button = event['button'] + 1  # JS numbers off by 1 compared to mpl.
+        buttons = {  # JS ordering different compared to mpl.
+            button for button, mask in [
+                (MouseButton.LEFT, 1),
+                (MouseButton.RIGHT, 2),
+                (MouseButton.MIDDLE, 4),
+                (MouseButton.BACK, 8),
+                (MouseButton.FORWARD, 16),
+            ] if event['buttons'] & mask  # State *after* press/release.
+        }
         modifiers = event['modifiers']
         guiEvent = event.get('guiEvent')
         if e_type in ['button_press', 'button_release']:
@@ -300,10 +307,12 @@
                        modifiers=modifiers, guiEvent=guiEvent)._process()
         elif e_type == 'motion_notify':
             MouseEvent(e_type + '_event', self, x, y,
-                       modifiers=modifiers, guiEvent=guiEvent)._process()
+                       buttons=buttons, modifiers=modifiers, guiEvent=guiEvent,
+                       )._process()
         elif e_type in ['figure_enter', 'figure_leave']:
             LocationEvent(e_type + '_event', self, x, y,
                           modifiers=modifiers, guiEvent=guiEvent)._process()
+
     handle_button_press = handle_button_release = handle_dblclick = \
         handle_figure_enter = handle_figure_leave = handle_motion_notify = \
         handle_scroll = _handle_mouse

diff --git a/lib/matplotlib/backends/backend_wx.py b/lib/matplotlib/backends/backend_wx.py
@@ -685,6 +685,22 @@
         ResizeEvent("resize_event", self)._process()
         self.draw_idle()
 
+    @staticmethod
+    def _mpl_buttons():
+        state = wx.GetMouseState()
+        # NOTE: Alternatively, we could use event.LeftIsDown() / etc. but this
+        # fails to report multiclick drags on macOS (other OSes have not been
+        # verified).
+        mod_table = [
+            (MouseButton.LEFT, state.LeftIsDown()),
+            (MouseButton.RIGHT, state.RightIsDown()),
+            (MouseButton.MIDDLE, state.MiddleIsDown()),
+            (MouseButton.BACK, state.Aux1IsDown()),
+            (MouseButton.FORWARD, state.Aux2IsDown()),
+        ]
+        # State *after* press/release.
+        return {button for button, flag in mod_table if flag}
+
     @staticmethod
     def _mpl_modifiers(event=None, *, exclude=None):
         mod_table = [
@@ -794,9 +810,8 @@
             MouseEvent("button_press_event", self, x, y, button,
                        modifiers=modifiers, guiEvent=event)._process()
         elif event.ButtonDClick():
-            MouseEvent("button_press_event", self, x, y, button,
-                       dblclick=True, modifiers=modifiers,
-                       guiEvent=event)._process()
+            MouseEvent("button_press_event", self, x, y, button, dblclick=True,
+                       modifiers=modifiers, guiEvent=event)._process()
         elif event.ButtonUp():
             MouseEvent("button_release_event", self, x, y, button,
                        modifiers=modifiers, guiEvent=event)._process()
@@ -826,6 +841,7 @@
         event.Skip()
         MouseEvent("motion_notify_event", self,
                    *self._mpl_coords(event),
+                   buttons=self._mpl_buttons(),
                    modifiers=self._mpl_modifiers(event),
                    guiEvent=event)._process()
 

diff --git a/lib/matplotlib/backends/web_backend/js/mpl.js b/lib/matplotlib/backends/web_backend/js/mpl.js
@@ -644,6 +644,7 @@ mpl.figure.prototype.mouse_event = function (event, name) {
         y: y,
         button: event.button,
         step: event.step,
+        buttons: event.buttons,
         modifiers: getModifiers(event),
         guiEvent: simpleKeys(event),
     });