Drop-In Easing Module for U++ Animate() (Edit-file path)

[Trilec]

Below is the same proposal with the correct file paths and a couple of wording tweaks so nobody has to hunt for headers again.

---

Industrial Bézier Curve Engine for U++ Animation

U++ 2025.1 shipped the first Animate() helper, but it only slides a widget’s rectangle with a fixed linear timer.
This patch adds a tiny cubic-Bézier API plus a generic AnimateProperty() template so any property—position, size, colour, opacity, angle—can move with ease-in, ease-out, or a designer-supplied curve. Four doubles describe the spline; classic helpers like EaseInQuad are just wrappers. Everything is header-only, constexpr, and costs four multiplies per frame.
Cubic-Bézier timing is standard in CSS, Qt, WPF, and Flutter, evaluated with the de Casteljau algorithm.

---

1 · Minimal source changes

File	Change
Core/Util.h	Add overload: template<class T> constexpr T Lerp(const T&, const T&, double, Upp::Easing::Fn) noexcept → returns Lerp(a,b,fn(t)).
CtrlLib/CtrlUtil.h	• Extend existing builder with .Easing(Fn). • Add template <class T> void AnimateProperty(...) (timer loop + new Lerp).
CtrlLib/Easing.h (new)	Header below — Bézier factory, presets, de Casteljau, using Fn.

No .cpp files are needed; everything is inline.

---

2 · Easing.h (drop-in)

// CtrlLib/Easing.h — single-header Bézier helper (≈50 LOC)
#pragma once
#include <Core/Core.h>

namespace Upp::Easing {

using Fn = double(*)(double) noexcept;   // maps 0-1 → 0-1, must be monotone

// de Casteljau for cubic Bézier (P0=(0,0), P3=(1,1))
constexpr double DeCasteljau(double x1,double y1,double x2,double y2,double t) noexcept
{
    double u = 1.0 - t;
    double a = 3.0 * u * u * t;
    double b = 3.0 * u * t * t;
    return (a * y1) + (b * y2) + (t * t * t);   // x term cancels (P0.x=0, P3.x=1)
}

// Factory
constexpr Fn Bezier(double x1,double y1,double x2,double y2) noexcept
{
    return [=](double t) noexcept -> double { return DeCasteljau(x1,y1,x2,y2,t); };
}

// Presets (CSS / easings.net)
constexpr Fn EaseLinear     = Bezier(0.0  ,0.0  ,1.0 ,1.0 );
constexpr Fn EaseInQuad     = Bezier(0.55 ,0.085,0.68,0.53);
constexpr Fn EaseOutQuad    = Bezier(0.25 ,0.46 ,0.45,0.94);
constexpr Fn EaseInOutQuad  = Bezier(0.455,0.03 ,0.515,0.955);
constexpr Fn EaseOutBounce  = Bezier(0.68 ,-0.55,0.265,1.55); // single-segment bounce
} // namespace Upp::Easing

The curve must start (0,0) and end (1,1)—same rule as Qt QEasingCurve::BezierSpline and WPF KeySpline.

---

3 · Usage examples

using namespace Upp;
using namespace Easing;

// 1. Slide a panel with ease-in-out
Animate(panel)
    .Time(400)
    .Easing(EaseInOutQuad)
    .Pos(Rect(40,40,200,100))
    .Run();

// 2. Fade dialog opacity
AnimateProperty<double>(1.0, 0.0,
    [&](double a){ dlg.SetOpacity(a); }, 250, EaseLinear);

// 3. Pulse button colour with custom curve (CSS “ease-out-expo”)
auto expo = Bezier(0.19,1.0,0.22,1.0);
AnimateProperty<Color>(Red(), Blue(),
    [&](Color c){ btn.SetInk(c); }, 500, expo);

// 4. Rotate a knob 0°→360° with ease-out
AnimateProperty<double>(0.0, 360.0,
    [&](double d){ knob.SetAngle(d); }, 600, EaseOutQuad);

// 5. Hover bounce pop
b.WhenMouseEnter = [=]{
    Animate(b).Time(350).Easing(EaseOutBounce)
              .Pos(Rect(b.Left()-4, b.Top()-4,
                        b.GetWidth()+8, b.GetHeight()+8))
              .Run();
};
b.WhenMouseLeave = [=]{
    Animate(b).Time(200).Easing(EaseInQuad)
              .Pos(b.GetRect()).Run();
};

Everything compiles after the three tiny edits above.

---

4 · Why this matters

• Industry-standard cubic-Bézier (CSS, Qt, WPF, Flutter).
• Tiny & fast — 4 multiplies + 3 adds per frame.
• Header-only — no ABI churn, minimal footprint.
• Drop-in compatible — linear timing remains default (0,0,1,1).
• Scalable — future spring or LUT curves can reuse the same Fn typedef.

Copy Easing.h, add the two small patches, rebuild TheIDE, and your widgets will glide like any modern toolkit.

[mirek-fidler]

Related?

#267

[Trilec]

Absolutely—same foundation, but the concept is broader:

Existing PR: adds Lerp(a,b,t, Fn)—you hand-write a lambda for each easing (e.g. a piece-wise “BounceOut”).

My patch: offers a parametric easing engine—four control-points in Easing::Bezier(x1,y1,x2,y2) generate an infinite family of curves; presets like EaseInQuad are just wrappers. No duplicate math, one constexpr helper.

Then .Easing(fn) + AnimateProperty() wire those Bézier lambdas into Animate().
So it extends, not overlaps, and gives designers more flexibility with less code.

[ismail-yilmaz]

Yes, Lerp is essentially the same in concept, but in my proposal, the easing function is left to the client code. This arguably (though not necessarily) has the advantage of reducing maintenance overhead for U++.

I also prefer the use of static assertions for invalid function signatures, as it definitely helps make template errors more readable/bearable.

That said, this implementation is more comprehensive and robust, and would be a great addition. I'm just not entirely sure the namespace is necessary. Does it really add any value in this context?

[Trilec]

I'm not usually a fan of name spaces but in this circumstance .
*Enhances clarity and supports future extensibility for the easing module,
*The usual prevention of conflicts,
*Minimal overhead.

Otherwise we could use prefixed names. ie EasingBezier, but still feels like a small namespace is just that much cleaner.

[Trilec]

Quick check-in on the Bézier easing patch:

I’m ready to finish my new upp_stateMachine demo and some nice upp_animationManager concepts, but it depends on the Bézier-based AnimateProperty helper.

If core devs are happy with the idea, let me know what’s still needed (tests? doc stubs?) and I’ll prep the PR against 2025.1 right away.

Thanks!

[klugier]

I think, we should move forward with this. However, we need to do it very careful, it is a big change. So, I have a questions:

• Right now Animate is a set of overloaded functions, but in your proposition, it is a class. How do you plan to solve it? Please, keep in mind backwards compatibility. Probably in this case, we will need to add Easing as a function parameter rather than introducing Builder. Also, Builder is not popular design pattern in U++.
• AnimateProperty, shouldn't we have more specialized functions like Animate::Fade, Animate::Rotate and Animate::Pulse? The main reason for that is avoid using template specailization in client code and make it as simple as possible. Of course, you can have something similar to AnimateProperty, but it should be used in the end

We can think about new animation API, but we will need to depricate the old one and then remove it after several releases. Since c++14 there is this excellent [[deprecated]] attribute.

In context of approving the patch for changes like this, you will need to prepare:

• T++ docs, please do not use Doxygen comments, we are in U++ :)
• reference/example - put example or reference for your changes, so other users can learn about it
• auotests - testing code - optional, but recommended
• Adding new chapter to GUI tutorial about animations - optional, but recommended, can be deliver in separate PR

[Trilec]

Great, thanks for the feedback. I'm certainly open to changes and being careful about how we approach things.

Here is my revised implementation (incorporating the feedback, thanks for that).

---

Proposed Implementation

This plan is designed to be minimally invasive.

A. New File: CtrlLib/Easing.h

This is a new file. The code below represents its entire content.

// CtrlLib/Easing.h — single-header Bézier helper
#pragma once

#include <Core/Core.h>
#include <functional>
#include <cmath>

