Fix docstring minspan* of selectors

ericpre · ericpre · commit ae93c40d925f · 2021-07-27T16:52:31.000+01:00
Improve docstring of selector: explain press and release event at same coordinates clear the selector
Clarify the docstring about when onselect is called and minspan* and fix calling onselect for RectangleSelector.
Rename `self._completed` to `self._selection_completed` in Selectors.
Improve `onselect` and `minspan` interaction for the `SpanSelector`.
Add next_whats_new entry
Add ignore_event_outside option for RectangleSelector and EllipseSelector
Add ignore_event_outside option for SpanSelector
Fix docstring for minspan argument of selectors.
Simplify RectangleSelector `_release` and test to check that `onselect` is called when the press and release event are the same
Fix onselect call when press and release events are identical than minspan
diff --git a/doc/users/next_whats_new/widget_ignore_events.rst b/doc/users/next_whats_new/widget_ignore_events.rst
@@ -0,0 +1,7 @@
+Ignore events outside selection
+-------------------------------
+The `~matplotlib.widgets.SpanSelector`, `~matplotlib.widgets.RectangleSelector`
+and `~matplotlib.widgets.EllipseSelector` have a new keyword argument,
+*ignore_event_outside*, which when set to `True` will ignore events outside of
+the current selection. The handles or the new dragging functionality can instead
+be used to change the selection.
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
@@ -190,6 +190,63 @@ def onselect(epress, erelease):
         tool._corner_handles.artist.get_markeredgecolor(), 'b')
 
 
+@pytest.mark.parametrize('interactive', [True, False])
+def test_rectangle_selector_onselect(interactive):
+    # check when press and release events take place at the same position
+    ax = get_ax()
+
+    def onselect(vmin, vmax):
+        ax._got_onselect = True
+
+    tool = widgets.RectangleSelector(ax, onselect, interactive=interactive)
+    do_event(tool, 'press', xdata=100, ydata=110, button=1)
+    # move outside of axis
+    do_event(tool, 'onmove', xdata=150, ydata=120, button=1)
+    do_event(tool, 'release', xdata=150, ydata=120, button=1)
+
+    assert tool.ax._got_onselect
+    assert tool.extents == (100.0, 150.0, 110.0, 120.0)
+
+    # Reset tool.ax._got_onselect
+    tool.ax._got_onselect = False
+
+    do_event(tool, 'press', xdata=10, ydata=100, button=1)
+    do_event(tool, 'release', xdata=10, ydata=100, button=1)
+
+    assert tool.ax._got_onselect
+
+
+@pytest.mark.parametrize('ignore_event_outside', [True, False])
+def test_rectangle_selector_ignore_outside(ignore_event_outside):
+    ax = get_ax()
+    def onselect(vmin, vmax):
+        ax._got_onselect = True
+
+    tool = widgets.RectangleSelector(ax, onselect,
+                                     ignore_event_outside=ignore_event_outside)
+    do_event(tool, 'press', xdata=100, ydata=110, button=1)
+    do_event(tool, 'onmove', xdata=150, ydata=120, button=1)
+    do_event(tool, 'release', xdata=150, ydata=120, button=1)
+
+    assert tool.ax._got_onselect
+    assert tool.extents == (100.0, 150.0, 110.0, 120.0)
+
+    # Reset
+    ax._got_onselect = False
+    # Trigger event outside of span
+    do_event(tool, 'press', xdata=150, ydata=150, button=1)
+    do_event(tool, 'onmove', xdata=160, ydata=160, button=1)
+    do_event(tool, 'release', xdata=160, ydata=160, button=1)
+    if ignore_event_outside:
+        # event have been ignored and span haven't changed.
+        assert not ax._got_onselect
+        assert tool.extents == (100.0, 150.0, 110.0, 120.0)
+    else:
+        # A new shape is created
+        assert ax._got_onselect
+        assert tool.extents == (150.0, 160.0, 150.0, 160.0)
+
+
 def check_span(*args, **kwargs):
     ax = get_ax()
 
