Class AnimTimeline

Index

Structure

Methods that relate to building the timeline or locating sequences within it.

numSequences root addSequences addSequencesAt findSequenceIndex removeSequences removeSequencesAt

Properties

Property Getter Methods

Methods that return objects that contain various internal fields of the timeline (such as isPaused from getStatus()).

getConfig getStatus getTiming

Playback Methods

Methods that control the playback of the animation timeline.

finishInProgressSequences jumpToPosition jumpToSequenceTag pause setPlaybackRate step togglePause toggleSkipping turnSkippingOff turnSkippingOn unpause

Structure

numSequences

get numSequences(): number
Number of sequences in this timeline.

Returns number
- Defined in src/1_playbackStructures/AnimationTimeline.ts:197

root

get root(): AnimTimeline
The highest level of this timeline's lineage.
- The timeline itself (there is currently no higher possible level)
Returns AnimTimeline
- Defined in src/1_playbackStructures/AnimationTimeline.ts:191

addSequences

addSequences(...animSequences): this
Adds one or more AnimSequence objects to the end of the timeline.
Parameters
- Rest...animSequences: AnimSequence[]
  comma-separated list of animation sequences
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:565

addSequencesAt

addSequencesAt(index, ...animSequences): this
Adds one or more AnimSequence objects to the specified index of the sequence.
Parameters
- index: number
  the index at which the sequences should be inserted
- Rest...animSequences: AnimSequence[]
  comma-separated list of animation sequences
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:596

findSequenceIndex

findSequenceIndex(animSequence): number
Finds the index of a given AnimSequence object within the timeline
Parameters
- animSequence: AnimSequence
  the animation sequence to search for within the timeline
Returns number
the index of animSequence within the timeline or -1 if the sequence is not part of the timeline.
- Defined in src/1_playbackStructures/AnimationTimeline.ts:713

removeSequences

removeSequences(...animSequences): this
Removes one or more AnimSequence objects from the timeline.
Parameters
- Rest...animSequences: AnimSequence[]
  comma-separated list of animation sequences
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:639

removeSequencesAt

removeSequencesAt(startIndex, endIndex?): AnimSequence[]
Removes a number of AnimSequence objects from the timeline based on the provided indices range (0-based).
Parameters
- startIndex: number
  the starting index, inclusive
- endIndex: number = ...
  the ending index, exclusive
Returns AnimSequence[]
an array containing the sequences that were removed from the timeline.
- Defined in src/1_playbackStructures/AnimationTimeline.ts:680

Properties

`Protected`generateError

generateError: TimelineErrorGenerator = ...

`Readonly`id

id: number

Number that uniquely identifies the timeline from other timelines. Automatically generated.

Property Getter Methods

getConfig

getConfig(): AnimTimelineConfig
Returns an object containing the configuration options used to define the name, debugging behavior, and button-linking behavior of the timeline.

Returns AnimTimelineConfig
an object containing
- autoLinksButtons,
- debugMode,
- timelineName,
- Defined in src/1_playbackStructures/AnimationTimeline.ts:173

getStatus

getStatus(): AnimTimelineStatus
Returns details about an timeline's current status.

Returns AnimTimelineStatus
an object containing
- isAnimating,
- isPaused,
- skippingOn,
- currentDirection,
- isJumping,
- stepNumber,
- atBeginning,
- atEnd,
- Defined in src/1_playbackStructures/AnimationTimeline.ts:229

getTiming

getTiming(): AnimTimelineTiming
Returns timing-related details about the timeline.

Returns AnimTimelineTiming
an object containing
- AnimTimelineStatus.playbackRate|playbackRate,
- Defined in src/1_playbackStructures/AnimationTimeline.ts:273

Playback Methods

finishInProgressSequences

finishInProgressSequences(): Promise<AnimTimeline>
Forces the animation sequences that are currently running within the timeline to instantly finish.
- After the currently running animation sequences complete, the rest of the timeline runs normally.
- The timeline will still pause for any roadblocks generated by AnimClip.addRoadblocks.
- (Currently, only 1 sequence can play at a time in a timeline, so by "sequences", we just mean "sequence").
Returns Promise<AnimTimeline>
- Defined in src/1_playbackStructures/AnimationTimeline.ts:1292

