API — ICoreEssentials/UI/Motion

The public contract of 4 header(s) under ICoreEssentials/UI/Motion — 3 class/struct definition(s), 22 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreAnimation.h#

ICoreEssentials/UI/Motion/ICoreAnimation.h

Both classes in this header are converted now (P3.7, P3.8), and since Q1.7 it names no Qt type at all -- the class QObject; forward declaration that stood here for the transitional target/parent parameters went with them. The three Qt includes that used to be here (<QAbstractAnimation>, <QObject>, <QVariantAnimation>) went with the second base, so this header no longer pulls the animation framework into the 44 files that include it.

Declares no class of its own — see the file.

ICoreAnimationGroup.h#

ICoreEssentials/UI/Motion/ICoreAnimationGroup.h

ICoreAnimationGroup#

ICoreAnimationGroup.h:51 · class · final · pImpl · 10 declaration(s)

ICoreAnimationGroup -- several animations run as one, with the policy applied to the whole.

class ICoreAnimationGroup final {
public:
    using Scope = ICoreAnimationPolicy::Scope;

    enum class Kind {
        // All children run at once, and the group ends with the last of them.
        Parallel,
        // Children run in the order they were added, each starting when the
        // one before it ends.
        Sequential
    };

    // `parent` is a lifetime guard, not a layout relationship: when it dies the
    // group dies with it, so an animation cannot outlive the object whose
    // properties it is writing. Pass nullptr for a group owned outright by the
    // caller -- as a member or a stack object -- which is the shape to prefer
    // for anything long-lived (see ~ICoreAnimationGroup).
    ICoreAnimationGroup(Kind kind, Scope scope, ICoreNativeObject* parent = nullptr);

    ~ICoreAnimationGroup();

    ICoreAnimationGroup(const ICoreAnimationGroup&) = delete;
    ICoreAnimationGroup& operator=(const ICoreAnimationGroup&) = delete;

    // ⚠ TAKES OWNERSHIP of `animation`, which is the toolkit's rule for a group
    // and is preserved here. The caller may keep the pointer to configure the
    // child afterwards -- ICoreTimeLineProgressBar does exactly that -- but it
    // is a borrowed observer from this point and must never be deleted.
    //
    // ⚠ A raw pointer rather than the std::unique_ptr that P4.2 chose for
    // ICoreTree::setItemDelegate, and the difference is not an oversight. That
    // parameter could promise "I destroy this", because the tree genuinely
    // does. This one cannot: after P3.7 the group's Impl owns the CHILD'S Impl,
    // and it is the child's Impl that takes the child wrapper down with it. A
    // unique_ptr parameter here would have to release() the pointer it was
    // handed and let something else do the deleting, which is a signature that
    // says one thing and does another.
    void addAnimation(ICoreAnimation* animation);

    // A gap of `milliseconds` in a Sequential group -- the wait between one
    // child ending and the next beginning. Meaningless in a Parallel group,
    // where it would simply be another child running alongside the rest.
    //
    // The pause is scaled and collapsed by the policy along with everything
    // else, so switching animations off removes the wait rather than leaving
    // the UI sitting still for it.
    void addPause(int milliseconds);

    // Restart from the beginning forever, until stop(). Spelled as a named
    // method rather than setLoopCount(int) because -1 is the only loop count
    // this editor uses, and "-1 means forever" is a toolkit convention no call
    // site should have to know (§9 -- do not publish surface nobody asks for).
    void loopForever();

    // Both routed through ICoreAnimationPolicy, exactly as ICoreAnimation's
    // are: the group is the thing whose duration the user's preferences act on.
    void start();

    // Run once and then destroy the group AND every child in it. Only valid for
    // a group nothing else holds -- a local built, filled and started in one
    // function. A group held as a member must use start().
    void startAndDeleteWhenStopped();

    void stop();

