Duration and easing of an animated change, CSS transition style. More...

#include <gin_animated.h>

Public Types
using	Easing = float (*) (float)
	An easing function, mapping linear progress 0..1 to eased progress.

Public Member Functions
	Transition ()=default
	Creates an instant transition.
	Transition (double durationMs, Easing easing)
	Creates a transition of the given duration in milliseconds and easing.
bool	isInstant () const
	True for "none", a duration of 0 and a default constructed Transition.
float	getProgress (double elapsedMs) const
	Returns the eased progress 0..1 at a time since the start; 1 from durationMs on and always for an instant transition.

Static Public Member Functions
static std::optional< Transition >	fromSpec (const juce::String &spec)
	Parses a spec string, "<ms> <easing>", "<ms>" or "none".
static Easing	findEasing (const juce::String &name)
	Returns the easing function for a name like "inOutQuad", nullptr for an unknown name.
static Transition	resolve (const juce::Component &c, const juce::String &nameOrSpec)
	Resolves a preset name, an inline spec or "none".
static Transition	forProperty (const juce::Component &c, const juce::String &property)
	Returns the transition a property of the component animates with, following the inheritance rules above: the nearest "transition" from the component up through its parents that covers the property, else the preset "default", else instant.
static void	setPresets (juce::Component &c, const juce::var &presets)
	Sets a component's presets, exactly as a layout json's top-level "transitions" does for the component its LayoutSupport lays out: an object of name -> spec, or a JSON string of one.
static juce::var	getPresets (const juce::Component &c)
	The presets setPresets() or a layout set on exactly this component, void if none.
static void	set (juce::Component &c, const juce::var &transition)
	Sets a component's "transition", exactly as the layout entry of that name does: a string (preset name, inline spec or "none") or a per-property object, "descendants" included.
static juce::var	get (const juce::Component &c)
	The "transition" set on exactly this component, void if none.
static void	setGlobalEnabled (bool enabled)
	Switches every transition in the app on or off, e.g.
static bool	isGlobalEnabled ()

Public Attributes
double	durationMs = 0.0
Easing	easing = nullptr

Static Public Attributes
static const juce::Identifier	componentProperty { "layoutTransition" }
	Component property holding a layout entry's "transition".
static const juce::Identifier	presetsProperty { "layoutTransitions" }
	Component property holding the presets of the layout that positions its children.

Detailed Description

Duration and easing of an animated change, CSS transition style.

Transitions are opt-in: a layout or a component without transition definitions behaves exactly as without this class, every change applies at once.

Spec strings

A spec string is "<ms> <easing>", e.g. "250 inOutQuad": the duration in milliseconds (digits and an optional decimal point), whitespace, the easing name. Also valid:

"250" a duration alone is linear
"0 ..." a duration of 0 is instant
"none" instant

Easing names (case sensitive, implemented by the functions in gin_easing.h):

linear
inQuad, outQuad, inOutQuad
inCubic, outCubic, inOutCubic
inQuart, outQuart, inOutQuart
inQuint, outQuint, inOutQuint
inSine, outSine, inOutSine
inCirc, outCirc, inOutCirc
inExpo, outExpo, inOutExpo
inBack, outBack, inOutBack
inElastic, outElastic, inOutElastic
inBounce, outBounce, inOutBounce

Presets

A layout json's top-level "transitions" object names specs. Several layout files of one LayoutSupport merge their presets in load order. Presets are looked up from the animated component up through its parents, so nested layouts can define their own and still use their ancestors'. The preset name "default" is special: it applies to every animated property under that layout that no "transition" entry covers.

"transitions": { "quick": "100 outQuad", "glide": "650 inOutCubic", "default": "250 inOutQuad" }

Per component "transition"

A component entry's "transition" is either

a string, a preset name, an inline spec or "none": applies to every animated property of the component
an object, one value per property name, like CSS transition-property: { "bounds": "glide", "alpha": "quick", "colour": "none" }

Property names: "bounds" (the layout moving and resizing the component), "alpha" and "scale" (the layout's entries of that name and States' values; "scale" is also AnimatedScale's default), "imageFilter" (AnimatedImageFilter's default), and any name an Animated or Crossfade value in code was given.

Inheritance

The transition for a property of a component is the first match walking from the component up through its parents:

a string "transition" matches every property (so "none" stops the walk, instant)
an object "transition" matches the properties it lists; others continue upwards If nothing matches, the "default" preset applies, else the change is instant. A container's transition therefore applies to all its descendants unless they override it.

An object may set what the descendants inherit instead with the key "descendants" (a string or a per-property object, same rules). It doesn't apply to the component itself, e.g. a page that slides in while the rows inside it keep jumping when they relayout: { "bounds": "glide", "alpha": "glide", "descendants": "none" }

{
  "transitions": { "quick": "100 outQuad", "glide": "650 inOutCubic" },
  "components": [
    { "id": "panel", "transition": "glide", "components": [
        { "id": "title" },                                              // glide
        { "id": "knob", "transition": { "bounds": "quick" } },          // bounds quick, rest glide
        { "id": "meter", "transition": "none" },                        // instant
        { "id": "list", "transition": { "alpha": "quick", "descendants": { "bounds": "quick" } } }
                                    // list: alpha quick, bounds glide; its children: bounds quick, alpha glide
    ] }
  ]
}

See also: Animated, Crossfade, LayoutSupport

Member Typedef Documentation

◆ Easing

using Transition::Easing = float (*) (float)

An easing function, mapping linear progress 0..1 to eased progress.

Constructor & Destructor Documentation

◆ Transition() [1/2]

