API Documentation for: 1.0.0
Show:

Timeline Class

Extends AbstractTween
Defined in: Timeline:42
Module: TweenJS

The Timeline class synchronizes multiple tweens and allows them to be controlled as a group. Please note that if a timeline is looping, the tweens on it may appear to loop even if the "loop" property of the tween is false.

NOTE: Timeline currently also accepts a param list in the form: tweens, labels, props. This is for backwards compatibility only and will be removed in the future. Include tweens and labels as properties on the props object.

Constructor

Timeline

(
  • [props]
)

Defined in Timeline:42

Parameters:

  • [props] Object optional

    The configuration properties to apply to this instance (ex. {loop:-1, paused:true}). Supported props are listed below. These props are set on the corresponding instance properties except where specified.

    • useTicks
    • ignoreGlobalPause
    • loop
    • reversed
    • bounce
    • timeScale
    • paused
    • position: indicates the initial position for this tween.
    • onChange: adds the specified function as a listener to the change event
    • onComplete: adds the specified function as a listener to the complete event

Methods

_dispatchEvent

(
  • eventObj
  • eventPhase
)
protected

Parameters:

_getCurrentLabel

() String protected

Use the currentLabel property instead.

Returns:

String:

The name of the current label or null if there is no label

_getPaused

() protected

Inherited from AbstractTween: _getPaused:244

Use the paused property instead.

_goto

() protected

Inherited from AbstractTween: _goto:490

_init

() protected

Inherited from AbstractTween: _init:472

Shared logic that executes at the end of the subclass constructor.

_runActions

() protected

Inherited from AbstractTween: _runActions:499

_setPaused

(
  • [value=true]
)
AbstractTween protected chainable

Inherited from AbstractTween: _setPaused:230

Use the paused property instead.

Parameters:

  • [value=true] Boolean optional

    Indicates whether the tween should be paused (true) or played (false).

Returns:

AbstractTween:

This tween instance (for chaining calls)

_updatePosition

() protected

addEventListener

(
  • type
  • listener
  • [useCapture]
)
Function | Object

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.

Example

 displayObject.addEventListener("click", handleClick);
 function handleClick(event) {
    // Click happened.
 }

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function | Object:

Returns the listener for chaining or assignment.

addLabel

(
  • label
  • position
)

Inherited from AbstractTween: addLabel:402

Adds a label that can be used with Timeline/gotoAndPlay/Timeline/gotoAndStop.

Parameters:

  • label String

    The label name.

  • position Number

    The position this label represents.

addTween

(
  • ...tween
)
Tween

Defined in addTween:105

Adds one or more tweens (or timelines) to this timeline. The tweens will be paused (to remove them from the normal ticking system) and managed by this timeline. Adding a tween to multiple timelines will result in unexpected behaviour.

Parameters:

  • ...tween Tween

    The tween(s) to add. Accepts multiple arguments.

Returns:

Tween:

The first tween that was passed in.

advance

(
  • delta
  • [ignoreActions=false]
)

Inherited from AbstractTween: advance:297

Advances the tween by a specified amount.

Parameters:

  • delta Number

    The amount to advance in milliseconds (or ticks if useTicks is true). Negative values are supported.

  • [ignoreActions=false] Number optional

    If true, actions will not be executed due to this change in position.

calculatePosition

(
  • rawPosition
)