@@ -222,13 +279,79 @@ def test_span_selector():
     check_span('horizontal', minspan=10, useblit=True)
     check_span('vertical', onmove_callback=True, button=1)
     check_span('horizontal', props=dict(fill=True))
+    check_span('horizontal', interactive=True)
+
+
+@pytest.mark.parametrize('interactive', [True, False])
+def test_span_selector_onselect(interactive):
+    # check when press and release events take place at the same position
+    ax = get_ax()
+
+    def onselect(vmin, vmax):
+        ax._got_onselect = True
+
+    tool = widgets.SpanSelector(ax, onselect, 'horizontal',
+                                interactive=interactive)
+    do_event(tool, 'press', xdata=100, ydata=100, button=1)
+    # move outside of axis
+    do_event(tool, 'onmove', xdata=150, ydata=100, button=1)
+    do_event(tool, 'release', xdata=150, ydata=100, button=1)
+
+    assert tool.ax._got_onselect
+    assert tool.extents == (100, 150)
+
+    # Reset tool.ax._got_onselect
+    tool.ax._got_onselect = False
+
+    do_event(tool, 'press', xdata=10, ydata=100, button=1)
+    do_event(tool, 'release', xdata=10, ydata=100, button=1)
+
+    assert tool.ax._got_onselect
+
+
+@pytest.mark.parametrize('ignore_event_outside', [True, False])
+def test_span_selector_ignore_outside(ignore_event_outside):
+    ax = get_ax()
+    def onselect(vmin, vmax):
+        ax._got_onselect = True
+
+    def onmove(vmin, vmax):
+        ax._got_on_move = True
+
+    tool = widgets.SpanSelector(ax, onselect, 'horizontal',
+                                onmove_callback=onmove,
+                                ignore_event_outside=ignore_event_outside)
+    do_event(tool, 'press', xdata=100, ydata=100, button=1)
+    do_event(tool, 'onmove', xdata=125, ydata=125, button=1)
+    do_event(tool, 'release', xdata=125, ydata=125, button=1)
+    assert ax._got_onselect
+    assert ax._got_on_move
+    assert tool.extents == (100, 125)
+
+    # Reset
+    ax._got_onselect = False
+    ax._got_on_move = False
+    # Trigger event outside of span
+    do_event(tool, 'press', xdata=150, ydata=150, button=1)
+    do_event(tool, 'onmove', xdata=160, ydata=160, button=1)
+    do_event(tool, 'release', xdata=160, ydata=160, button=1)
+    if ignore_event_outside:
+        # event have been ignored and span haven't changed.
+        assert not ax._got_onselect
+        assert not ax._got_on_move
+        assert tool.extents == (100, 125)
+    else:
+        # A new shape is created
+        assert ax._got_onselect
+        assert ax._got_on_move
+        assert tool.extents == (150, 160)
 
 
 @pytest.mark.parametrize('drag_from_anywhere', [True, False])
 def test_span_selector_drag(drag_from_anywhere):
     ax = get_ax()
 
-    def onselect(epress, erelease):
+    def onselect(*args):
         pass
 
     # Create span
@@ -263,7 +386,7 @@ def onselect(epress, erelease):
 def test_span_selector_direction():
     ax = get_ax()
 
-    def onselect(epress, erelease):
+    def onselect(*args):
         pass
 
     tool = widgets.SpanSelector(ax, onselect, 'horizontal', interactive=True)
@@ -702,7 +825,7 @@ def test_MultiCursor(horizOn, vertOn):
 def test_rect_visibility(fig_test, fig_ref):
     # Check that requesting an invisible selector makes it invisible
     ax_test = fig_test.subplots()
-    ax_ref = fig_ref.subplots()
+    _ = fig_ref.subplots()
 
     def onselect(verts):
         pass
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
