matplotlib
diff --git a/‎doc/api/axes_api.rst
Copy file name to clipboardExpand all lines: doc/api/axes_api.rst
+3Lines changed: 3 additions & 0 deletions b/‎doc/api/axes_api.rst
Copy file name to clipboardExpand all lines: doc/api/axes_api.rst
+3Lines changed: 3 additions & 0 deletions
diff --git a/‎doc/api/next_api_changes/behavior/22347-RQ.rst
Copy file name to clipboard
+13Lines changed: 13 additions & 0 deletions b/‎doc/api/next_api_changes/behavior/22347-RQ.rst
Copy file name to clipboard
+13Lines changed: 13 additions & 0 deletions
diff --git a/‎galleries/examples/showcase/pan_zoom_overlap.py
Copy file name to clipboard
+74Lines changed: 74 additions & 0 deletions b/‎galleries/examples/showcase/pan_zoom_overlap.py
Copy file name to clipboard
+74Lines changed: 74 additions & 0 deletions
diff --git a/‎lib/matplotlib/axes/_base.py
Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_base.py
+39Lines changed: 39 additions & 0 deletions b/‎lib/matplotlib/axes/_base.py
Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_base.py
+39Lines changed: 39 additions & 0 deletions
diff --git a/‎lib/matplotlib/axes/_base.pyi
Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_base.pyi
+3Lines changed: 3 additions & 0 deletions b/‎lib/matplotlib/axes/_base.pyi
Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_base.pyi
+3Lines changed: 3 additions & 0 deletions
diff --git a/‎lib/matplotlib/backend_bases.py
Copy file name to clipboardExpand all lines: lib/matplotlib/backend_bases.py
+67-10Lines changed: 67 additions & 10 deletions b/‎lib/matplotlib/backend_bases.py
Copy file name to clipboardExpand all lines: lib/matplotlib/backend_bases.py
+67-10Lines changed: 67 additions & 10 deletions
@@ -517,6 +517,9 @@ Interactive
    Axes.get_navigate_mode
    Axes.set_navigate_mode
 
+   Axes.get_forward_navigation_events
+   Axes.set_forward_navigation_events
+
    Axes.start_pan
    Axes.drag_pan
    Axes.end_pan
 
