Merge pull request #10050 from timhoffm/legend-draggable

jklymak · web-flow · commit d2968e651914 · 2018-05-17T09:20:26.000-07:00
Update Legend draggable API
diff --git a/doc/api/animation_api.rst b/doc/api/animation_api.rst
@@ -36,6 +36,9 @@ To save an animation to disk use `Animation.save` or `Animation.to_html5_video`
 See :ref:`ani_writer_classes` below for details about what movie formats are
 supported.
 
+
+.. _func-animation:
+
 ``FuncAnimation``
 -----------------
 
diff --git a/doc/api/api_changes/2017-12-20-TH.rst b/doc/api/api_changes/2017-12-20-TH.rst
@@ -0,0 +1,5 @@
+Deprecations
+````````````
+
+`.Legend.draggable()` is drepecated in favor of `.Legend.set_draggable()`.
+``Legend.draggable`` may be reintroduced as a property in future releases.
diff --git a/lib/matplotlib/backends/qt_editor/figureoptions.py b/lib/matplotlib/backends/qt_editor/figureoptions.py
@@ -242,7 +242,7 @@ def apply_callback(data):
                 ncol = old_legend._ncol
             new_legend = axes.legend(ncol=ncol)
             if new_legend:
-                new_legend.draggable(draggable)
+                new_legend.set_draggable(draggable)
 
         # Redraw
         figure = axes.get_figure()
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -31,7 +31,7 @@
 from matplotlib import rcParams
 from matplotlib import docstring
 from matplotlib.artist import Artist, allow_rasterization
-from matplotlib.cbook import silent_list, is_hashable
+from matplotlib.cbook import silent_list, is_hashable, warn_deprecated
 import matplotlib.colors as colors
 from matplotlib.font_manager import FontProperties
 from matplotlib.lines import Line2D
@@ -52,11 +52,18 @@
 class DraggableLegend(DraggableOffsetBox):
     def __init__(self, legend, use_blit=False, update="loc"):
         """
+        Wrapper around a `.Legend` to support mouse dragging.
+
         Parameters
         ----------
-        update : string
-            If "loc", update *loc* parameter of legend upon finalizing.
-            If "bbox", update *bbox_to_anchor* parameter.
+        legend : `.Legend`
+            The `.Legend` instance to wrap.
+        use_blit : bool, optional
+            Use blitting for faster image composition. For details see
+            :ref:`func-animation`.
+        update : {'loc', 'bbox'}, optional
+            If "loc", update the *loc* parameter of the legend upon finalizing.
+            If "bbox", update the *bbox_to_anchor* parameter.
         """
         self.legend = legend
 
@@ -1110,6 +1117,43 @@ def _find_best_position(self, width, height, renderer, consider=None):
     def contains(self, event):
         return self.legendPatch.contains(event)
 
+    def set_draggable(self, state, use_blit=False, update='loc'):
+        """
+        Enable or disable mouse dragging support of the legend.
+
+        Parameters
+        ----------
+        state : bool
+            ``True`` / ``False`` enables / disables mouse dragging.
+        use_blit : bool, optional
+            Use blitting for faster image composition. For details see
+            :ref:`func-animation`.
+        update : ['loc' | 'bbox'], optional
+            The legend parameter to be changed when dragged:
+
+            - 'loc': update the *loc* parameter of the legend
+            - 'bbox': update the *bbox_to_anchor* parameter of the legend
+
+        Returns
+        -------
+        If *state* is ``True`` this returns the `~.DraggableLegend` helper
+        instance. Otherwise this returns ``None``.
+        """
+        if state:
+            if self._draggable is None:
+                self._draggable = DraggableLegend(self,
+                                                  use_blit,
+                                                  update=update)
+        else:
+            if self._draggable is not None:
+                self._draggable.disconnect()
+            self._draggable = None
+        return self._draggable
+
+    def get_draggable(self):
+        """Return ``True`` if the legend is draggable, ``False`` otherwise."""
+        return self._draggable is not None
+
     def draggable(self, state=None, use_blit=False, update="loc"):
         """
         Set the draggable state -- if state is
@@ -1128,21 +1172,16 @@ def draggable(self, state=None, use_blit=False, update="loc"):
         when dragged. If update is "loc", the *loc* parameter of the legend
         is changed. If "bbox", the *bbox_to_anchor* parameter is changed.
         """
-        is_draggable = self._draggable is not None
+        warn_deprecated("2.2",
+                        message="Legend.draggable() is drepecated in "
+                                "favor of Legend.set_draggable(). "
+                                "Legend.draggable may be reintroduced as a "
+                                "property in future releases.")
 
-        # if state is None we'll toggle
         if state is None:
-            state = not is_draggable
+            state = not self.get_draggable()  # toggle state
 
-        if state:
-            if self._draggable is None:
-                self._draggable = DraggableLegend(self,
-                                                  use_blit,
-                                                  update=update)
-        else:
-            if self._draggable is not None:
-                self._draggable.disconnect()
-            self._draggable = None
+        self.set_draggable(state, use_blit, update)
 
         return self._draggable
 
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -12,6 +12,7 @@
 import matplotlib.collections as mcollections
 from matplotlib.legend_handler import HandlerTuple
 import matplotlib.legend as mlegend
+from matplotlib.cbook.deprecation import MatplotlibDeprecationWarning
 
 
 def test_legend_ordereddict():
@@ -511,3 +512,30 @@ def test_legend_title_fontsize():
     ax.plot(range(10))
     leg = ax.legend(title='Aardvark', title_fontsize=22)
     assert leg.get_title().get_fontsize() == 22
+
+
+def test_get_set_draggable():
+    legend = plt.legend()
+    assert not legend.get_draggable()
+    legend.set_draggable(True)
+    assert legend.get_draggable()
+    legend.set_draggable(False)
+    assert not legend.get_draggable()
+
+
+def test_draggable():
+    legend = plt.legend()
+    with pytest.warns(MatplotlibDeprecationWarning):
+        legend.draggable(True)
+    assert legend.get_draggable()
+    with pytest.warns(MatplotlibDeprecationWarning):
+        legend.draggable(False)
+    assert not legend.get_draggable()
+
+    # test toggle
+    with pytest.warns(MatplotlibDeprecationWarning):
+        legend.draggable()
+    assert legend.get_draggable()
+    with pytest.warns(MatplotlibDeprecationWarning):
+        legend.draggable()
+    assert not legend.get_draggable()