Transition::Transition ( )

default

Creates an instant transition.

Referenced by forProperty(), and resolve().

◆ Transition() [2/2]

Transition::Transition	(	double	durationMs,
		Easing	easing )

Creates a transition of the given duration in milliseconds and easing.

References durationMs, and easing.

Member Function Documentation

◆ fromSpec()

std::optional< Transition > Transition::fromSpec ( const juce::String & spec )

static

Parses a spec string, "<ms> <easing>", "<ms>" or "none".

Returns: std::nullopt for a malformed spec or an unknown easing name, also for a preset name (use resolve() for those)

◆ findEasing()

Easing Transition::findEasing ( const juce::String & name )

static

Returns the easing function for a name like "inOutQuad", nullptr for an unknown name.

◆ resolve()

Transition Transition::resolve	(	const juce::Component &	c,
		const juce::String &	nameOrSpec )

static

Resolves a preset name, an inline spec or "none".

Presets are searched from the component up through its parents (the presets of each LayoutSupport live on the component it lays out). An unknown name asserts and is instant.

References Transition().

Referenced by Animated< T >::followTarget(), Animated< T >::setTarget(), and Crossfade< T >::setTarget().

◆ forProperty()

Transition Transition::forProperty	(	const juce::Component &	c,
		const juce::String &	property )

static

Returns the transition a property of the component animates with, following the inheritance rules above: the nearest "transition" from the component up through its parents that covers the property, else the preset "default", else instant.

References Transition().

◆ isInstant()

bool Transition::isInstant ( ) const

True for "none", a duration of 0 and a default constructed Transition.

References durationMs, and easing.

◆ getProgress()

float Transition::getProgress ( double elapsedMs ) const

Returns the eased progress 0..1 at a time since the start; 1 from durationMs on and always for an instant transition.

◆ setPresets()

void Transition::setPresets	(	juce::Component &	c,
		const juce::var &	presets )

static

Sets a component's presets, exactly as a layout json's top-level "transitions" does for the component its LayoutSupport lays out: an object of name -> spec, or a JSON string of one.

They apply to the component and everything inside it, also children added later. A void var clears them. Invalid specs assert. A LayoutSupport replaces the presets of the component it lays out on every pass, so set them on another component.

For code-built UIs without a layout json above them:

// The grid of game tiles, built in code: presets, timings and the tiles' hover state
GameGrid()
{
    gin::Transition::setPresets (*this, R"({ "hover": "60 inOutQuad", "fade": "300 outQuad" })");
    gin::Transition::set (*this, juce::JSON::parse (R"({ "descendants": { "scale": "hover", "imageFilter": "hover", "alpha": "fade" } })"));
    gin::States::setForChildren (*this, juce::JSON::parse (R"({ "hover": { "scale": 1.05, "imageFilter": "contrast 20" } })"));
}
 
// Each tile, added whenever; it inherits the grid's transitions and states
class GameTile : public juce::Component
{
public:
    void paint (juce::Graphics& g) override             { cover.draw (g, getLocalBounds().toFloat()); }
 
private:
    gin::AnimatedImageFilter cover { *this };   // its image set elsewhere
};

◆ getPresets()

juce::var Transition::getPresets ( const juce::Component & c )

static

The presets setPresets() or a layout set on exactly this component, void if none.

◆ set()

void Transition::set	(	juce::Component &	c,
		const juce::var &	transition )

static

Sets a component's "transition", exactly as the layout entry of that name does: a string (preset name, inline spec or "none") or a per-property object, "descendants" included.

Inherited by everything inside it as described above. A void var clears it. A layout pass that positions the component replaces it with the entry's own.

◆ get()

juce::var Transition::get ( const juce::Component & c )

static

The "transition" set on exactly this component, void if none.

◆ setGlobalEnabled()

void Transition::setGlobalEnabled ( bool enabled )

static

Switches every transition in the app on or off, e.g.

off for software renderers or slow machines. Off, everything that would animate (Animated, Crossfade, AnimatedScale, AnimatedImageFilter, the layout's bounds, alpha and scale, States, box shadows) jumps straight to its target, its owner repainting once per change, and the vertical blank driver doesn't tick at all. Switching off makes running transitions jump to their targets at once. The initial value is GIN_TRANSITIONS_ENABLED_BY_DEFAULT: off on Linux (JUCE's software renderer only), on elsewhere, unless the app defines it.

◆ isGlobalEnabled()

bool Transition::isGlobalEnabled ( )

static

Member Data Documentation

◆ durationMs

double Transition::durationMs = 0.0

Referenced by isInstant(), and Transition().

◆ easing

Easing Transition::easing = nullptr

Referenced by isInstant(), and Transition().

◆ componentProperty

const juce::Identifier Transition::componentProperty { "layoutTransition" }

static

Component property holding a layout entry's "transition".

◆ presetsProperty

const juce::Identifier Transition::presetsProperty { "layoutTransitions" }

static

Component property holding the presets of the layout that positions its children.

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

gin_animated.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Spec strings

Presets

Per component "transition"

Inheritance

Member Typedef Documentation

◆ Easing

Constructor & Destructor Documentation

◆ Transition() [1/2]

◆ Transition() [2/2]

Member Function Documentation

◆ fromSpec()

◆ findEasing()

◆ resolve()

◆ forProperty()

◆ isInstant()

◆ getProgress()

◆ setPresets()

◆ getPresets()

◆ set()

◆ get()

◆ setGlobalEnabled()

◆ isGlobalEnabled()

Member Data Documentation

◆ durationMs

◆ easing

◆ componentProperty

◆ presetsProperty