Magnum::Ui::GenericNodeAnimator class new in Git master
#include <Magnum/Ui/GenericAnimator.h>

Generic animator with animations attached to nodes.

Each animation is a function that gets called with an associated node handle and an animation factor in the range. The function can then call arbitrary node-related setters on the UI instance or elsewhere. Use GenericDataAnimator for animations associated with a particular layer data, GenericAnimator is then for animations not tied to either.

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 be played, 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.

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.

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 played, Nanoseconds duration, NodeHandle node, UnsignedInt repeatCount = 1, AnimationFlags flags = {}) -> AnimationHandle: Create an animation.
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

Magnum::Ui::GenericNodeAnimator::GenericNodeAnimator(AnimatorHandle handle) explicit

Constructor.

Parameters
handle	Handle returned by AbstractUserInterface::createAnimator()

Magnum::Ui::GenericNodeAnimator::GenericNodeAnimator(GenericNodeAnimator&&) noexcept

Move constructor.

Performs a destructive move, i.e. the original object isn't usable afterwards anymore.

UnsignedInt Magnum::Ui::GenericNodeAnimator::usedAllocatedAnimationCount() const

Count of allocated animation functions.

Always at most usedCount(). Counts all animation functions that capture non-trivially-destructible state or state that's too large to be stored in-place. The operation is done with a complexity where is capacity().

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

Create an animation.

Parameters
animation	Animation function
easing	Easing function between `0.0f` and `1.0f`, applied to the `factor` passed to `animation`. Pick one from Animation::Easing or supply a custom one.
played	Time at which the animation is played. Use Nanoseconds::max() for creating a stopped animation.
duration	Duration of a single play of the animation
node	Node the animation is attached to. Use NodeHandle::Null to create an animation that isn't attached to any node.
repeatCount	Repeat count. Use `0` for an indefinitely repeating animation.
flags	Flags

Expects that both animation and easing are not nullptr. Delegates to AbstractAnimator::create(Nanoseconds, Nanoseconds, DataHandle, UnsignedInt, AnimationFlags), see its documentation for more information.

Assuming the easing function correctly maps 0.0f and 1.0f to themselves, the animation function is guaranteed to be called with factor being exactly 1.0f once the animation is stopped. Other than that, it may be an arbitrary value from the range.

void Magnum::Ui::GenericNodeAnimator::remove(AnimationHandle handle)

Remove an animation.

Expects that handle is valid. Delegates to AbstractAnimator::remove(AnimationHandle), see its documentation for more information.

void Magnum::Ui::GenericNodeAnimator::remove(AnimatorDataHandle handle)

Remove an animation assuming it belongs to this animator.

Compared to remove(AnimationHandle) delegates to AbstractAnimator::remove(AnimatorDataHandle) instead.

auto Magnum::Ui::GenericNodeAnimator::easing(AnimationHandle handle)

Animation easing function.

Expects that handle is valid. The returned pointer is never nullptr.

auto Magnum::Ui::GenericNodeAnimator::easing(AnimatorDataHandle handle)

Animation easing function assuming it belongs to this animator.

Like easing(AnimationHandle) const but without checking that handle indeed belongs to this animator. See its documentation for more information.