add animation func getter and clear_animations() method (#896)

clewis7 · web-flow · commit 8b128d34008a · 2025-10-22T18:36:05.000-04:00
* add animation func getter and clear() method

* requested changes

* fix kwarg name

* requested changes

* update api docs
diff --git a/docs/source/api/layouts/figure.rst b/docs/source/api/layouts/figure.rst
@@ -20,6 +20,7 @@ Properties
 .. autosummary::
     :toctree: Figure_api
 
+    Figure.animations
     Figure.cameras
     Figure.canvas
     Figure.controllers
@@ -38,6 +39,7 @@ Methods
     Figure.add_animations
     Figure.add_subplot
     Figure.clear
+    Figure.clear_animations
     Figure.close
     Figure.export
     Figure.export_numpy
diff --git a/docs/source/api/layouts/imgui_figure.rst b/docs/source/api/layouts/imgui_figure.rst
@@ -20,6 +20,7 @@ Properties
 .. autosummary::
     :toctree: ImguiFigure_api
 
+    ImguiFigure.animations
     ImguiFigure.cameras
     ImguiFigure.canvas
     ImguiFigure.controllers
@@ -42,6 +43,7 @@ Methods
     ImguiFigure.add_gui
     ImguiFigure.add_subplot
     ImguiFigure.clear
+    ImguiFigure.clear_animations
     ImguiFigure.close
     ImguiFigure.export
     ImguiFigure.export_numpy
diff --git a/docs/source/api/layouts/subplot.rst b/docs/source/api/layouts/subplot.rst
@@ -20,6 +20,7 @@ Properties
 .. autosummary::
     :toctree: Subplot_api
 
+    Subplot.animations
     Subplot.axes
     Subplot.background_color
     Subplot.camera
@@ -57,6 +58,7 @@ Methods
     Subplot.center_graphic
     Subplot.center_scene
     Subplot.clear
+    Subplot.clear_animations
     Subplot.delete_graphic
     Subplot.get_figure
     Subplot.insert_graphic
diff --git a/fastplotlib/layouts/_figure.py b/fastplotlib/layouts/_figure.py
@@ -543,6 +543,11 @@ def show_tooltips(self) -> bool:
         """show/hide tooltips for all graphics"""
         return self._show_tooltips
 
+    @property
+    def animations(self) -> dict[str, list[callable]]:
+        """Returns a dictionary of 'pre' and 'post' animation functions."""
+        return {"pre": self._animate_funcs_pre, "post": self._animate_funcs_post}
+
     @show_tooltips.setter
     def show_tooltips(self, val: bool):
         self._show_tooltips = val
@@ -765,6 +770,37 @@ def remove_animation(self, func):
         if func in self._animate_funcs_post:
             self._animate_funcs_post.remove(func)
 
+    def clear_animations(self, removal: str = None):
+        """
+        Remove animation functions.
+
+        Parameters
+        ----------
+        removal: str, default ``None``
+            The type of animation functions to clear. One of 'pre' or 'post'. If `None`, removes all animation
+            functions.
+        """
+        if removal is None:
+            # remove all
+            for func in self._animate_funcs_pre:
+                self._animate_funcs_pre.remove(func)
+
+            for func in self._animate_funcs_post:
+                self._animate_funcs_post.remove(func)
+        elif removal == "pre":
+            # only pre
+            for func in self._animate_funcs_pre:
+                self._animate_funcs_pre.remove(func)
+        elif removal == "post":
+            # only post
+            for func in self._animate_funcs_post:
+                self._animate_funcs_post.remove(func)
+        else:
+            raise ValueError(
+                f"Animation type: {removal} must be one of 'pre' or 'post'. To remove all animation "
+                f"functions, pass `type=None`"
+            )
+
     def clear(self):
         """Clear all Subplots"""
         for subplot in self:
diff --git a/fastplotlib/layouts/_plot_area.py b/fastplotlib/layouts/_plot_area.py
@@ -274,6 +274,11 @@ def background_color(self, colors: str | tuple[float]):
         """1, 2, or 4 colors, each color must be acceptable by pygfx.Color"""
         self._background_material.set_colors(*colors)
 
+    @property
+    def animations(self) -> dict[str, list[callable]]:
+        """Returns a dictionary of 'pre' and 'post' animation functions."""
+        return {"pre": self._animate_funcs_pre, "post": self._animate_funcs_post}
+
     def map_screen_to_world(
         self, pos: tuple[float, float] | pygfx.PointerEvent, allow_outside: bool = False
     ) -> np.ndarray | None:
@@ -395,6 +400,37 @@ def remove_animation(self, func):
         if func in self._animate_funcs_post:
             self._animate_funcs_post.remove(func)
 
+    def clear_animations(self, removal: str = None):
+        """
+        Remove animation functions.
+
+        Parameters
+        ----------
+        removal: str, default ``None``
+            The type of animation functions to clear. One of 'pre' or 'post'. If `None`, removes all animation
+            functions.
+        """
+        if removal is None:
+            # remove all
+            for func in self._animate_funcs_pre:
+                self._animate_funcs_pre.remove(func)
+
+            for func in self._animate_funcs_post:
+                self._animate_funcs_post.remove(func)
+        elif removal == "pre":
+            # only pre
+            for func in self._animate_funcs_pre:
+                self._animate_funcs_pre.remove(func)
+        elif removal == "post":
+            # only post
+            for func in self._animate_funcs_post:
+                self._animate_funcs_post.remove(func)
+        else:
+            raise ValueError(
+                f"Animation type: {removal} must be one of 'pre' or 'post'. To remove all animation "
+                f"functions, pass `type=None`"
+            )
+
     def _sort_images_by_depth(self):
         """
         In general, we want to avoid setting the offset of a graphic, because the
