Class AnimTimeline

Index

Structure

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

numSequences root addSequences 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
The number of sequences in this timeline.

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

root

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

addSequences

addSequences(animSequences: AnimSequence[]): this
Adds AnimSequence objects to the end of the timeline.
Parameters
- animSequences: AnimSequence[]
  An array of animation sequences to add.
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:584
addSequences(location: AddSequencesOptions, animSequences: AnimSequence[]): this
Adds AnimSequence objects to the specified location within the timeline.
Parameters
- location: AddSequencesOptions
  Object containing options specifying the location at which the sequences should be inserted.
- animSequences: AnimSequence[]
  An array of animation sequences to add.
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:592

findSequenceIndex

findSequenceIndex(animSequence: 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:714

removeSequences

removeSequences(animSequences: AnimSequence[]): this
Removes specified AnimSequence objects from the timeline.
Parameters
- animSequences: AnimSequence[]
  An array of animation sequences to remove.
Returns this
- Defined in src/1_playbackStructures/AnimationTimeline.ts:638

removeSequencesAt

removeSequencesAt(startIndex: number, endIndex?: number): 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 (if not specified, startIndex + 1 is used, removing one sequence).
Returns AnimSequence[]
An array containing the sequences that were removed from the timeline.
- Defined in src/1_playbackStructures/AnimationTimeline.ts:681

Properties

`Protected`generateError

generateError: TimelineErrorGenerator = ...

`Readonly`id

id: number

A 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:186

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:242

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:286

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 scheduleTask generated by AnimClip.scheduleTask.
- (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:1298

jumpToPosition

jumpToPosition(
    position: number | "end" | "beginning",
    options?: {
        autoplayDetection?: "none" | "forward" | "backward";
        targetOffset?: number;
    },
): 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 } = {}
  An options object 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
    An 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:1027

jumpToSequenceTag

jumpToSequenceTag(
    jumpTag: string | RegExp,
    options?: {
        autoplayDetection?: "none" | "forward" | "backward";
        search?:
            | "forward"
            | "backward"
            | "forward-from-beginning"
            | "backward-from-end";
        searchOffset?: number;
        targetOffset?: number;
    },
): Promise<AnimTimeline>

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

Parameters

jumpTag: string | RegExp
The 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;
} = {}
An options object 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
  An offset that changes the starting point of the search by the indicated amount.
- OptionaltargetOffset?: number
  An 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} = webchalk.createAnimationClipFactories();
const square = document.querySelector('.square');

const tLine = webchalk.newTimeline(
  [
    webchalk.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}),
      ]
    ),

    webchalk.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'}]),
      ]
    ),

    webchalk.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: number): 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:728

step

step(direction: "forward" | "backward"): 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?: { forceState?: "pause" | "unpause" }): this
Pauses the animation timeline if it is unpaused or unpauses it if it is currently paused.
Parameters
- options: { forceState?: "pause" | "unpause" } = {}
  An options object specifying the behavior 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?: { forceState?: "off" | "on" }): Promise<AnimTimeline>
Turns on skipping if it is currently off or turns it off if it is currently on.
Parameters
- options: { forceState?: "off" | "on" } = {}
  An options object 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:1230

turnSkippingOff

turnSkippingOff(): this
Turns off the skipping effect.

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

turnSkippingOn

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

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:186

Methods

`Protected`generateLockedStructureError

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

Playback UI

playbackButtons

get playbackButtons(): Readonly<PlaybackButtons>
Object containing properties that are either references to <webchalk-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:362

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:561

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:571

linkPlaybackButtons

linkPlaybackButtons(
    options?: {
        buttonsSubset?: PlaybackButtonPurpose[];
        searchRoot?: HTMLElement;
    },
): this
Searches the page for <webchalk-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 } = {}
  An object containing settings to define the behavior of the search
  - OptionalbuttonsSubset?: PlaybackButtonPurpose[]
    An 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:375

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

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>

unpause

`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