Deprecate DraggableBase.artist_picker.

anntzer · anntzer · commit 25d05ac06aff · 2020-02-10T20:59:30.000+01:00
This method could previously be overridden in order to customize the
artist's picker function when dragging it.  However, the default picker
of all artists is already checking whether the artist contain()s the
event; moreover the picker is "global" for the artist so it stays set on
it even after making it undraggable.  Hence it is really just an
artist's property and the user should just call artist.set_picker() if
desired.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -199,3 +199,8 @@ The change from "nonpos" to "nonpositive" also affects `~.scale.LogTransform`,
 
 To use *different* bases for the x-axis and y-axis of a `~.Axes.loglog` plot,
 use e.g. ``ax.set_xscale("log", base=10); ax.set_yscale("log", base=2)``.
+
+``DraggableBase.artist_picker``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This method is deprecated.  If you previously reimplemented it in a subclass,
+set the artist's picker instead with `.Artist.set_picker`.
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -1694,11 +1694,7 @@ def update_offset(self, dx, dy):
             the point where the mouse drag started.
             '''
 
-    Optionally, you may override the following methods::
-
-        def artist_picker(self, artist, evt):
-            '''The picker method that will be used.'''
-            return self.ref_artist.contains(evt)
+    Optionally, you may override the following method::
 
         def finalize_offset(self):
             '''Called when the mouse is released.'''
@@ -1719,7 +1715,18 @@ def __init__(self, ref_artist, use_blit=False):
         c2 = self.canvas.mpl_connect('pick_event', self.on_pick)
         c3 = self.canvas.mpl_connect('button_release_event', self.on_release)
 
-        ref_artist.set_picker(self.artist_picker)
+        if not ref_artist.pickable():
+            ref_artist.set_picker(True)
+        with cbook._suppress_matplotlib_deprecation_warning():
+            if self.artist_picker != DraggableBase.artist_picker.__get__(self):
+                overridden_picker = self.artist_picker
+            else:
+                overridden_picker = None
+        if overridden_picker is not None:
+            cbook.warn_deprecated(
+                "3.3", name="artist_picker", obj_type="method",
+                addendum="Directly set the artist's picker if desired.")
+            ref_artist.set_picker(overridden_picker)
         self.cids = [c2, c3]
 
     def on_motion(self, evt):
@@ -1786,6 +1793,7 @@ def disconnect(self):
         else:
             self.canvas.mpl_disconnect(c1)
 
+    @cbook.deprecated("3.3", alternative="self.ref_artist.contains")
     def artist_picker(self, artist, evt):
         return self.ref_artist.contains(evt)
 
