Ths chapter discusses how to use Textual's animation system to create visual effects such as movement, blending, and fading.
Textual's animator can change an attribute from one value to another in fixed increments over a period of time. You can apply animations to styles such as
offset to move widgets around the screen, and
opacity to create fading effects.
Apps and widgets both have an animate method which will animate properties on those objects. Additionally,
styles objects have an identical
animate method which will animate styles.
Let's look at an example of how we can animate the opacity of a widget to make it fade out.
The following example app contains a single
Static widget which is immediately animated to an opacity of
0.0 (making it invisible) over a duration of two seconds.
from textual.app import App, ComposeResult from textual.widgets import Static class AnimationApp(App): def compose(self) -> ComposeResult: self.box = Static("Hello, World!") self.box.styles.background = "red" self.box.styles.color = "black" self.box.styles.padding = (1, 2) yield self.box def on_mount(self): self.box.styles.animate("opacity", value=0.0, duration=2.0) if __name__ == "__main__": app = AnimationApp() app.run()
The animator updates the value of the
opacity attribute on the
styles object in small increments over two seconds. Here's what the output will look like after each half a second.
Duration and Speed¶
When requesting an animation you can specify a duration or speed. The duration is how long the animation should take in seconds. The speed is how many units a value should change in one second. For instance, if you animate a value at 0 to 10 with a speed of 2, it will complete in 5 seconds.
The easing function determines the journey a value takes on its way to the target value. It could move at a constant pace, or it might start off slow then accelerate towards its final value. Textual supports a number of easing functions.
Run the following from the command prompt to preview them.
You can specify which easing method to use via the
easing parameter on the
animate method. The default easing method is
"in_out_cubic" which accelerates and then decelerates to produce a pleasing organic motion.
textual easing preview requires the
textual-dev package to be installed (using
pip install textual-dev).
You can pass a callable to the animator via the
on_complete parameter. Textual will run the callable when the animation has completed.
You can delay the start of an animation with the
delay parameter of the
This parameter accepts a
float value representing the number of seconds to delay the animation by.
self.box.styles.animate("opacity", value=0.0, duration=2.0, delay=5.0) delays the start of the animation by five seconds,
meaning the animation will start after 5 seconds and complete 2 seconds after that.