buildrtech / elm-animator-with-elm-css / Animator.Timeline

Getting started


type alias Timeline state =
Internal.Timeline.Timeline state

A timeline of state values.

Behind the scenes this is roughly a list of states and the times that they should occur!

init : state -> Timeline state

Create a timeline with an initial state.

So, if you previously had a Bool in your model:

type alias Model = { checked : Bool }

-- created via
{ checked = False }

You could replace that with an Animator.Timeline Bool

type alias Model = { checked : Animator.Timeline Bool }

-- created via
{ checked = Animator.init False }

Transitioning to a new state

Now that we have a Timeline set up, we likely want to set a new value.

In order to do that we need to specify both —

to : Duration -> state -> Timeline state -> Timeline state

Go to a new state!

update : Time.Posix -> Timeline state -> Timeline state

If you're creating something like a game, you might want to update your Timelines manually instead of using an Animator.

This will allow you to do whatever calculations you need while updating each Timeline.

Note — You'll have to take care of subscribing to Browser.Events.onAnimationFrame.

isRunning : Timeline state -> Basics.Bool

Does this timeline have upcoming events?

Note this is only useful if you're not using a Animator.Watcher

Interruptions and Queueing

In some more advanced cases you might want to define a series of states to animate through instead of just going to one directly.

Timeline.interrupt
    [ Timeline.wait (Timeline.millis 300)

    -- after waiting 300 milliseconds,
    -- start transitioning to a new state, Griffyndor
    -- Take 1 whole second to make the transition
    , Timeline.transitionTo (Timeline.seconds 1) Griffyndor

    -- Once we've arrived at Griffyndor,
    -- immediately start transitioning to Slytherin
    -- and take half a second to make the transition
    , Timeline.transitionTo (Timeline.seconds 0.5) Slytherin
    ]

interrupt : List (Step state) -> Timeline state -> Timeline state

Interrupt what's currently happening with a new list.

queue : List (Step state) -> Timeline state -> Timeline state

Wait until the current timeline is finished and then continue with these new steps.


type Step state

wait : Duration -> Step state

transitionTo : Duration -> state -> Step state

scale : Basics.Float -> Timeline state -> Timeline state

Scale timeline durations.

0.5 -> Animations take half as much time
1.0 -> normal
2.0 -> Animations take twice as long

Note - 0.1 is the lowest number allowed, and 5 is the highest.

This is generally used in your view function to add a bit of variety when animating multiple elements.

delay : Duration -> Timeline state -> Timeline state

Delay the events of a timeline.

This is generally used in your view function to add a bit of variety when animating multiple elements.

    Animator.move (Animator.delay (Animator.millis 200) timeline) <|
        \state ->
            if state then
                Animator.at 0

            else
                Animator.at 1

This has a maximum value of 5 seconds.

If you need a longer delay, it's likely you want to create a separate timeline.

Reading the timeline

You might be wondering, 'How do we get our value "out" of a Timeline?'

Well, we can ask the Timeline all sorts of questions.

current : Timeline state -> state

Get the current state of the timeline.

This value will switch to a new value when a transition begins.

If you had a timeline that went from A to B to C, here's what current would be at various points on the timeline.

          A---------B---------C
               ^    ^    ^    ^
current:       B    B    C    C

Note — If you want to detect the moment when you arrive at a new state, try using arrivedAt

previous : Timeline state -> state

Get the previous state on this timeline.

As you'll see in the Loading example, it means we can use previous to refer to data that we've already "deleted" or set to Nothing.

How cool!

          A---------B---------C
               ^    ^    ^
previous:      A    A    B

upcoming : state -> Timeline state -> Basics.Bool

Check to see if a state is upcoming on a timeline.

Note — This can be used to ensure a set of states can only be queued if they aren't already running.

Note 2 — This only checks if an event is in the future, but does not check the value you're currently at. You might need to use arrived as well if you also care about the current state.

upcomingWith : (state -> Basics.Bool) -> Timeline state -> Basics.Bool

For complicated values it can be computationally expensive to use ==.

upcomingWith allows you to specify your own equality function, so you can be smarter in checking how two value are equal.

arrived : Timeline state -> state

Subtley different than current, this will provide the new state as soon as the transition has finished.

          A---------B---------C
               ^    ^    ^    ^
arrived:       A    B    B    C

arrivedAt : state -> Time.Posix -> Timeline state -> Basics.Bool

Sometimes we want to know when we've arrived at a state so we can trigger some other work.

You can use arrivedAt in the Tick branch of your update to see if you will arrive at an event on this tick.

Tick time ->
    if Animator.arrivedAt MyState time model.timeline then
        --...do something special

arrivedAtWith : (state -> Basics.Bool) -> Time.Posix -> Timeline state -> Basics.Bool

Again, sometimes you'll want to supply your own equality function!