@@ -0,0 +1,13 @@
+Correctly treat pan/zoom events of overlapping Axes
+---------------------------------------------------
+
+The forwarding of pan/zoom events is now determined by the visibility of the
+background-patch (e.g. ``ax.patch.get_visible()``) and by the ``zorder`` of the axes.
+
+- Axes with a visible patch capture the event and do not pass it on to axes below.
+  Only the Axes with the highest ``zorder`` that contains the event is triggered
+  (if there are multiple Axes with the same ``zorder``, the last added Axes counts)
+- Axes with an invisible patch are also invisible to events and they are passed on to the axes below.
+
+To override the default behavior and explicitly set whether an Axes
+should forward navigation events, use `.Axes.set_forward_navigation_events`.
@@ -0,0 +1,74 @@
+"""
+===================================
+Pan/zoom events of overlapping axes
+===================================
+
+Example to illustrate how pan/zoom events of overlapping axes are treated.
+
+
+The default is the following:
+
+- Axes with a visible patch capture pan/zoom events
+- Axes with an invisible patch forward pan/zoom events to axes below
+- Shared axes always trigger with their parent axes
+  (irrespective of the patch visibility)
+
+Note: The visibility of the patch hereby refers to the value of
+``ax.patch.get_visible()``. The color and transparency of a
+patch have no effect on the treatment of pan/zoom events!
+
+
+``ax.set_forward_navigation_events(val)`` can be used to override the
+default behaviour:
+
+- ``True``:  Forward navigation events to axes below.
+- ``False``: Execute navigation events only on this axes.
+- ``"auto"``: Use the default behaviour.
+
+To disable pan/zoom events completely, use ``ax.set_navigate(False)``
+
+"""
+
+
+import matplotlib.pyplot as plt
+
+fig = plt.figure(figsize=(11, 6))
+fig.suptitle("Showcase for pan/zoom events on overlapping axes.")
+
+ax = fig.add_axes((.05, .05, .9, .9))
+ax.patch.set_color(".75")
+ax_twin = ax.twinx()
+
+ax1 = fig.add_subplot(221)
+ax1_twin = ax1.twinx()
+ax1.text(.5, .5,
+         "Visible patch\n\n"
+         "Pan/zoom events are NOT\n"
+         "forwarded to axes below",
+         ha="center", va="center", transform=ax1.transAxes)
+
+ax11 = fig.add_subplot(223, sharex=ax1, sharey=ax1)
+ax11.set_forward_navigation_events(True)
+ax11.text(.5, .5,
+          "Visible patch\n\n"
+          "Override capture behavior:\n\n"
+          "ax.set_forward_navigation_events(True)",
+          ha="center", va="center", transform=ax11.transAxes)
+
+ax2 = fig.add_subplot(222)
+ax2_twin = ax2.twinx()
+ax2.patch.set_visible(False)
+ax2.text(.5, .5,
+         "Invisible patch\n\n"
+         "Pan/zoom events are\n"
+         "forwarded to axes below",
+         ha="center", va="center", transform=ax2.transAxes)
+
+ax22 = fig.add_subplot(224, sharex=ax2, sharey=ax2)
+ax22.patch.set_visible(False)
+ax22.set_forward_navigation_events(False)
+ax22.text(.5, .5,
+          "Invisible patch\n\n"
+          "Override capture behavior:\n\n"
+          "ax.set_forward_navigation_events(False)",
+          ha="center", va="center", transform=ax22.transAxes)
@@ -571,6 +571,7 @@ def __init__(self, fig,
                  xscale=None,
                  yscale=None,
                  box_aspect=None,
+                 forward_navigation_events="auto",
                  **kwargs
                  ):
         """
@@ -605,6 +606,11 @@ def __init__(self, fig,
             Set a fixed aspect for the Axes box, i.e. the ratio of height to
             width. See `~.axes.Axes.set_box_aspect` for details.
 
+        forward_navigation_events : bool or "auto", default: "auto"
+            Control whether pan/zoom events are passed through to Axes below
+            this one. "auto" is *True* for axes with an invisible patch and
+            *False* otherwise.
+
         **kwargs
             Other optional keyword arguments:
 
@@ -640,6 +646,7 @@ def __init__(self, fig,
         self._adjustable = 'box'
         self._anchor = 'C'
         self._stale_viewlims = {name: False for name in self._axis_names}
+        self._forward_navigation_events = forward_navigation_events
         self._sharex = sharex
         self._sharey = sharey
         self.set_label(label)
@@ -4016,6 +4023,11 @@ def set_navigate(self, b):
         Parameters
         ----------
         b : bool
+
+        See Also
+        --------
+        matplotlib.axes.Axes.set_forward_navigation_events
+
         """
         self._navigate = b
 
@@ -4466,6 +4478,8 @@ def _make_twin_axes(self, *args, **kwargs):
                     [0, 0, 1, 1], self.transAxes))
         self.set_adjustable('datalim')
         twin.set_adjustable('datalim')
+        twin.set_zorder(self.zorder)
+
         self._twinned_axes.join(self, twin)
         return twin
 
