Class: SC.Timer


Extends SC.Object.

A Timer executes a method after a defined period of time. Timers are significantly more efficient than using setTimeout() or setInterval() because they are cooperatively scheduled using the run loop. Timers are also gauranteed to fire at the same time, making it far easier to keep multiple timers in sync.

Overview

Timers were created for SproutCore as a way to efficiently defer execution of code fragments for use in Animations, event handling, and other tasks.

Browsers are typically fairly inconsistent about when they will fire a timeout or interval based on what the browser is currently doing. Timeouts and intervals are also fairly expensive for a browser to execute, which means if you schedule a large number of them it can quickly slow down the browser considerably.

Timers, on the other handle, are scheduled cooperatively using the SC.RunLoop, which uses exactly one timeout to fire itself when needed and then executes by timers that need to fire on its own. This approach can be many times faster than using timers and guarantees that timers scheduled to execute at the same time generally will do so, keeping animations and other operations in sync.

Scheduling a Timer

To schedule a basic timer, you can simply call SC.Timer.schedule() with a target and action you wish to have invoked:

var timer = SC.Timer.schedule({
  target: myObject, action: 'timerFired', interval: 100
});

When this timer fires, it will call the timerFired() method on myObject.

In addition to calling a method on a particular object, you can also use a timer to execute a variety of other types of code:

In general these properties are read-only. Changing an interval, target, or action after creating a timer will have an unknown effect.

Scheduling Repeating Timers

In addition to scheduling one time timers, you can also schedule timers to execute periodically until some termination date. You make a timer repeating by adding the repeats: YES property:

var timer = SC.Timer.schedule({
  target: myObject,
  action: 'updateAnimation',
  interval: 100,
  repeats: YES,
  until: Time.now() + 1000
}) ;

The above example will execute the myObject.updateAnimation() every 100msec for 1 second from the current time.

If you want a timer to repeat without expiration, you can simply omit the until: property. The timer will then repeat until you invalidate it.

Pausing and Invalidating Timers

If you have created a timer but you no longer want it to execute, you can call the invalidate() method on it. This will remove the timer from the run loop and clear certain properties so that it will not run again.

You can use the invalidate() method on both repeating and one-time timers.

If you do not want to invalidate a timer completely but you just want to stop the timer from execution temporarily, you can alternatively set the isPaused property to YES:

timer.set('isPaused', YES) ;
// Perform some critical function; timer will not execute
timer.set('isPaused', NO) ;

When a timer is paused, it will be scheduled and will fire like normal, but it will not actually execute the action method when it fires. For a one time timer, this means that if you have the timer paused when it fires, it may never actually execute the action method. For repeating timers, this means the timer will remain scheduled but simply will not execute its action while the timer is paused.

Firing Timers

If you need a timer to execute immediately, you can always call the fire() method yourself. This will execute the timer action, if the timer is not paused. For a one time timer, it will also invalidate the timer and remove it from the run loop. Repeating timers can be fired anytime and it will not interrupt their regular scheduled times.

Defined in: timer.js

Since:
version 1.0

Field Summary

Class Methods

Instance Methods

Field Detail

action

The action to execute.

The action can be a method name, a property path, or a function. If you pass a method name, it will be invoked on the target object or it will be called up the responder chain if target is null. If you pass a property path and it resolves to a function then the function will be called. If you pass a function instead, then the function will be called in the context of the target object.

interval

The time interval in milliseconds.

You generally set this when you create the timer. If you do not set it then the timer will fire as soon as possible in the next run loop.

isPaused

Set to YES to pause the timer.

Pausing a timer does not remove it from the run loop, but it will temporarily suspend it from firing. You should use this property if you will want the timer to fire again the future, but you want to prevent it from firing temporarily.

If you are done with a timer, you should call invalidate() instead of setting this property.

isPooled Boolean

Set if the timer should be created from a memory pool. Normally you will want to leave this set, but if you plan to use bindings or observers with this timer, then you must set isPooled to NO to avoid reusing your timer.

isScheduled
YES onces the timer has been scheduled for the first time.
isValid

YES if the timer can still execute.

This read only property will return YES as long as the timer may possibly fire again in the future. Once a timer has become invalid, it cannot become valid again.

lastFireTime

Set to the current time when the timer last fired. Used to find the next 'frame' to execute.

repeats
YES if you want the timer to execute repeatedly.
startTime

Timer start date offset.

The start date determines when the timer will be scheduled. The first time the timer fires will be interval milliseconds after the start date.

Generally you will not set this property yourself. Instead it will be set automatically to the current run loop start date when you schedule the timer. This ensures that all timers scheduled in the same run loop cycle will execute in the sync with one another.

The value of this property is an offset like what you get if you call Date.now().

target

The target object whose method will be invoked when the time fires.

You can set either a target/action property or you can pass a specific method.

until

Last date when the timer will execute.

If you have set repeats to YES, then you can also set this property to have the timer automatically stop executing past a certain date.

This property should contain an offset value like startOffset. However if you set it to a Date object on create, it will be converted to an offset for you.

If this property is null, then the timer will continue to repeat until you call invalidate().

Class Method Detail

returnTimerToPool(timer)

Returns a timer instance to the timer pool for later use. This is done automatically when a timer is invalidated if isPooled is YES.

Parameters:
timer
schedule(props)
Parameters:
props
timerFromPool(props)

Returns a new timer from the timer pool, copying the passed properties onto the timer instance. If the timer pool is currently empty, this will return a new instance.

Parameters:
props

Instance Method Detail

fire()

Immediately fires the timer.

If the timer is not-repeating, it will be invalidated. If it is repeating you can call this method without interrupting its normal schedule.

Returns:
void
fireTime()

Computed property returns the next time the timer should fire. This property resets each time the timer fires. Returns -1 if the timer cannot fire again.

init()
invalidate()

Invalidates the timer so that it will not execute again. If a timer has been scheduled, it will be removed from the run loop immediately.

Returns:
SC.Timer
The receiver
performAction()

Actually fires the action. You can override this method if you need to change how the timer fires its action.

reset(props)

Resets the timer settings with the new settings. This is the method called by the Timer pool when a timer is reused. You will not normally call this method yourself, though you could override it if you need to reset additional properties when a timer is reused.

Parameters:
props
Returns:
SC.Timer
receiver
schedule()

Schedules the timer to execute in the runloop.

This method is called automatically if you create the timer using the schedule() class method. If you create the timer manually, you will need to call this method yourself for the timer to execute.

Returns:
SC.Timer
The receiver
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)