sproutcore 1.4.5 → 1.5.0.pre.3

data/lib/frameworks/sproutcore/frameworks/{foundation → amber}/system/timer.js

@@ -7,46 +7,46 @@
 /**
   @class
 
-  A Timer executes a method after a defined period of time.  Timers are 
-  significantly more efficient than using setTimeout() or setInterval() 
+  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 
+  also gauranteed to fire at the same time, making it far easier to keep
   multiple timers in sync.
-  
+
   h2. 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 inconsistant 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 
+
+  Browsers are typically fairly inconsistant 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 
+
+  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 timers faster than using timers and gaurantees that timers scheduled
   to execute at the same time generally will do so, keeping animations and
   other operations in sync.
-  
+
   h2. Scheduling a Timer
 
-  To schedule a basic timer, you can simply call SC.Timer.schedule() with 
+  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 
+    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.
@@ -55,61 +55,61 @@
   or action after creating a timer will have an unknown effect.
 
   h2. 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', 
+      target: myObject,
+      action: 'updateAnimation',
       interval: 100,
-      repeats: YES, 
+      repeats: YES,
       until: Time.now() + 1000
     }) ;
   }}}
-  
+
   The above example will execute the myObject.updateAnimation() every 100msec
-  for 1 second from the current time.  
-  
+  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.
-  
+
   h2. 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 
+  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 
+
+  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, 
+  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.
-  
+
   h2. 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.
 
-  
+
   @extends SC.Object
   @author Charles Jolley
   @version 1.0
@@ -120,102 +120,102 @@ SC.Timer = SC.Object.extend(
 
   /**
     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.
-    
+
     @type {Object}
     @field
   */
   target: null,
-  
+
   /**
     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 
+    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.
-    
+
     @type {String, Function}
   */
   action: null,
-  
+
   /**
     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.
-    
+
     @property {Boolean}
   */
   isPooled: NO,
-  
+
   /**
     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.
-    
+
     @type {Number}
   */
   interval: 0,
-  
+
   /**
     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 
+    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().
-    
+
     @type {Number}
   */
   startTime: null,
-  
+
   /**
     YES if you want the timer to execute repeatedly.
-    
+
     @type {Boolean}
   */
   repeats: NO,
-  
+
   /**
     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().
-    
+
     @type {Date, Number}
   */
   until: null,
-  
+
   /**
     Set to YES to pause the timer.
-    
-    Pausing a timer does not remove it from the run loop, but it will 
+
+    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 
+
+    If you are done with a timer, you should call invalidate() instead of
     setting this property.
-    
+
     @type {Boolean}
   */
   isPaused: NO,
@@ -224,99 +224,101 @@ SC.Timer = SC.Object.extend(
     YES onces the timer has been scheduled for the first time.
   */
   isScheduled: NO,
-  
+
   /**
     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. 
-    
+    fire again in the future.  Once a timer has become invalid, it cannot
+    become valid again.
+
     @field
     @type {Boolean}
   */
   isValid: YES,
-  
+
   /**
-    Set to the current time when the timer last fired.  Used to find the 
+    Set to the current time when the timer last fired.  Used to find the
     next 'frame' to execute.
   */
   lastFireTime: 0,
-  
+
   /**
-    Computed property returns the next time the timer should fire.  This 
-    property resets each time the timer fires.  Returns -1 if the timer 
+    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.
-    
+
     @property {Time}
   */
   fireTime: function() {
-    if (!this.get('isValid')) return -1 ;  // not valid - can't fire
-    
+    if (!this.get('isValid')) { return -1 ; }  // not valid - can't fire
+
     // can't fire w/o startTime (set when schedule() is called).
     var start = this.get('startTime');
-    if (!start || start === 0) return -1; 
+    if (!start || start === 0) { return -1; }
 
     // fire interval after start.
     var interval = this.get('interval'), last = this.get('lastFireTime');
-    if (last < start) last = start; // first time to fire
-    
+    if (last < start) { last = start; } // first time to fire
+
     // find the next time to fire
     var next ;
     if (this.get('repeats')) {
       if (interval === 0) { // 0 means fire as fast as possible.
         next = last ; // time to fire immediately!
-        
+
       // find the next full interval after start from last fire time.
       } else {
         next = start + (Math.floor((last - start) / interval)+1)*interval;
       }
-      
+
     // otherwise, fire only once interval after start
-    } else next = start + interval ;
-    
+    } else {
+      next = start + interval ;
+    }
+
     // can never have a fireTime after until
     var until = this.get('until');
     if (until && until>0 && next>until) next = until;
-    
+
     return next ;
   }.property('interval', 'startTime', 'repeats', 'until', 'isValid', 'lastFireTime').cacheable(),
