Merge pull request matplotlib#19934 from dstansby/drawtype

Deprecate drawtype to RectangleSelector

Author: QuLogic

doc/api/next_api_changes/deprecations/19934-DS.rst

@@ -0,0 +1,17 @@
+*drawtype* argument to RectangleSelector
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The *drawtype* keyword argument to
+`~matplotlib.widgets.RectangleSelector` is deprecated. In the future the
+behaviour will be the default behaviour of ``drawtype='box'``.
+
+Support for ``drawtype=line`` will be removed altogether as it is not clear
+which points are within and outside a selector that is just a line.
+As a result, the ``lineprops`` keyword argument to
+`~matplotlib.widgets.RectangleSelector` is also deprecated.
+
+To retain the behaviour of ``drawtype='none'``, use
+``rectprops={'visible': False}`` to make the drawn
+`~matplotlib.patches.Rectangle` invisible.
+
+These changes also apply to `~matplotlib.widgets.EllipseSelector`, which
+is a sub-class of `~matplotlib.widgets.RectangleSelector`. 

examples/widgets/rectangle_selector.py

@@ -48,9 +48,8 @@ def toggle_selector(event):
     "Click and drag to draw a rectangle.\n"
     "Press 't' to toggle the selector on and off.")
 
-# drawtype is 'box' or 'line' or 'none'
 toggle_selector.RS = RectangleSelector(ax, line_select_callback,
-                                       drawtype='box', useblit=True,
+                                       useblit=True,
                                        button=[1, 3],  # disable middle button
                                        minspanx=5, minspany=5,
                                        spancoords='pixels',

lib/matplotlib/tests/test_widgets.py

@@ -1,7 +1,8 @@
+from matplotlib._api.deprecation import MatplotlibDeprecationWarning
 import matplotlib.colors as mcolors
 import matplotlib.widgets as widgets
 import matplotlib.pyplot as plt
-from matplotlib.testing.decorators import image_comparison
+from matplotlib.testing.decorators import check_figures_equal, image_comparison
 from matplotlib.testing.widgets import do_event, get_ax, mock_event
 
 from numpy.testing import assert_allclose
@@ -37,9 +38,19 @@ def onselect(epress, erelease):
 
 def test_rectangle_selector():
     check_rectangle()
-    check_rectangle(drawtype='line', useblit=False)
+
+    with pytest.warns(
+        MatplotlibDeprecationWarning,
+            match="Support for drawtype='line' is deprecated"):
+        check_rectangle(drawtype='line', useblit=False)
+
     check_rectangle(useblit=True, button=1)
-    check_rectangle(drawtype='none', minspanx=10, minspany=10)
+
+    with pytest.warns(
+        MatplotlibDeprecationWarning,
+            match="Support for drawtype='none' is deprecated"):
+        check_rectangle(drawtype='none', minspanx=10, minspany=10)
+
     check_rectangle(minspanx=10, minspany=10, spancoords='pixels')
     check_rectangle(rectprops=dict(fill=True))
 
@@ -500,3 +511,17 @@ def test_MultiCursor(horizOn, vertOn):
         assert l.get_xdata() == (.5, .5)
     for l in multi.hlines:
         assert l.get_ydata() == (.25, .25)
+
+
+@check_figures_equal()
+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()
+
+    def onselect(verts):
+        pass
+
+    tool = widgets.RectangleSelector(ax_test, onselect,
+                                     rectprops={'visible': False})
+    tool.extents = (0.2, 0.8, 0.3, 0.7)

lib/matplotlib/widgets.py

@@ -2185,6 +2185,8 @@ class RectangleSelector(_SelectorWidget):
 
     _shape_klass = Rectangle
 
+    @_api.delete_parameter("3.5", "drawtype")
+    @_api.delete_parameter("3.5", "lineprops")
     def __init__(self, ax, onselect, drawtype='box',
                  minspanx=0, minspany=0, useblit=False,
                  lineprops=None, rectprops=None, spancoords='data',
@@ -2270,6 +2272,11 @@ def onselect(eclick: MouseEvent, erelease: MouseEvent)
         self.interactive = interactive
 
         if drawtype == 'none':  # draw a line but make it invisible
+            _api.warn_deprecated(
+                "3.5", message="Support for drawtype='none' is deprecated "
+                               "since %(since)s and will be removed "
+                               "%(removal)s."
+                               "Use rectprops=dict(visible=False) instead.")
             drawtype = 'line'
             self.visible = False
 
@@ -2279,10 +2286,15 @@ def onselect(eclick: MouseEvent, erelease: MouseEvent)
                                  alpha=0.2, fill=True)
             rectprops['animated'] = self.useblit
             self.rectprops = rectprops
+            self.visible = self.rectprops.pop('visible', self.visible)
             self.to_draw = self._shape_klass((0, 0), 0, 1, visible=False,
                                              **self.rectprops)
             self.ax.add_patch(self.to_draw)
         if drawtype == 'line':
+            _api.warn_deprecated(
+                "3.5", message="Support for drawtype='line' is deprecated "
+                               "since %(since)s and will be removed "
+                               "%(removal)s.")
             if lineprops is None:
                 lineprops = dict(color='black', linestyle='-',
                                  linewidth=2, alpha=0.5)
@@ -2609,7 +2621,7 @@ def toggle_selector(event):
         fig, ax = plt.subplots()
         ax.plot(x, y)
 
-        toggle_selector.ES = EllipseSelector(ax, onselect, drawtype='line')
+        toggle_selector.ES = EllipseSelector(ax, onselect)
         fig.canvas.mpl_connect('key_press_event', toggle_selector)
         plt.show()
     """