Magnum::Ui::GenericNodeAnimator class new in Git master

#include <Magnum/Ui/GenericAnimator.h>

Setting up an animator instance

The animator doesn't have any shared state or configuration, so it's just about constructing it from a fresh AbstractUserInterface::createAnimator() handle and passing it to setGenericAnimatorInstance(). After that, assuming AbstractUserInterface::advanceAnimations() is called in an appropriate place, it's ready to use.

Ui::GenericNodeAnimator& animator = ui.setGenericAnimatorInstance(
    Containers::pointer<Ui::GenericNodeAnimator>(ui.createAnimator()));

Unlike builtin layers or layouters, the default UserInterface implementation doesn't implicitly provide a GenericNodeAnimator instance.

Creating animations

An animation is created by calling create() with an appropriate function taking the node handle and interpolation factor as arguments, an easing function from Animation::Easing or a custom one, time at which it's meant to start, its duration and the NodeHandle it's attached to. For example, animating a dropdown opening by gradually enlarging its height and turning it from transparent to opaque:

Ui::NodeHandle dropdown = …;

animator.create([&ui](Ui::NodeHandle dropdown, Float factor) {
    ui.setNodeSize(dropdown, {ui.nodeSize(dropdown).x(), 150.0f*factor});
    ui.setNodeOpacity(dropdown, 1.0f*factor);
}, Animation::Easing::cubicIn, now, 0.5_sec, dropdown);

If the function performs easing on its own, pass Animation::Easing::linear as the easing function to have the animation factor passed unchanged. There's also an overload taking an extra GenericAnimationStates parameter to perform an action exactly once at animation start and stop. For example, assuming the node is initially hidden, at the start it could be made visible but not reacting to events, and made fully interactive only at the end:

animator.create([&ui](Ui::NodeHandle dropdown, Float factor,
                      Ui::GenericAnimationStates state) {
    if(state & Ui::GenericAnimationState::Started) {
        ui.clearNodeFlags(dropdown, Ui::NodeFlag::Hidden);
        ui.setNodeFlags(dropdown, Ui::NodeFlag::NoEvents);
    }
    ui.setNodeSize(dropdown, {ui.nodeSize(dropdown).x(), 150.0f*factor});
    ui.setNodeOpacity(dropdown, 1.0f*factor);
    if(state & Ui::GenericAnimationState::Stopped) {
        ui.clearNodeFlags(dropdown, Ui::NodeFlag::NoEvents);
    }
}, Animation::Easing::cubicIn, now, 0.5_sec, dropdown);

The animation function is free to do anything except for touching state related to the animations or associated nodes, such as playing or stopping the animations, or creating, removing animations or nodes. This isn't checked or enforced in any way, but the behavior of doing so is undefined.

Ui::NodeHandle tooltip = …;

animator.callOnce([&ui](Ui::NodeHandle tooltip) {
    ui.setNodeFlags(tooltip, Ui::NodeFlag::Hidden);
}, now + 10.0_sec, tooltip);

Animation lifetime and node attachment

As with all other animations, they're implicitly removed once they're played. Pass AnimationFlag::KeepOncePlayed to create() or addFlags() to disable this behavior.

As the animations are associated with nodes they animate, when the node the animation is attached to is removed, the animation gets removed as well. If you want to preserve the animation when the node is removed, call attach(AnimationHandle, NodeHandle) with NodeHandle::Null to detach it from the node before removing. After that, or if you call create() with NodeHandle::Null in the first place, the animation will still play, but the animation function will get a null handle.

Base classes

class AbstractGenericAnimator new in Git master

Base for generic animators.

Constructors, destructors, conversion operators

GenericNodeAnimator(AnimatorHandle handle) explicit

Constructor.

GenericNodeAnimator(const GenericNodeAnimator&) deleted

Copying is not allowed.

GenericNodeAnimator(GenericNodeAnimator&&) noexcept

Move constructor.

Public functions

auto operator=(const GenericNodeAnimator&) -> GenericNodeAnimator& deleted

Copying is not allowed.

auto operator=(GenericNodeAnimator&&) -> GenericNodeAnimator& noexcept

Move assignment.

auto usedAllocatedAnimationCount() const -> UnsignedInt

Count of allocated animation functions.

auto create(Containers::Function<void(NodeHandle node, Float factor)>&& animation, Float(*)(Float) easing, Nanoseconds start, Nanoseconds duration, NodeHandle node, UnsignedInt repeatCount = 1, AnimationFlags flags = {}) -> AnimationHandle

Create an animation.

auto create(Containers::Function<void(NodeHandle node, Float factor, GenericAnimationStates state)>&& animation, Float(*)(Float) easing, Nanoseconds start, Nanoseconds duration, NodeHandle node, UnsignedInt repeatCount = 1, AnimationFlags flags = {}) -> AnimationHandle

Create an animation with an extra state input.

auto callOnce(Containers::Function<void(NodeHandle node)>&& callback, Nanoseconds at, NodeHandle node, AnimationFlags flags = {}) -> AnimationHandle

Call a function once at specified time.

void remove(AnimationHandle handle)

Remove an animation.

void remove(AnimatorDataHandle handle)

Remove an animation assuming it belongs to this animator.

auto easing(AnimationHandle handle) -> auto

Animation easing function.

auto easing(AnimatorDataHandle handle) -> auto

Animation easing function assuming it belongs to this animator.

Function documentation