Tween Class
A Tween instance tweens properties for a single target. Instance methods can be chained for easy construction and sequencing:
Example
target.alpha = 1;
createjs.Tween.get(target)
.wait(500)
.to({alpha:0, visible:false}, 1000)
.call(handleComplete);
function handleComplete() {
//Tween complete
}
Multiple tweens can point to the same instance, 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 change event to get notified when a property of the target is changed.
createjs.Tween.get(target, {override:true}).to({x:100}).addEventListener("change", handleChange);
function handleChange(event) {
// The tween changed.
}
See the Tween get method for additional param documentation.
Constructor
Tween
-
target
-
[props]
-
[pluginData]
Parameters:
-
target
ObjectThe target object that will have its properties tweened.
-
[props]
Object optionalThe configuration properties to apply to this tween instance (ex.
{loop:true, paused:true}
. All properties default to false. Supported props are:- loop: sets the loop property on this tween.
- useTicks: uses ticks for all durations instead of milliseconds.
- ignoreGlobalPause: sets the ignoreGlobalPause property on this tween.
- override: if true,
Tween.removeTweens(target)
will be called to remove any other tweens with the same target. - paused: indicates whether to start the tween paused.
- position: indicates the initial position for this tween.
- onChange: specifies a listener for the "change" event.
-
[pluginData]
Object optionalAn object containing data for use by installed plugins. See individual plugins' documentation for details.
Item Index
Methods
- _addAction
- _addStep
- _appendQueueProps
- _cloneProps
- _dispatchEvent
- _register static
- _runActions
- _set
- _updateTargetProps
- addEventListener
- call
- clone
- dispatchEvent
- get static
- handleEvent static
- hasActiveTweens static
- hasEventListener
- initialize deprecated
- installPlugin static
- off
- on
- pause
- play
- removeAllEventListeners
- removeAllTweens static
- removeEventListener
- removeTweens static
- set
- setPaused
- setPosition
- tick static
- tick
- to
- toString
- wait
- willTrigger
Properties
- _actions
- _captureListeners
- _curQueueProps
- _inited
- _initQueueProps
- _listeners static
- _paused
- _plugins static
- _prevPos
- _prevPosition
- _registered
- _stepPosition
- _steps
- _target
- _useTicks
- duration
- IGNORE static
- ignoreGlobalPause
- loop
- LOOP static
- NONE static
- passive
- pluginData
- position
- REVERSE static
- target
Events
Methods
_dispatchEvent
-
eventObj
-
eventPhase
_register
-
tween
-
value
Registers or unregisters a tween with the ticking system.
_runActions
-
startPos
-
endPos
-
includeStart
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.
call
-
callback
-
[params]
-
[scope]
Queues an action to call the specified function.
Example
//would call myFunction() after 1 second.
myTween.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
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:
Returns:
Returns the value of eventObj.defaultPrevented.
get
-
target
-
[props]
-
[pluginData]
-
[override=false]
Returns a new tween instance. This is functionally identical to using "new Tween(...)", but looks cleaner with the chained syntax of TweenJS.
Example
var tween = createjs.Tween.get(target);
Parameters:
-
target
ObjectThe target object that will have its properties tweened.
-
[props]
Object optionalThe configuration properties to apply to this tween instance (ex.
{loop:true, paused:true}
). All properties default tofalse
. Supported props are:- loop: sets the loop property on this tween.
- useTicks: uses ticks for all durations instead of milliseconds.
- ignoreGlobalPause: sets the ignoreGlobalPause property on this tween.
- override: if true,
createjs.Tween.removeTweens(target)
will be called to remove any other tweens with the same target. - paused: indicates whether to start the tween paused.
- position: indicates the initial position for this tween.
- onChange: specifies a listener for the change event.
-
[pluginData]
Object optionalAn object containing data for use by installed plugins. See individual plugins' documentation for details.
-
[override=false]
Boolean optionalIf true, any previous tweens on the same target will be removed. This is the same as calling
Tween.removeTweens(target)
.
Returns:
A reference to the created tween. Additional chained tweens, method calls, or callbacks can be applied to the returned tween instance.
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 (and how many) 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:
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.
initialize
()
deprecated
protected
installPlugin
-
plugin
-
properties
Installs a plugin, which can modify how certain properties are handled when tweened. See the CSSPlugin for an example of how to write TweenJS plugins.
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.
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 created anonymous function is returned for use with .removeEventListener (or .off).
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
Queues an action to pause the specified tween.
Parameters:
-
tween
TweenThe tween to pause. If null, it pauses this tween.
Returns:
This tween instance (for chaining calls)
play
-
tween
Queues 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
TweenThe tween to play.
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.
set
-
props
-
[target]
Queues an action to set the specified props on the specified target. If target is null, it will use this tween's target.
Example
myTween.wait(1000).set({visible:false},foo);
Parameters:
Returns:
This tween instance (for chaining calls).
setPaused
-
[value=true]
Pauses or plays this tween.
Parameters:
-
[value=true]
Boolean optionalIndicates whether the tween should be paused (
true
) or played (false
).
Returns:
This tween instance (for chaining calls)
setPosition
-
value
-
[actionsMode=1]
Advances the tween to a specified position.
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:
-
delta
NumberThe change in time in milliseconds since the last tick. Required unless all tweens have
useTicks
set to true. -
paused
BooleanIndicates whether a global pause is in effect. Tweens with ignoreGlobalPause will ignore this, but all others will pause if this is
true
.
tick
-
delta
Advances this tween by the specified amount of time in milliseconds (or ticks ifuseTicks
is true
).
This is normally called automatically by the Tween engine (via tick), but is
exposed for advanced uses.
Parameters:
-
delta
NumberThe time to advance in milliseconds (or ticks if
useTicks
istrue
).
to
-
props
-
[duration=0]
-
[ease="linear"]
Queues a tween from the current values to the target 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}, 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 wait 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]
Queues 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]
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
_listeners
ArrayTween
protected
static
_registered
Boolean
protected
Indicates whether the tween is currently registered with Tween.
Default: false
duration
Number
readonly
Specifies the total duration of this tween in milliseconds (or ticks if useTicks is true). 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 true (the default) will cause this tween to be paused when Ticker.setPaused(true)
is called. See the Tween tick method for more info. Can be set via the props
parameter.
Default: false
loop
Boolean
If true, the tween will loop when it reaches the end. Can be set via the props param.
Default: false
passive
Boolean
readonly
Indicates the tween's current position is within a passive wait.
Default: false
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 setting it to a property of pluginData with the same name as the plugin class.
Example:
myTween.pluginData.PluginClassName = data;
Also, most plugins support a property to enable or disable them. This is typically the plugin class name followed by "_enabled".
myTween.pluginData.PluginClassName_enabled = false;<br/>
Some plugins also store instance 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 no effect.
REVERSE
Number
static
Constant defining the reverse actionsMode for use with setPosition.
Default: 2
target
Object
readonly
The target of this tween. This is the object on which the tweened properties will be changed. Changing this property after the tween is created will not have any effect.
Events
change
Called whenever the tween's position changes.