Loading...
Searching...
No Matches
juce::ValueAnimatorBuilder Class Reference

## 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.

The documentation for this class was generated from the following file:

- juce_animation/animation/juce_ValueAnimatorBuilder.h

## Public Types

using | ValueChangedCallback = std::function<void (float)>
| The type of the value change callback.
using | OnStartReturningValueChangedCallback = std::function<ValueChangedCallback()>
| The type of the on start callback.
using | EasingFn = std::function<float (float)>
| The type of an optional easing function that can be passed to the withEasing() builder function.

## Public Member Functions

ValueAnimatorBuilder | withOnStartCallback (std::function< void()> onStartCallback) 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.
ValueAnimatorBuilder | withOnStartReturningValueChangedCallback (OnStartReturningValueChangedCallback value) const
| Use this function to specify an optional on start callback.
ValueAnimatorBuilder | withOnCompleteCallback (std::function< void()> value) const
| Use this function to optionally specify an on complete callback.
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 | 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.
auto & | getOnComplete () const
| Getter function used by the corresponding Animator implementation.
auto & | getOnStartWithValueChanged () const
| Getter function used by the corresponding Animator implementation.
auto | getDurationMs () const
| Getter function used by the corresponding Animator implementation.
auto | isInfinitelyRunning () const
| Getter function used by the corresponding Animator implementation.
auto & | getEasing () const
| Getter function used by the corresponding Animator implementation.
Animator | build () const &
| The build() function will instantiate a new underlying implementation with the specified parameters and return an Animator object referencing it.
Animator | build () &&
| The build() function will instantiate a new underlying implementation with the specified parameters and return an Animator object referencing it.

## Member Typedef Documentation

## 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

## 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

## 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

## Member Functions

## withOnStartCallback()

ValueAnimatorBuilder juce::ValueAnimatorBuilder::withOnStartCallback | ( | std::function< void()> | onStartCallback | ) | const

inline nodiscard

Use this function to specify an optional on start callback.

Alternatively you can use the withOnStartReturningValueChangedCallback function that allows you to return the ValueChangedCallback from inside your on start callback.

You can only use either withOnStartCallback() or withOnStartReturningValueChangedCallback().

References juce::NullCheckedInvocation::invoke().

## withValueChangedCallback()

ValueAnimatorBuilder juce::ValueAnimatorBuilder::withValueChangedCallback | ( | ValueChangedCallback | valueChangedCallback | ) | const

inline nodiscard

Use this function to specify an optional on change callback.

Alternatively you can use the withOnStartReturningValueChangedCallback function that allows you to return the ValueChangedCallback from inside your on start callback.

You can only use either withValueChangedCallback or withOnStartReturningValueChangedCallback.

See also
  OnStartReturningValueChangedCallback

References juce::NullCheckedInvocation::invoke(), and x.

## withOnStartReturningValueChangedCallback()

ValueAnimatorBuilder juce::ValueAnimatorBuilder::withOnStartReturningValueChangedCallback | ( | OnStartReturningValueChangedCallback | value | ) | const

inline nodiscard

Use this function to specify an optional on start callback.

The return value of the provided function is a ValueChangedCallback. This allows you to construct a new ValueChangedCallback on every on start event, capturing state that is also constructed at the time of starting.

If you don't need to return a new ValueChangedCallback on every animation start, you can use the simpler variants withOnStartCallback and withValueChangedCallback. However you cannot use those functions together with this one.

See also
  OnStartReturningValueChangedCallback, withOnStartCallback, withValueChangedCallback

## withOnCompleteCallback()

ValueAnimatorBuilder juce::ValueAnimatorBuilder::withOnCompleteCallback | ( | std::function< void()> | value | ) | const

inline nodiscard

Use this function to optionally specify an on complete callback.

This function will be called after the Animator reached a progress value >= 1.0, or in the case of an infinitely running animation, if Animator::complete() has been called.

## withDurationMs()

ValueAnimatorBuilder juce::ValueAnimatorBuilder::withDurationMs | ( | double | durationMsIn | ) | const

inline nodiscard

Use this function to specify the time it takes for the Animator to reach a progress of 1.0.

The default value is 300 ms.

A progress of 1.0 will be reached after this time elapses even if the Animator is infinitely running.

## withEasing()

ValueAnimatorBuilder juce::ValueAnimatorBuilder::withEasing | ( | EasingFn | fn | ) | const

inline nodiscard

Supply a function that transforms the linear progression of time.

See also
  EasingFn

## runningInfinitely()

ValueAnimatorBuilder juce::ValueAnimatorBuilder::runningInfinitely | ( |  | ) | const

inline nodiscard

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.

## getOnComplete()

auto & juce::ValueAnimatorBuilder::getOnComplete | ( |  | ) | const

inline

Getter function used by the corresponding Animator implementation.

## getOnStartWithValueChanged()

auto & juce::ValueAnimatorBuilder::getOnStartWithValueChanged | ( |  | ) | const

inline

Getter function used by the corresponding Animator implementation.

## getDurationMs()

auto juce::ValueAnimatorBuilder::getDurationMs | ( |  | ) | const

inline

Getter function used by the corresponding Animator implementation.

## isInfinitelyRunning()

auto juce::ValueAnimatorBuilder::isInfinitelyRunning | ( |  | ) | const

inline

Getter function used by the corresponding Animator implementation.

## getEasing()

auto & juce::ValueAnimatorBuilder::getEasing | ( |  | ) | const

inline

Getter function used by the corresponding Animator implementation.

## build() [1/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.

Referenced by build().

## build() [2/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.

References build().

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited