guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::components::Animation Class Reference

A timer that runs from 0 to a duration and reports its eased progress, from 0 to 1, to a callback on every frame. More...

#include <headers/guillaume/components/animation.hpp>

Inheritance diagram for guillaume::components::Animation:
Collaboration diagram for guillaume::components::Animation:

Public Types

using SampleHandler
 Receives the eased progress.
using CompleteHandler
 Called on completion.

Public Member Functions

 Animation (void)
 Construct a stopped animation lasting the Material 3 Medium2 motion duration of the theme.
 ~Animation (void)=default
 Default destructor.
float getDuration (void) const
 Get how long one run of the animation lasts.
Animation & setDuration (float duration)
 Set how long one run of the animation lasts.
float getElapsed (void) const
 Get the time spent in the current run.
Animation & setElapsed (float elapsed)
 Move the animation to a point in time, without calling any handler.
float getProgress (void) const
 Get how far the current run is, before easing.
bool isPlaying (void) const
 Check whether the animation is running.
Animation & play (void)
 Start the animation from the beginning, even when it is already running.
Animation & stop (void)
 Stop the animation and bring the elapsed time back to 0.
bool isLooping (void) const
 Check whether the animation starts again when it completes.
Animation & setLooping (bool looping)
 Set whether the animation starts again when it completes.
motion::Easing getEasing (void) const
 Get the curve that turns the linear progress into the value passed to the sample handler.
Animation & setEasing (motion::Easing easing)
 Set the curve that turns the linear progress into the value passed to the sample handler.
Animation & setOnSampleHandler (const SampleHandler &handler)
 Store the callback that applies the animation.
SampleHandler getOnSampleHandler (void) const
 Get the callback that applies the animation.
Animation & setOnCompleteHandler (const CompleteHandler &handler)
 Store the callback run when the animation reaches its duration.
CompleteHandler getOnCompleteHandler (void) const
 Get the callback run when the animation reaches its duration.
void advance (float deltaTime)
 Move the animation forward in time and call the handlers.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Detailed Description

A timer that runs from 0 to a duration and reports its eased progress, from 0 to 1, to a callback on every frame.

The component does not know what it animates: the sample handler receives the progress and interpolates whatever it wants (a width, a color, a pose). systems::Animation calls advance() on every Animation in the Event phase with the time of the frame, capped at theme::MotionScale::MaxFrameStep.

registry.addComponent<components::Animation>(identifier)
.setDuration(0.2f)
.setEasing(motion::Easing::Standard)
.setOnSampleHandler([&registry, identifier](float progress) {
registry.getComponent<components::Bound>(identifier)
.setWidth(40.0f + 60.0f * progress);
})
.play();
A timer that runs from 0 to a duration and reports its eased progress, from 0 to 1,...
Definition animation.hpp:61
Animation & setEasing(motion::Easing easing)
Set the curve that turns the linear progress into the value passed to the sample handler.
Animation & setDuration(float duration)
Set how long one run of the animation lasts.
Definition animation.cpp:41
Animation & setOnSampleHandler(const SampleHandler &handler)
Store the callback that applies the animation.
Animation & play(void)
Start the animation from the beginning, even when it is already running.
Definition animation.cpp:79
Size of an entity: the width and height, in dp, of the rectangle that starts at the position of its c...
Definition bound.hpp:62

Nothing runs until play() is called. A playing animation marks the component changed on every frame, so a looping one never lets the frame settle. The handlers run inside the Event phase of the frame.

See also
systems::Animation, motion::Easing

Definition at line 60 of file animation.hpp.

Member Typedef Documentation

◆ CompleteHandler

Initial value:
std::function<void(void)>

Called on completion.

Definition at line 65 of file animation.hpp.

◆ SampleHandler

Initial value:
std::function<void(float)>

Receives the eased progress.

Definition at line 63 of file animation.hpp.

Constructor & Destructor Documentation

◆ Animation()

guillaume::components::Animation::Animation ( void )

Construct a stopped animation lasting the Material 3 Medium2 motion duration of the theme.

Definition at line 31 of file animation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ advance()

void guillaume::components::Animation::advance ( float deltaTime)

Move the animation forward in time and call the handlers.

Called once per frame by systems::Animation. Does nothing when the animation is not playing. Otherwise it adds the delta to the elapsed time, marks the component changed and calls the sample handler with the eased progress. When the duration is reached, the sample handler receives 1, the completion handler runs, then the animation stops, or restarts from 0 when looping.

Parameters
deltaTimeThe time since the previous frame, in seconds. A negative value counts as 0.

Definition at line 147 of file animation.cpp.

Here is the call graph for this function:

◆ getDuration()

float guillaume::components::Animation::getDuration ( void ) const