    // Re-emit of the toolkit's group-completion signal. Fires when the last
    // child finishes; for a looping group it does not fire until stop().
    ICoreSignal<> onFinished;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreAnimationPolicy.h#

ICoreEssentials/UI/Motion/ICoreAnimationPolicy.h

ICoreAnimationPolicy#

ICoreAnimationPolicy.h:40 · class · 2 declaration(s)

The one place animations are started, so the user's animation preferences actually mean something.

class ICoreAnimationPolicy {
public:
    enum class Scope {
        Canvas,
        Widget,
        // ⚠ EXEMPT FROM BOTH PREFERENCES AND FROM THE SPEED SCALE (W10.60). For
        // the few motions that ARE the control rather than decorating it -- the
        // Copilot chip's hover growth, which the owner wants on whatever the
        // user chose. Collapsed to 0 ms it jumped to size on every enter and
        // back on every leave, and the growth itself moves the chip under the
        // pointer, so a disabled run read as the chip flickering between sizes.
        // Use sparingly: it overrides a user's stated wish.
        Always
    };

    static bool isEnabled(Scope scope);

    // The duration an animation should ACTUALLY run for, given the user's two
    // preferences and the duration its call site authored. Every animation on
    // every backend asks this instead of asking isEnabled() and forgetting the
    // other half.
    //
    //   * animations off for this scope -> 0, the collapse described above:
    //     the run still happens and still lands on its end value.
    //   * animations on -> the authored duration scaled by the user's
    //     animation-SPEED preference (ICoreRenderingPolicy::
    //     animationDurationPercent(): "Fast" 60, "Normal" 100, "Slow" 150).
    //
    // ⚠ IT TAKES THE AUTHORED DURATION AND RETURNS A NEW ONE RATHER THAN
    // WRITING BACK, and that is what retires P3.9's compounding bug by
    // construction. The Qt-only enforcement this replaces scaled the animation
    // object's own duration field in place, so a RETAINED animation re-read
    // what the previous start had written -- 200ms -> 120 -> 72 -> 43 at
    // "Fast", and unbounded growth at "Slow" -- and needed two dynamic
    // properties to remember its way back out. Nothing is written back here,
    // so there is nothing to compound and nothing to remember.
    static int effectiveDurationMs(Scope scope, int authoredMs);

    // The two duration walks that used to be private statics here went with
    // start(), into ICoreAnimationPolicy.cpp's anonymous namespace: they took
    // QAbstractAnimation* and were the only remaining reason this header
    // needed <QAbstractAnimation> at all. Nothing outside that .cpp ever
    // called them -- they were private.
};
};

ICoreFrameTicker.h#

ICoreEssentials/UI/Motion/ICoreFrameTicker.h

ICoreFrameTicker#

ICoreFrameTicker.h:29 · class · pImpl · 10 declaration(s)

A handler run once per display frame, on the main thread -- the way to redraw something in step with the screen instead of on a timer.

class ICoreFrameTicker {
public:
    ICoreFrameTicker();
    ~ICoreFrameTicker();

    ICoreFrameTicker(const ICoreFrameTicker&) = delete;
    ICoreFrameTicker& operator=(const ICoreFrameTicker&) = delete;

    // Called with the frame's time in milliseconds on a monotonic clock, and
    // the milliseconds since the previous call -- 0 for the first frame after
    // the ticker was idle, so a motion that resumes does not jump by the time
    // it spent stopped.
    using Handler = std::function<void(double frameTimeMs, double deltaMs)>;
    void setHandler(Handler handler);

    // One call at the next frame. Coalesced; cheap to call often.
    void requestFrame();

    // Every frame while on; requestFrame() still works while it is off.
    void setContinuous(bool continuous);
    [[nodiscard]] bool isContinuous() const;

    // Whether a call is owed: a request not yet delivered, or continuous mode.
    [[nodiscard]] bool isActive() const;

    // How many times the handler has been called.
    [[nodiscard]] long long frameCount() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};