window

tween

scene/tween.h, moves a float over a duration through a curve

moves a float from where it is to where you want it, over a duration, through a curve, and fires once when it lands. every slide and fade and smooth value is made of this

why it is shaped this way lives in the scene system, under tween, P1.22. this page is the contract only

#include "scene/tween.h"

the shape of it

one tweens_t holds every live tween and one tick steps the lot, so there is no timer per tween and no timer in here at all. whoever drives frames owns a manager, ticks it with its own clock, and every tween in that window shares it

gui::tweens_t tweens;

// a real host hangs SetTimer and KillTimer off the pair, a check installs nothing
tweens.set_ticker([&] { start_timer(); }, [&] { stop_timer(); });

// somewhere in a frame
tweens.tick(now_ms);

types

typewhat it is
tween_id_tuint64_t, what start hands back, 0 means nothing was started
ease_tlinear, in, out, in_out, all four monotonic so nothing overshoots
ease_fn_tfloat(float), a curve of your own, a spring or a bounce goes here
done_fn_tvoid(), fired once when a tween lands
ticker_fn_tvoid(), the arm and park pair, see set_ticker

an id and never a pointer. a tween frees itself the instant it lands, so a pointer to one is a dangling read waiting to happen. a stale id is simply not found, and every call taking one is a no-op on it, so holding an id past the end of its animation is safe rather than fatal

tween_spec_t

what one tween is made of. a new field here never moves an existing call site, which is the same bargain paint_ctx_t makes

fielddefaultmeans
float* targetnullptrthe value we move, BORROWED, see ownership below
float to0.0fwhere it ends up, it starts wherever it already is
int32_t dur150how long in ms, clamped to 1 or more so t cannot divide by zero
ease_t curveoutwhich named curve, ignored when custom is set
ease_fn_t customemptya curve of your own, wins over curve
done_fn_t on_doneemptyfired once when it lands, never fired when it is cancelled
control_t* repaintnullptrwho to ask for a repaint after each write, BORROWED, optional

starting one

tween_id_t start(tween_spec_t _spec);
tween_id_t to(float* _target, float _to, int32_t _dur, ease_t _curve = ease_t::out);
tween_id_t drive(control_t& _ctrl, float* _target, float _to, int32_t _dur, ease_t _curve = ease_t::out, done_fn_t _on_done = {});
  • start is the full one. a null target returns 0 and does nothing
  • to is the common case, a value and a target and a duration, no repaint and no callback
  • drive is the control facing one, it repaints the control after each write

retargeting the same value CANCELS the old tween, and it is cancel and not finish, so the old on_done never fires. two tweens writing one float would fight over it every tick and the value would visibly jitter

drive SNAPS instead of animating when the control has no route to a host. a control built and set up before its tree ever reached a window should just BE in its resting state, not animate itself in. it still fires on_done and still invalidates, it just does it now

a return of 0 means nothing is running, either the target was null or it snapped. that is not an error

stepping it

void tick(int64_t _now_ms);

the clock arrives as a PARAMETER and is never read in here. you hand it the clock you already have, and every tween advances off the DELTA between two ticks, which is what makes a check deterministic instead of a sleep with a tolerance on it

  • the first tick is a zero. without that, a manager built at 0 and first ticked with a real clock hands every tween the whole uptime of the machine and lands the lot on frame one
  • the delta is clamped at 250ms. a stall, a breakpoint or a big load stretches the animation rather than teleporting every tween to its end
  • on_done callbacks fire AFTER the list is settled, so a handler is free to start the next leg, cancel its siblings, or ask the manager anything

stopping things

calllands the value ?fires on_done ?
cancel(id)no, leaves it where it sitsno
finish(id)yes, jumps to the endyes
kill(const float*)nono
cancel_for(const control_t*)nono
cancel_all()nono
finish_all()yesyes
  • kill cancels whatever is moving a value, so a caller can write it by hand without a fight
  • cancel_for cancels every tween repainting a control, what a control calls on its way out
  • a stale id is a no-op and never an error

asking it things

std::size_t live() const;                       // how many are running
int64_t     now() const;                        // the last clock we were ticked with
bool        running() const;                    // is the ticker armed
bool        enabled() const;
bool        idle() const;                       // nothing running
bool        has(tween_id_t) const;
bool        has_target(const float*) const;

running() is the parking criterion in one call. the ticker arms on the empty to non-empty edge and parks itself when the last tween lands, so an idle widget never sits on a live timer. every path that empties the list parks for free and none of them can forget

wiring

void set_ticker(ticker_fn_t _arm, ticker_fn_t _park);
void set_enabled(bool _on);

set the ticker BEFORE the first tween or the arm for one already running is missed

set_enabled(false) FINISHES every live tween rather than cancelling it, so nothing is left stuck half faded, and it parks on the way through. turning it back on needs no work. that is the reduced motion switch, and landing values instantly is a product decision as much as a code one

reaching a manager from the tree

control_t carries two slots for this, both ROOT ONLY and both walked up to, the same way invalidate finds its own

void set_tweens(tweens_t* _mgr);        // on the root, BORROWED
tweens_t* tweens() const;               // walks to the root, null when nobody wired one
bool has_tweens() const;

void set_leaving(leaving_fn_t _fn);     // on the root, fired from EVERY controls dtor
bool has_leaving() const;
root.set_tweens(&tweens);
root.set_leaving([&](const gui::control_t* _c) { tweens.cancel_for(_c); });

a manager set on a CHILD is never read, and that fails quiet, same as every other slot in control_t

ownership, and what this does NOT do

a tween does not keep anything alive. it holds a raw float* and a borrowed control_t*, so whatever owns those has to outlive the tween or kill it on the way out. same bargain as the borrowed theme pointer and the overlay slot

with set_leaving wired, a control dying takes its own tweens with it and you do not have to remember. one gap, a control that is REMOVED from its tree and then dropped reports nothing, bc remove_child detaches it first and it has no root left to reach. that one is still your cancel_for, and the reason it is a trade rather than a miss is in the folder README

out of scope and deliberately absent, keyframes and sequencing. one tween has one from, one to and one curve, and anything richer is built by chaining on_done

free functions

float eased(ease_t _curve, float _t);

runs a t through one of the named curves, both ends clamped. free rather than a method so a paint easing something by hand does not have to find a manager first

On this page