Deprecate setting Line2D's pickradius via set_picker.

anntzer · anntzer · commit dd78991857e0 · 2020-01-08T01:56:41.000+01:00
There's set_pickradius just for that purpose; moreover
`set_picker(True)` would previously accidentally also set the pickradius
to 1 (because True == 1...).

Also don't set self._contains in Line2D.set_picker -- this is consistent
with all other artist classes.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -124,3 +124,11 @@ The following parameters do not have any effect and are deprecated:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This method is deprecated.  Use
 ``ax.dataLim.set(Bbox.union([ax.dataLim, bounds]))`` instead.
+
+Setting `.Line2D`\'s pickradius via `.Line2D.set_picker`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Setting a `.Line2D`\'s pickradius (i.e. the tolerance for pick events and
+containment checks) is deprecated.  Use `.Line2D.set_pickradius` instead.
+
+`.Line2D.set_picker` no longer sets the artist's custom-contain() check.  Use
+``Line2D.set_contains`` instead.
diff --git a/examples/event_handling/legend_picking.py b/examples/event_handling/legend_picking.py
@@ -5,45 +5,37 @@
 
 Enable picking on the legend to toggle the original line on and off
 """
+
 import numpy as np
 import matplotlib.pyplot as plt
 
-t = np.arange(0.0, 0.2, 0.1)
-y1 = 2*np.sin(2*np.pi*t)
-y2 = 4*np.sin(2*np.pi*2*t)
+t = np.linspace(0, 1)
+y1 = 2 * np.sin(2*np.pi*t)
+y2 = 4 * np.sin(2*np.pi*2*t)
 
 fig, ax = plt.subplots()
 ax.set_title('Click on legend line to toggle line on/off')
-line1, = ax.plot(t, y1, lw=2, label='1 HZ')
-line2, = ax.plot(t, y2, lw=2, label='2 HZ')
-leg = ax.legend(loc='upper left', fancybox=True, shadow=True)
-leg.get_frame().set_alpha(0.4)
-
+line1, = ax.plot(t, y1, lw=2, label='1 Hz')
+line2, = ax.plot(t, y2, lw=2, label='2 Hz')
+leg = ax.legend(fancybox=True, shadow=True)
 
-# we will set up a dict mapping legend line to orig line, and enable
-# picking on the legend line
 lines = [line1, line2]
-lined = dict()
+lined = {}  # Will legend lines to original lines.
 for legline, origline in zip(leg.get_lines(), lines):
-    legline.set_picker(5)  # 5 pts tolerance
+    legline.set_picker(True)  # Enable picking on the legend line.
     lined[legline] = origline
 
-
 def on_pick(event):
-    # on the pick event, find the orig line corresponding to the
-    # legend proxy line, and toggle the visibility
+    # On the pick event, find the original line corresponding to the legend
+    # proxy line, and toggle its visibility.
     legline = event.artist
     origline = lined[legline]
-    vis = not origline.get_visible()
-    origline.set_visible(vis)
+    visible = not origline.get_visible()
+    origline.set_visible(visible)
     # Change the alpha on the line in the legend so we can see what lines
-    # have been toggled
-    if vis:
-        legline.set_alpha(1.0)
-    else:
-        legline.set_alpha(0.2)
+    # have been toggled.
+    legline.set_alpha(1.0 if visible else 0.2)
     fig.canvas.draw()
 
 fig.canvas.mpl_connect('pick_event', on_pick)
-
 plt.show()
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -516,7 +516,7 @@ def set_picker(self, picker):
 
         Parameters
         ----------
-        picker : None or bool or float or callable
+        picker : None or bool or callable
             This can be one of the following:
 
             - *None*: Picking is disabled for this artist (default).
@@ -525,14 +525,6 @@ def set_picker(self, picker):
               artist will fire a pick event if the mouse event is over
               the artist.
 
-            - A float: If picker is a number it is interpreted as an
-              epsilon tolerance in points and the artist will fire
-              off an event if it's data is within epsilon of the mouse
-              event.  For some artists like lines and patch collections,
-              the artist may provide additional data to the pick event
-              that is generated, e.g., the indices of the data within
-              epsilon of the pick event
-
             - A function: If picker is callable, it is a user supplied
               function which determines whether the artist is hit by the
               mouse event::
@@ -543,6 +535,9 @@ def set_picker(self, picker):
               artist, return *hit=True* and props is a dictionary of
               properties you want added to the PickEvent attributes.
 
+            - For `.Line2D` only, *picker* can also be a float that sets the
+              tolerance for checking whether an event occurred "on" the line;
+              this is deprecated.  Use `.Line2D.set_pickradius` instead.
         """
         self._picker = picker
 
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -399,8 +399,6 @@ def __init__(self, xdata, ydata,
         self.update(kwargs)
         self.pickradius = pickradius
         self.ind_offset = 0
-        if isinstance(self._picker, Number):
-            self.pickradius = self._picker
 
         self._xorig = np.asarray([])
         self._yorig = np.asarray([])
@@ -603,16 +601,12 @@ def get_markevery(self):
         return self._markevery
 
     def set_picker(self, p):
-        """Sets the event picker details for the line.
-
-        Parameters
-        ----------
-        p : float or callable[[Artist, Event], Tuple[bool, dict]]
-            If a float, it is used as the pick radius in points.
-        """
-        if callable(p):
-            self._contains = p
-        else:
+        # docstring inherited
+        if isinstance(p, Number) and not isinstance(p, bool):
+            # After deprecation, the whole method can be deleted and inherited.
+            cbook.warn_deprecated(
+                "3.3", message="Setting the line's pick radius via set_picker "
+                "is deprecated; use set_pickradius instead.")
             self.pickradius = p
         self._picker = p
 