NAMESPACE_UPP

namespace Easing {

// The core contract: a callable object mapping time progress (0-1) to eased progress (0-1).
using Fn = std::function<double(double)>;

namespace Detail {
    // Helper to get the X-coordinate for a given curve parameter 't'
    constexpr double BezierX(double x1, double x2, double t) noexcept {
        double u = 1.0 - t;
        return (3.0 * u * u * t * x1) + (3.0 * u * t * t * x2) + (t * t * t);
    }
}

// Correct de Casteljau implementation that solves for the curve parameter 't'
// that corresponds to a given time 'x' using binary search.
inline double DeCasteljau(double x1, double y1, double x2, double y2, double x) noexcept
{
    if (x <= 0.0) return 0.0;
    if (x >= 1.0) return 1.0;

    double t_min = 0.0, t_max = 1.0;
    double t = x; // Start with a good guess

    // Iteratively find the 't' that produces the desired 'x'
    for (int i = 0; i < 8; ++i) {
        double current_x = Detail::BezierX(x1, x2, t);
        if (std::abs(x - current_x) < 1e-6) break;
        if (current_x < x) t_min = t;
        else t_max = t;
        t = (t_max + t_min) / 2.0;
    }

    // Now use the correct 't' to find the Y value (the eased progress)
    double u = 1.0 - t;
    return (3.0 * u * u * t * y1) + (3.0 * u * t * t * y2) + (t * t * t);
}

// Factory to create a custom Bézier easing function.
inline Fn Bezier(double x1, double y1, double x2, double y2) noexcept
{
    return [=](double t) noexcept -> double { return DeCasteljau(x1, y1, x2, y2, t); };
}

// Common presets, matching CSS standards for ease of use.
static Fn EaseLinear     = Bezier(0.0,   0.0,   1.0,   1.0);
static Fn EaseInQuad     = Bezier(0.55,  0.085, 0.68,  0.53);
static Fn EaseOutQuad    = Bezier(0.25,  0.46,  0.45,  0.94);
static Fn EaseInOutQuad  = Bezier(0.455, 0.03,  0.515, 0.955);
static Fn EaseOutBounce  = Bezier(0.68, -0.55,  0.265, 1.55);

} // namespace Easing

END_UPP_NAMESPACE

B. Additions to CtrlLib/CtrlUtil.h

The following declarations should be added to the existing CtrlLib/CtrlUtil.h file.

#include "Easing.h"

// The new Animate overload for Rects
void Animate(Ctrl& q, Rect target, int ms, const Easing::Fn& easing);

// The existing Animate remains for perfect backwards compatibility
inline void Animate(Ctrl& q, Rect target, int ms) { Animate(q, target, ms, Easing::EaseLinear); }

// New specialized, simple property animators
void AnimateFade(Ctrl& q, double target_opacity, int ms, const Easing::Fn& easing = Easing::EaseLinear);
void AnimateColor(Gate<void(Color)> setter, Color from, Color to, int ms, const Easing::Fn& easing = Easing::EaseLinear);

C. Additions to CtrlLib/CtrlUtil.cpp

The following implementations should be added to the existing CtrlLib/CtrlUtil.cpp file.

#include "CtrlLib.h"
#include <algorithm>

NAMESPACE_UPP

namespace Detail {
    // The robust, recursive-safe, correctly-timed animation engine
    template <typename T>
    void AnimateProperty(Gate<void(T)> setter, T from, T to, int ms, const Easing::Fn& easing)
    {
        int start_time = msecs();
        
        std::function<void()> update;
        update = [=, &update]() mutable {
            int elapsed = msecs() - start_time;
            double t = std::min(1.0, ms > 0 ? (double)elapsed / ms : 1.0);
            
            // Apply easing to time 't' before passing to Lerp
            setter(Lerp(from, to, easing(t)));
            
            if (t < 1.0) {
                SetTimeCallback(0, update);
            }
        };
        update();
    }
}

void Animate(Ctrl& q, Rect target, int ms, const Easing::Fn& easing) {
    Detail::AnimateProperty<Rect>([&](Rect r) { q.SetRect(r); }, q.GetRect(), target, ms, easing);
}

void AnimateFade(Ctrl& q, double target_opacity, int ms, const Easing::Fn& easing) {
    Detail::AnimateProperty<double>([&](double o) { q.SetOpacity(o); }, q.GetOpacity(), target_opacity, ms, easing);
}

void AnimateColor(Gate<void(Color)> setter, Color from, Color to, int ms, const Easing::Fn& easing) {
    Detail::AnimateProperty<Color>(setter, from, to, ms, easing);
}

END_UPP_NAMESPACE

[Trilec]

Just checking in — since the full code is already in the discussion above and incorporates the feedback, do you want me to submit a formal PR as well, or are we happy to proceed from here?

Happy to create the PR if that’s the preferred next step.

Cheers,
Trilec

[Trilec]

Animation lib update

