API Documentation for: 1.0.0
Show:

Tween Class

Extends AbstractTween
Defined in: Tween:76
Module: TweenJS

Tweens properties for a single target. Methods can be chained to create complex animation sequences:

Example

createjs.Tween.get(target)
    .wait(500)
    .to({alpha:0, visible:false}, 1000)
    .call(handleComplete);

Multiple tweens can share a target, however if they affect the same properties there could be unexpected behaviour. To stop all tweens on an object, use removeTweens or pass override:true in the props argument.

createjs.Tween.get(target, {override:true}).to({x:100});

Subscribe to the Tween/change:event event to be notified when the tween position changes.

createjs.Tween.get(target, {override:true}).to({x:100}).addEventListener("change", handleChange);
function handleChange(event) {
    // The tween changed.
}

See the get method also.

Constructor

Tween

(
  • target
  • [props]
)

Defined in Tween:76

Parameters:

  • target Object

    The target object that will have its properties tweened.

  • [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=false] Boolean optional

      See the useTicks property for more information.

    • [ignoreGlobalPause=false] Boolean optional

      See the ignoreGlobalPause for more information.

    • [loop=0] Number | Boolean optional

      See the loop for more information.

    • [reversed=false] Boolean optional

      See the reversed for more information.

    • [bounce=false] Boolean optional

      See the bounce for more information.

    • [timeScale=1] Number optional

      See the timeScale for more information.

    • [pluginData] Object optional

      See the pluginData for more information.

    • [paused=false] Boolean optional

      See the paused for more information.

    • [position=0] Number optional

      The initial position for this tween. See position

    • [onChange] Function optional

      Adds the specified function as a listener to the change event

    • [onComplete] Function optional

      Adds the specified function as a listener to the complete event

    • [override=false] Boolean optional

      Removes all existing tweens for the target when set to true.

Methods

_addAction

(
  • scope
  • funct
  • params
)
protected

Defined in _addAction:809

Parameters:

_addPlugin

(
  • plugin
)
protected

Defined in _addPlugin:621

Adds a plugin to this tween.

Parameters:

_addStep

(
  • duration
  • props
  • ease
  • passive
)
protected

Defined in _addStep:795

Parameters:

_appendProps

(
  • props
  • step
  • stepPlugins
)
protected

Defined in _appendProps:718

Parameters:

_cloneProps

(
  • props
)
protected

Defined in _cloneProps:835

Parameters:

_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.

_injectProp

(
  • name
  • value
)
protected

Defined in _injectProp:781

Used by plugins to inject properties onto the current step. Called from within Plugin.step calls. For example, a plugin dealing with color, could read a hex color, and inject red, green, and blue props into the tween. See the SamplePlugin for more info.

Parameters:

_installPlugin

(
  • plugin
)
protected static

Defined in _installPlugin:402

Installs a plugin, which can modify how certain properties are handled when tweened. See the SamplePlugin for an example of how to write TweenJS plugins. Plugins should generally be installed via their own install method, in order to provide the plugin with an opportunity to configure itself.

Parameters:

  • plugin Object

    The plugin to install

_register

(
  • tween
  • paused
)
protected static

Defined in _register:419

Registers or unregisters a tween with the ticking system.

Parameters:

  • tween Tween

    The tween instance to register or unregister.

  • paused Boolean

    If false, the tween is registered. If true the tween is unregistered.

_runActions

() protected

Inherited from AbstractTween: _runActions:499

_runActionsRange

(
  • startPos
  • endPos
  • jump
  • includeStart
)
protected

Parameters:

_set

(
  • props
)
protected

Defined in _set:824

Parameters:

_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

_updateTargetProps

(
  • step
  • ratio
  • end
)
protected

Parameters:

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.

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.

call

(
  • callback
  • [params]
  • [scope]
)
Tween chainable

Defined in call:522

Adds an action to call the specified function.

Example

//would call myFunction() after 1 second.
createjs.Tween.get().wait(1000).call(myFunction);

Parameters:

  • callback Function

    The function to call.

  • [params] Array optional

    The parameters to call the function with. If this is omitted, then the function will be called with a single param pointing to this tween.

  • [scope] Object optional

    The scope to call the function in. If omitted, it will be called in the target's scope.

Returns:

Tween:

This tween instance (for chaining calls).

clone

() protected

Inherited from AbstractTween but overwritten in clone:611

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.

get

