Deprecate FigureCanvasMac.invalidate in favor of draw_idle.

anntzer · anntzer · commit aefc9871603a · 2019-05-01T12:23:35.000+02:00
... as that name is standard across most interactive backends (I plan to
harmonize the remaining cases -- tk and nbagg -- to use draw_idle as
well).
diff --git a/doc/api/next_api_changes/2019-05-01-AL.rst b/doc/api/next_api_changes/2019-05-01-AL.rst
@@ -0,0 +1,5 @@
+Deprecations
+````````````
+
+``FigureCanvasMac.invalidate`` is deprecated in favor of its synonym,
+``FigureCanvasMac.draw_idle``.
diff --git a/lib/matplotlib/backends/backend_macosx.py b/lib/matplotlib/backends/backend_macosx.py
@@ -6,7 +6,7 @@
     TimerBase)
 
 from matplotlib.figure import Figure
-from matplotlib import rcParams
+from matplotlib import cbook, rcParams
 
 from matplotlib.widgets import SubplotTool
 
@@ -83,15 +83,17 @@ def _draw(self):
 
     def draw(self):
         # docstring inherited
-        self.invalidate()
+        self.draw_idle()
         self.flush_events()
 
-    def draw_idle(self, *args, **kwargs):
-        # docstring inherited
-        self.invalidate()
+    # draw_idle is provided by _macosx.FigureCanvas
+
+    @cbook.deprecated("3.2", alternative="draw_idle()")
+    def invalidate(self):
+        return self.draw_idle()
 
     def blit(self, bbox=None):
-        self.invalidate()
+        self.draw_idle()
 
     def resize(self, width, height):
         dpi = self.figure.dpi
@@ -182,12 +184,7 @@ class _BackendMac(_Backend):
 
     @staticmethod
     def trigger_manager_draw(manager):
-        # For performance reasons, we don't want to redraw the figure after
-        # each draw command. Instead, we mark the figure as invalid, so that it
-        # will be redrawn as soon as the event loop resumes via PyOS_InputHook.
-        # This function should be called after each draw event, even if
-        # matplotlib is not running interactively.
-        manager.canvas.invalidate()
+        manager.canvas.draw_idle()
 
     @staticmethod
     def mainloop():
diff --git a/src/_macosx.m b/src/_macosx.m
@@ -384,7 +384,7 @@ static CGFloat _get_device_scale(CGContextRef cr)
 }
 
 static PyObject*
-FigureCanvas_invalidate(FigureCanvas* self)
+FigureCanvas_draw_idle(FigureCanvas* self)
 {
     View* view = self->view;
     if(!view)
@@ -596,12 +596,12 @@ static CGFloat _get_device_scale(CGContextRef cr)
     {"draw",
      (PyCFunction)FigureCanvas_draw,
      METH_NOARGS,
-     "Draws the canvas."
+     NULL,  // docstring inherited.
     },
-    {"invalidate",
-     (PyCFunction)FigureCanvas_invalidate,
+    {"draw_idle",
+     (PyCFunction)FigureCanvas_draw_idle,
      METH_NOARGS,
-     "Invalidates the canvas."
+     NULL,  // docstring inherited.
     },
     {"flush_events",
      (PyCFunction)FigureCanvas_flush_events,