(https://github.com/Trilec/upp_AnimationEasing)

Hey all — just a quick update after a few weeks on this. The little easing header I dropped earlier has grown into a proper animation lib.

What’s working now
• Core ops: play, cancel, stop, delay, looping/yoyo, pause/resume.
• Easing: both presets and custom Beziers.
• Safe: reentrancy is handled, memory cleans up properly (no leaks or dangling refs).
• Stress tests: concurrent bursts, pause/resume loops, cancel/restart abuse… holding up well so far.
• API surface is still U++-native and clean (AnimateProperty, AnimateFade, AnimateColor, Easing::Bezier, etc.).

What’s different from the old helpers
• Old Animate() was narrow and ad-hoc; this lib has one consistent core + thin wrappers.
• Wrappers (Fade, Rotate, Pulse, etc.) are now just sugar over the same engine.
• Animations finish/cancel deterministically — no dangling timers.
• Designed with UI integration in mind rather than bolted on.

Next steps
I’ll keep polishing stress tests + examples, but we’re close to PR-ready.

Integration idea (small + safe):

• Keep runtime self-contained (Animation.h/.cpp).
• Add one light layer in Chameleon: an animated look wrapper that interpolates between normal/hot/pushed/disabled. Themes can opt-in by swapping style.look[] to this animated one.
• Same helper can animate draw-time values (colors, fonts, underlines, sliding panels).
• Global switch ChAnim::SetEnabled(bool) for users who want to disable animations.

This keeps it host-look-first, opt-in, and widget code stays untouched. A couple of tasteful demos (button hover fade, focus ring pulse, tab highlight slide) would prove the path.

Would love feedback on whether this direction feels right before I wire it into CtrlLib.

UI TEST Demo :

—Cheers

[klugier]

This is nice! Thank you for your contribution. However, the repository layout is not compatible with UppHub, so it can not be easily consumed by our users. You need to adapt your repository to our format. Otherwise, I don't foresee much success for this package. For reference you can look at https://github.com/ismail-yilmaz/Terminal package. The main difference to your approch is that you are treating main repo dir as assembbly. In this repository you should have two directories AnimationEasing and examples/AnimationEasing.

Also, what is the point of having src and include directories. This is not standard practice in U++ world. You should have everything in single AnimationEasing package and the new package should be included by <AnimationEasing/AnimationEasing.h>.

[Trilec]

lol, I like to think im one of those users...

I’ve split things per UppHub conventions:
Library package Animation/ with Animation.upp + Animation.h/.cpp (flat, no src/include).
Two examples: examples/ConsoleAnim and examples/GUIAnim, each with its own .upp.

Public include is #include <Animation/Animation.h>.

Structure:

LICENSE
README.md
\Animation
..Animation.cpp
..Animation.h
..Animation.upp
\examples
..\ConsoleAnim
....ConsoleAnim.cpp
....ConsoleAnim.h
....ConsoleAnim.upp
....main.cpp
..\GUIAnim
....GUIAnim.cpp
....GUIAnim.h
....GUIAnim.upp
....main.cpp

[klugier]

Thanks! Your package is now on UppHub. However, it doesn't compile. The main reason for that is that in Animation/Animation.cpp, instead of using
#include "Animation.h"
you use
#include <Animation.h>

In GUIAnim, there is also compilation error:
#include <Animation.h>
should be
#include <Animation/Animation.h>

Also, it looks like there are memory leaks in your package. Please debug and eliminate. Here is more info how to do that https://www.ultimatepp.org/srcdoc$Core$Leaks_en-us.html.

Besides that, there is some comsetic things that can be improve:

• #pragma once is not standard, in U++ we always use header guard. Please use U++ notation of the guard naming convention, you can just create new file in your packages and then copy and modify the guard to fit the exact file name

Please fix. Besides that, it looks good! Thank you for this amazing contribution.

[Trilec]

thank ive change the #pragma and compilation error: the memory leaks i will check, there was an issue with running debug mode , and a memory leak was not at the coming from the application but from some "top.h" code, I assumed it was a older branch and was going to try it with the new 17810

[ismail-yilmaz]

Hi, the line below will leak.

    static Scheduler& Inst() { static Scheduler* s = new Scheduler; return *s; }

This, IMO, is very dangerous anyway. IF you really need to use heap for this type of global stuff, you can use INITBLOCK and EXITBLOCK macros, where you can allocate and deallocate it from the heap. Even in that case I would recommend using One<T> to let it track the object for you.

If it is meant to be a global singleton, let's make it a singleton in more U++ style: :):

    static Scheduler& Inst() { return Single<Scheduler>(); }

This will prevent the leak.

[ismail-yilmaz]

A quick fix for leaking easing functions:

inline const Fn& Linear()        { static auto f = Upp::MakeOne<Fn>(Bezier(0.000, 0.000, 1.000, 1.000));  return *f; }
inline const Fn& OutBounce()     { static auto f = Upp::MakeOne<Fn>(Bezier(0.680, -0.550, 0.265, 1.550)); return *f; }
inline const Fn& InQuad()        { static auto f = Upp::MakeOne<Fn>(Bezier(0.550, 0.085, 0.680, 0.530));  return *f; }
inline const Fn& OutQuad()       { static auto f = Upp::MakeOne<Fn>(Bezier(0.250, 0.460, 0.450, 0.940));  return *f; }
inline const Fn& InOutQuad()     { static auto f = Upp::MakeOne<Fn>(Bezier(0.455, 0.030, 0.515, 0.955));  return *f; }
inline const Fn& InCubic()       { static auto f = Upp::MakeOne<Fn>(Bezier(0.550, 0.055, 0.675, 0.190));  return *f; }
inline const Fn& OutCubic()      { static auto f = Upp::MakeOne<Fn>(Bezier(0.215, 0.610, 0.355, 1.000));  return *f; }
inline const Fn& InOutCubic()    { static auto f = Upp::MakeOne<Fn>(Bezier(0.645, 0.045, 0.355, 1.000));  return *f; }
inline const Fn& InQuart()       { static auto f = Upp::MakeOne<Fn>(Bezier(0.895, 0.030, 0.685, 0.220));  return *f; }
inline const Fn& OutQuart()      { static auto f = Upp::MakeOne<Fn>(Bezier(0.165, 0.840, 0.440, 1.000));  return *f; }
inline const Fn& InOutQuart()    { static auto f = Upp::MakeOne<Fn>(Bezier(0.770, 0.000, 0.175, 1.000));  return *f; }
inline const Fn& InQuint()       { static auto f = Upp::MakeOne<Fn>(Bezier(0.755, 0.050, 0.855, 0.060));  return *f; }
inline const Fn& OutQuint()      { static auto f = Upp::MakeOne<Fn>(Bezier(0.230, 1.000, 0.320, 1.000));  return *f; }
inline const Fn& InOutQuint()    { static auto f = Upp::MakeOne<Fn>(Bezier(0.860, 0.000, 0.070, 1.000));  return *f; }
inline const Fn& InSine()        { static auto f = Upp::MakeOne<Fn>(Bezier(0.470, 0.000, 0.745, 0.715));  return *f; }
inline const Fn& OutSine()       { static auto f = Upp::MakeOne<Fn>(Bezier(0.390, 0.575, 0.565, 1.000));  return *f; }
inline const Fn& InOutSine()     { static auto f = Upp::MakeOne<Fn>(Bezier(0.445, 0.050, 0.550, 0.950));  return *f; }
inline const Fn& InExpo()        { static auto f = Upp::MakeOne<Fn>(Bezier(0.950, 0.050, 0.795, 0.035));  return *f; }
inline const Fn& OutExpo()       { static auto f = Upp::MakeOne<Fn>(Bezier(0.190, 1.000, 0.220, 1.000));  return *f; }
inline const Fn& InOutExpo()     { static auto f = Upp::MakeOne<Fn>(Bezier(1.000, 0.000, 0.000, 1.000));  return *f; }
inline const Fn& InElastic()     { static auto f = Upp::MakeOne<Fn>(Bezier(0.600, -0.280, 0.735, 0.045)); return *f; }
inline const Fn& OutElastic()    { static auto f = Upp::MakeOne<Fn>(Bezier(0.175, 0.885, 0.320, 1.275));  return *f; }
inline const Fn& InOutElastic()  { static auto f = Upp::MakeOne<Fn>(Bezier(0.680, -0.550, 0.265, 1.550)); return *f; }

This will hopefully solve the leak. However, this doesn't solve the potential dangling pointer issue if it is called later. So instead of returning a reference, you can return a pointer.

ps: Note that this can be implemented more elegantly using a Vector or Array.

[Trilec]

yep, still trying to get my head around all of the U++ idiosyncrasies, it took quite a while to wire up everything for good memory management. Thanks for the info I can try and do another version with Makeone

[ismail-yilmaz]

@Trilec

yep, still trying to get my head around all of the U++ idiosyncrasies, it took quite a while to wire up everything for good memory management. Thanks for the info I can try and do another version with Makeone

Also please check my proposal here with constexpr functions. They are more effective and would be less painful to refactor + develop your code later. I am interested in using this package when it matures.

[Trilec]

Thanks —I've made the changes (Updated GitHub).
I’d like to keep the call-site API callable (not a pointer) to keep usage simple, e.g. Animate(..., Easing::OutQuad());.
Thanks for the constexpr idea — I like it. For this package though I was prioritizing the designer workflow. Cubic-Bézier control points are easy to reason about, and work great with the curve editor in the demo so people can see and tweak the feel. The runtime Bézier eval is tiny and fast enough for UI (paint is the bottleneck, not the easing). -- but ill investigate further.

The next step (which I'm hoping I get some traction on) is how we start putting this in chameleon.
I'm starting to look at this next because I'm also designing a gallery control, and would like to have this driven by styles

[ismail-yilmaz]

Fair enough.

But this:

inline const Fn& Linear()       { static Upp::One<Fn> f; ONCELOCK { f.Create() = Bezier(0.000, 0.000, 1.000, 1.000); } return *f; }

Why do you use ONCELOCK here? All modern cpp compilers initialize static local variables once and take care of the concurrency issue automatically.

This should work exactly the same

inline const Fn& Linear()       { static auto f = MakeOne<Fn>(Bezier(0.000, 0.000, 1.000, 1.000));  return *f; }

You don't need to change it of course, I'm just curious.

[Trilec]

Originally tried ONCELOCK to mirror U++’s historical lazy-init pattern (avoid static-init order pitfalls) the new code uses constexpr, return-by-value lambdas, so there’s no runtime init or locking anymore coolo, thanks for that.

[didierq]

Hi, I just did some quick testing and seems quite interesting and easy to use.
My two remarks:

• Maybe add a Reset() method to class Animation
• Replace callbacks with Function<> : can't use lambda with callbacks (or I didn't try hard enough :) )

Question : What does Animation::Progress() return ? : it seems to be the time progress and not the progress of the animation status.

For my testing I wanted to try to apply it to some usual Ctrl => so I did this small template class and applied it to buttons.
Animation simply draws a green ellipse in the button, but I can imagine flashing button to catch user eye or Button that sparkles when cursor passes over it :)

template <class BUTT>
class ShineAnimate : public BUTT {
	private:
		One<Animation> anim;
		double easeP;
	