-  
+
   /**
-    Schedules the timer to execute in the runloop. 
-    
+    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
   */
   schedule: function() {
     if (!this.get('isValid')) return this; // nothing to do
-    
+
     this.beginPropertyChanges();
-    
-    // if start time was not set explicitly when the timer was created, 
+
+    // if start time was not set explicitly when the timer was created,
     // get it from the run loop.  This way timer scheduling will always
     // occur in sync.
     if (!this.startTime) this.set('startTime', SC.RunLoop.currentRunLoop.get('startTime')) ;
 
-    // now schedule the timer if the last fire time was < the next valid 
+    // now schedule the timer if the last fire time was < the next valid
     // fire time.  The first time lastFireTime is 0, so this will always go.
     var next = this.get('fireTime'), last = this.get('lastFireTime');
     if (next >= last) {
       this.set('isScheduled', YES);
       SC.RunLoop.currentRunLoop.scheduleTimer(this, next);
     }
-    
+
     this.endPropertyChanges() ;
-    
+
     return this ;
   },
   /**
     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
   */
   invalidate: function() {
@@ -325,18 +327,18 @@ SC.Timer = SC.Object.extend(
     SC.RunLoop.currentRunLoop.cancelTimer(this);
     this.action = this.target = null ; // avoid memory leaks
     this.endPropertyChanges();
-    
+
     // return to pool...
     if (this.get('isPooled')) SC.Timer.returnTimerToPool(this);
     return this ;
   },
-  
+
   /**
     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}
   */
   fire: function() {
@@ -349,7 +351,7 @@ SC.Timer = SC.Object.extend(
 
     // now perform the fire action unless paused.
     if (!this.get('isPaused')) this.performAction() ;
-    
+
      // reschedule the timer if needed...
      if (next > last) {
        this.schedule();
@@ -364,7 +366,7 @@ SC.Timer = SC.Object.extend(
   */
   performAction: function() {
     var typeOfAction = SC.typeOf(this.action);
-    
+
     // if the action is a function, just try to call it.
     if (typeOfAction == SC.T_FUNCTION) {
       this.action.call((this.target || this), this) ;
@@ -391,59 +393,59 @@ SC.Timer = SC.Object.extend(
       }
     }
   },
-  
+
   init: function() {
     sc_super();
-    
+
     // convert startTime and until to times if they are dates.
     if (this.startTime instanceof Date) {
       this.startTime = this.startTime.getTime() ;
     }
-    
+
     if (this.until instanceof Date) {
       this.until = this.until.getTime() ;
     }
   },
-  
+
   /** @private - Default values to reset reused timers to. */
   RESET_DEFAULTS: {
-    target: null, action: null, 
+    target: null, action: null,
     isPooled: NO, isPaused: NO, isScheduled: NO, isValid: YES,
     interval: 0, repeats: NO, until: null,
     startTime: null, lastFireTime: 0
   },
-  
-  /** 
-    Resets the timer settings with the new settings.  This is the method 
+
+  /**
+    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 
+    call this method yourself, though you could override it if you need to
     reset additonal properties when a timer is reused.
-    
+
     @params {Hash} props properties to copy over
     @returns {SC.Timer} receiver
   */
   reset: function(props) {
     if (!props) props = SC.EMPTY_HASH;
-    
-    // note: we copy these properties manually just to make them fast.  we 
-    // don't expect you to use observers on a timer object if you are using 
+
+    // note: we copy these properties manually just to make them fast.  we
+    // don't expect you to use observers on a timer object if you are using
     // pooling anyway so this won't matter.  Still notify of property change
     // on fireTime to clear its cache.
     this.propertyWillChange('fireTime');
     var defaults = this.RESET_DEFAULTS ;
     for(var key in defaults) {
-      if (!defaults.hasOwnProperty(key)) continue ; 
+      if (!defaults.hasOwnProperty(key)) continue ;
       this[key] = SC.none(props[key]) ? defaults[key] : props[key];
     }
     this.propertyDidChange('fireTime');
     return this ;
   },
-    
+
   // ..........................................................
   // TIMER QUEUE SUPPORT
-  // 
+  //
 
-  /** @private - removes the timer from its current timerQueue if needed. 
+  /** @private - removes the timer from its current timerQueue if needed.
     return value is the new "root" timer.
   */
   removeFromTimerQueue: function(timerQueueRoot) {
@@ -457,11 +459,11 @@ SC.Timer = SC.Object.extend(
     this._timerQueuePrevious = this._timerQueueNext = null ;
     return (timerQueueRoot === this) ? next : timerQueueRoot ;
   },
-  
+
   /** @private - schedules the timer in the queue based on the runtime. */
   scheduleInTimerQueue: function(timerQueueRoot, runTime) {
     this._timerQueueRunTime = runTime ;
-    
+
     // find the place to begin
     var beforeNode = timerQueueRoot;
     var afterNode = null ;
@@ -474,18 +476,18 @@ SC.Timer = SC.Object.extend(
       afterNode._timerQueueNext = this ;
       this._timerQueuePrevious = afterNode ;
     }
-    
+
     if (beforeNode) {
       beforeNode._timerQueuePrevious = this ;
       this._timerQueueNext = beforeNode ;
     }
-    
+
     // I am the new root if beforeNode === root
     return (beforeNode === timerQueueRoot) ? this : timerQueueRoot ;
   },
-  
-  /** @private 
-    adds the receiver to the passed array of expired timers based on the 
+
+  /** @private
+    adds the receiver to the passed array of expired timers based on the
     current time and then recursively calls the next timer.  Returns the
     first timer that is not expired.  This is faster than iterating through
     the timers because it does some faster cleanup of the nodes.
@@ -496,22 +498,22 @@ SC.Timer = SC.Object.extend(
     var next = this._timerQueueNext ;
     this._timerQueueNext = null;
     if (next) next._timerQueuePrevious = null;
-    return next ? next.collectExpiredTimers(timers, now) : null; 
+    return next ? next.collectExpiredTimers(timers, now) : null;
   }
-  
+
 }) ;
 
 /** @scope SC.Timer */
 
-/*  
-  Created a new timer with the passed properties and schedules it to 
+/*
+  Created a new timer with the passed properties and schedules it to
   execute.  This is the same as calling SC.Time.create({ props }).schedule().
-  
-  Note that unless you explicitly set isPooled to NO, this timer will be 
+
+  Note that unless you explicitly set isPooled to NO, this timer will be
   pulled from a shared memory pool of timers.  You cannot using bindings or
   observers on these timers as they may be reused for future timers at any
   time.
-  
+
   @params {Hash} props Any properties you want to set on the timer.
   @returns {SC.Timer} new timer instance.
 */
@@ -537,7 +539,7 @@ SC.Timer.timerFromPool = function(props) {
   return timer.reset(props) ;
 };
 
-/** 
+/**
   Returns a timer instance to the timer pool for later use.  This is done
   automatically when a timer is invalidated if isPooled is YES.
 */