Animate between two Float
values. For examples and general usage, see the README.
Animators have to keep track of different sorts of numbers. All of these are Float
s 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.
Basics.Float
A type alias for the difference between two Clock
times.
Basics.Float
A type alias for amount of time (milliseconds) passed since page load.
An Animation is an opaque type that represents a time-varying number (floating point value).
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.
animate : Clock -> Animation -> Value
Produce the value of an animation at a given time.
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 : Basics.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 : (Basics.Float -> Basics.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
.
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.
equals : Animation -> Animation -> Basics.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
isScheduled : Clock -> Animation -> Basics.Bool
Determine if an animation is scheduled, meaning that it has not yet changed value.
isRunning : Clock -> Animation -> Basics.Bool
Determine if an animation is running, meaning that it is currently changing value.
Static animations are never running.
isDone : Clock -> Animation -> Basics.Bool
Determine if an animation is done, meaning that it has arrived at its final value.
Static animations are always done.
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 -> Basics.Float
Get the current velocity of the animation, aproximated by looking 10ms forwards and backwards (the central difference). The velocity may be negative.
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 -> Basics.Float
Get the average speed of the animation.
getDelay : Animation -> TimeDelta
Get the delay of the animation.
getEase : Animation -> Basics.Float -> Basics.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.