Timeline Class
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]
Parameters:
-
[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 -
ignoreGlobalPause -
loop -
reversed -
bounce -
timeScale -
paused -
position: indicates the initial position for this tween. -
onChange: adds the specified function as a listener to thechangeevent -
onComplete: adds the specified function as a listener to thecompleteevent
-
Item Index
Methods
- _dispatchEvent
- _getCurrentLabel
- _getPaused
- _goto
- _init
- _runActions
- _setPaused
- _updatePosition
- addEventListener
- addLabel
- addTween
- advance
- calculatePosition
- clone
- dispatchEvent
- getLabels
- gotoAndPlay
- gotoAndStop
- hasEventListener
- off
- on
- removeAllEventListeners
- removeEventListener
- removeTween
- resolve
- setLabels
- setPosition
- toString
- updateDuration
- willTrigger
Properties
Methods
_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.
_runActions
()
protected
_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
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:
-
typeStringThe string type of the event.
-
listenerFunction | 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.
addTween
-
...tween
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:
-
...tweenTweenThe tween(s) to add. Accepts multiple arguments.
Returns:
The first tween that was passed in.
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:
-
rawPositionNumberA raw position.
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:
-
eventObjObject | 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
bubblesvalue when a string was passed to eventObj. -
[cancelable]Boolean optionalSpecifies the
cancelablevalue when a string was passed to eventObj.
Returns:
Returns false if preventDefault() was called on a cancelable event, true otherwise.
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.
hasEventListener
-
type
Indicates whether there is at least one listener for the specified event type.
Parameters:
-
typeStringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
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:
-
typeStringThe string type of the event.
-
listenerFunction | 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.
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.
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);removeTween
-
...tween
Removes one or more tweens from this timeline.
Parameters:
-
...tweenTweenThe tween(s) to remove. Accepts multiple arguments.
Returns:
Boolean Returns true if all of the tweens were successfully removed.
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.
setLabels
-
labels
Defines labels for use with gotoAndPlay/Stop. Overwrites any previously set labels.
Parameters:
-
labelsObjectAn object defining labels for using Timeline/gotoAndPlay/Timeline/gotoAndStop in the form
{myLabelName:time}where time is in milliseconds (or ticks ifuseTicksistrue).
setPosition
-
rawPosition -
[ignoreActions=false] -
[jump=false] -
[callback]
Advances the tween to a specified position.
Parameters:
-
rawPositionNumberThe 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.
toString
()
String
Returns a string representation of this object.
Returns:
a string representation of the instance.
updateDuration
()
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
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:
-
typeStringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
Properties
_labelList
ArrayObject
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
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.
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
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
tweens
Array
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
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.