Calculates a normalized position based on a raw position. For example, given a tween with a duration of 3000ms set to loop: console.log(myTween.calculatePosition(3700); // 700

Parameters:

  • rawPosition Number

    A raw position.

clone

() protected

Inherited from AbstractTween but overwritten in clone:184

dispatchEvent

(
  • eventObj
  • [bubbles]
  • [cancelable]
)
Boolean

Dispatches the specified event to all listeners.

Example

 // Use a string event
 this.dispatchEvent("complete");

 // Use an Event instance
 var event = new createjs.Event("progress");
 this.dispatchEvent(event);

Parameters:

  • eventObj Object | String | Event

    An object with a "type" property, or a string type. While a generic object will work, it is recommended to use a CreateJS Event instance. If a string is used, dispatchEvent will construct an Event instance if necessary with the specified type. This latter approach can be used to avoid event object instantiation for non-bubbling events that may not have any listeners.

  • [bubbles] Boolean optional

    Specifies the bubbles value when a string was passed to eventObj.

  • [cancelable] Boolean optional

    Specifies the cancelable value when a string was passed to eventObj.

Returns:

Boolean:

Returns false if preventDefault() was called on a cancelable event, true otherwise.

getLabels

() ArrayObject

Inherited from AbstractTween: getLabels:372

Returns a list of the labels defined on this tween sorted by position.

Returns:

ArrayObject:

A sorted array of objects with label and position properties.

gotoAndPlay

(
  • positionOrLabel
)

Inherited from AbstractTween: gotoAndPlay:418

Unpauses this timeline and jumps to the specified position or label.

Parameters:

  • positionOrLabel String | Number

    The position in milliseconds (or ticks if useTicks is true) or label to jump to.

gotoAndStop

(
  • positionOrLabel
)

Inherited from AbstractTween: gotoAndStop:429

Pauses this timeline and jumps to the specified position or label.

Parameters:

  • positionOrLabel String | Number

    The position in milliseconds (or ticks if useTicks is true) or label to jump to.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean:

Returns true if there is at least one listener for the specified event.

off

(
  • type
  • listener
  • [useCapture]
)

Inherited from EventDispatcher: off:249

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.

IMPORTANT: To remove a listener added with on, you must pass in the returned wrapper function as the listener. See on for an example.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

on

(
  • type
  • listener
  • [scope]
  • [once=false]
  • [data]
  • [useCapture=false]
)
Function

Inherited from EventDispatcher: on:173

A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener.

This method works by creating an anonymous wrapper function and subscribing it with addEventListener. The wrapper function is returned for use with removeEventListener (or off).

IMPORTANT: To remove a listener added with on, you must pass in the returned wrapper function as the listener, or use remove. Likewise, each time you call on a NEW wrapper function is subscribed, so multiple calls to on with the same params will create multiple listeners.

Example

    var listener = myBtn.on("click", handleClick, null, false, {count:3});
    function handleClick(evt, data) {
        data.count -= 1;
        console.log(this == myBtn); // true - scope defaults to the dispatcher
        if (data.count == 0) {
            alert("clicked 3 times!");
            myBtn.off("click", listener);
            // alternately: evt.remove();
        }
    }

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

  • [scope] Object optional

    The scope to execute the listener in. Defaults to the dispatcher/currentTarget for function listeners, and to the listener itself for object listeners (ie. using handleEvent).

  • [once=false] Boolean optional

    If true, the listener will remove itself after the first time it is triggered.

  • [data] optional

    Arbitrary data that will be included as the second parameter when the listener is called.

  • [useCapture=false] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function:

Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.

removeAllEventListeners

(
  • [type]
)

Removes all listeners for the specified type, or all listeners of all types.

Example

 // Remove all listeners
 displayObject.removeAllEventListeners();

 // Remove all click listeners
 displayObject.removeAllEventListeners("click");

Parameters:

  • [type] String optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeEventListener

(
  • type
  • listener
  • [useCapture]
)

Removes the specified event listener.

Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.

Example

 displayObject.removeEventListener("click", handleClick);

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

removeTween

(
  • ...tween
)

Defined in removeTween:133

Removes one or more tweens from this timeline.

Parameters:

  • ...tween Tween

    The tween(s) to remove. Accepts multiple arguments.

Returns:

Boolean Returns true if all of the tweens were successfully removed.

resolve

(
  • positionOrLabel
)

Inherited from AbstractTween: resolve:440

If a numeric position is passed, it is returned unchanged. If a string is passed, the position of the corresponding frame label will be returned, or null if a matching label is not defined.

Parameters:

  • positionOrLabel String | Number

    A numeric position value or label string.

setLabels

(
  • labels
)

Inherited from AbstractTween: setLabels:391

Defines labels for use with gotoAndPlay/Stop. Overwrites any previously set labels.

Parameters:

  • labels Object

    An object defining labels for using Timeline/gotoAndPlay/Timeline/gotoAndStop in the form {myLabelName:time} where time is in milliseconds (or ticks if useTicks is true).

setPosition

(
  • rawPosition
  • [ignoreActions=false]
  • [jump=false]
  • [callback]
)

Inherited from AbstractTween: setPosition:307

Advances the tween to a specified position.

Parameters:

  • rawPosition Number

    The raw position to seek to in milliseconds (or ticks if useTicks is true).

  • [ignoreActions=false] Boolean optional

    If true, do not run any actions that would be triggered by this operation.

  • [jump=false] Boolean optional

    If true, only actions at the new position will be run. If false, actions between the old and new position are run.

  • [callback] Function optional

    Primarily for use with MovieClip, this callback is called after properties are updated, but before actions are run.

toString

() String

Inherited from EventDispatcher but overwritten in toString:175

Returns a string representation of this object.

Returns:

String:

a string representation of the instance.

updateDuration

()

Defined in updateDuration:160

Recalculates the duration of the timeline. The duration is automatically updated when tweens are added or removed, but this method is useful if you modify a tween after it was added to the timeline.

willTrigger

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type on this object or any of its ancestors (parent, parent's parent, etc). A return value of true indicates that if a bubbling event of the specified type is dispatched from this object, it will trigger at least one listener.

This is similar to hasEventListener, but it searches the entire event flow for a listener, not just this object.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean:

Returns true if there is at least one listener for the specified event.

Properties

_captureListeners

Object protected

_labelList

ArrayObject protected

Inherited from AbstractTween: _labelList:192

_labels

Object protected

Inherited from AbstractTween: _labels:185

_listeners

Object protected

Inherited from EventDispatcher: _listeners:99

_next

Tween protected

Inherited from AbstractTween: _next:161

Default: null

_parent

Object protected

Inherited from AbstractTween: _parent:177

Default: null

_paused

Boolean protected

Inherited from AbstractTween: _paused:153

Default: false

_prev

Tween protected

Inherited from AbstractTween: _prev:169

Default: null

bounce

Boolean

Inherited from AbstractTween: bounce:102

Causes the tween to reverse direction at the end of each loop. Each single-direction play-through of the tween counts as a single bounce. For example, to play a tween once forward, and once back, set the loop to 1.

Default: false

currentLabel

String readonly

Returns the name of the label on or immediately before the current position. For example, given a tween with two labels, "first" on frame index 4, and "second" on frame 8, currentLabel would return:

  • null if the current position is 2.
  • "first" if the current position is 4.
  • "first" if the current position is 7.
  • "second" if the current position is 15.

duration

Number readonly

Inherited from AbstractTween: duration:121

Indicates the duration of this tween in milliseconds (or ticks if useTicks is true), irrespective of loops. This value is automatically updated as you modify the tween. Changing it directly could result in unexpected behaviour.

Default: 0

ignoreGlobalPause

Boolean

Causes this tween to continue playing when a global pause is active. For example, if TweenJS is using Ticker, then setting this to false (the default) will cause this tween to be paused when Ticker.paused is set to true. See the tick method for more info. Can be set via the props parameter.

Default: false

loop

Number

Inherited from AbstractTween: loop:73

Indicates the number of times to loop. If set to -1, the tween will loop continuously.

Note that a tween must loop at least once to see it play in both directions when bounce is set to true.

Default: 0

paused

Boolean

Inherited from AbstractTween: paused:268

Pauses or unpauses the tween. A paused tween is removed from the global registry and is eligible for garbage collection if no other references to it exist.

position

Object readonly

Inherited from AbstractTween: position:132

The current normalized position of the tween. This will always be a value between 0 and duration. Changing this property directly will have unexpected results, use Tween/setPosition.

Default: 0

rawPosition

Number readonly

Inherited from AbstractTween: rawPosition:142

The raw tween position. This value will be between 0 and loops * duration while the tween is active, or -1 before it activates.

Default: -1

reversed

Boolean

Inherited from AbstractTween: reversed:94

Causes the tween to play in reverse.

Default: false

timeScale

Number

Inherited from AbstractTween: timeScale:112

Changes the rate at which the tween advances. For example, a timeScale value of 2 will double the playback speed, a value of 0.5 would halve it.

Default: 1

tweens

Array

Defined in tweens:82

The array of tweens in the timeline. It is strongly recommended that you use Tween/addTween and Tween/removeTween, rather than accessing this directly, but it is included for advanced uses.

useTicks

Boolean readonly

Inherited from AbstractTween: useTicks:84

Uses ticks for all durations instead of milliseconds. This also changes the behaviour of some actions (such as call). Changing this value on a running tween could have unexpected results.

Default: false

Events

change

Inherited from AbstractTween: change:216

Dispatched whenever the tween's position changes. It occurs after all tweened properties are updated and actions are executed.

complete

Inherited from AbstractTween: complete:222

Dispatched when the tween reaches its end and has paused itself. This does not fire until all loops are complete; tweens that loop continuously will never fire a complete event.