@@ -4612,6 +4626,31 @@ def _label_outer_yaxis(self, *, skip_non_rectangular_axes,
             if self.yaxis.offsetText.get_position()[0] == 1:
                 self.yaxis.offsetText.set_visible(False)
 
+    def set_forward_navigation_events(self, forward):
+        """
+        Set how pan/zoom events are forwarded to Axes below this one.
+
+        Parameters
+        ----------
+        forward : bool or "auto"
+            Possible values:
+
+            - True: Forward events to other axes with lower or equal zorder.
+            - False: Events are only executed on this axes.
+            - "auto": Default behaviour (*True* for axes with an invisible
+              patch and *False* otherwise)
+
+        See Also
+        --------
+        matplotlib.axes.Axes.set_navigate
+
+        """
+        self._forward_navigation_events = forward
+
+    def get_forward_navigation_events(self):
+        """Get how pan/zoom events are forwarded to Axes below this one."""
+        return self._forward_navigation_events
+
 
 def _draw_rasterized(figure, artists, renderer):
     """
 
@@ -75,6 +75,7 @@ class _AxesBase(martist.Artist):
         xscale: str | ScaleBase | None = ...,
         yscale: str | ScaleBase | None = ...,
         box_aspect: float | None = ...,
+        forward_navigation_events: bool | Literal["auto"] = ...,
         **kwargs
     ) -> None: ...
     def get_subplotspec(self) -> SubplotSpec | None: ...
@@ -363,6 +364,8 @@ class _AxesBase(martist.Artist):
     def can_pan(self) -> bool: ...
     def get_navigate(self) -> bool: ...
     def set_navigate(self, b: bool) -> None: ...
+    def get_forward_navigation_events(self) -> bool | Literal["auto"]: ...
+    def set_forward_navigation_events(self, forward: bool | Literal["auto"]) -> None: ...
     def get_navigate_mode(self) -> Literal["PAN", "ZOOM"] | None: ...
     def set_navigate_mode(self, b: Literal["PAN", "ZOOM"] | None) -> None: ...
     def start_pan(self, x: float, y: float, button: MouseButton) -> None: ...
 
@@ -2996,6 +2996,59 @@ def _zoom_pan_handler(self, event):
             elif event.name == "button_release_event":
                 self.release_zoom(event)
 
+    def _start_event_axes_interaction(self, event, *, method):
+
+        def _ax_filter(ax):
+            return (ax.in_axes(event) and
+                    ax.get_navigate() and
+                    getattr(ax, f"can_{method}")()
+                    )
+
+        def _capture_events(ax):
+            f = ax.get_forward_navigation_events()
+            if f == "auto":  # (capture = patch visibility)
+                f = not ax.patch.get_visible()
+            return not f
+
+        # get all relevant axes for the event
+        axes = list(filter(_ax_filter, self.canvas.figure.get_axes()))
+
+        if len(axes) == 0:
+            return []
+
+        if self._nav_stack() is None:
+            self.push_current()   # Set the home button to this view.
+
+        # group axes by zorder (reverse to trigger later axes first)
+        grps = dict()
+        for ax in reversed(axes):
+            grps.setdefault(ax.get_zorder(), []).append(ax)
+
+        axes_to_trigger = []
+        # go through zorders in reverse until we hit a capturing axes
+        for zorder in sorted(grps, reverse=True):
+            for ax in grps[zorder]:
+                axes_to_trigger.append(ax)
+                # NOTE: shared axes are automatically triggered, but twin-axes not!
+                axes_to_trigger.extend(ax._twinned_axes.get_siblings(ax))
+
+                if _capture_events(ax):
+                    break  # break if we hit a capturing axes
+            else:
+                # If the inner loop finished without an explicit break,
+                # (e.g. no capturing axes was found) continue the
+                # outer loop to the next zorder.
+                continue
+
+            # If the inner loop was terminated with an explicit break,
+            # terminate the outer loop as well.
+            break
+
+        # avoid duplicated triggers (but keep order of list)
+        axes_to_trigger = list(dict.fromkeys(axes_to_trigger))
+
+        return axes_to_trigger
+
     def pan(self, *args):
         """
         Toggle the pan/zoom tool.
@@ -3021,16 +3074,18 @@ def press_pan(self, event):
         if (event.button not in [MouseButton.LEFT, MouseButton.RIGHT]
                 or event.x is None or event.y is None):
             return
-        axes = [a for a in self.canvas.figure.get_axes()
-                if a.in_axes(event) and a.get_navigate() and a.can_pan()]
+
+        axes = self._start_event_axes_interaction(event, method="pan")
         if not axes:
             return
-        if self._nav_stack() is None:
-            self.push_current()  # set the home button to this view
+
+        # call "ax.start_pan(..)" on all relevant axes of an event
         for ax in axes:
             ax.start_pan(event.x, event.y, event.button)
+
         self.canvas.mpl_disconnect(self._id_drag)
         id_drag = self.canvas.mpl_connect("motion_notify_event", self.drag_pan)
+
         self._pan_info = self._PanInfo(
             button=event.button, axes=axes, cid=id_drag)
 
@@ -3076,21 +3131,23 @@ def press_zoom(self, event):
         if (event.button not in [MouseButton.LEFT, MouseButton.RIGHT]
                 or event.x is None or event.y is None):
             return
-        axes = [a for a in self.canvas.figure.get_axes()
-                if a.in_axes(event) and a.get_navigate() and a.can_zoom()]
+
+        axes = self._start_event_axes_interaction(event, method="zoom")
         if not axes:
             return
-        if self._nav_stack() is None:
-            self.push_current()  # set the home button to this view
+
         id_zoom = self.canvas.mpl_connect(
             "motion_notify_event", self.drag_zoom)
+
         # A colorbar is one-dimensional, so we extend the zoom rectangle out
         # to the edge of the Axes bbox in the other dimension. To do that we
         # store the orientation of the colorbar for later.
-        if hasattr(axes[0], "_colorbar"):
-            cbar = axes[0]._colorbar.orientation
+        parent_ax = axes[0]
+        if hasattr(parent_ax, "_colorbar"):
+            cbar = parent_ax._colorbar.orientation
         else:
             cbar = None
+
         self._zoom_info = self._ZoomInfo(
             direction="in" if event.button == 1 else "out",
             start_xy=(event.x, event.y), axes=axes, cid=id_zoom, cbar=cbar)