		void PlayAnim() {
			if ( !anim.IsEmpty() ) {
				anim->Cancel(false);
			}
			anim.Create(*this);
			anim->Duration(500);
			anim->Ease(Easing::OutQuart());
            (*anim)([&](double e) {
                easeP = e;
                this->Refresh();
                return true;
            });
            
            anim->OnFinish( callback(this, &ShineAnimate<BUTT>::AnimEnd));
			anim->Play();
		}

	public:
		ShineAnimate() {}
		
		void AnimEnd() {
			PostCallback( [&] { anim.Clear(); BUTT::Refresh(); } );
		}

		virtual void LeftDown(Point pt, dword k) {
			BUTT::LeftDown( pt, k );
			PlayAnim();
		}

		virtual void Paint(Draw& w) {
			BUTT::Paint(w);
			if ( !anim.IsEmpty() ) {
				double pr = easeP;
				Rect r = BUTT::GetSize();
				r.Deflate((1.0-pr)*r.Width()/2.0, (1.0-pr)*r.Height()/2.0);
	            w.DrawEllipse(r, LtGreen());
			}
	}
};

I could imagine a more complex class that furnishes several standard button animations

[Trilec]

Thanks for giving the library a spin.

Note: I'm still waiting for some feedback from the developers ( taking a while) on how they would like to approach the integration into the main controls. I have some ideas which I will spin up in the next few weeks

On your notes:

Reset → this is called Cancel(). That’s what the demo’s Reset button is doing under the hood: cancel the animation, zero out the visual, move on. Clean, simple.

Progress() → That’s not raw wall-clock time. It’s a normalized 0→1 of how far through the animation you are (after any Delay()). The per-frame lambda you pass in gets the eased curve value, while Progress() is always the raw timeline. If you Stop(), it freezes at 1.0; if you Cancel(), it stays at whatever forward progress you’d reached. Think of it as the “honest report card” of time.

Callbacks and lambdas → The per-frame function is Function<bool(double)>, so lambdas are exactly what it was built for. Demo code with [&](double e) { … } is the poster child. Lifecycle hooks (OnFinish, OnCancel, etc.) are U++ Callbacks, so you wire them with callback(this, &MyType::Method). If you want capture-heavy work on finish, just trigger it inside your per-frame lambda or throw a PostCallback there.

Hope that helps :

Example of a button:

On click →
First thing you do is call Cancel() on any running animation for that button (that’s the “reset”).
Then you create a fresh animation instance tied to the button.

Setup →
Give it a Duration(500) so it runs for half a second.
Pick an easing curve, say Easing::OutQuart().

Frame-by-frame →
You pass in a lambda that receives a number between 0.0 and 1.0 (the eased value).
Inside that lambda, you stash the value in a member variable and call Refresh() so the button repaints.

Painting →
In the button’s paint method, you look at that eased value.
For example: shrink or grow an ellipse depending on whether it’s closer to 0 or 1.

Finishing →
You hook OnFinish() with a method pointer, so once the animation completes you can clear the animation object and repaint one last time.

Cheers

[didierq]

Hello Trilec,

Callback is deprecated in Upp and in new code, it's better to use Function<> or the two helpers Event<> and Gate<>.
The main advantage I see is that with Function<> user code can use lambdas and Callbacks, while with Callbacks, this is not true.

I did a test, I replaced all the Callbacks with Event<> and all works fine

As for the Reset. I was thinking about not having to create a new Animation instance.
I just tried using Cancel but if Play() is launched before the end of previous Play() it crashes although I called Cancel().
When I create a new instance of Animation, all works fine

In my case it crashes here:
Animation& Animation::Duration(int ms) { RET(spec_->duration_ms = ms); }
With : spec_=0

This package is a great add to Upp.
thank you :)

[Trilec]

Hey — thanks for stress-testing it.

Reset / reuse: awesome catch :) . After the first Play(), the internal “spec” is moved into the running state. Today that means if you Cancel() and then immediately call setters like Duration(...) on the same Animation object, you’re writing into a null spec — that’s the crash you saw.

• Now: either create a fresh Animation instance (what you did), or call Cancel() and then re-prime the spec .
• I'll try and test a possible fix making the setters lazily recreate the spec when needed, so “Cancel → set params → Play” works without ceremony. I can also add a one-liner Reset() (your suggestion) that just does Cancel(false) + “ and primes a new spec.”
I'm thinking along these lines,

-Keep Pause strictly reversible.
-Keep Cancel strictly destructive.
-Add Reset as destructive + clean slate.

On the progress note:
Progress(): returns the straight 0→1 time progress (after any Delay()); your per-frame lambda gets the eased value. Think of Progress() as the stopwatch; the lambda param is the slow-mo.

Callbacks vs Function<> / Event<>:
The per-frame path is already Function<bool(double)> (so lambdas with captures are the happy path). I agree on Event<>/Gate<> for lifecycle hooks and I'll explore if this is easy lift to get it a bit more friendly to modern usage.

Appreciate the report — this was a interesting edge case.
cheers

[Trilec]

Hi ,
I’ve added a new Reset() method, renamed the internal Spec to Staging for clarity, guarded all setters to prevent crashes, and included new tests (L27/L28); semantics for Pause and Cancel remain unchanged apart from clearer documentation.
Note:
No changes to the public API or removal of existing methods.

currently pushed to the Trilec upp_AnimationEasing
Cheers

[didierq]

Callbacks vs Function<> / Event<>:
The per-frame path is already Function<bool(double)> (so lambdas with captures are the happy path). I agree on Event<>/Gate<> for lifecycle hooks and I'll explore if this is easy lift to get it a bit more friendly to modern usage.

Go for it : just replace in Method signature and it's plug and play :) (I tryied it the other day)

currently pushed to the Trilec upp_AnimationEasing

I'll give it shot

[didierq]

Hi,
I just tried out you're modifications : no more crash now while using the same instance again and again :)
I tried both Cancel() and Reset() : no difference in behavior : both work the same

[didierq]

I modified you're code to replace Callback with Event<> only where necessary : all works fine

Animation.h

// Animation/Animation.h
//
// Animation system for U++ controls.
// Single-threaded scheduler (TimeCallback) that drives per-frame updates with
// easing, looping, yoyo, pause/resume, and simple lifecycle callbacks.
//
// Design model (two compartments):
//   • Staging  — the parameters being prepared by setters (duration, easing,
//                callbacks, tick function). Setters write here until Play().
//   • State    — a live scheduled run created by moving the Staging config
//                into the scheduler. State is immutable during a run.
//
// On Play():  Staging → State (move), staging_ becomes nullptr.
// After Cancel()/Stop(): staging_ is often null; the next setter will lazily
//                        re-prime it (EnsureStaging_()).
// Reset():    Cancel(false) + EnsureStaging_() + Progress() = 0.0
//
// Progress() always returns [0..1]. After Stop(): 1.0.
// After Cancel(): last forward progress snapshot. KillAllFor(): 0.0.

#ifndef _Animation_Animation_h_
#define _Animation_Animation_h_

#include <Core/Core.h>
#include <CtrlCore/CtrlCore.h>

