matplotlib
diff --git a/‎doc/users/event_handling.rst
Copy file name to clipboardExpand all lines: doc/users/event_handling.rst
+4-4Lines changed: 4 additions & 4 deletions b/‎doc/users/event_handling.rst
Copy file name to clipboardExpand all lines: doc/users/event_handling.rst
+4-4Lines changed: 4 additions & 4 deletions
diff --git a/‎lib/matplotlib/backend_bases.py
Copy file name to clipboardExpand all lines: lib/matplotlib/backend_bases.py
+10Lines changed: 10 additions & 0 deletions b/‎lib/matplotlib/backend_bases.py
Copy file name to clipboardExpand all lines: lib/matplotlib/backend_bases.py
+10Lines changed: 10 additions & 0 deletions
diff --git a/‎lib/matplotlib/backends/backend_qt5agg.py
Copy file name to clipboardExpand all lines: lib/matplotlib/backends/backend_qt5agg.py
+7-3Lines changed: 7 additions & 3 deletions b/‎lib/matplotlib/backends/backend_qt5agg.py
Copy file name to clipboardExpand all lines: lib/matplotlib/backends/backend_qt5agg.py
+7-3Lines changed: 7 additions & 3 deletions
@@ -57,12 +57,12 @@ Here are the events that you can connect to, the class instances that
 are sent back to you when the event occurs, and the event descriptions
 
 
-=======================  ======================================================================================
+=======================  =============================================================================================
 Event name               Class and description
-=======================  ======================================================================================
+=======================  =============================================================================================
 'button_press_event'     :class:`~matplotlib.backend_bases.MouseEvent`     - mouse button is pressed
 'button_release_event'   :class:`~matplotlib.backend_bases.MouseEvent`     - mouse button is released
-'draw_event'             :class:`~matplotlib.backend_bases.DrawEvent`      - canvas draw
+'draw_event'             :class:`~matplotlib.backend_bases.DrawEvent`      - canvas draw (but before screen update)
 'key_press_event'        :class:`~matplotlib.backend_bases.KeyEvent`       - key is pressed
 'key_release_event'      :class:`~matplotlib.backend_bases.KeyEvent`       - key is released
 'motion_notify_event'    :class:`~matplotlib.backend_bases.MouseEvent`     - mouse motion
@@ -73,7 +73,7 @@ Event name               Class and description
 'figure_leave_event'     :class:`~matplotlib.backend_bases.LocationEvent`  - mouse leaves a figure
 'axes_enter_event'       :class:`~matplotlib.backend_bases.LocationEvent`  - mouse enters a new axes
 'axes_leave_event'       :class:`~matplotlib.backend_bases.LocationEvent`  - mouse leaves an axes
-=======================  ======================================================================================
+=======================  =============================================================================================
 
 .. _event-attributes:
 
 
@@ -1425,6 +1425,16 @@ class DrawEvent(Event):
     """
     An event triggered by a draw operation on the canvas
 
+    In most backends callbacks subscribed to this callback will be
+    fired after the rendering is complete but before the screen is
+    updated.  Any extra artists drawn to the canvas's renderer will
+    be reflected without an explicit call to ``blit``.
+
+    .. warning ::
+
+       Calling ``canvas.draw`` and ``canvas.blit`` in these callbacks may
+       not be safe with all backends and may cause infinite recursion.
+
     In addition to the :class:`Event` attributes, the following event
     attributes are defined:
 
 
@@ -140,18 +140,22 @@ def draw_idle(self):
             QtCore.QTimer.singleShot(0, self.__draw_idle_agg)
 
     def __draw_idle_agg(self, *args):
+        # if nothing to do, bail
         if not self._agg_draw_pending:
             return
+        # we have now tried this function at least once, do not run
+        # again until re-armed.  Doing this here rather than after
+        # protects against recursive calls triggered through self.draw
+        self._agg_draw_pending = False
+        # if negative size, bail
         if self.height() < 0 or self.width() < 0:
-            self._agg_draw_pending = False
             return
         try:
+            # actually do the drawing
             self.draw()
         except Exception:
             # Uncaught exceptions are fatal for PyQt5, so catch them instead.
             traceback.print_exc()
-        finally:
-            self._agg_draw_pending = False
 
     def blit(self, bbox=None):
         """Blit the region in bbox.