Animation

Animate between two Float values. For examples and general usage, see the README.

Types

Animators have to keep track of different sorts of numbers. All of these are Floats under the hood, so they exist to clarify documentation. Be warned that the compiler won't help you keep them straight.

Clock refers to a point in time, identified by duration since an epoch. For our purposes, the epoch is typically page load. (Why not use the UNIX epoch? Sometimes we have to take the sine of the clock and that's expensive for large numbers.) You are responsible for maintaining the clock and passing it in as necessary, most notably to run and create animations.
TimeDelta refers to the difference between two Clock times, such as a duration or a delay.
Value refers to the value being animated. It's used to indicate the output of the animation, as well as the initial from and final to values.
A plain Float refers to the speed at which the Value changes.

type alias TimeDelta =

Float

A type alias for the difference between two Clock times.

type alias Clock =

Float

A type alias for amount of time (milliseconds) passed since page load.

type Animation

An Animation is an opaque type that represents a time-varying number (floating point value).

Create

animation : Clock -> Animation

Create an animation that begins at the given time. By default, animations have no delay, last 750ms, and interpolate between 0 and 1 with a sinusoidal easing function. All of these can be changed.

static : Value -> Animation

Create a static animation that is always the given value.

Run

animate : Clock -> Animation -> Value

Produce the value of an animation at a given time.

Modify

Settings

You may set an animation's duration or speed but not both, since one determines the other.

duration : TimeDelta -> Animation -> Animation

Set the duration of an animation to the time specified.

speed : Float -> Animation -> Animation

Set the average speed of an animation. Speed is the rate at which the animation progresses between the from and to values per milisecond. Most easing functions will deviate from the average speed. You do not need to worry about the sign. It is safe to alter the from and to values after setting speed.

delay : TimeDelta -> Animation -> Animation

Set the delay of an animation to the time specified. An animation will not start until after the delay. The default delay is 0.

ease : (Float -> Float) -> Animation -> Animation

Set the easing function of an animation. It is expected that f 0 == 0 and f 1 == 1. The default is a sinusoidal in-out.

from : Value -> Animation -> Animation

Set the initial value of an animation. The default is 0.

to : Value -> Animation -> Animation

Set the final value of an animation. The default is 1.

For animations that are already running, use retarget.

Interruptions

undo : Clock -> Animation -> Animation

Run an animation in reverse from its current state, beginning immediately (even if the animation was delayed or has been done for a while).

Usually you don't want to undo an animation that has been retargeted; just retarget it again. Similarly, undoing an undone animation is frequently not what you want.

retarget : Clock -> Value -> Animation -> Animation

Change the to value of a running animation, without an abrupt change in velocity. The easing function will be retained (but you can change it with ease). The animation will retain its average speed (but not necessarily duration). If you retarget multiple animations at once (e.g. x and y), you will need to sync their durations (perhaps to the timeRemaining in the old animations).

If the retargeted animation is still scheduled, the to value is replaced. If it's already done, from becomes the old to, to and start are set to the values provided, and the delay is set to zero. If the old and new to values are the same, the animation is unchanged.

Inspect

Equality

equals : Animation -> Animation -> Bool

Equality on animations. Compared to (==) (which should not be used), this function handles the conversion of speed and duration, and start and delay. It also samples the easing functions, which may produce false positives (but usually not in practice).

equals (animation 0) (animation 0) --> True
equals (animation 0 |> delay 10) (animation 10) --> True
equals (animation 0 |> duration 1000) (animation 0 |> speed 0.001) --> True


equals (static 0) (animation 0) --> False
equals (animation 0 |> from -1) (animation 0) --> False
equals (animation 0 |> ease identity) (animation 0) --> False

Lifecycle

isScheduled : Clock -> Animation -> Bool

Determine if an animation is scheduled, meaning that it has not yet changed value.

isRunning : Clock -> Animation -> Bool

Determine if an animation is running, meaning that it is currently changing value.

Static animations are never running.

isDone : Clock -> Animation -> Bool

Determine if an animation is done, meaning that it has arrived at its final value.

Static animations are always done.

Physics

timeElapsed : Clock -> Animation -> TimeDelta

Get the time elapsed since the animation started playing (after the end of delay). Will be zero for animations that are still scheduled, and is not bounded for animations that are already done.

timeRemaining : Clock -> Animation -> TimeDelta

Get the time until the animation is done. This time may be spent animating or be part of the delay. Will be zero for animations that are already done.

getVelocity : Clock -> Animation -> Float

Get the current velocity of the animation, aproximated by looking 10ms forwards and backwards (the central difference). The velocity may be negative.

Settings

getStart : Animation -> Clock

Get the start time of the animation, not accounting for delay. For animations created with animate, this is the argument that was passed. For interrupted animations, this is when the interruption occured.

getDuration : Animation -> TimeDelta

Get the duration of the animation, not counting delay.

getSpeed : Animation -> Float

Get the average speed of the animation.

getDelay : Animation -> TimeDelta

Get the delay of the animation.

getEase : Animation -> Float -> Float

Get the easing function of the animation.

getFrom : Animation -> Value

Get the initial value of the animation.

getTo : Animation -> Value

Get the final value of the animation.