Chapter 170: Find a Nested Label's Time (Helper)

Core Idea

Labels only exist within the timeline they were added to, so a parent timeline can't seek() directly to a label defined inside a nested child timeline. This helper walks the child hierarchy to translate a nested label into the parent's own time coordinate.

Key Concepts

• Searches all descendant timelines/tweens for the given label, then walks back up through each ancestor's startTime()/timeScale() to convert the nested time into the outer timeline's timescale.
• Typical usage: tl.seek(getNestedLabelTime(tl, "someNestedLabel")).

Code Examples

function getNestedLabelTime(timeline, label) {
  let children = timeline.getChildren(true, false, true), i = children.length, tl, time;
  while (i--) {
    if (label in children[i].labels) {
      tl = children[i];
      time = tl.labels[label];
      break;
    }
  }
  if (tl) {
    while (tl !== timeline) {
      time = tl.startTime() + time / tl.timeScale();
      tl = tl.parent;
    }
  }
  return time;
}

Key Takeaways

1. Needed only for labels inside a nested timeline — labels on the timeline you're calling seek() on work with no helper.

Connects To

• Timeline.addLabel(), Timeline.seek(): the core APIs this helper bridges across nesting.