Magnum::Ui::GenericDataAnimator 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, use setLayer() to register the animator with a concrete layer instance. Then, assuming AbstractUserInterface::advanceAnimations() is called in an appropriate place, the animator is ready to use.

Ui::AbstractLayer& layer = …;

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

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

Creating animations

An animation is created by calling create() with an appropriate function taking the data 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 DataHandle it's attached to. For example, animating a progress bar change, where the value is visualized using custom BaseLayer padding on the left side:

Ui::BaseLayer& baseLayer = …;
Ui::DataHandle progressbar = …;

Float from = …;
Float to = …;
animator.create([&baseLayer, from, to](Ui::DataHandle progressbar, Float factor) {
    baseLayer.setPadding(progressbar, {Math::lerp(from, to, factor), 0.0f, 0.0f, 0.0f});
}, Animation::Easing::cubicIn, now, 0.5_sec, progressbar);

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 a custom style, setting a different one for the active and completion state:

animator.create([&baseLayer, from, to](Ui::DataHandle progressbar, Float factor,
                                       Ui::GenericAnimationStates state) {
    if(state & Ui::GenericAnimationState::Started)
        baseLayer.setStyle(progressbar, Style::ProgressBarActive);
    baseLayer.setPadding(progressbar, {Math::lerp(from, to, factor), 0.0f, 0.0f, 0.0f});
    if(state & Ui::GenericAnimationState::Stopped)
        baseLayer.setStyle(progressbar, Style::ProgressBarComplete);
}, Animation::Easing::cubicIn, now, 0.5_sec, progressbar);

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

Ui::TextLayer& textLayer = …;
Ui::DataHandle label = …;

animator.callOnce([&textLayer](Ui::DataHandle label) {
    textLayer.setText(label, "Timed out.", {});
}, now + 10.0_sec, label);

Animation lifetime and data 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 data they animate, when the data the animation is attached to, or the node the data is attached to, is removed, the animation gets removed as well. If you want to preserve the animation when the data is removed, call attach(AnimationHandle, DataHandle) with DataHandle::Null to detach it from the data before removing. After that, or if you call create() with DataHandle::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

GenericDataAnimator(AnimatorHandle handle) explicit

Constructor.

GenericDataAnimator(const GenericDataAnimator&) deleted

Copying is not allowed.

GenericDataAnimator(GenericDataAnimator&&) noexcept

Move constructor.

Public functions

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

Copying is not allowed.

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

Move assignment.

void setLayer(const AbstractLayer& layer)

Set a layer associated with this animator.

auto usedAllocatedAnimationCount() const -> UnsignedInt

Count of allocated animation functions.

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

Create an animation.

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

Create an animation with an extra state input.

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

Create an animation assuming the data it's attached to belongs to the layer the animator is registered with.

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

Create an animation assuming the data it's attached to belongs to the layer the animator is registered with, with an extra state input.

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

Call a function once at specified time.

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

Call a function once at specified time assuming the data it's attached to belongs to the layer the animator is registered with.

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