Merge pull request #17826 from DCtheTall/pauseresume

dopplershift · web-flow · commit 3c8af996415c · 2020-07-28T17:58:55.000-06:00
Add pause() and resume() methods to the base Animation class
diff --git a/doc/missing-references.json b/doc/missing-references.json
@@ -1136,6 +1136,12 @@
     "matplotlib.animation.ArtistAnimation.to_jshtml": [
       "doc/api/_as_gen/matplotlib.animation.ArtistAnimation.rst:21:<autosummary>:1"
     ],
+    "matplotlib.animation.ArtistAnimation.pause": [
+      "doc/api/_as_gen/matplotlib.animation.ArtistAnimation.rst:23:<autosummary>:1"
+    ],
+    "matplotlib.animation.ArtistAnimation.resume": [
+      "doc/api/_as_gen/matplotlib.animation.ArtistAnimation.rst:23:<autosummary>:1"
+    ],
     "matplotlib.animation.FFMpegFileWriter.args_key": [
       "lib/matplotlib/animation.py:docstring of matplotlib.animation.FFMpegFileWriter.supported_formats:1:<autosummary>:1"
     ],
@@ -1235,6 +1241,12 @@
     "matplotlib.animation.FuncAnimation.to_jshtml": [
       "lib/matplotlib/animation.py:docstring of matplotlib.animation.FuncAnimation.new_frame_seq:1:<autosummary>:1"
     ],
+    "matplotlib.animation.FuncAnimation.pause": [
+      "doc/api/_as_gen/matplotlib.animation.ArtistAnimation.rst:23:<autosummary>:1"
+    ],
+    "matplotlib.animation.FuncAnimation.resume": [
+      "doc/api/_as_gen/matplotlib.animation.ArtistAnimation.rst:23:<autosummary>:1"
+    ],
     "matplotlib.animation.HTMLWriter.bin_path": [
       "doc/api/_as_gen/matplotlib.animation.HTMLWriter.rst:28:<autosummary>:1"
     ],
@@ -1361,6 +1373,12 @@
     "matplotlib.animation.TimedAnimation.to_jshtml": [
       "doc/api/_as_gen/matplotlib.animation.TimedAnimation.rst:21:<autosummary>:1"
     ],
+    "matplotlib.animation.TimedAnimation.pause": [
+      "doc/api/_as_gen/matplotlib.animation.ArtistAnimation.rst:23:<autosummary>:1"
+    ],
+    "matplotlib.animation.TimedAnimation.resume": [
+      "doc/api/_as_gen/matplotlib.animation.ArtistAnimation.rst:23:<autosummary>:1"
+    ],
     "matplotlib.cbook.ls_mapper": [
       "doc/api/prev_api_changes/api_changes_1.5.0.rst:11",
       "doc/api/prev_api_changes/api_changes_1.5.0.rst:8"
diff --git a/doc/users/next_whats_new/pausing_animations.rst b/doc/users/next_whats_new/pausing_animations.rst
@@ -0,0 +1,6 @@
+Pausing and Resuming Animations
+-------------------------------
+The `.animation.Animation.pause` and `.animation.Animation.resume` methods
+allow you to pause and resume animations. These methods can be used as callbacks
+for event listeners on UI elements so that your plots can have some playback
+control UI.
diff --git a/examples/animation/pause_resume.py b/examples/animation/pause_resume.py
@@ -0,0 +1,47 @@
+"""
+=================================
+Pausing and Resuming an Animation
+=================================
+
+This example showcases:
+- using the Animation.pause() method to pause an animation.
+- using the Animation.resume() method to resume an animation.
+"""
+
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import numpy as np
+
+
+class PauseAnimation:
+    def __init__(self):
+        fig, ax = plt.subplots()
+        ax.set_title('Click to pause/resume the animation')
+        x = np.linspace(-0.1, 0.1, 1000)
+
+        # Start with a normal distribution
+        self.n0 = (1.0 / ((4 * np.pi * 2e-4 * 0.1) ** 0.5)
+                   * np.exp(-x ** 2 / (4 * 2e-4 * 0.1)))
+        self.p, = ax.plot(x, self.n0)
+
+        self.animation = animation.FuncAnimation(
+            fig, self.update, frames=200, interval=50, blit=True)
+        self.paused = False
+
+        fig.canvas.mpl_connect('button_press_event', self.toggle_pause)
+
+    def toggle_pause(self, *args, **kwargs):
+        if self.paused:
+            self.animation.resume()
+        else:
+            self.animation.pause()
+        self.paused = not self.paused
+
+    def update(self, i):
+        self.n0 += i / 100 % 5
+        self.p.set_ydata(self.n0 % 20)
+        return (self.p,)
+
+
+pa = PauseAnimation()
+plt.show()
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -1355,6 +1355,20 @@ def _repr_html_(self):
         elif fmt == 'jshtml':
             return self.to_jshtml()
 
+    def pause(self):
+        """Pause the animation."""
+        self.event_source.stop()
+        if self._blit:
+            for artist in self._drawn_artists:
+                artist.set_animated(False)
+
+    def resume(self):
+        """Resume the animation."""
+        self.event_source.start()
+        if self._blit:
+            for artist in self._drawn_artists:
+                artist.set_animated(True)
+
 
 class TimedAnimation(Animation):
     """
