Deprecate DraggableBase.artist_picker.

anntzer · anntzer · commit 2033ee7f8d21 · 2020-01-06T22:48:16.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
@@ -124,3 +124,8 @@ 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.
+
+``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
@@ -1697,11 +1697,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.'''
@@ -1722,7 +1718,17 @@ 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)
+        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):
@@ -1789,6 +1795,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)
 
