DOC : add whats new entry

tacaswell · tacaswell · commit 16bcbdfe4dfc · 2015-05-25T00:50:37.000-04:00
diff --git a/doc/users/whats_new/2015-05_interactive_OO.rst b/doc/users/whats_new/2015-05_interactive_OO.rst
@@ -0,0 +1,37 @@
+Interactive OO usage
+--------------------
+
+All `Artists` now keep track of if their internal state has been
+changed but not reflected in the display ('stale') by a call to
+``draw``.  It is thus possible to pragmatically determine if a given
+`Figure` needs to be re-drawn in an interactive session.
+
+To facilitate interactive usage a ``draw_all`` method has been added
+to ``pyplot`` which will redraw all of the figures which are 'stale'.
+
+To make this convenient for interactive use matplotlib now registers
+a function either with IPython's 'post_execute' event or with the
+displayhook in the standard python REPL to automatically call
+``plt.draw_all`` just before control is returned to the REPL.  This ensures
+that the draw command is deferred and only called once.
+
+The upshot of this is that for interactive backends (including notebook)
+
+.. ipython :: python
+
+   import matplotlib.pyplot as plt
+
+   fig, ax = plt.subplots()
+
+   ln, = ax.plot([0, 1, 4, 9, 16])
+
+   plt.show()
+
+   ln.set_color('g')
+
+
+will automatically update the plot to be green.  Subsequent
+modifications to the `Artist` objects will do likewise.
+
+This is the first step of a larger consolidation and simplification of
+the pyplot internals.
