Animation
Alto moves a few things on purpose: the exercise list slides shut, the settings pane slides open and its pages slide in and out, switches slide, and an answer button fades to green or red. None of it is decoration. Motion tells the eye what changed and where it went. This chapter explains Qt’s animation tools, how each of Alto’s animations is built, the patterns that keep them from going wrong, and the design rules that decide how long and in what manner to move something.
What an animation is
An animation changes a value over time. Everything else follows from that sentence.
- Pick a value that describes the look: a number from 0 to 1, a position, a width, a colour.
- Pick a start and an end and a duration.
- At each tick Qt computes where the value is on its way (a number between the start and the end, shaped by an easing curve) and hands it to you.
- You apply it: move something, resize it, set a colour, call
update()and repaint with it.
A screen refreshes about 60 times a second, so a 200 ms animation is roughly twelve frames. Qt drives the ticks from its event loop, which means they stop if you block the loop. That is why the first rule of Qt and PySide6 (never block) is also the first rule of animation.
The tools Qt provides
| Class | What it does |
|---|---|
QVariantAnimation |
Animates any value (a float, a colour, a point) and calls a function with each value: valueChanged. The general tool. |
QPropertyAnimation |
Animates a named property of an object (b"pos", b"maximumWidth", b"volume") directly, so you do not write the callback. |
QParallelAnimationGroup |
Runs several animations at once. |
QSequentialAnimationGroup |
Runs them one after another. |
QEasingCurve |
Shapes the progress: OutCubic, InOutQuad, Linear, OutBack and about forty more. |
QTimer |
Not an animation, but the tool for “do this once, later”. |
Two of these cover nearly everything. Use QPropertyAnimation when the thing you are animating is already a Qt property, and
QVariantAnimation when it is not (or you need to draw from the value).
Easing
A linear animation moves at constant speed, which looks mechanical, because real things accelerate and slow. An easing
curve changes the speed over the animation. The names say where the speed changes: In starts slowly, Out ends slowly,
InOut does both. Alto uses OutCubic almost everywhere: it starts fast and settles gently, which feels responsive,
because the first thing the user sees is immediate movement. The curves go back to the easing equations of Robert Penner,
which Qt’s set is based on.
Rules of thumb that most design systems agree on: use ease-out for things entering or responding to the user (they arrive and settle); ease-in for things leaving (they accelerate away); ease-in-out for things that move from one place to another on screen; and linear only for colour fades, rotations and progress bars, where no physical object is implied.
Alto’s animations, one at a time
The settings page slide: SlideStack
SlideStack in settings_panel.py is a QStackedWidget whose pages slide instead of switching. It is a good model of how
to build a transition by hand:
def slide_to(self, index):
if self.sliding or index == self.currentIndex():
return # ignore requests mid-transition
old, new = self.currentWidget(), self.widget(index)
w, sign = self.width(), 1 if index > self.currentIndex() else -1
new.setGeometry(0, 0, w, self.height())
new.move(sign * w, 0) # park the new page just outside, on the side it enters from
new.show()
new.raise_()
group = QParallelAnimationGroup(self)
for widget, start, end in ((old, 0, -sign * w), (new, sign * w, 0)):
anim = QPropertyAnimation(widget, b"pos", group) # animate the widget's own position property
anim.setDuration(220)
anim.setEasingCurve(QEasingCurve.Type.OutCubic)
anim.setStartValue(QPoint(start, 0))
anim.setEndValue(QPoint(end, 0))
group.addAnimation(anim)
group.finished.connect(done) # setCurrentIndex(index) and put both pages at (0, 0)
group.start()
Points to copy: the new page is positioned off-screen before it is shown (otherwise it flashes in place for one frame); the two
pages move in parallel; a request that arrives mid-slide is ignored rather than queued (so a double click does not slide twice);
and the final state is set in finished, not assumed, so the widgets always end in a clean position.
Opening and closing a pane: animate a limit
The exercise’s settings pane opens by animating maximumWidth of the pane from 0 to PANE_WIDTH (QPropertyAnimation(self.pane,
b"maximumWidth", self), 220 ms, OutCubic). The layout does the rest: as the pane’s allowed width grows, the layout gives it
the room and shrinks its neighbour. This is a common Qt trick: animate a constraint, not a position, and let the layout
move everything. The pane is hidden when it finishes at zero (_pane_settled) so it takes no space and cannot be tabbed into.
The sidebar: animate the splitter
The sidebar collapse in MainWindow._set_sidebar uses a QVariantAnimation from the current width to the target and, on each
tick, calls splitter.setSizes. The animation is a number; the callback decides what the number means. Two details:
- It temporarily lowers the list’s minimum width so the width can pass through values below the usual minimum, and restores it
in
done. - It stops the previous animation first (
self._sidebar_anim.stop()) and starts from wherever the sidebar currently is, so clicking the toggle in the middle of a slide reverses smoothly instead of jumping.
The switch knob: animate a number, paint from it
Switch (also in settings_panel.py) holds a float _pos between 0 and 1. A QVariantAnimation of 140 ms moves _pos, and
each tick calls update(). paintEvent draws the track colour as blend(off, b=on, t=self._pos) and the knob at
margin + r + _pos * travel. One number drives both the colour and the position, so they cannot disagree. The class
setChecked skips the animation (“no animation when set programmatically”) so that loading a setting at start-up does not
make every switch slide.
The right/wrong flash: animate a colour
ExerciseView._flash fades an answer button from black to green or red in 350 ms with a linear curve, because it is a colour
fade. It uses QVariantAnimation with a start of 0.0 and an end of 1.0 and in its callback computes blend(start, b=end, t=t)
and sets the button’s style sheet from the result. The animations are kept in a list (self._anims) that is cleared when the next
question appears, so nothing animates a button that no longer exists.
The fade of a sound
Not visual, but the same idea: Sounds._release fades a QSoundEffect’s volume property to 0 in 70 ms with a
QPropertyAnimation, then stops it. See Computer audio.
Patterns that keep animations correct
- Keep a reference. A
QVariantAnimationcreated in a function with no parent and no stored reference can be garbage collected while running, and simply stops. Give it a parent (QVariantAnimation(self)) or store it (self._anim = ...). - Stop the old one first. If an animation of the same property may already be running, call
.stop()before starting a new one, and start from the current value, not from a remembered end. Otherwise two animations fight. - Set the end state in
finished. Do not rely on the last tick landing exactly on the end value. - Guard against re-entry. Ignore a request while a transition is running (
SlideStack), or cancel and restart (the sidebar). Decide deliberately which; the one you did not decide on is the one with the bug. - Cancel late callbacks with a token. A
QTimer.singleShotcannot be cancelled once scheduled. If the callback might fire after the state has moved on (a new question has appeared), have it compare a counter it captured against the current one and do nothing if they differ.ExerciseView._pair_tokenandSounds._sequence_rundo this. - Do not animate loading. Setting a value from saved settings should jump, not animate (see
Switch.setChecked). - Animate cheap things. Each tick repaints. Moving a widget or changing a width is cheap; repainting a large, complex
widget sixty times a second is not. If a widget is expensive to draw, draw it once into a
QPixmapand animate the pixmap.
Testing animations
Tests run the event loop long enough for an animation to finish: QTest.qWait(300) after triggering a 220 ms slide, then
assert the end state. A shorter wait asserts the middle. tests/test_settings_panels.py has a slide() helper that waits
300 ms for a page to finish sliding, and SlideStack.sliding reports whether a slide is under way. To test that your code ignores a request
during a slide, call it twice in a row and assert one slide happened.
Because tests wait in real time, keep durations short. There is no virtual clock in Qt’s animation framework.
Deciding how it should move
A few principles, from animation and interface design.
- Duration. Interface animations feel good between about 150 and 300 ms. Under 100 ms the eye barely registers movement; over 500 ms it feels slow, and a user doing something repeatedly is made to wait. Larger moves can take longer than small ones. Alto’s are 70 to 350 ms.
- Purpose. Each animation should answer a question: where did that come from, what changed, did my action work? An animation that only decorates is noise the second time you see it.
- Direction means something. A page that slides in from the right says “forward”; sliding back from the left says “back”. Alto’s settings pages use this, and so should anything new.
- Continuity. Moving the object from where it was to where it is, instead of cutting, preserves the user’s sense of what it is.
- Follow-through and easing. Real objects do not stop dead. Easing out gives a soft landing.
- Respect the user’s settings. Many people turn on a “reduce motion” option in their operating system. Alto does not read it yet, which is a good first improvement: if it is set, use durations of 0.
- Stay consistent. Same durations and curves for the same kinds of motion, so the program feels like one thing.
The 12 principles of animation from the Disney studios (squash and stretch, anticipation, staging, slow in and slow out, and so on) were written for cartoon characters, and the subset that applies to interfaces is the last three paragraphs above.
Words to search for
Tweening (calculating the frames between two states). Easing, ease-in, ease-out, Bézier easing, cubic-bezier. Spring animation (physically based, overshoots; not in Qt’s standard set). Frame rate, vsync, jank. Dirty rectangle (repaint only what changed). Compositing. Reduced motion (an accessibility setting). Skeleton screens and loading states.
Further reading
- The Qt documentation: “The Animation Framework”, and the class pages for
QVariantAnimation,QPropertyAnimation,QAbstractAnimation,QParallelAnimationGroupandQEasingCurve(which has a picture of every curve), at doc.qt.io. - Robert Penner, Programming Macromedia Flash MX (McGraw-Hill/Osborne, 2002), chapter 7: the easing equations that nearly every animation library, Qt included, implements.
- Val Head, Designing Interface Animation: Improving the User Experience Through Animation (Rosenfeld Media, 2016): the book on motion in interfaces, with guidance on duration, easing and purpose.
- Frank Thomas and Ollie Johnston, The Illusion of Life: Disney Animation (Abbeville Press, 1981): the twelve principles.
- Richard Williams, The Animator’s Survival Kit (Faber and Faber, 2001): timing and spacing in depth.
- Page Laubheimer, “Executing UX Animations: Duration and Motion Characteristics”, Nielsen Norman Group, nngroup.com (2014): research-backed guidance on how long interface animations should last.
- World Wide Web Consortium, Web Content Accessibility Guidelines 2.1, success criterion 2.3.3 “Animation from Interactions”, w3.org/TR/WCAG21: on motion and people who are sensitive to it.