jumpToPosition

jumpToPosition(position, options?): Promise<AnimTimeline>
Jumps instantly to the position within the timeline based on the position argument.
Parameters
- position: number | "end" | "beginning"
  the target position within the timeline
- options: {
  autoplayDetection?: "none" | "forward" | "backward";
  targetOffset?: number;
  } = {}
  set of options defining the offset of the jump and whether to consider autoplay
  - OptionalautoplayDetection?: "none" | "forward" | "backward"
    determines how the timeline should handle sequences set to autoplay once the jump destination (after considering options.targetOffset) has been reached
    
    if 'none', the timeline stays at the final landing position after the initial jumping operation.
    
    if 'forward', the timeline will jump forward for as long as the next sequence is supposed to autoplay after the current sequence.
    
    if 'backward', the timeline will jump backward for as long as the previous sequence as long as the previous sequence is supposed to automatically rewind after the current sequence is rewound (this is naturally only true when the current sequence is set to autoplay when the timeline steps forward).
    Default Value
    'none'
  - OptionaltargetOffset?: number
    offset that adds to the initial landing position
Returns Promise<AnimTimeline>
a Promise that resolves when the timeline has finished jumping.
- Defined in src/1_playbackStructures/AnimationTimeline.ts:1021

jumpToSequenceTag

jumpToSequenceTag(jumpTag, options?): Promise<AnimTimeline>

Jumps instantly to the sequence whose AnimSequence.getJumpTag() value matches the jumpTag argument.

Parameters

jumpTag: string | RegExp
string that is used to search for the target sequence with the matching AnimSequence.getJumpTag() value
options: {
    autoplayDetection?: "none" | "forward" | "backward";
    search?:
        | "forward"
        | "backward"
        | "forward-from-beginning"
        | "backward-from-end";
    searchOffset?: number;
    targetOffset?: number;
} = {}
set of options defining the behavior of the search, the offset of the jump, and whether to consider autoplay
- OptionalautoplayDetection?: "none" | "forward" | "backward"
  determines how the timeline should handle sequences set to autoplay once the jump destination (after considering options.targetOffset) has been reached
  - if 'none', the timeline stays at the final landing position after the initial jumping operation.
  - if 'forward', the timeline will jump forward for as long as the next sequence is supposed to autoplay after the current sequence.
  - if 'backward', the timeline will jump backward for as long as the previous sequence is supposed to automatically rewind after the current sequence is rewound (this is naturally only true when the current sequence is set to autoplay when the timeline steps forward).
  Default Value
```
'none'
```
- Optionalsearch?:
      | "forward"
      | "backward"
      | "forward-from-beginning"
      | "backward-from-end"
  the direction and/or the starting point of the search
  Default Value
```
'forward-from-beginning'
```
- OptionalsearchOffset?: number
  offset that changes the starting point of the search by the indicated amount
- OptionaltargetOffset?: number
  offset that adds to the initial landing position

Returns Promise<AnimTimeline>

a Promise that resolves when the timeline has finished jumping.

Example

const {Entrance, Motion, Exit} = webimator.createAnimationClipFactories();
const square = document.querySelector('.square');

const tLine = webimator.newTimeline(
  webimator.newSequence(
    {jumpTag: 'flickering'},
    Entrance(square, '~appear', [], {endDelay: 500}),
    Exit(square, '~disappear', [], {endDelay: 500}),
    Entrance(square, '~appear', [], {endDelay: 500}),
    Exit(square, '~disappear', [], {endDelay: 500}),
    Entrance(square, '~appear', [], {endDelay: 500}),
    Exit(square, '~disappear', [], {endDelay: 500}),
  ),

  webimator.newSequence(
    {jumpTag: 'move around'},
    Motion(square, '~translate', [{translate: '200px, 0px'}]),
    Motion(square, '~translate', [{translate: '0px, 200px'}]),
    Motion(square, '~translate', [{translate: '-200px, 0px'}]),
    Motion(square, '~translate', [{translate: '0px, -200px'}]),
  ),

  webimator.newSequence(
    {jumpTag: 'go away', autoplays: true},
    Exit(square, '~pinwheel', []),
  )
);

