A value that eases to a new target over a Transition and repaints its owner on every step. More...

#include <gin_animated.h>

Inheritance diagram for Animated< T >:

Public Member Functions
	Animated (juce::Component &owner, const juce::String &property={}, T initial=T())
const T &	get () const
	Returns the current, possibly mid-transition, value.
	operator const T & () const
	Returns the current value, so an Animated<T> can be passed where a T is expected.
const T &	getTarget () const
	Returns the value the transition heads for, the current one when none runs.
void	setValue (T newValue)
	Jumps to the value, stopping any transition.
void	setTarget (T newTarget)
	Eases to the value with the owner's transition for the property.
void	setTarget (T newTarget, const juce::String &nameOrSpec)
	Eases to the value with a preset name (looked up from the owner up), an inline spec like "120 outQuad" or "none".
void	setTarget (T newTarget, const Transition &t)
	Eases to the value with an explicit Transition.
void	updateTarget (T newTarget)
	Changes the target of a running transition without restarting it: start value, start time and easing stay, so it still ends on time.
void	followTarget (T newTarget)
	For a target that streams in, like live colours or a meter: starts a transition when none runs, otherwise moves the running one's target (updateTarget()).
void	followTarget (T newTarget, const juce::String &nameOrSpec)
	followTarget() with a preset name, an inline spec or "none"
void	followTarget (T newTarget, const Transition &t)
	followTarget() with an explicit Transition
Public Member Functions inherited from AnimatedBase
	AnimatedBase (juce::Component &owner, const juce::String &property)
virtual	~AnimatedBase ()
bool	isAnimating () const
	True while a transition runs.
juce::Component *	getOwner () const
	The owning component, nullptr once it was deleted.
const juce::String &	getProperty () const
	The name the layout's "transition" entries know this value by.
Transition	getTransition () const
	The transition setTarget (value) uses: the owner's for the property, see Transition::forProperty.

Additional Inherited Members
Public Attributes inherited from AnimatedBase
std::function< void()>	onChange
	Called on every change of the current value (each animation step, and jumps), after the owner was asked to repaint.
Protected Member Functions inherited from AnimatedBase
bool	start (const Transition &t)
	Returns false when the change has to apply at once: an instant transition or an owner not on screen.
void	stop ()
void	changed ()
virtual void	valueChanged ()
	For subclasses that apply the value somewhere: called on every change, before onChange.
float	getLastProgress () const
	The eased progress of the latest step of the running transition.

Detailed Description

template<typename T>
class Animated< T >

A value that eases to a new target over a Transition and repaints its owner on every step.

Setting a target starts from the current value, so retargeting mid-flight continues smoothly; setting the target it already heads for changes nothing.
Reading it (get() or the implicit conversion) returns the current value, so paint() just reads it.
A target set while the owner isn't showing, with an instant transition, or before a layout defined any transition, applies at once (setValue()).
Steps run on the vertical blank of the owner's window via a shared AnimationDriver, which goes idle when nothing animates.

The transition comes from the layout json by the property name given to the constructor (see Transition for the json syntax and inheritance), or from a preset name or inline spec passed to setTarget().

Any type with an Interpolator works: float (any scalar such as a font height or corner radius), double, juce::Colour, juce::Point<float>, juce::Rectangle<float>, juce::Rectangle<int>, juce::Font and juce::ColourGradient come with one.

// layout json: "transitions": { "quick": "100 outQuad" },
//              { "id": "panel", "transition": { "glow": "quick" } }
class Panel : public juce::Component
{
public:
    void setLit (bool lit)
    {
        glow.setTarget (lit ? 1.0f : 0.0f);                 // the layout's "glow" transition
        tint.setTarget (lit ? juce::Colours::gold : juce::Colours::grey, "250 inOutQuad");
    }
 
    void paint (juce::Graphics& g) override
    {
        g.setColour (tint.get().withMultipliedAlpha (glow));
        g.fillEllipse (getLocalBounds().toFloat());
    }
 
private:
    gin::Animated<float> glow { *this, "glow" };
    gin::Animated<juce::Colour> tint { *this, "tint", juce::Colours::grey };
};

See also: Crossfade, Interpolator, Transition

Constructor & Destructor Documentation

◆ Animated()

template<typename T>

Animated< T >::Animated	(	juce::Component &	owner,
		const juce::String &	property = {},
		T	initial = T() )

Parameters

owner	The component that repaints on every step and whose layout transitions apply
property	The name the layout's "transition" object knows this value by
initial	The starting value

Member Function Documentation

◆ get()

template<typename T>

const T & Animated< T >::get ( ) const

Returns the current, possibly mid-transition, value.

◆ operator const T &()

template<typename T>

Animated< T >::operator const T & ( ) const

Returns the current value, so an Animated<T> can be passed where a T is expected.

◆ getTarget()

template<typename T>

const T & Animated< T >::getTarget ( ) const

Returns the value the transition heads for, the current one when none runs.

◆ setValue()

template<typename T>

void Animated< T >::setValue ( T newValue )

Jumps to the value, stopping any transition.

Calls onChange only if the value changed

References AnimatedBase::changed(), and AnimatedBase::stop().

Referenced by followTarget(), setTarget(), setTarget(), and updateTarget().

◆ setTarget() [1/3]

template<typename T>

void Animated< T >::setTarget ( T newTarget )

Eases to the value with the owner's transition for the property.

References AnimatedBase::getTransition(), and setTarget().

Referenced by followTarget(), setTarget(), and setTarget().

◆ setTarget() [2/3]

template<typename T>

void Animated< T >::setTarget	(	T	newTarget,
		const juce::String &	nameOrSpec )

Eases to the value with a preset name (looked up from the owner up), an inline spec like "120 outQuad" or "none".

References AnimatedBase::getOwner(), Transition::resolve(), setTarget(), and setValue().

◆ setTarget() [3/3]

template<typename T>

void Animated< T >::setTarget	(	T	newTarget,
		const Transition &	t )

Eases to the value with an explicit Transition.

References AnimatedBase::isAnimating(), setValue(), and AnimatedBase::start().

◆ updateTarget()

template<typename T>

void Animated< T >::updateTarget ( T newTarget )

Changes the target of a running transition without restarting it: start value, start time and easing stay, so it still ends on time.

For a target that moves continuously while a transition runs, e.g. a level dragged during a colour blend. Without a running transition it jumps (setValue()).

References AnimatedBase::changed(), AnimatedBase::getLastProgress(), AnimatedBase::isAnimating(), and setValue().

Referenced by followTarget().

◆ followTarget() [1/3]

template<typename T>

void Animated< T >::followTarget ( T newTarget )

For a target that streams in, like live colours or a meter: starts a transition when none runs, otherwise moves the running one's target (updateTarget()).

The value keeps following without restarting on every update, and without lagging further behind than one transition.

References followTarget(), and AnimatedBase::getTransition().

Referenced by followTarget(), and followTarget().