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

Generic animator.

Each animation is a function that gets called with an animation factor in the range. The function can then call arbitrary setters on the UI instance, on layers or elsewhere. If an animation is associated with a particular node or layer data, you may want to use GenericNodeAnimator or GenericDataAnimator instead.

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::GenericAnimator& animator = ui.setGenericAnimatorInstance(
    Containers::pointer<Ui::GenericAnimator>(ui.createAnimator()));

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

Creating animations

An animation is created by calling create() with an appropriate function taking the interpolation factor as a single argument, an easing function from Animation::Easing or a custom one, time at which it's meant to be played and its duration.

animator.create([](Float factor) {
    …;
}, Animation::Easing::cubicIn, now, 1.5_sec);

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 themselves, such as playing, stopping, creating or removing them. This isn't checked or enforced in any way, but the behavior of doing so is undefined.

Animation lifetime

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

The animator has no way of knowing what resources the animation function accesses and thus the user is responsible of making sure the animation doesn't attempt to access no longer valid handles and such. For this reason, if the animation is associated with a particular node or layer data, it's recommended to use GenericNodeAnimator or GenericDataAnimator instead, which will ensure that as soon as the node or data the animation is attached to is removed the animation gets removed as well.

Base classes

class AbstractGenericAnimator new in Git master: Base for generic animators.

Constructors, destructors, conversion operators

GenericAnimator(AnimatorHandle handle) explicit: Constructor.
GenericAnimator(const GenericAnimator&) deleted: Copying is not allowed.
GenericAnimator(GenericAnimator&&) noexcept: Move constructor.

Public functions

auto operator=(const GenericAnimator&) -> GenericAnimator& deleted: Copying is not allowed.
auto operator=(GenericAnimator&&) -> GenericAnimator& noexcept: Move assignment.
auto usedAllocatedAnimationCount() const -> UnsignedInt: Count of allocated animation functions.
auto create(Containers::Function<void(Float factor)>&& animation, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, 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::GenericAnimator::GenericAnimator(AnimatorHandle handle) explicit

Constructor.

Parameters
handle	Handle returned by AbstractUserInterface::createAnimator()

Magnum::Ui::GenericAnimator::GenericAnimator(GenericAnimator&&) noexcept

Move constructor.

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

UnsignedInt Magnum::Ui::GenericAnimator::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::GenericAnimator::create(Containers::Function<void(Float factor)>&& animation, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, 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
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::GenericAnimator::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::GenericAnimator::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::GenericAnimator::easing(AnimationHandle handle)

Animation easing function.

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

auto Magnum::Ui::GenericAnimator::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.