// Promise-based timer
async function wait(milliseconds: number) {
  return new Promise(resolve => setTimeout(resolve, milliseconds));
}

(async () => {
  // jump straight to sequence with tag "move around"
  await tLine.jumpToSequenceTag('move around');

  await wait (1000); // wait 1 second

  // jump to sequence whose tag contains "flick"
  // (so now we're back at the beginning of the timeline)
  await tLine.jumpToSequenceTag(/flick/);

  await wait (1000); // wait 1 second

  // jump to sequence with tag "move around"
  // then look forward to see if any sequences have {autoplays: true}
  // the next one does, so it continues, skipping to the third sequence
  await tLine.jumpToSequenceTag('move around', {autoplayDetection: 'forward'});

  await wait (1000); // wait 1 second

  // play the last sequence
  await tLine.step('forward');
})();

pause

pause(): this
Pauses the animation timeline.
- If the timeline is not already in progress, it will still be paused, preventing playback until unpaused.
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:877

setPlaybackRate

setPlaybackRate(rate): this
Sets the base playback rate of the timeline.
Parameters
- rate: number
  the new playback rate
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:727

step

step(direction): Promise<AnimTimeline>
Takes 1 step in the specified direction.
- If any sequences are set to autoplay, the timeline automatically continues stepping through them.
Parameters
- direction: "forward" | "backward"
  the direction in which the timeline should step
Returns Promise<AnimTimeline>
a Promise that resolves when the timeline has finished stepping.
- Defined in src/1_playbackStructures/AnimationTimeline.ts:745

togglePause

togglePause(options?): this
Pauses the animation timeline if it is unpaused or unpauses it if it is currently paused.
Parameters
- options: {
  forceState?: "pause" | "unpause";
  } = {}
  options for the bevior of the toggle
  - OptionalforceState?: "pause" | "unpause"
    Explicitly instructs the method to either pause (equivalent to pause()) or unpause (equivalent to unpause())
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:840

toggleSkipping

toggleSkipping(options?): Promise<AnimTimeline>
Turns on skipping if it is currently off or turns it off if it is currently on.
Parameters
- options: {
  forceState?: "off" | "on";
  } = {}
  options defining the behavior of the toggle
  - OptionalforceState?: "off" | "on"
    Explicitly instructs the method to either turn skipping on (equivalent to turnSkippingOn()) or turn skipping off (equivalent to turnSkippingOff())
Returns Promise<AnimTimeline>
See
turnSkippingOn()
- Defined in src/1_playbackStructures/AnimationTimeline.ts:1224

turnSkippingOff

turnSkippingOff(): this
Turns off the skipping effect.

Returns this
See
turnSkippingOff()
- Defined in src/1_playbackStructures/AnimationTimeline.ts:1275

turnSkippingOn

turnSkippingOn(): Promise<AnimTimeline>
Makes it so that any sequence that is played is finished instantly.
- The timeline will still pause for any roadblocks generated by AnimClip.addRoadblocks.
Returns Promise<AnimTimeline>
- Defined in src/1_playbackStructures/AnimationTimeline.ts:1259

unpause

unpause(): this
Unpauses the animation timeline.
- If the timeline is not currently paused, this method does nothing.
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:892

Configuration

getConfig

getConfig(): AnimTimelineConfig
Returns an object containing the configuration options used to define the name, debugging behavior, and button-linking behavior of the timeline.

Returns AnimTimelineConfig
an object containing
- autoLinksButtons,
- debugMode,
- timelineName,
- Defined in src/1_playbackStructures/AnimationTimeline.ts:173

Methods

`Protected`generateLockedStructureError

generateLockedStructureError(methodName): LockedOperationError
Parameters
- methodName: string
Returns LockedOperationError
- Defined in src/1_playbackStructures/AnimationTimeline.ts:1322