Get how long one run of the animation lasts.

Returns
The duration, in seconds.

Definition at line 36 of file animation.cpp.

◆ getEasing()

motion::Easing guillaume::components::Animation::getEasing ( void ) const

Get the curve that turns the linear progress into the value passed to the sample handler.

Returns
The easing curve; motion::Easing::Standard by default.

Definition at line 110 of file animation.cpp.

◆ getElapsed()

float guillaume::components::Animation::getElapsed ( void ) const

Get the time spent in the current run.

Returns
The elapsed time, in seconds; 0 when stopped.

Definition at line 51 of file animation.cpp.

◆ getOnCompleteHandler()

Animation::CompleteHandler guillaume::components::Animation::getOnCompleteHandler ( void ) const

Get the callback run when the animation reaches its duration.

Returns
A copy of the handler; empty when none was set.

Definition at line 142 of file animation.cpp.

◆ getOnSampleHandler()

Animation::SampleHandler guillaume::components::Animation::getOnSampleHandler ( void ) const

Get the callback that applies the animation.

Returns
A copy of the handler; empty when none was set.

Definition at line 131 of file animation.cpp.

◆ getProgress()

float guillaume::components::Animation::getProgress ( void ) const

Get how far the current run is, before easing.

Returns
The elapsed time divided by the duration, clamped to 0 to
  1. With a duration of 0 or less: 0 while playing, 1 otherwise.

Definition at line 66 of file animation.cpp.

Here is the caller graph for this function:

◆ isLooping()

bool guillaume::components::Animation::isLooping ( void ) const

Check whether the animation starts again when it completes.

Returns
True when looping.

Definition at line 95 of file animation.cpp.

◆ isPlaying()

bool guillaume::components::Animation::isPlaying ( void ) const

Check whether the animation is running.

Returns
True between play() and the end of the run or stop().

Definition at line 74 of file animation.cpp.

Here is the caller graph for this function:

◆ play()

Animation & guillaume::components::Animation::play ( void )

Start the animation from the beginning, even when it is already running.

Always marks the component changed. The first sample is delivered by the next advance().

Returns
This component, to chain calls.

Definition at line 79 of file animation.cpp.

Here is the call graph for this function:

◆ setDuration()

Animation & guillaume::components::Animation::setDuration ( float duration)

Set how long one run of the animation lasts.

Marks the component changed only when the duration differs.

Parameters
durationThe duration, in seconds. With 0 or less the animation completes on its first advance().
Returns
This component, to chain calls.

Definition at line 41 of file animation.cpp.

Here is the call graph for this function:

◆ setEasing()

Animation & guillaume::components::Animation::setEasing ( motion::Easing easing)

Set the curve that turns the linear progress into the value passed to the sample handler.

Marks the component changed only when the curve differs.

Parameters
easingThe easing curve.
Returns
This component, to chain calls.

Definition at line 115 of file animation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setElapsed()

Animation & guillaume::components::Animation::setElapsed ( float elapsed)

Move the animation to a point in time, without calling any handler.

Marks the component changed only when the time differs.

Parameters
elapsedThe time spent in the current run, in seconds.
Returns
This component, to chain calls.

Definition at line 56 of file animation.cpp.

Here is the call graph for this function:

◆ setLooping()

Animation & guillaume::components::Animation::setLooping ( bool looping)

Set whether the animation starts again when it completes.

Marks the component changed only when the flag differs.

Parameters
loopingTrue to restart from 0 after each completion; the completion handler still runs at the end of every run.
Returns
This component, to chain calls.

Definition at line 100 of file animation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setOnCompleteHandler()

Animation & guillaume::components::Animation::setOnCompleteHandler ( const CompleteHandler & handler)

Store the callback run when the animation reaches its duration.

It runs after the last sample, at the end of every run of a looping animation. Does not mark the component changed.

Parameters
handlerThe callback, or nullptr to remove the current one.
Returns
This component, to chain calls.

Definition at line 136 of file animation.cpp.

Here is the call graph for this function:

◆ setOnSampleHandler()

Animation & guillaume::components::Animation::setOnSampleHandler ( const SampleHandler & handler)

Store the callback that applies the animation.

advance() calls it with the eased progress, 0 to 1, while the animation plays, and with exactly 1 on completion. Does not mark the component changed.

Parameters
handlerThe callback, or nullptr to remove the current one.
Returns
This component, to chain calls.

Definition at line 125 of file animation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stop()

Animation & guillaume::components::Animation::stop ( void )

Stop the animation and bring the elapsed time back to 0.

Calls neither the sample handler nor the completion handler. Always marks the component changed.

Returns
This component, to chain calls.

Definition at line 87 of file animation.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: