From aefc9871603af821b25055f0b96a0db5ddf4843e Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Wed, 1 May 2019 11:59:46 +0200
Subject: [PATCH] Deprecate FigureCanvasMac.invalidate in favor of draw_idle.

... 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).
---
 doc/api/next_api_changes/2019-05-01-AL.rst |  5 +++++
 lib/matplotlib/backends/backend_macosx.py  | 21 +++++++++------------
 src/_macosx.m                              | 10 +++++-----
 3 files changed, 19 insertions(+), 17 deletions(-)
 create mode 100644 doc/api/next_api_changes/2019-05-01-AL.rst

diff --git a/doc/api/next_api_changes/2019-05-01-AL.rst b/doc/api/next_api_changes/2019-05-01-AL.rst
new file mode 100644
index 000000000000..96bbf3775278
--- /dev/null
+++ 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
index ca32842ae55a..b828e74b28fe 100644
--- 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
index ef66f56ddadc..65f091f3d0d4 100644
--- 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,