(
  • target
  • [props]
)
Tween static

Defined in get:283

Returns a new tween instance. This is functionally identical to using new Tween(...), but may look cleaner with the chained syntax of TweenJS.

Example

var tween = createjs.Tween.get(target).to({x:100}, 500);
// equivalent to:
var tween = new createjs.Tween(target).to({x:100}, 500);

Parameters:

  • target Object

    The target object that will have its properties tweened.

  • [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=false] Boolean optional

      See the useTicks property for more information.

    • [ignoreGlobalPause=false] Boolean optional

      See the ignoreGlobalPause for more information.

    • [loop=0] Number | Boolean optional

      See the loop for more information.

    • [reversed=false] Boolean optional

      See the reversed for more information.

    • [bounce=false] Boolean optional

      See the bounce for more information.

    • [timeScale=1] Number optional

      See the timeScale for more information.

    • [pluginData] Object optional

      See the pluginData for more information.

    • [paused=false] Boolean optional

      See the paused for more information.

    • [position=0] Number optional

      The initial position for this tween. See position

    • [onChange] Function optional

      Adds the specified function as a listener to the change event

    • [onComplete] Function optional

      Adds the specified function as a listener to the complete event

    • [override=false] Boolean optional

      Removes all existing tweens for the target when set to true.

Returns:

Tween:

A reference to the created tween.

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.

handleEvent

(
  • event
)
private static

Defined in handleEvent:336

Available since 0.4.2

Handle events that result from Tween being used as an event handler. This is included to allow Tween to handle tick events from the createjs Ticker. No other events are handled in Tween.

Parameters:

hasActiveTweens

(
  • [target]
)
Boolean static

Defined in hasActiveTweens:389

Indicates whether there are any active tweens on the target object (if specified) or in general.

Parameters:

  • [target] Object optional

    The target to check for active tweens. If not specified, the return value will indicate if there are any active tweens on any target.

Returns:

Boolean:

Indicates if there are active tweens.

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.

label

(
  • name
)
Tween chainable

Defined in label:501

Adds a label that can be used with Tween/gotoAndPlay/Tween/gotoAndStop at the current point in the tween. For example:

var tween = createjs.Tween.get(foo)
                .to({x:100}, 1000)
                .label("myLabel")
                .to({x:200}, 1000);

// ... tween.gotoAndPlay("myLabel"); // would play from 1000ms in.

Parameters:

Returns:

Tween:

This tween instance (for chaining calls).

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.

pause

(
  • [tween]
)
Tween chainable

Defined in pause:574

Adds an action to pause the specified tween.

myTween.pause(otherTween).to({alpha:1}, 1000).play(otherTween);

Note that this executes at the end of a tween update, so the tween may advance beyond the time the pause action was inserted at. For example:

myTween.to({foo:0}, 1000).pause().to({foo:1}, 1000);

At 60fps the tween will advance by ~16ms per tick, if the tween above was at 999ms prior to the current tick, it will advance to 1015ms (15ms into the second "step") and then pause.

Parameters:

  • [tween] Tween optional

    The tween to pause. Defaults to this tween.

Returns:

Tween:

This tween instance (for chaining calls)

play

(
  • [tween]
)
Tween chainable

Defined in play:559

Adds an action to play (unpause) the specified tween. This enables you to sequence multiple tweens.

Example

myTween.to({x:100}, 500).play(otherTween);

Parameters:

  • [tween] Tween optional

    The tween to play. Defaults to this tween.

Returns:

Tween:

This tween instance (for chaining calls).

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.

removeAllTweens

() static

Defined in removeAllTweens:371

Available since 0.4.1

Stop and remove all existing tweens.

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.

removeTweens

(
  • target
)
static

Defined in removeTweens:353

Removes all existing tweens for a target. This is called automatically by new tweens if the override property is true.

Parameters:

  • target Object

    The target object to remove existing tweens from.

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.

set

(
  • props
  • [target]
)
Tween chainable

Defined in set:541

Adds an action to set the specified props on the specified target. If target is null, it will use this tween's target. Note that for properties on the target object, you should consider using a zero duration to operation instead so the values are registered as tweened props.

Example

myTween.wait(1000).set({visible:false}, foo);

Parameters:

  • props Object

    The properties to set (ex. {visible:false}).

  • [target] Object optional

    The target to set the properties on. If omitted, they will be set on the tween's target.

Returns:

Tween:

This tween instance (for chaining calls).

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.

tick

(
  • delta
  • paused
)
static

Defined in tick:316

Advances all tweens. This typically uses the Ticker class, but you can call it manually if you prefer to use your own "heartbeat" implementation.

Parameters:

  • delta Number

    The change in time in milliseconds since the last tick. Required unless all tweens have useTicks set to true.

  • paused Boolean

    Indicates whether a global pause is in effect. Tweens with Tween/ignoreGlobalPause:property will ignore this, but all others will pause if this is true.

to

(
  • props
  • [duration=0]
  • [ease="linear"]
)
Tween chainable

Defined in to:477

Adds a tween from the current values to the specified properties. Set duration to 0 to jump to these value. Numeric properties will be tweened from their current value in the tween to the target value. Non-numeric properties will be set at the end of the specified duration.

Example

createjs.Tween.get(target).to({alpha:0, visible:false}, 1000);

Parameters:

  • props Object

    An object specifying property target values for this tween (Ex. {x:300} would tween the x property of the target to 300).

  • [duration=0] Number optional

    The duration of the tween in milliseconds (or in ticks if useTicks is true).

  • [ease="linear"] Function optional

    The easing function to use for this tween. See the Ease class for a list of built-in ease functions.

Returns:

Tween:

This tween instance (for chaining calls).

toString

() String

Inherited from EventDispatcher but overwritten in toString:602

Returns a string representation of this object.

Returns:

String:

a string representation of the instance.

wait

(
  • duration
  • [passive=false]
)
Tween chainable

Defined in wait:457

Adds a wait (essentially an empty tween).

Example

//This tween will wait 1s before alpha is faded to 0.
createjs.Tween.get(target).wait(1000).to({alpha:0}, 1000);

Parameters:

  • duration Number

    The duration of the wait in milliseconds (or in ticks if useTicks is true).

  • [passive=false] Boolean optional

    Tween properties will not be updated during a passive wait. This is mostly useful for use with Timeline instances that contain multiple tweens affecting the same target at different times.

Returns:

Tween:

This tween instance (for chaining calls).

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

_actionHead

TweenAction protected

Defined in _actionHead:187

_actionTail

TweenAction protected

Defined in _actionTail:194

_captureListeners

Object protected

_injected

Object protected

Defined in _injected:219

Used by plugins to inject new properties.

Default: null

_labelList

ArrayObject protected

Inherited from AbstractTween: _labelList:192

_labels

Object protected

Inherited from AbstractTween: _labels:185

_listeners

ArrayTween protected static

Inherited from EventDispatcher but overwritten in _listeners:249

_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

_plugins

Object protected static

Defined in _plugins:257

_plugins

Object protected

Defined in _plugins:210

Hash for quickly looking up added plugins. Null until a plugin is added.

Default: null

_plugins

ArrayObject protected

Defined in _plugins:201

Plugins added to this tween instance.

Default: null

_prev

Tween protected

Inherited from AbstractTween: _prev:169

Default: null

_stepHead

TweenStep protected

Defined in _stepHead:164

_stepPosition

Number protected

Defined in _stepPosition:178

The position within the current step. Used by MovieClip.

Default: 0

_stepTail

TweenStep protected

Defined in _stepTail:171

_tweenHead

Tween protected static

Defined in _tweenHead:265

_tweenTail

Tween protected static

Defined in _tweenTail:273

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

IGNORE

Object static

Defined in IGNORE:241

Constant returned by plugins to tell the tween not to use default assignment.

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

passive

Boolean readonly

Defined in passive:152

Indicates the tween's current position is within a passive wait.

Default: false

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.

pluginData

Object

Defined in pluginData:125

Allows you to specify data that will be used by installed plugins. Each plugin uses this differently, but in general you specify data by assigning it to a property of pluginData with the same name as the plugin. Note that in many cases, this data is used as soon as the plugin initializes itself for the tween. As such, this data should be set before the first to call in most cases.

Example:

myTween.pluginData.SmartRotation = data;

Most plugins also support a property to disable them for a specific tween. This is typically the plugin name followed by "_disabled".

myTween.pluginData.SmartRotation_disabled = true;

Some plugins also store working data in this object, usually in a property named _PluginClassName. See the documentation for individual plugins for more details.

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

target

Object readonly

Defined in target:144

The target of this tween. This is the object on which the tweened properties will be changed.

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

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.