/*---------------- Easing helpers (constexpr cubic-bézier) ----------------
   Factory and presets for CSS-like cubic Bézier easing. Use presets like
   Easing::OutQuart(), or build custom curves with Bezier(x1,y1,x2,y2).
-----------------------------------------------------------------------------*/
namespace Easing {

using Fn = Upp::Function<double(double)>;

namespace detail {
// Unit-time cubic Bézier with P0=(0,0), P3=(1,1).
constexpr double BX(double x1, double x2, double t) noexcept {
    double u = 1.0 - t;
    return 3.0*u*u*t*x1 + 3.0*u*t*t*x2 + t*t*t;
}
constexpr double BY(double y1, double y2, double t) noexcept {
    double u = 1.0 - t;
    return 3.0*u*u*t*y1 + 3.0*u*t*t*y2 + t*t*t;
}
constexpr double Solve(double x1, double y1, double x2, double y2, double x) noexcept {
    if (x <= 0.0) return 0.0;
    if (x >= 1.0) return 1.0;
    double lo = 0.0, hi = 1.0, t = x;
    // 8 bisection steps are enough for UI precision.
    for (int i = 0; i < 8; ++i) {
        double cx = BX(x1, x2, t);
        (cx < x ? lo : hi) = t;
        t = 0.5 * (lo + hi);
    }
    return BY(y1, y2, t);
}
} // namespace detail

// Factory: returns a tiny callable to evaluate the curve.
constexpr auto Bezier(double x1, double y1, double x2, double y2) {
    return [x1, y1, x2, y2](double t) noexcept -> double {
        return detail::Solve(x1, y1, x2, y2, t);
    };
}

// Presets (CSS-ish feel). Usage: .Ease(Easing::OutCubic())
inline constexpr auto Linear()        { return Bezier(0.000, 0.000, 1.000, 1.000); }
inline constexpr auto InQuad()        { return Bezier(0.550, 0.085, 0.680, 0.530); }
inline constexpr auto OutQuad()       { return Bezier(0.250, 0.460, 0.450, 0.940); }
inline constexpr auto InOutQuad()     { return Bezier(0.455, 0.030, 0.515, 0.955); }
inline constexpr auto InCubic()       { return Bezier(0.550, 0.055, 0.675, 0.190); }
inline constexpr auto OutCubic()      { return Bezier(0.215, 0.610, 0.355, 1.000); }
inline constexpr auto InOutCubic()    { return Bezier(0.645, 0.045, 0.355, 1.000); }
inline constexpr auto InQuart()       { return Bezier(0.895, 0.030, 0.685, 0.220); }
inline constexpr auto OutQuart()      { return Bezier(0.165, 0.840, 0.440, 1.000); }
inline constexpr auto InOutQuart()    { return Bezier(0.770, 0.000, 0.175, 1.000); }
inline constexpr auto InQuint()       { return Bezier(0.755, 0.050, 0.855, 0.060); }
inline constexpr auto OutQuint()      { return Bezier(0.230, 1.000, 0.320, 1.000); }
inline constexpr auto InOutQuint()    { return Bezier(0.860, 0.000, 0.070, 1.000); }
inline constexpr auto InSine()        { return Bezier(0.470, 0.000, 0.745, 0.715); }
inline constexpr auto OutSine()       { return Bezier(0.390, 0.575, 0.565, 1.000); }
inline constexpr auto InOutSine()     { return Bezier(0.445, 0.050, 0.550, 0.950); }
inline constexpr auto InExpo()        { return Bezier(0.950, 0.050, 0.795, 0.035); }
inline constexpr auto OutExpo()       { return Bezier(0.190, 1.000, 0.220, 1.000); }
inline constexpr auto InOutExpo()     { return Bezier(1.000, 0.000, 0.000, 1.000); }
inline constexpr auto InElastic()     { return Bezier(0.600, -0.280, 0.735, 0.045); }
inline constexpr auto OutElastic()    { return Bezier(0.175, 0.885, 0.320, 1.275); }
inline constexpr auto InOutElastic()  { return Bezier(0.680, -0.550, 0.265, 1.550); }
// “Bounce”-like single segment with overshoot.
inline constexpr auto OutBounce()     { return Bezier(0.680, -0.550, 0.265, 1.550); }

} // namespace Easing



namespace Upp {

class Animation {
public:
    /*---------------- Staging describes the next run ("the recipe") ------------
       All setters write here prior to Play(). On Play(), a copy/move of this
       configuration is embedded into a live State for deterministic execution.
    ---------------------------------------------------------------------------*/
    struct Staging {
        int  duration_ms = 400;                 // duration per leg (ms)
        int  loop_count  = 1;                   // number of legs; -1 = infinite
        int  delay_ms    = 0;                   // start delay (ms)
        bool yoyo        = false;               // forward then reverse per cycle
        Easing::Fn easing = Easing::InOutCubic();// easing function (t in 0..1)

        // Per-frame tick. Receives eased t in [0..1]. Return false to stop early.
        Function<bool(double)> tick;

        // Lifecycle hooks. on_update(e) fires every frame with the eased value.
        Event<> on_start, on_finish, on_cancel;
        Event<double> on_update;
    };

    /*---------------- State is the live scheduled run ("the execution") --------
       Owned and advanced by the scheduler. Immutable settings copied from
       Staging at Play() time; holds timing/yoyo bookkeeping for the current run.
    ---------------------------------------------------------------------------*/
    struct State : Pte<State> {
        Ptr<Ctrl> owner;         // safe watcher of owning Ctrl
        Staging   spec;          // immutable snapshot of the staging config
        int64     start_ms   = 0;// current leg start wall time
        int64     elapsed_ms = 0;// accumulated time when paused
        bool      paused     = false;
        bool      reverse    = false;
        int       cycles     = 1;// remaining cycles (if loop_count >= 0)

        Animation* anim  = nullptr; // back-pointer (non-owning)
        bool       dying = false;   // deferred removal flag during sweep

        // Step the state to 'now'. Returns true to keep scheduling; false to stop.
        bool Step(int64 now);
    };

    /*---------------- Lifecycle -------------------------------------------------
       Construct an animation bound to a control. Destructor detaches safely.
    ---------------------------------------------------------------------------*/
    explicit Animation(Ctrl& owner);
    ~Animation();

    Animation(Animation&&) = default;
    Animation& operator=(Animation&&) = default;
    Animation(const Animation&) = delete;
    Animation& operator=(const Animation&) = delete;

    /*---------------- Fluent configuration (staging) ----------------------------
       Each setter prepares the next run. If staging is null (e.g., right after
       Play()), we lazily re-prime it so callers can immediately reconfigure.
    ---------------------------------------------------------------------------*/
    Animation& Duration(int ms);                     // set duration per leg (ms)
    Animation& Ease(const Easing::Fn& fn);           // set easing by reference
    Animation& Ease(Easing::Fn&& fn);                // set easing by move
    Animation& Loop(int n = -1);                     // set loop count (-1 infinite)
    Animation& Yoyo(bool b = true);                  // enable/disable yoyo playback
    Animation& Delay(int ms);                        // set start delay (ms)
    Animation& OnStart(const Event<>& cb);          // set on_start hook
    Animation& OnStart(Event<>&& cb);               // set on_start (move)
    Animation& OnFinish(const Event<>& cb);         // set on_finish hook
    Animation& OnFinish(Event<>&& cb);              // set on_finish (move)
    Animation& OnCancel(const Event<>& cb);         // set on_cancel hook
    Animation& OnCancel(Event<>&& cb);              // set on_cancel (move)
    Animation& OnUpdate(const Event<double>& c); // set on_update(eased) hook
    Animation& OnUpdate(Event<double>&& c);      // set on_update (move)
    Animation& operator()(const Function<bool(double)>& f); // per-frame tick
    Animation& operator()(Function<bool(double)>&& f);      // per-frame tick (move)

    /*---------------- Control ---------------------------------------------------
       Play() commits the staged config and schedules a new run.
       Pause()/Resume() are reversible. Stop() completes to 1.0 and fires finish.
       Cancel() aborts and preserves forward progress. Reset() aborts and primes
       a clean slate so the same instance is immediately reusable.
    ---------------------------------------------------------------------------*/
    void   Play();                         // commit staging → schedule a run
    void   Pause();                        // reversible freeze; no time accrual
    void   Resume();                       // continue after Pause()
    void   Stop();                         // finish now (Progress=1), fire finish
    void   Cancel(bool fire_cancel = true);// abort run; preserve forward snapshot
    void   Reset(bool fire_cancel = false);// abort + re-prime staging; Progress=0

    bool   IsPlaying() const;              // true if scheduled and not paused
    bool   IsPaused()  const;              // true if scheduled and paused
    double Progress()  const;              // normalized time progress [0..1]

    /*---------------- Global helpers -------------------------------------------
       Affect the shared scheduler. FPS changes re-arm the timer if needed.
    ---------------------------------------------------------------------------*/
    static void SetFPS(int fps);           // clamp to [1..240]; set target FPS
    static int  GetFPS();                  // current target FPS
    static void KillAllFor(Ctrl& c);       // abort all animations for this Ctrl
    static void Finalize();                // stop scheduler; free all states

