Merge pull request #9505 from tacaswell/doc_draw_event_details

jklymak · web-flow · commit e2180d7306fa · 2017-10-22T21:37:54.000-07:00
Doc draw event details
diff --git a/doc/users/event_handling.rst b/doc/users/event_handling.rst
@@ -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:
 
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -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:
 
diff --git a/lib/matplotlib/backends/backend_qt5agg.py b/lib/matplotlib/backends/backend_qt5agg.py
@@ -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.
