timeline method

Widget timeline({
  1. Object? trigger,
  2. TimelineController? controller,
  3. VoidCallback? onEnd,
  4. int repeat = 0,
})

Compiles the effect/TimelineChainExt.step chain this is called on into a single-controller timeline and plays it on trigger changes.

Unlike animate, every effect in the chain is a keyframe VALUE on a shared timeline — values are absolute and hand off between keyframes, they do not stack.

A trigger is purely an identity signal: any change restarts the timeline from the beginning and plays it forward. It never implies a direction. For directional or positional control — reversing, pausing, seeking, scrubbing — attach a TimelineController instead.

Passing the sentinel #immediate as the trigger plays the timeline as soon as it is mounted — once per State lifetime, since rebuilds do not change the sentinel's identity. Combined with repeat this expresses auto-playing and looping timelines without any imperative code.

Implementation

Widget timeline({
  Object? trigger,
  TimelineController? controller,
  VoidCallback? onEnd,
  int repeat = 0,
}) =>
    TimelineEffect(
      trigger: trigger,
      controller: controller,
      onEnd: onEnd,
      repeat: repeat,
      chain: this,
    );