    // Test/diagnostic: step scheduler n frames; clamp each dt to max_ms_per_tick.
    static void Tick(int n = 1, int max_ms_per_tick = 0);
    static inline void TickOnce() { Tick(1, 0); } // convenience single step

    // Called by scheduler when a State is removed; updates our progress cache.
    void _OnStateRemovedFinish();                       // Progress ← 1.0
    void _OnStateRemovedCancel(double forward_snapshot);// Progress ← snapshot

private:
    // Owner and staging
    Ctrl*        owner_ = nullptr;     // non-owning: the target control
    One<Staging> staging_box_;         // storage for staging configuration
    Staging*     staging_ = nullptr;   // points into staging_box_ while staging
    Ptr<State>   live_;                // scheduler-owned state; Ptr guards UAF

    // Progress cache that persists after Stop()/Cancel(), used when !live_.
    double       progress_cache_ = 0.0;

    // Lazily (re)create staging if null so setters always have a target.
    void EnsureStaging_();

    // Internal helper for tests/tools.
    void _SetProgressCache(double v) { progress_cache_ = v; }
};

/*---------------- Convenience helpers for animating values --------------------
   AnimateValue<T>: builds a one-shot animation that lerps from 'from' to 'to'
   using the provided setter, refreshing the control each frame.
-----------------------------------------------------------------------------*/
template <class T>
inline Animation AnimateValue(Ctrl& ctrl, Event<const T&> set, T from, T to,
                              int ms, Easing::Fn ease = Easing::InOutCubic())
{
    Animation a(ctrl);
    a([ctrlPtr = Ptr<Ctrl>(&ctrl), set, from, to](double p) -> bool {
        if(!ctrlPtr) return false;
        if constexpr(std::is_same_v<T, Color>)
            set(Blend(from, to, int(255 * p)));
        else if constexpr(std::is_same_v<T, Point>)
            set(Point(int(from.x + (to.x - from.x) * p + .5),
                      int(from.y + (to.y - from.y) * p + .5)));
        else if constexpr(std::is_same_v<T, Size>)
            set(Size(int(from.cx + (to.cx - from.cx) * p + .5),
                     int(from.cy + (to.cy - from.cy) * p + .5)));
        else if constexpr(std::is_same_v<T, Rect>)
            set(Rect(Point(int(from.left + (to.left - from.left) * p + .5),
                           int(from.top  + (to.top  - from.top ) * p + .5)),
                     Size(int(from.Width()  + (to.Width()  - from.Width() ) * p + .5),
                          int(from.Height() + (to.Height() - from.Height()) * p + .5))));
        else
            set(from + (to - from) * p);
        ctrlPtr->Refresh();
        return true;
    })
    .Duration(ms)
    .Ease(ease)
    .Play();
    return pick(a);
}

inline Animation AnimateColor(Ctrl& c, Event<const Color&> cb, Color f, Color t,
                              int ms, Easing::Fn e = Easing::InOutCubic())
{ return AnimateValue<Color>(c, cb, f, t, ms, e); }

inline Animation AnimateRect (Ctrl& c, Event<const Rect&>  cb, Rect  f, Rect  t,
                              int ms, Easing::Fn e = Easing::InOutCubic())
{ return AnimateValue<Rect>(c, cb, f, t, ms, e); }

} // namespace Upp

#endif // _Animation_Animation_h_

Animation.cpp

// Animation/Animation.cpp
//
// U++ Animation scheduler and state machine.
// - Drives per-frame updates for UI animations (position, color, opacity, etc.)
// - Designer-friendly easing via cubic-Bézier (CSS-style control points)
// - Looping, yoyo, delays, pause/resume, and lifecycle callbacks
// - Single-threaded: runs entirely on the UI thread via TimeCallback
//
// Invariants / behavior:
// - Never deletes animation state while iterating the active list.
//   (Removals are deferred to end-of-frame; Cancel/Stop is safe inside ticks.)
// - Progress() returns [0..1]. After Stop(): 1.0. After forced KillFor(): 0.0.
// - Easing callables are tiny lambdas; no global singletons or leaks.
//
// Changelog:
// 2025-08-19 — initial test pass / cleaned comments / cache helper
// 2025-08-21 — runtime Tick(n, max_ms_per_tick) manual driver (no #define)
// 2025-08-27 — yoyo fix, naming clarity, optimized scheduler
// 2025-08-27 — adjusted yoyo cycle count in Play, catch all exceptions
// 2025-09-07 — constexpr Bézier presets; move FPS config into Scheduler
//              defer removals to end-of-frame (fix access violation on Cancel/Stop),
//              KillFor(): Progress=0.0 semantics, no globals
// 2025-09-11 — headless deterministic console probe; owned re-entrant spawns;
//              explicit shutdown order (ClearPool → Animation::Finalize());
//              eliminated exit-time AV/leak; added L23–L26 tests & docs.
// 2025-09-13 — Reset(): abort + re-prime staging so the same instance can be
//              reused immediately. Tightened semantics (Pause reversible,
//              Cancel destructive, Reset clean slate). All setters and
//              operator()(...) now EnsureStaging_() to avoid null deref after
//              Cancel(). Added L27/L28 tests.
//
// Note: file banner path reflects package directory (Animation/).

#include "Animation.h"

using namespace Upp;

/*==================== Scheduler ====================*/
namespace {

struct Scheduler {
    // Singleton accessor (U++-style; safe for shutdown + memdiag).
    static Scheduler& Inst() { return Single<Scheduler>(); }

    // State
    Vector<Animation::State*> active; // Owns State* pointers
    TimeCallback ticker;              // Timer for frame updates
    bool running = false;             // Scheduler active state
    int  timer_id = 0;                // Timer identifier for validation
    int64 manual_last_now = 0;        // Monotonic time for manual ticking
    bool sweeping = false;            // true while RunFrame() iterates 'active'

    // Frame pacing
    int fps     = 60;
    int step_ms = 1000 / 60;

    // Change FPS safely while running: re-arms timer with new step.
    void SetFPSInternal(int f) {
        fps     = clamp(f, 1, 240);
        step_ms = max(1, 1000 / fps);
        if (running) {
            Stop();   // kills timer, bumps timer_id
            Start();  // re-arms with new step_ms
        }
    }
    int GetFPSInternal() const { return fps; }

    // Stop timer if there is nothing to advance (all paused or dying).
    void MaybeStopIfAllPaused() {
        for (Animation::State* s : active)
            if (s && !s->paused && !s->dying)
                return; // at least one needs ticking
        Stop();
    }

    // Ensure timer runs if there is something to advance.
    void EnsureRunningIfAnyUnpaused() {
        for (Animation::State* s : active)
            if (s && !s->paused && !s->dying) { Start(); return; }
        // all paused: nothing to do
    }

    // Destroy a state if present.
    void DeleteState(Animation::State* s) { if (s) delete s; }

    // Finalize: stop and purge all animations; detach back-pointers first.
    void Finalize() {
        running = false;
        ++timer_id;
        ticker.Kill();

        // Phase 1: break Animation ↔ State links so Animations don't keep live_.
        for (Animation::State* s : active) {
            if (!s) continue;
            if (s->anim) {
                Animation* a = s->anim;
                double snap = a->Progress();          // snapshot forward progress
                a->_OnStateRemovedCancel(snap);       // sets live_ = nullptr; cache
                s->anim = nullptr;                    // break back-pointer
            }
        }
        // Phase 2: delete states and clear.
        for (Animation::State* s : active)
            DeleteState(s);
        active.Clear();
        manual_last_now = 0;
    }

    // Start/stop timer loop.
    void Start() {
        if (running) return;
        running = true;
        int current_id = ++timer_id;
        ticker.Set(step_ms, callback1(this, &Scheduler::TickTimer, current_id));
    }
    void Stop() {
        if (!running) return;
        running = false;
        ++timer_id; // invalidate queued ticks
        ticker.Kill();
    }