Playback UI

playbackButtons

get playbackButtons(): Readonly<PlaybackButtons>
Object containing properties that are either references to <wbmtr-playback-button> elements that are connected to this timeline or null.
- A property being null indicates that there is currently no corresponding button on the page that is linked to this timeline.
Returns Readonly<PlaybackButtons>
- Defined in src/1_playbackStructures/AnimationTimeline.ts:343

disablePlaybackButtons

disablePlaybackButtons(): void
Disables this timeline's connection to its playback buttons until re-enabled using enablePlaybackButtons().

Returns void
- Defined in src/1_playbackStructures/AnimationTimeline.ts:542

enablePlaybackButtons

enablePlaybackButtons(): void
Allows this timeline's linked playback buttons to trigger (and be triggered by) this timeline's playback methods.
- This method is only useful if the buttons were previously disabled using disablePlaybackButtons().
Returns void
- Defined in src/1_playbackStructures/AnimationTimeline.ts:552

linkPlaybackButtons

linkPlaybackButtons(options?): this
Searches the page for <wbmtr-playback-button> elements whose timeline-name attributes are equivalent to this timeline's timelineName configuration option, then links those buttons to this timeline.
- By default, all button types are searched for.
Parameters
- options: {
  buttonsSubset?: PlaybackButtonPurpose[];
  searchRoot?: HTMLElement;
  } = {}
  Settings to define the behavior of the search
  - OptionalbuttonsSubset?: PlaybackButtonPurpose[]
    Array of strings indicating which specific buttons we want to link. By default, all buttons are searched for
  - OptionalsearchRoot?: HTMLElement
    The HTML element from which to begin searching for the buttons
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:356

Class AnimTimeline

Index

Structure

Properties

Property Getter Methods

Playback Methods

Configuration

Methods

Playback UI

Structure

numSequences

Returns number

root

Returns AnimTimeline

addSequences

Parameters

Returns this

addSequencesAt

Parameters

Returns this

findSequenceIndex

Parameters

Returns number

removeSequences

Parameters

Returns this

removeSequencesAt

Parameters

Returns AnimSequence[]

Properties

ProtectedgenerateError

Readonlyid

Property Getter Methods

getConfig

Returns AnimTimelineConfig

getStatus

Returns AnimTimelineStatus

getTiming

Returns AnimTimelineTiming

Playback Methods

finishInProgressSequences

Returns Promise<AnimTimeline>

jumpToPosition

Parameters

OptionalautoplayDetection?: "none" | "forward" | "backward"

Default Value

OptionaltargetOffset?: number

Returns Promise<AnimTimeline>

jumpToSequenceTag

Parameters

OptionalautoplayDetection?: "none" | "forward" | "backward"

Default Value

Optionalsearch?: | "forward" | "backward" | "forward-from-beginning" | "backward-from-end"

Default Value

OptionalsearchOffset?: number

OptionaltargetOffset?: number

Returns Promise<AnimTimeline>

Example

pause

Returns this

setPlaybackRate

Parameters

Returns this

step

Parameters

Returns Promise<AnimTimeline>

togglePause

Parameters

OptionalforceState?: "pause" | "unpause"

Returns this

toggleSkipping

Parameters

OptionalforceState?: "off" | "on"

Returns Promise<AnimTimeline>

See

turnSkippingOff

Returns this

See

turnSkippingOn

Returns Promise<AnimTimeline>

`Protected`generateError

`Readonly`id

`Optional`autoplayDetection?: "none" | "forward" | "backward"

`Optional`targetOffset?: number

`Optional`autoplayDetection?: "none" | "forward" | "backward"

`Optional`search?:
| "forward"
| "backward"
| "forward-from-beginning"
| "backward-from-end"

`Optional`searchOffset?: number

`Optional`targetOffset?: number

`Optional`forceState?: "pause" | "unpause"

`Optional`forceState?: "off" | "on"

`Protected`generateLockedStructureError

`Optional`buttonsSubset?: PlaybackButtonPurpose[]

`Optional`searchRoot?: HTMLElement