invert logic and rename "set_capture_..." to "set_forward_..."

raphaelquast · raphaelquast · commit 022982008e27 · 2023-07-21T10:54:35.000+02:00
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -515,8 +515,8 @@ Interactive
    Axes.get_navigate_mode
    Axes.set_navigate_mode
 
-   Axes.get_capture_navigation_events
-   Axes.set_capture_navigation_events
+   Axes.get_forward_navigation_events
+   Axes.set_forward_navigation_events
 
    Axes.start_pan
    Axes.drag_pan
diff --git a/doc/api/next_api_changes/behavior/22347-RQ.rst b/doc/api/next_api_changes/behavior/22347-RQ.rst
@@ -7,7 +7,7 @@ background-patch (e.g. ``ax.patch.get_visible()``) and by the ``zorder`` of the
 - 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 is also invisible to events and they are passed on to the axes below.
+- 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 capture navigation events, use `.Axes.set_capture_navigation_events`.
+should forward navigation events, use `.Axes.set_forward_navigation_events`.
diff --git a/galleries/examples/showcase/pan_zoom_overlap.py b/galleries/examples/showcase/pan_zoom_overlap.py
@@ -14,12 +14,13 @@
   (irrespective of the patch visibility)
 
 
-``ax.set_capture_navigation_events(val)`` can be used to override the
+``ax.set_forward_navigation_events(val)`` can be used to override the
 default behaviour:
 
-- ``False``:  Forward navigation events to axes below
-- ``True``:   Capture navigation events
+- ``True``:  Forward navigation events to axes below.
+- ``False``: Execute navigation events only on this axes.
 - ``"auto"``: Use the default behaviour
+  (``True`` for axes with an invisible patch and ``False`` otherwise).
 
 To disable pan/zoom events completely, use ``ax.set_navigate(False)``
 """
@@ -43,11 +44,11 @@
          ha="center", va="center", transform=ax1.transAxes)
 
 ax11 = f.add_subplot(223, sharex=ax1, sharey=ax1)
-ax11.set_capture_navigation_events(False)
+ax11.set_forward_navigation_events(True)
 ax11.text(.5, .5,
           "Visible patch\n\n"
           "Override capture behavior:\n\n"
-          "ax.set_capture_navigation_events(False)",
+          "ax.set_forward_navigation_events(True)",
           ha="center", va="center", transform=ax11.transAxes)
 
 ax2 = f.add_subplot(222)
@@ -61,9 +62,9 @@
 
 ax22 = f.add_subplot(224, sharex=ax2, sharey=ax2)
 ax22.patch.set_visible(False)
-ax22.set_capture_navigation_events(True)
+ax22.set_forward_navigation_events(False)
 ax22.text(.5, .5,
           "Invisible patch\n\n"
           "Override capture behavior:\n\n"
-          "ax.set_capture_navigation_events(True)",
+          "ax.set_forward_navigation_events(False)",
           ha="center", va="center", transform=ax22.transAxes)
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -581,7 +581,7 @@ def __init__(self, fig,
                  xscale=None,
                  yscale=None,
                  box_aspect=None,
-                 capture_navigation_events="auto",
+                 forward_navigation_events="auto",
                  **kwargs
                  ):
         """
@@ -616,7 +616,7 @@ 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.
 