    // Add/remove active states.
    void Add(Animation::State* s) {
        active.Add(s);
        Start();
    }
    void Remove(Animation::State* st) {
        if (!st) return;
        if (sweeping) { // never mutate 'active' mid-iteration
            st->dying = true;
            return;
        }
        for (int i = 0; i < active.GetCount(); ++i) {
            if (active[i] == st) {
                DeleteState(active[i]);
                active.Remove(i);
                break;
            }
        }
        if (active.IsEmpty())
            Stop();
    }

    // Kill all animations for a given Ctrl or dead owners; Progress=0.0.
    void KillFor(Ctrl* c) {
        for (int i = active.GetCount() - 1; i >= 0; --i) {
            Animation::State* s = active[i];
            if (!s || !s->owner || s->owner == c) {
                if (s && s->anim) {
                    Animation* a = s->anim;
                    a->_OnStateRemovedCancel(0.0); // clears a->live_, Progress=0
                    s->anim = nullptr;
                }
                if (s) s->dying = true; // defer delete to next sweep
            }
        }
        // Defer actual free to RunFrame(); avoids re-entrancy.
    }

    // Advance all active animations to 'now'; sweep dead states after iteration.
    void RunFrame(int64 now) {
        sweeping = true;
        Vector<int> to_remove;

        for (int i = 0; i < active.GetCount(); ++i) {
            Animation::State* s = active[i];
            bool cont = true;

            if (!s || s->dying) {
                cont = false;
            } else {
                try {
                    cont = s->Step(now);
                } catch (...) {
                    Cerr() << "Exception in Animation::State::Step\n";
                    cont = false;
                }
            }

            if (!cont) {
                if (s && s->anim) {
                    Animation* a = s->anim;
                    if (!s->owner) a->_OnStateRemovedCancel(0.0); // owner died → abort
                    else           a->_OnStateRemovedFinish();    // natural finish
                    s->anim = nullptr;
                }
                to_remove.Add(i);
            }
        }

        sweeping = false;

        // Delete after iteration to keep iteration stable.
        for (int k = to_remove.GetCount() - 1; k >= 0; --k) {
            DeleteState(active[to_remove[k]]);
            active.Remove(to_remove[k]);
        }

        if (active.IsEmpty())
            Stop();
    }

    // Timer-driven frame updates.
    void TickTimer(int current_id) {
        if (current_id != timer_id || !running) return;
        RunFrame(msecs());
        if (!active.IsEmpty())
            ticker.Set(step_ms, callback1(this, &Scheduler::TickTimer, current_id));
    }

    // One manual tick for tests; clamps dt if requested.
    void TickManualOnce(int max_ms_per_tick) {
        int64 wall_now = msecs();
        if (manual_last_now == 0)
            manual_last_now = wall_now;

        int64 dt = wall_now - manual_last_now;
        if (max_ms_per_tick > 0 && dt > max_ms_per_tick)
            dt = max_ms_per_tick;
        if (dt < 0) dt = 0; // guard against clock skew

        manual_last_now += dt;
        RunFrame(manual_last_now);
    }
};

} // namespace

/*==================== Animation::State::Step ====================
  Advance time within the current leg, compute eased value, invoke callbacks,
  and handle loop/yoyo bookkeeping. Returns true to keep scheduling. */
bool Animation::State::Step(int64 now)
{
    if (!owner) return false;   // owner died
    if (paused) return true;    // stay scheduled, do not advance

    const int64 local = now - start_ms + elapsed_ms;
    if (local < spec.delay_ms)
        return true;            // still in delay window

    const int dur = max(1, spec.duration_ms);
    double leg_progress = double(local - spec.delay_ms) / dur;
    leg_progress = clamp(leg_progress, 0.0, 1.0);

    // Adjust for yoyo direction.
    double t = reverse ? (1.0 - leg_progress) : leg_progress;

    // Apply easing.
    const double e = spec.easing ? spec.easing(t) : t;

    // Callbacks.
    if (spec.on_update) spec.on_update(e);
    if (spec.tick && !spec.tick(e))
        return false;           // user requested stop → treated as finish/cancel

    // Leg finished?
    if (leg_progress >= 1.0) {
        if (spec.yoyo) {
            reverse = !reverse;
            if (!reverse) { // finished a forward+reverse cycle
                if (spec.loop_count >= 0 && --cycles <= 0) {
                    if (spec.on_finish) spec.on_finish();
                    return false;       // natural finish
                }
            }
            start_ms = now;             // next leg
            elapsed_ms = 0;
        } else {
            if (spec.loop_count >= 0 && --cycles <= 0) {
                if (spec.on_finish) spec.on_finish();
                return false;           // natural finish
            }
            start_ms = now;             // next loop
            elapsed_ms = 0;
        }
    }
    return true;
}

/*==================== Animation implementation ====================*/

// Construct an Animation bound to 'owner'. Initializes empty staging config.
Animation::Animation(Ctrl& owner)
    : owner_(&owner)
{
    staging_box_.Create();
    staging_ = ~staging_box_;
}

// Destructor: if still live, perform a silent cancel and detach safely.
Animation::~Animation()
{
    if (live_)
        Cancel(false);   // snapshot progress, detach, sweep-safe remove
}

#define RET(e) do { e; return *this; } while (0)

/*---------------- Staging setters (lazily re-prime if null) ----------------*/

Animation& Animation::Duration(int ms)                    { EnsureStaging_(); RET(staging_->duration_ms = ms); }
Animation& Animation::Ease(const Easing::Fn& fn)          { EnsureStaging_(); RET(staging_->easing = fn); }
Animation& Animation::Ease(Easing::Fn&& fn)               { EnsureStaging_(); RET(staging_->easing = pick(fn)); }
Animation& Animation::Loop(int n)                         { EnsureStaging_(); RET(staging_->loop_count = n); }
Animation& Animation::Yoyo(bool b)                        { EnsureStaging_(); RET(staging_->yoyo = b); }
Animation& Animation::Delay(int ms)                       { EnsureStaging_(); RET(staging_->delay_ms = ms); }
Animation& Animation::OnStart(const Event<>& cb)         { EnsureStaging_(); RET(staging_->on_start = cb); }
Animation& Animation::OnStart(Event<>&& cb)              { EnsureStaging_(); RET(staging_->on_start = pick(cb)); }
Animation& Animation::OnFinish(const Event<>& cb)        { EnsureStaging_(); RET(staging_->on_finish = cb); }
Animation& Animation::OnFinish(Event<>&& cb)             { EnsureStaging_(); RET(staging_->on_finish = pick(cb)); }
Animation& Animation::OnCancel(const Event<>& cb)        { EnsureStaging_(); RET(staging_->on_cancel = cb); }
Animation& Animation::OnCancel(Event<>&& cb)             { EnsureStaging_(); RET(staging_->on_cancel = pick(cb)); }
Animation& Animation::OnUpdate(const Event<double>& c){ EnsureStaging_(); RET(staging_->on_update = c); }
Animation& Animation::OnUpdate(Event<double>&& c)     { EnsureStaging_(); RET(staging_->on_update = pick(c)); }
Animation& Animation::operator()(const Function<bool(double)>& f) { EnsureStaging_(); RET(staging_->tick = f); }
Animation& Animation::operator()(Function<bool(double)>&& f)      { EnsureStaging_(); RET(staging_->tick = pick(f)); }

#undef RET

/*---------------- Control methods ----------------*/

// EnsureStaging_(): lazily create a fresh staging config if missing.
// Needed after Play()/Cancel()/Stop() so setters always have a target.
void Animation::EnsureStaging_() {
    if (staging_)
        return;
    staging_box_.Create();
    staging_ = ~staging_box_;
    *staging_ = Staging(); // default config
}

// Reset(): Abort current run (optionally fire on_cancel), then prime fresh
// staging and zero Progress() so the instance is immediately reusable.
void Animation::Reset(bool fire_cancel) {
    Cancel(fire_cancel);
    EnsureStaging_();
    _SetProgressCache(0.0);
}

