API — ICoreEssentials/UI/Motion

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

ICoreAnimation.h#

src/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.

ICoreAnimationAccess.h#

src/ICoreEssentials/UI/Motion/ICoreAnimationAccess.h

IMPLEMENTATION SIDE ONLY -- include from a .cpp, never from a public wrapper header. This names Qt, exactly as ICoreNativeHandleAccess.h does and for the same reason: the unchecked cast belongs in one place per kind rather than one per call site.

Kept SEPARATE from ICoreNativeHandleAccess.h deliberately. That header is included very widely and, since P7.2, pulls in all thirteen Group D value headers; the Motion seam has no business widening that blast radius, and nothing outside Motion and its call sites needs this cast.

Declares no class of its own — see the file.

ICoreAnimationGroup.h#

src/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#

src/ICoreEssentials/UI/Motion/ICoreAnimationPolicy.h

ICoreAnimationPolicy#

ICoreAnimationPolicy.h:39 · class · 1 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
    };

    static bool isEnabled(Scope scope);

    // 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.
};
};