-        capture_navigation_events : bool or "auto", default: "auto"
+        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.
@@ -656,7 +656,7 @@ def __init__(self, fig,
         self._adjustable = 'box'
         self._anchor = 'C'
         self._stale_viewlims = {name: False for name in self._axis_names}
-        self._capture_navigation_events = capture_navigation_events
+        self._forward_navigation_events = forward_navigation_events
         self._sharex = sharex
         self._sharey = sharey
         self.set_label(label)
@@ -3970,7 +3970,7 @@ def set_navigate(self, b):
 
         See Also
         --------
-        matplotlib.axes.Axes.set_capture_navigation_events
+        matplotlib.axes.Axes.set_forward_navigation_events
 
         """
         self._navigate = b
@@ -4549,30 +4549,30 @@ def _label_outer_yaxis(self, *, check_patch):
             if self.yaxis.offsetText.get_position()[0] == 1:
                 self.yaxis.offsetText.set_visible(False)
 
-    def set_capture_navigation_events(self, capture):
+    def set_forward_navigation_events(self, forward):
         """
         Set how pan/zoom events are forwarded to Axes below this one.
 
         Parameters
         ----------
-        capture : bool or 'auto'
+        forward : bool or "auto"
             Possible values:
 
-            - True: Events are only executed on this axes.
-            - False: Forward events to other axes with lower or equal zorder
-            - "auto": Default behaviour ("True" for axes with an invisible
-              patch and False otherwise)
+            - 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._capture_navigation_events = capture
+        self._forward_navigation_events = forward
 
-    def get_capture_navigation_events(self):
+    def get_forward_navigation_events(self):
         """Get how pan/zoom events are forwarded to Axes below this one."""
-        return self._capture_navigation_events
+        return self._forward_navigation_events
 
 
 def _draw_rasterized(figure, artists, renderer):
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2983,11 +2983,11 @@ def _start_event_axes_pan(self, event):
         def _ax_filter(ax):
             return ax.in_axes(event) and ax.get_navigate() and ax.can_zoom()
 
-        def _ax_capture(ax):
-            c = ax.get_capture_navigation_events()
-            if c == "auto":  # (capture = patch visibility)
-                c = ax.patch.get_visible()
-            return c
+        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()))
@@ -3022,7 +3022,7 @@ def _ax_capture(ax):
                     # only trigger twinned-axes not the shared axes!
                     pan_axes.extend((i for i in ax_t if i is not ax_s))
 
-                if _ax_capture(ax):
+                if _capture_events(ax):
                     break  # break if we hit a capturing axes
             else:
                 continue   # continue to lower zorder if we did not break
diff --git a/lib/matplotlib/tests/test_backend_bases.py b/lib/matplotlib/tests/test_backend_bases.py
@@ -444,14 +444,14 @@ def test_toolmanager_update_keymap():
 @pytest.mark.parametrize("tool", ["zoom", "pan"])
 @pytest.mark.parametrize("button", [MouseButton.LEFT, MouseButton.RIGHT])
 @pytest.mark.parametrize("patch_vis", [True, False])
-@pytest.mark.parametrize("capture_nav", [True, False, "auto"])
+@pytest.mark.parametrize("forward_nav", [True, False, "auto"])
 @pytest.mark.parametrize("t_s", ["twin", "share"])
 def test_interactive_pan_zoom_events(tool, button, patch_vis,
-                                     capture_nav, t_s):
+                                     forward_nav, t_s):
     # Bottom axes: ax_b    Top axes: ax_t
     fig, ax_b = plt.subplots()
     ax_t = fig.add_subplot(221, zorder=99)
-    ax_t.set_capture_navigation_events(capture_nav)
+    ax_t.set_forward_navigation_events(forward_nav)
     ax_t.patch.set_visible(patch_vis)
 
     # ----------------------------
@@ -515,10 +515,10 @@ def test_interactive_pan_zoom_events(tool, button, patch_vis,
         xlim_t, ylim_t = ax_t._prepare_view_from_bbox(
             [*s0, *s1], direction)
 
-        if ax_t.get_capture_navigation_events() is False:
+        if ax_t.get_forward_navigation_events() is True:
             xlim_b, ylim_b = ax_b._prepare_view_from_bbox(
                 [*s0, *s1], direction)
-        elif ax_t.get_capture_navigation_events() is True:
+        elif ax_t.get_forward_navigation_events() is False:
             xlim_b = init_xlim
             ylim_b = init_ylim
         else:
@@ -552,12 +552,12 @@ def test_interactive_pan_zoom_events(tool, button, patch_vis,
             button, None, *s1).T.astype(float)
         ax_t.end_pan()
 
-        if ax_t.get_capture_navigation_events() is False:
+        if ax_t.get_forward_navigation_events() is True:
             ax_b.start_pan(*s0, button)
             xlim_b, ylim_b = ax_b._get_pan_points(
                 button, None, *s1).T.astype(float)
             ax_b.end_pan()
-        elif ax_t.get_capture_navigation_events() is True:
+        elif ax_t.get_forward_navigation_events() is False:
             xlim_b = init_xlim
             ylim_b = init_ylim
         else:
