diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst index cae555887193..29d123bbbcb6 100644 --- a/doc/api/next_api_changes/deprecations.rst +++ b/doc/api/next_api_changes/deprecations.rst @@ -135,3 +135,12 @@ access the transform classes from the :mod:`.scale` module. ``TexManager.cachedir`` ~~~~~~~~~~~~~~~~~~~~~~~ Use `matplotlib.get_cachedir()` instead. + +Setting `.Line2D`\'s pickradius via `.Line2D.set_picker` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Setting a `.Line2D`\'s pickradius (i.e. the tolerance for pick events +and containment checks) via `.Line2D.set_picker` 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 index 787d621b6ffb..5f8a3d1bb779 100644 --- a/examples/event_handling/legend_picking.py +++ b/examples/event_handling/legend_picking.py @@ -5,45 +5,39 @@ 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 map 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 index 081c38192202..5d73abe2d9b4 100644 --- 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,10 @@ def set_picker(self, picker): artist, return *hit=True* and props is a dictionary of properties you want added to the PickEvent attributes. + - *deprecated*: 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 index 047da1d27e6e..a244e02bb015 100644 --- 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