Ticker Class
The Ticker provides a centralized tick or heartbeat broadcast at a set interval. Listeners can subscribe to the tick event to be notified when a set time interval has elapsed.
Note that the interval that the tick event is called is a target interval, and may be broadcast at a slower interval
during times of high CPU load. The Ticker class uses a static interface (ex. Ticker.getPaused()
) and
should not be instantiated.
Example
createjs.Ticker.addEventListener("tick", handleTick); function handleTick(event) { // Actions carried out each frame if (!event.paused) { // Actions carried out when the Ticker is not paused. } }To update a stage every tick, the Stage instance can also be used as a listener, as it will automatically update when it receives a tick event:
createjs.Ticker.addEventListener("tick", stage);
Item Index
Methods
- _dispatchEvent
- _getTime static
- _handleRAF static
- _handleSynch static
- _handleTimeout static
- _setupTick static
- _tick static
- addEventListener
- dispatchEvent
- getEventTime
- getFPS static
- getInterval static
- getMeasuredFPS static
- getMeasuredTickTime static
- getTicks static
- getTime static
- hasEventListener
- init static
- initialize
- off
- on
- removeAllEventListeners
- removeEventListener
- reset static
- setFPS static
- setInterval static
- setPaused static
- toString
Properties
- _captureListeners
- _inited
- _interval
- _lastTime
- _listeners
- _paused
- _pausedTicks
- _pausedTime
- _raf
- _startTime
- _ticks
- _tickTimes
- _timerId
- _times
- maxDelta static
- RAF static
- RAF static
- RAF_SYNCHED static
- timingMode static
- useRAF static deprecated
Events
Methods
_dispatchEvent
-
eventObj
-
eventPhase
_getTime
()
protected
static
_handleRAF
()
protected
static
_handleSynch
()
protected
static
_handleTimeout
()
protected
static
_setupTick
()
protected
static
_tick
()
protected
static
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.
dispatchEvent
-
eventObj
-
[target]
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 with the specified type.
-
[target]
Object optionalThe object to use as the target property of the event object. This will default to the dispatching object. This parameter is deprecated and will be removed.
Returns:
Returns the value of eventObj.defaultPrevented.
getEventTime
-
runTime
Similar to getTime(), but returns the time included with the current (or most recent) tick event object.
Parameters:
-
runTime
Boolean[runTime=false] If true, the runTime property will be returned instead of time.
Returns:
The time or runTime property from the most recent tick event.
getFPS
()
Number
static
Returns the target frame rate in frames per second (FPS). For example, with an interval of 40, getFPS()
will return 25 (1000ms per second divided by 40 ms per tick = 25fps).
Returns:
The current target number of frames / ticks broadcast per second.
getInterval
()
Number
static
Returns the current target time between ticks, as set with setInterval.
Returns:
The current target interval in milliseconds between tick events.
getMeasuredFPS
-
[ticks]
Returns the actual frames / ticks per second.
Parameters:
-
[ticks]
Number optionalThe number of previous ticks over which to measure the actual frames / ticks per second. Defaults to the number of ticks per second.
Returns:
The actual frames / ticks per second. Depending on performance, this may differ from the target frames per second.
getMeasuredTickTime
-
[ticks]
Returns the average time spent within a tick. This can vary significantly from the value provided by getMeasuredFPS because it only measures the time spent within the tick execution stack.
Example 1: With a target FPS of 20, getMeasuredFPS() returns 20fps, which indicates an average of 50ms between the end of one tick and the end of the next. However, getMeasuredTickTime() returns 15ms. This indicates that there may be up to 35ms of "idle" time between the end of one tick and the start of the next.
Example 2: With a target FPS of 30, getFPS() returns 10fps, which indicates an average of 100ms between the end of one tick and the end of the next. However, getMeasuredTickTime() returns 20ms. This would indicate that something other than the tick is using ~80ms (another script, DOM rendering, etc).
Parameters:
-
[ticks]
Number optionalThe number of previous ticks over which to measure the average time spent in a tick. Defaults to the number of ticks per second. To get only the last tick's time, pass in 1.
Returns:
The average time spent in a tick in milliseconds.
getTicks
-
pauseable
Returns the number of ticks that have been broadcast by Ticker.
Parameters:
-
pauseable
BooleanIndicates whether to include ticks that would have been broadcast while Ticker was paused. If true only tick events broadcast while Ticker is not paused will be returned. If false, tick events that would have been broadcast while Ticker was paused will be included in the return value. The default value is false.
Returns:
of ticks that have been broadcast.
getTime
-
[runTime=false]
Returns the number of milliseconds that have elapsed since Ticker was initialized. For example, you could use this in a time synchronized animation to determine the exact amount of time that has elapsed.
Parameters:
-
[runTime=false]
Boolean optionalIf true only time elapsed while Ticker was not paused will be returned. If false, the value returned will be total time elapsed since the first tick event listener was added.
Returns:
Number of milliseconds that have elapsed since Ticker was initialized.
hasEventListener
-
type
Indicates whether there is at least one listener for the specified event type and useCapture
value.
Parameters:
-
type
StringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
init
()
static
Starts the tick. This is called automatically when the first listener is added.
initialize
()
protected
Initialization method.
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.
removeAllEventListeners
-
[type]
Removes all listeners for the specified type, or all listeners of all types.
Example
// Remove all listeners
displayObject.removeAllEvenListeners();
// 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);
reset
()
static
Stops the Ticker and removes all listeners. Use init() to restart the Ticker.
setFPS
-
value
Sets the target frame rate in frames per second (FPS). For example, with an interval of 40, getFPS()
will return 25 (1000ms per second divided by 40 ms per tick = 25fps).
Parameters:
-
value
NumberTarget number of ticks broadcast per second.
setInterval
-
interval
Sets the target time (in milliseconds) between ticks. Default is 50 (20 FPS).
Note actual time between ticks may be more than requested depending on CPU load.
Parameters:
-
interval
NumberTime in milliseconds between ticks. Default value is 50.
setPaused
-
value
Changes the "paused" state of the Ticker, which can be retrieved by the Ticker/getPaused
method, and is passed as the "paused" property of the tick
event. When the ticker is paused, all
listeners will still receive a tick event, but the paused
property will be false.
Note that in EaselJS v0.5.0 and earlier, "pauseable" listeners would not receive the tick callback when Ticker was paused. This is no longer the case.
Example
createjs.Ticker.addEventListener("tick", handleTick); createjs.Ticker.setPaused(true); function handleTick(event) { console.log("Paused:", event.paused, createjs.Ticker.getPaused()); }Parameters:
-
value
BooleanIndicates whether to pause (true) or unpause (false) Ticker.
Properties
maxDelta
Number
static
Specifies a maximum value for the delta property in the tick event object. This is useful when building time based animations and systems to prevent issues caused by large time gaps caused by background tabs, system sleep, alert dialogs, or other blocking routines. Double the expected frame duration is often an effective value (ex. maxDelta=50 when running at 40fps).
This does not impact any other values (ex. time, runTime, etc), so you may experience issues if you enable maxDelta when using both delta and other values.
If 0, there is no maximum.
Default: 0
RAF
String
static
In this mode, Ticker passes through the requestAnimationFrame heartbeat, ignoring the target framerate completely. Because requestAnimationFrame frequency is not deterministic, any content using this mode should be time based. You can leverage getTime and the tick event object's "delta" properties to make this easier.
Falls back on TIMEOUT if the requestAnimationFrame API is not supported.
Default: "raf"
RAF
String
static
In this mode, Ticker uses the setTimeout API. This provides predictable, adaptive frame timing, but does not provide the benefits of requestAnimationFrame (screen synch, background throttling).
Default: "timer"
RAF_SYNCHED
String
static
In this mode, Ticker uses the requestAnimationFrame API, but attempts to synch the ticks to target framerate. It uses a simple heuristic that compares the time of the RAF return to the target time for the current frame and dispatches the tick when the time is within a certain threshold.
This mode has a higher variance for time between frames than TIMEOUT, but does not require that content be time based as with RAF while gaining the benefits of that API (screen synch, background throttling).
Variance is usually lowest for framerates that are a divisor of the RAF frequency. This is usually 60, so framerates of 10, 12, 15, 20, and 30 work well.
Falls back on TIMEOUT if the requestAnimationFrame API is not supported.
Default: "synched"
timingMode
String
static
Specifies the timing api (setTimeout or requestAnimationFrame) and mode to use. See Ticker/TIMEOUT, Ticker/RAF, and Ticker/RAF_SYNCHED for mode details.
Default: Ticker.TIMEOUT
useRAF
Boolean
deprecated
static
Deprecated in favour of Ticker/timingMode, and will be removed in a future version. If true, timingMode will use Ticker/RAF_SYNCHED by default.
Default: false
Events
tick
Dispatched each tick. The event will be dispatched to each listener even when the Ticker has been paused using setPaused.
Example
createjs.Ticker.addEventListener("tick", handleTick); function handleTick(event) { console.log("Paused:", event.paused, event.delta); }Event Payload:
-
target
ObjectThe object that dispatched the event.
-
type
StringThe event type.
-
paused
BooleanIndicates whether the ticker is currently paused.
-
delta
NumberThe time elapsed in ms since the last tick.
-
time
NumberThe total time in ms since Ticker was initialized.
-
runTime
NumberThe total time in ms that Ticker was not paused since it was initialized. For example, you could determine the amount of time that the Ticker has been paused since initialization with time-runTime.