Tween Class
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]
Parameters:
-
target
ObjectThe target object that will have its properties tweened.
-
[props]
Object optionalThe 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 optionalSee the useTicks property for more information.
-
[ignoreGlobalPause=false]
Boolean optionalSee the ignoreGlobalPause for more information.
-
[loop=0]
Number | Boolean optionalSee the loop for more information.
-
[reversed=false]
Boolean optionalSee the reversed for more information.
-
[bounce=false]
Boolean optionalSee the bounce for more information.
-
[timeScale=1]
Number optionalSee the timeScale for more information.
-
[pluginData]
Object optionalSee the pluginData for more information.
-
[paused=false]
Boolean optionalSee the paused for more information.
-
[position=0]
Number optionalThe initial position for this tween. See position
-
[onChange]
Function optionalAdds the specified function as a listener to the change event
-
[onComplete]
Function optionalAdds the specified function as a listener to the complete event
-
[override=false]
Boolean optionalRemoves all existing tweens for the target when set to
true
.
-
Item Index
Methods
- _addAction
- _addPlugin
- _addStep
- _appendProps
- _cloneProps
- _dispatchEvent
- _getCurrentLabel
- _getPaused
- _goto
- _init
- _injectProp
- _installPlugin static
- _register static
- _runActions
- _runActionsRange
- _set
- _setPaused
- _updatePosition
- _updateTargetProps
- addEventListener
- addLabel
- advance
- calculatePosition
- call
- clone
- dispatchEvent
- get static
- getLabels
- gotoAndPlay
- gotoAndStop
- handleEvent static
- hasActiveTweens static
- hasEventListener
- label
- off
- on
- pause
- play
- removeAllEventListeners
- removeAllTweens static
- removeEventListener
- removeTweens static
- resolve
- set
- setLabels
- setPosition
- tick static
- to
- toString
- wait
- willTrigger
Properties
- _actionHead
- _actionTail
- _captureListeners
- _injected
- _labelList
- _labels
- _listeners static
- _next
- _parent
- _paused
- _plugins static
- _plugins
- _plugins
- _prev
- _stepHead
- _stepPosition
- _stepTail
- _tweenHead static
- _tweenTail static
- bounce
- currentLabel
- duration
- IGNORE static
- ignoreGlobalPause
- loop
- passive
- paused
- pluginData
- position
- rawPosition
- reversed
- target
- timeScale
- useTicks
Methods
_addStep
-
duration
-
props
-
ease
-
passive
_appendProps
-
props
-
step
-
stepPlugins
_dispatchEvent
-
eventObj
-
eventPhase
_getCurrentLabel
()
String
protected
Use the currentLabel property instead.
Returns:
The name of the current label or null if there is no label
_goto
()
protected
_init
()
protected
Shared logic that executes at the end of the subclass constructor.
_injectProp
-
name
-
value
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.
_installPlugin
-
plugin
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
ObjectThe plugin to install
_register
-
tween
-
paused
Registers or unregisters a tween with the ticking system.
_runActions
()
protected
_runActionsRange
-
startPos
-
endPos
-
jump
-
includeStart
_setPaused
-
[value=true]
Use the paused property instead.
Parameters:
-
[value=true]
Boolean optionalIndicates whether the tween should be paused (
true
) or played (false
).
Returns:
This tween instance (for chaining calls)
_updatePosition
()
protected
_updateTargetProps
-
step
-
ratio
-
end
addEventListener
-
type
-
listener
-
[useCapture]
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
StringThe string type of the event.
-
listener
Function | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[useCapture]
Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
addLabel
-
label
-
position
Adds a label that can be used with Timeline/gotoAndPlay/Timeline/gotoAndStop.
advance
-
delta
-
[ignoreActions=false]
Advances the tween by a specified amount.
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
NumberA raw position.
call
-
callback
-
[params]
-
[scope]
Adds an action to call the specified function.
Example
//would call myFunction() after 1 second.
createjs.Tween.get().wait(1000).call(myFunction);
Parameters:
-
callback
FunctionThe function to call.
-
[params]
Array optionalThe 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 optionalThe scope to call the function in. If omitted, it will be called in the target's scope.
Returns:
This tween instance (for chaining calls).
clone
()
protected
dispatchEvent
-
eventObj
-
[bubbles]
-
[cancelable]
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 | EventAn 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 optionalSpecifies the
bubbles
value when a string was passed to eventObj. -
[cancelable]
Boolean optionalSpecifies the
cancelable
value when a string was passed to eventObj.
Returns:
Returns false if preventDefault()
was called on a cancelable event, true otherwise.
get
-
target
-
[props]
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
ObjectThe target object that will have its properties tweened.
-
[props]
Object optionalThe 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 optionalSee the useTicks property for more information.
-
[ignoreGlobalPause=false]
Boolean optionalSee the ignoreGlobalPause for more information.
-
[loop=0]
Number | Boolean optionalSee the loop for more information.
-
[reversed=false]
Boolean optionalSee the reversed for more information.
-
[bounce=false]
Boolean optionalSee the bounce for more information.
-
[timeScale=1]
Number optionalSee the timeScale for more information.
-
[pluginData]
Object optionalSee the pluginData for more information.
-
[paused=false]
Boolean optionalSee the paused for more information.
-
[position=0]
Number optionalThe initial position for this tween. See position
-
[onChange]
Function optionalAdds the specified function as a listener to the change event
-
[onComplete]
Function optionalAdds the specified function as a listener to the complete event
-
[override=false]
Boolean optionalRemoves all existing tweens for the target when set to
true
.
-
Returns:
A reference to the created tween.
getLabels
()
ArrayObject
Returns a list of the labels defined on this tween sorted by position.
Returns:
A sorted array of objects with label and position properties.
gotoAndPlay
-
positionOrLabel
Unpauses this timeline and jumps to the specified position or label.
gotoAndStop
-
positionOrLabel
Pauses this timeline and jumps to the specified position or label.
handleEvent
-
event
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:
-
event
ObjectAn event object passed in by the EventDispatcher. Will usually be of type "tick".
hasActiveTweens
-
[target]
Indicates whether there are any active tweens on the target object (if specified) or in general.
Parameters:
-
[target]
Object optionalThe target to check for active tweens. If not specified, the return value will indicate if there are any active tweens on any target.
Returns:
Indicates if there are active tweens.
hasEventListener
-
type
Indicates whether there is at least one listener for the specified event type.
Parameters:
-
type
StringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
label
-
name
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:
-
name
StringThe label name.
Returns:
This tween instance (for chaining calls).
off
-
type
-
listener
-
[useCapture]
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.
on
-
type
-
listener
-
[scope]
-
[once=false]
-
[data]
-
[useCapture=false]
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
StringThe string type of the event.
-
listener
Function | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[scope]
Object optionalThe 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 optionalIf true, the listener will remove itself after the first time it is triggered.
-
[data]
optionalArbitrary data that will be included as the second parameter when the listener is called.
-
[useCapture=false]
Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Returns:
Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.
pause
-
[tween]
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 optionalThe tween to pause. Defaults to this tween.
Returns:
This tween instance (for chaining calls)
play
-
[tween]
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 optionalThe tween to play. Defaults to this tween.
Returns:
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 optionalThe string type of the event. If omitted, all listeners for all types will be removed.
removeAllTweens
()
static
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);
removeTweens
-
target
Removes all existing tweens for a target. This is called automatically by new tweens if the override
property is true
.
Parameters:
-
target
ObjectThe target object to remove existing tweens from.
resolve
-
positionOrLabel
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.
set
-
props
-
[target]
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:
Returns:
This tween instance (for chaining calls).
setLabels
-
labels
Defines labels for use with gotoAndPlay/Stop. Overwrites any previously set labels.
Parameters:
-
labels
ObjectAn object defining labels for using Timeline/gotoAndPlay/Timeline/gotoAndStop in the form
{myLabelName:time}
where time is in milliseconds (or ticks ifuseTicks
istrue
).
setPosition
-
rawPosition
-
[ignoreActions=false]
-
[jump=false]
-
[callback]
Advances the tween to a specified position.
Parameters:
-
rawPosition
NumberThe raw position to seek to in milliseconds (or ticks if useTicks is true).
-
[ignoreActions=false]
Boolean optionalIf true, do not run any actions that would be triggered by this operation.
-
[jump=false]
Boolean optionalIf true, only actions at the new position will be run. If false, actions between the old and new position are run.
-
[callback]
Function optionalPrimarily for use with MovieClip, this callback is called after properties are updated, but before actions are run.
tick
-
delta
-
paused
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:
to
-
props
-
[duration=0]
-
[ease="linear"]
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
ObjectAn object specifying property target values for this tween (Ex.
{x:300}
would tween the x property of the target to 300). -
[duration=0]
Number optionalThe duration of the tween in milliseconds (or in ticks if
useTicks
is true). -
[ease="linear"]
Function optionalThe easing function to use for this tween. See the Ease class for a list of built-in ease functions.
Returns:
This tween instance (for chaining calls).
toString
()
String
Returns a string representation of this object.
Returns:
a string representation of the instance.
wait
-
duration
-
[passive=false]
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
NumberThe duration of the wait in milliseconds (or in ticks if
useTicks
is true). -
[passive=false]
Boolean optionalTween 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:
This tween instance (for chaining calls).
willTrigger
-
type
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
StringThe string type of the event.
Returns:
Returns true
if there is at least one listener for the specified event.
Properties
_actionHead
TweenAction
protected
_actionTail
TweenAction
protected
_labelList
ArrayObject
protected
_listeners
ArrayTween
protected
static
_plugins
Object
protected
Hash for quickly looking up added plugins. Null until a plugin is added.
Default: null
_plugins
ArrayObject
protected
Plugins added to this tween instance.
Default: null
_stepHead
TweenStep
protected
_stepTail
TweenStep
protected
bounce
Boolean
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
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
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
Indicates the tween's current position is within a passive wait.
Default: false
paused
Boolean
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
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
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
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
target
Object
readonly
The target of this tween. This is the object on which the tweened properties will be changed.
timeScale
Number
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
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
Dispatched whenever the tween's position changes. It occurs after all tweened properties are updated and actions are executed.
complete
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.