ENH: Scroll to zoom

timhoffm · timhoffm · commit e3395211abfa · 2025-08-07T23:31:45.000+02:00
Implements a minimal version of #20317, in particular https://github .com//pull/20317#issuecomment-2233156558: When any of the axes manipulation tools is active (pan or zoom tool), a mouse scroll results in a zoom towards the cursor, keeping aspect ratio. I've decided to require an active manipulation tool, so that without any active tool the plot cannot be changed (accidentally) - as before. For convenience, scroll-to-zoom is allowed with both the zoom and pan tools. Limiting further feels unnecessarily restrictive. Zooming is also limited to not having a modifier key pressed. This is because we might later want to add scroll+modifiers for other operations . It's better for now not to react to these at all to not introduce behaviors we later want to change.
diff --git a/doc/users/next_whats_new/scroll_to_zoom.rst b/doc/users/next_whats_new/scroll_to_zoom.rst
@@ -0,0 +1,9 @@
+Scroll-to-zoom in GUIs
+~~~~~~~~~~~~~~~~~~~~~~
+
+When a plot manipulation tool (pan or zoom tool) in plot windows is selected,
+a mouse scroll operation results in a zoom towards the mouse pointer, keeping the
+aspect ratio of the axes.
+
+There is no effect if no manipulation tool is selected. This is intentional to
+keep a state in which accidental manipulation of the plot is excluded.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2574,6 +2574,41 @@ def button_press_handler(event, canvas=None, toolbar=None):
             toolbar.forward()
 
 
+def scroll_handler(event, canvas=None, toolbar=None):
+    ax = event.inaxes
+    if ax is None:
+        return
+
+    if toolbar is None:
+        if canvas is None:
+            canvas = event.canvas
+        toolbar = canvas.toolbar
+
+    if toolbar is None or toolbar.mode == _Mode.NONE:
+        return
+
+    if event.key is None:  # zoom towards the mouse position
+        toolbar.push_current()
+
+        xmin, xmax = ax.get_xlim()
+        ymin, ymax = ax.get_ylim()
+
+        # mouse position in data coordinates
+        x = event.xdata
+        y = event.ydata
+
+        scale_factor = 1.0 - 0.05 * event.step
+        new_xmin = x - (x - xmin) * scale_factor
+        new_xmax = x + (xmax - x) * scale_factor
+        new_ymin = y - (y - ymin) * scale_factor
+        new_ymax = y + (ymax - y) * scale_factor
+
+        ax.set_xlim(new_xmin, new_xmax)
+        ax.set_ylim(new_ymin, new_ymax)
+
+        ax.figure.canvas.draw_idle()
+
+
 class NonGuiException(Exception):
     """Raised when trying show a figure in a non-GUI backend."""
     pass
@@ -2653,11 +2688,14 @@ def __init__(self, canvas, num):
 
         self.key_press_handler_id = None
         self.button_press_handler_id = None
+        self.scroll_handler_id = None
         if rcParams['toolbar'] != 'toolmanager':
             self.key_press_handler_id = self.canvas.mpl_connect(
                 'key_press_event', key_press_handler)
             self.button_press_handler_id = self.canvas.mpl_connect(
                 'button_press_event', button_press_handler)
+            self.scroll_handler_id = self.canvas.mpl_connect(
+                'scroll_event', scroll_handler)
 
         self.toolmanager = (ToolManager(canvas.figure)
                             if mpl.rcParams['toolbar'] == 'toolmanager'
diff --git a/lib/matplotlib/backend_bases.pyi b/lib/matplotlib/backend_bases.pyi
@@ -407,6 +407,11 @@ def button_press_handler(
     canvas: FigureCanvasBase | None = ...,
     toolbar: NavigationToolbar2 | None = ...,
 ) -> None: ...
+def scroll_handler(
+    event: MouseEvent,
+        canvas: FigureCanvasBase | None = ...,
+        toolbar: NavigationToolbar2 | None = ...,
+) -> None: ...
 
 class NonGuiException(Exception): ...
 
@@ -415,6 +420,7 @@ class FigureManagerBase:
     num: int | str
     key_press_handler_id: int | None
     button_press_handler_id: int | None
+    scroll_handler_id: int | None
     toolmanager: ToolManager | None
     toolbar: NavigationToolbar2 | ToolContainerBase | None
     def __init__(self, canvas: FigureCanvasBase, num: int | str) -> None: ...
