Add clear method to selector

Author: ericpre

doc/users/next_whats_new/widget_clear.rst

@@ -0,0 +1,7 @@
+Clear selector
+--------------
+The selectors (`~matplotlib.widgets.SpanSelector`, `~matplotlib.widgets.RectangleSelector`,
+`~matplotlib.widgets.EllipseSelector`, `~matplotlib.widgets.PolygonSelector` and
+`~matplotlib.widgets.LassoSelector` have a new method *clear*, which will clear
+the current selection and get the selector ready to make a new selection. This
+is equivalent to press the *escape* key.

lib/matplotlib/tests/test_widgets.py

@@ -496,6 +496,41 @@ def onselect(*args):
     assert not tool._selection_completed
 
 
+@pytest.mark.parametrize('selector', ['span', 'rectangle'])
+def test_selector_clear_method(selector):
+    ax = get_ax()
+
+    def onselect(*args):
+        pass
+
+    if selector == 'span':
+        tool = widgets.SpanSelector(ax, onselect, 'horizontal',
+                                    interactive=True,
+                                    ignore_event_outside=True)
+    else:
+        tool = widgets.RectangleSelector(ax, onselect, interactive=True)
+    do_event(tool, 'press', xdata=10, ydata=10, button=1)
+    do_event(tool, 'onmove', xdata=100, ydata=120, button=1)
+    do_event(tool, 'release', xdata=100, ydata=120, button=1)
+    assert tool._selection_completed
+    assert tool.visible
+    if selector == 'span':
+        assert tool.extents == (10, 100)
+
+    tool.clear()
+    assert not tool._selection_completed
+    assert not tool.visible
+
+    # Do another cycle of events to make sure we can
+    do_event(tool, 'press', xdata=10, ydata=10, button=1)
+    do_event(tool, 'onmove', xdata=50, ydata=120, button=1)
+    do_event(tool, 'release', xdata=50, ydata=120, button=1)
+    assert tool._selection_completed
+    assert tool.visible
+    if selector == 'span':
+        assert tool.extents == (10, 50)
+
+
 def test_tool_line_handle():
     ax = get_ax()
 

lib/matplotlib/widgets.py

@@ -1978,10 +1978,7 @@ def on_key_press(self, event):
             key = event.key or ''
             key = key.replace('ctrl', 'control')
             if key == self.state_modifier_keys['clear']:
-                self._selection_completed = False
-                for artist in self.artists:
-                    artist.set_visible(False)
-                self.update()
+                self.clear()
                 return
             for (state, modifier) in self.state_modifier_keys.items():
                 if modifier in key:
@@ -2009,6 +2006,12 @@ def set_visible(self, visible):
         for artist in self.artists:
             artist.set_visible(visible)
 
+    def clear(self):
+        """Clear the selection and set the selector ready to make a new one."""
+        self._selection_completed = False
+        self.set_visible(False)
+        self.update()
+
     @property
     def artists(self):
         """Tuple of the artists of the selector."""