A builder class that can be used to construct an Animator wrapping a ValueAnimator implementation. More...

#include <juce_ValueAnimatorBuilder.h>

Collaboration diagram for juce::ValueAnimatorBuilder:

[legend]

Public Types
using	EasingFn = std::function< float(float)>
	The type of an optional easing function that can be passed to the withEasing() builder function.

using	OnStartReturningValueChangedCallback = std::function< ValueChangedCallback()>
	The type of the on start callback.

using	ValueChangedCallback = std::function< void(float)>
	The type of the value change callback.

Public Member Functions
Animator	build () &&
	The build() function will instantiate a new underlying implementation with the specified parameters and return an Animator object referencing it.

Animator	build () const &
	The build() function will instantiate a new underlying implementation with the specified parameters and return an Animator object referencing it.

auto	getDurationMs () const
	Getter function used by the corresponding Animator implementation.

auto &	getEasing () const
	Getter function used by the corresponding Animator implementation.

auto &	getOnComplete () const
	Getter function used by the corresponding Animator implementation.

auto &	getOnStartWithValueChanged () const
	Getter function used by the corresponding Animator implementation.

auto	isInfinitelyRunning () const
	Getter function used by the corresponding Animator implementation.

ValueAnimatorBuilder	runningInfinitely () const
	This function specifies that the Animator will keep running even after its progress > 1.0 and its on complete function will not be called until Animator::complete() is called.

ValueAnimatorBuilder	withDurationMs (double durationMsIn) const
	Use this function to specify the time it takes for the Animator to reach a progress of 1.0.

ValueAnimatorBuilder	withEasing (EasingFn fn) const
	Supply a function that transforms the linear progression of time.

ValueAnimatorBuilder	withOnCompleteCallback (std::function< void()> value) const
	Use this function to optionally specify an on complete callback.

ValueAnimatorBuilder	withOnStartCallback (std::function< void()> onStartCallback) const
	Use this function to specify an optional on start callback.

ValueAnimatorBuilder	withOnStartReturningValueChangedCallback (OnStartReturningValueChangedCallback value) const
	Use this function to specify an optional on start callback.

ValueAnimatorBuilder	withValueChangedCallback (ValueChangedCallback valueChangedCallback) const
	Use this function to specify an optional on change callback.

Private Member Functions
template<typename Member , typename Value >
ValueAnimatorBuilder	with (Member &&member, Value &&value) const noexcept

Private Attributes
double	durationMs = 300.0

EasingFn	easing = Easings::createEase()

bool	infinitelyRunning = false

std::function< void()>	onComplete

OnStartReturningValueChangedCallback	onStartReturningValueChanged

Detailed Description

A builder class that can be used to construct an Animator wrapping a ValueAnimator implementation.

Every ValueAnimatorBuilder object is immutable, and every "with..." function returns a new object. Each object can be used independently and as many times as required to build an Animator object.

Calling build() multiple times will return an independent Animator object referencing a new instance of the underlying implementation. Such Animator objects don't affect each other's lifetime. The copy of an Animator object however shares ownership with the object that it was copied from.

You can treat ValueAnimatorBuilder instances as disposable objects that are only needed until you call build() on them. You can then store only the returned Animator object, which can be started and completed multiple times as needed.

All functions beginning with "with..." are optional and can be used to affect the created Animator's behaviour by overriding defaults.

@tags{Animations}

Member Typedef Documentation

◆ EasingFn

using juce::ValueAnimatorBuilder::EasingFn = std::function<float (float)>

The type of an optional easing function that can be passed to the withEasing() builder function.

If this function is specified it will be called with the progress value going from 0.0 to 1.0 (and beyond in case of an infinitely running Animator), that would otherwise be passed directly to the value change callback. The return value is then passed to the on value change callback instead.

This function can be used to change the linear progression of the animation and create effects like rubber band like motion.

See also: ValueChangedCallback

◆ OnStartReturningValueChangedCallback

using juce::ValueAnimatorBuilder::OnStartReturningValueChangedCallback = std::function<ValueChangedCallback()>

The type of the on start callback.

It can be used to do any initialisation necessary at the start of an animation, then it must return a ValueChangedCallback.

The ValueChangedCallback is called during every update of the Animator after the on start callback and before the on complete callback.

The on start callback is called during the first update that the Animator receives after Animator::start() has been called. Immediately after the on start callback the first call to the value changed callback is made.

See also: ValueChangedCallback

◆ ValueChangedCallback

using juce::ValueAnimatorBuilder::ValueChangedCallback = std::function<void (float)>

The type of the value change callback.

The float parameter is related to the time parameter passed to Animator::update(). The update function is typically called by an AnimatorUpdater. The parameter will have a value of 0.0 during the first call of the value change callback, and it will reach 1.0 when the time passed equals the duration of the Animator. This however can be changed if an EasingFn is also specified. Correctly written easing functions should preserve the 0.0 and 1.0 start and end values, but intermittent values can fall outside the range of [0.0, 1.0].

After a call with a progress value of 1.0, the on complete callback will be called and the updates will stop, unless the Animator is infinitely running, in which case the progress will go beyond 1.0 and on complete will not be called until after Animator::complete() has been called.

A value change callback is optional. If you want to use one, you need to create it inside your on start callback that you must pass to withOnStartCallback().

See also: withOnStartCallback, withDurationMs, withEasing, runningInfinitely

Member Function Documentation

◆ build() [1/2]

Animator juce::ValueAnimatorBuilder::build ( ) &&

The build() function will instantiate a new underlying implementation with the specified parameters and return an Animator object referencing it.

Calling build() multiple times will return unrelated Animator objects, that reference separate underlying implementation instances.

This overload will be called on rvalue handles.

◆ build() [2/2]

Animator juce::ValueAnimatorBuilder::build ( ) const &

The build() function will instantiate a new underlying implementation with the specified parameters and return an Animator object referencing it.

Calling build() multiple times will return unrelated Animator objects, that reference separate underlying implementation instances.