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:

• If you include an action name, but not a target object, then the action will be passed down the responder chain.
• If you include a property path for the action property (e.g. 'MyApp.someController.someMethod'), then the method you name will be executed.
• If you include a function in the action property, then the function will be executed. If you also include a target object, the function will be called with this set to the target object.

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

• returnTimerToPool(timer)
• schedule(props)
• timerFromPool(props)

Instance Methods

• fire()
• fireTime()
• init()
• invalidate()
• performAction()
• reset(props)
• schedule()