// Play(): commit the current staging into a live State and schedule it.
// Staging becomes null and will be recreated on the next setter call.
void Animation::Play()
{
    if (!staging_) return;
    live_ = new State;
    live_->anim  = this;
    live_->owner = owner_;
    live_->spec  = pick(*staging_);
    staging_ = nullptr;         // staging consumed

    _SetProgressCache(0.0);     // reset cache on (re)start
    live_->start_ms = msecs();
    live_->cycles = (live_->spec.loop_count < 0)
                  ? INT_MAX
                  : (live_->spec.yoyo ? (live_->spec.loop_count + 1) / 2
                                      :  live_->spec.loop_count);
    if (live_->spec.on_start) live_->spec.on_start();
    Scheduler::Inst().Add(live_);
}

// Pause(): reversible freeze; accumulates elapsed_ms and stops time advancement.
// Scheduler may stop ticking if everything is paused.
void Animation::Pause()
{
    if (live_ && !live_->paused) {
        live_->elapsed_ms += msecs() - live_->start_ms;
        live_->paused = true;
        Scheduler::Inst().MaybeStopIfAllPaused();
    }
}

// Resume(): continue after Pause(); re-arms scheduler if needed.
void Animation::Resume()
{
    if (live_ && live_->paused) {
        live_->start_ms = msecs();
        live_->paused = false;
        Scheduler::Inst().EnsureRunningIfAnyUnpaused();
    }
}

// Stop(): complete the animation immediately (Progress=1.0). Fires final tick
// and on_finish, then unschedules and frees state.
void Animation::Stop()
{
    if (!live_) return;

    // Deliver final callbacks at boundary values.
    if (live_->spec.tick)      live_->spec.tick(live_->reverse ? 0.0 : 1.0);
    if (live_->spec.on_finish) live_->spec.on_finish();

    Animation::State* st = live_;
    _OnStateRemovedFinish();        // Progress ← 1.0; live_ ← nullptr

    if (st->anim) st->anim = nullptr;
    Scheduler::Inst().Remove(st);
}

// Cancel(): abort the current run; unschedule it and preserve a forward
// progress snapshot so Progress() remains meaningful after abort.
void Animation::Cancel(bool fire_cancel)
{
    if (!live_) return;

    if (fire_cancel && live_->spec.on_cancel)
        live_->spec.on_cancel();

    const double p = Progress();     // snapshot forward time progress
    Animation::State* st = live_;
    live_ = nullptr;                 // detach from State
    if (st->anim) st->anim = nullptr;

    Scheduler::Inst().Remove(st);    // sweep-safe removal
    _OnStateRemovedCancel(p);        // Progress ← snapshot
}

// IsPlaying(): true if a live state exists and is not paused.
bool Animation::IsPlaying() const
{
    return live_ && !live_->paused;
}

// IsPaused(): true if a live state exists and is paused.
bool Animation::IsPaused() const
{
    return live_ && live_->paused;
}

// Progress(): normalized *time* progress in [0..1], independent of easing.
// Uses cached value when no run is live.
double Animation::Progress() const
{
    if (!live_) return progress_cache_;
    int64 run = live_->elapsed_ms + (live_->paused ? 0 : (msecs() - live_->start_ms));
    run = max<int64>(0, run - live_->spec.delay_ms);
    return clamp(double(run) / max(1, live_->spec.duration_ms), 0.0, 1.0);
}

/*---------------- Manual ticking (tests/diagnostics) ----------------*/

// Tick(): advance scheduler by n frames; optionally clamp each dt.
void Animation::Tick(int n, int max_ms_per_tick)
{
    if (n <= 0) return;
    Scheduler& s = Scheduler::Inst();
    for (int i = 0; i < n; ++i)
        s.TickManualOnce(max_ms_per_tick);
}

/*---------------- FPS control ----------------*/

// SetFPS(): change target FPS; re-arms the timer loop if running.
void Animation::SetFPS(int fps) {
    Scheduler::Inst().SetFPSInternal(fps);
}

// GetFPS(): read current target FPS.
int Animation::GetFPS() {
    return Scheduler::Inst().GetFPSInternal();
}

/*---------------- Global helpers ----------------*/

// KillAllFor(): abort all animations for the given Ctrl; Progress=0.0.
void Animation::KillAllFor(Ctrl& c)
{
    Scheduler::Inst().KillFor(&c);
}

// Finalize(): stop scheduler; free all states; sever back-pointers safely.
void Animation::Finalize()
{
    Scheduler::Inst().Finalize();
}

/*---------------- Scheduler → Animation hooks ----------------*/

// Finish path: cache 1.0 and clear live_.
void Animation::_OnStateRemovedFinish() {
    progress_cache_ = 1.0;
    live_ = nullptr;
}

// Cancel/kill path: cache provided forward progress snapshot and clear live_.
void Animation::_OnStateRemovedCancel(double p) {
    progress_cache_ = clamp(p, 0.0, 1.0);
    live_ = nullptr;
}

[didierq]

After further testing, I noticed that the configuration of the Animation instance is lost after Play(), so you have to reconfigure it before each play for ex:

anim.Duration(180);
anim.Ease(Easing::OutQuart());
anim.Yoyo(true);
anim.Play();

[Trilec]

Thanks for the info , Im knee deep in the gallery code at the mo, so will jump back on this when I finish up, cheers

[Trilec]

Got Some time to look at thinks:
I’ve made a few adjustments based on your suggestions 👍

Just to clarify how some of the internals behave:
Cancel() aborts the current run but keeps the forward progress snapshot, so Progress() still reflects how far the animation got before it was cut short.
Reset() is basically Cancel + fresh staging + progress reset to 0, so the same instance is ready to go again immediately.

I get why that might feel a bit odd at first, but the idea is to keep things safe and predictable — avoiding any stale config silently leaking across runs.

To help with the case you mentioned (where you’d like to just run the same config again without re-typing setters), I’ve added a new Replay() method. That simply starts a fresh run using the last spec you played.
Should make those reuse scenarios feel more natural without changing the one-shot staging model.
Cheers
C

[didierq]

Hi,
My point concerning the need to reconfigure before launching a play() is mainly dew to the fact that Play() works but with some default values ... that are different from the ones configured previously : this is confusing for users : you think everything is still working but not quite as expected
So I think a correct behavior could be one of the following cases :

1. Play only works if a fresh config has been set and so it doesn't play at all on second call (without reconfig) rather than play with some default config
2. The previous config is kept, an play = replay

Case 2 doesn't seem good to me because you're point about 'play only once' is needed, so I think the correct behavior should be :

• Play only works if a fresh config has been set and so it doesn't play at all on second call (without reconfig)
• If need to play again ==> call Replay() (note: replay() and play() should have the same behavior on the first call for simplicity)

Thank's for you're work

[Trilec]

MMM, That’s a fair point — calling Play() twice and suddenly getting a run with defaults is confusing.
I agree it’s safer if Play() only runs when there’s an actual config staged, otherwise it should just no-op.

so......Setters mark a tiny staging_dirty_ = true.

Play()
If there’s a fresh staging → run it, cache it as last_spec_, clear dirty.
Else if there’s a last_spec_ → reuse it (natural “play again”).
Else → no-op with a debug log/assert (so you don’t accidentally run with defaults).

Replay()
Always re-run last_spec_ if it exists. Otherwise no-op with a debug log.

Cancel() aborts but preserves last_spec_ (and a forward progress snapshot).

Reset() is cancel + re-prime + set Progress=0. last_spec_ remains, so Replay still works.

I also will clean up API so some of the confusing aspects are reduced:
void Play(); // commit staging → schedule a run
void Pause(); // reversible freeze; no time accrual
void Resume(); // continue after Pause()
void Stop(); // finish now (Progress=1), fire finish
void Cancel(); // abort run; fires on_cancel; keeps last_spec_
void Reset(); // silent abort; primes fresh staging; Progress=0; keeps last_spec_
void Replay(); // (re)start using last_spec_; silently interrupts if running

Great sorting these out, behaviour and API friendliness are very important for me, and I haven't had time to really play with the API as I want to build up the other components before I really get into how we integrate animation into the full system via chameleon ( see the discord chats)

cheers
Curt

[Trilec]

Commited those changes,
added in the replay for GUI and console tests.
Hope that feels a bit better from a usage perspective, enjoy

[didierq]

Hello Trilec,
I will give it a shot soon