sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/core_foundation/system/theme.js

@@ -0,0 +1,316 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/** @class
+  Represents a theme, and is also the core theme in which SC looks for
+  other themes.
+
+  If an SC.View has a theme of "ace", it will look in its parent's theme
+  for the theme "ace". If there is no parent--that is, if the view is a
+  frame--it will look in SC.Theme for the named theme. To find a theme,
+  it calls find(themeName) on the theme.
+
+  To be located, themes must be registered either as a root theme (by
+  calling SC.Theme.addTheme) or as a child theme of another theme (by
+  calling theTheme.addTheme).
+
+  All themes are instances. However, new instances based on the current
+  instance can always be created: just call .create(). This method is used
+  by SC.View when you name a theme that doesn't actually exist: it creates
+  a theme based on the parent theme.
+
+  Renderers
+  ---------------------------
+  Themes are used to keep track of theme class names and, more important,
+  to keep track of renderers.
+
+  Renderers are added to a theme using theme.addRenderer(theRenderer). After
+  this has been done, they may be instantiated using theme.renderer(rendererName).
+
+  Instantiating with renderer() instantiates a version of that renderer
+  specialized for this specific theme-- not any parent themes. The renderer
+  will include all class names for _this_ theme. This means that you can
+  theme controls differently without overriding any renderers: just subclass
+  the original theme that _has_ the renderers, give it its own name, and
+  all renderers will render with that name as a class name.
+
+  Locating Child Themes
+  ----------------------------
+  Locating child themes is relatively simple for the most part: it looks in
+  its own "themes" property, which is an object inheriting from its parent's
+  "themes" set, so it includes all parent themes.
+
+  However, it does _not_ include global themes. This is because, when find()
+  is called, it wants to ensure any child theme is specialized. That is, the
+  child theme should include all class names of the base class theme. This only
+  makes sense if the theme really is a child theme of the theme or one of its
+  base classes; if the theme is a global theme, those class names should not
+  be included.
+
+  This makes sense logically as well, because when searching for a renderer,
+  it will locate it in any base theme that has it, but that doesn't mean
+  class names from the derived theme shouldn't be included.
+
+  @extends SC.Object
+  @since SproutCore 1.1
+  @author Alex Iskander
+*/
+SC.Theme = {
+  /**
+    Walks like a duck.
+  */
+  isTheme: YES,
+
+  /**
+    Class names for the theme.
+
+    These class names include the name of the theme and the names
+    of all parent themes. You can also add your own.
+   */
+  classNames: SC.CoreSet.create(),
+
+  /**
+    @private
+    A helper to extend class names with another set of classnames. The
+    other set of class names can be a hash, an array, a Set, or a space-
+    delimited string.
+  */
+  _extend_class_names: function(classNames) {
+    // class names may be a CoreSet, array, string, or hash
+    if (classNames) {
+      if (SC.typeOf(classNames) === SC.T_HASH && !classNames.isSet) {
+        for (var className in classNames) {
+          if (classNames[className]) this.classNames.add(className);
+          else this.classNames.remove(className);
+        }
+      } else if (typeof classNames === "string") {
+        this.classNames.addEach(classNames.split(' '));
+      } else {
+        // it must be an array or another CoreSet... same difference.
+        this.classNames.addEach(classNames);
+      }
+    }
+  },
+
+  /**
+    @private
+    Helper method that extends this theme with some extra properties.
+
+    Used during Theme.create();
+   */
+  _extend_self: function(ext) {
+    if (ext.classNames) this._extend_class_names(ext.classNames);
+
+    // mixin while enabling sc_super();
+    var key, value, cur;
+    for (key in ext) {
+      if (key === 'classNames') continue; // already handled.
+      if (!ext.hasOwnProperty(key)) continue;
+
+      value = ext[key];
+      if (value instanceof Function && !value.base && (value !== (cur=this[key]))) {
+        value.base = cur;
+      }
+
+      this[key] = value;
+    }
+  },
+
+  /**
+    Creates a new theme based on this one. The name of the new theme will
+    be added to the classNames set.
+  */
+  create: function() {
+    var result = SC.beget(this);
+    result.baseTheme = this;
+
+    // if we don't beget themes, the same instance would be shared between
+    // all themes. this would be bad: imagine that we have two themes:
+    // "Ace" and "Other." Each one has a "capsule" child theme. If they
+    // didn't have their own child themes hash, the two capsule themes
+    // would conflict.
+    if (this.themes === SC.Theme.themes) {
+      result.themes = {};
+    } else {
+      result.themes = SC.beget(this.themes);
+    }
+    
+    // we also have private ("invisible") child themes; look at invisibleSubtheme
+    // method.
+    result._privateThemes = {};
+
+    // the theme also specializes all renderers it creates so that they
+    // have the theme's classNames and have their 'theme' property set.
+    result._specializedRenderers = {};
+
+    // also, the theme specializes all child themes as they are created
+    // to ensure that all of the class names on this theme are included.
+    result._specializedThemes = {};
+
+    // we could put this in _extend_self, but we don't want to clone
+    // it for each and every argument passed to create().
+    result.classNames = SC.clone(this.classNames);
+
+    var args = arguments, len = args.length, idx, mixin;
+    for (idx = 0; idx < len; idx++) {
+      result._extend_self(args[idx]);
+    }
+
+    if (result.name) result.classNames.add(result.name);
+
+    return result;
+  },
+
+  /**
+    Creates a child theme based on this theme, with the given name,
+    and automatically registers it as a child theme.
+  */
+  subtheme: function(name) {
+    // extend the theme
+    var t = this.create({ name: name });
+
+    // add to our set of themes
+    this.addTheme(t);
+
+    // and return the theme class
+    return t;
+  },
+  
+  /**
+    Semi-private, only used by SC.View to create "invisible" subthemes. You
+    should never need to call this directly, nor even worry about.
+    
+    Invisible subthemes are only available when find is called _on this theme_;
+    if find() is called on a child theme, it will _not_ locate this theme.
+    
+    The reason for "invisible" subthemes is that SC.View will create a subtheme
+    when it finds a theme name that doesn't exist. For example, imagine that you 
+    have a parent view with theme "base", and a child view with theme "popup".
+    If no "popup" theme can be found inside "base", SC.View will call
+    base.subtheme. This will create a new theme with the name "popup",
+    derived from "base". Everyone is happy.
+    
+    But what happens if you then change the parent theme to "ace"? The view
+    will try again to find "popup", and it will find it-- but it will still be
+    a child theme of "base"; SC.View _needs_ to re-subtheme it, but it won't
+    know it needs to, because it has been found.
+  */
+  invisibleSubtheme: function(name) {
+    // extend the theme
+    var t = this.create({ name: name });
+
+    // add to our set of themes
+    this._privateThemes[name] = t;
+    
+    // and return the theme class
+    return t;
+  },
+  
+  //
+  // THEME MANAGEMENT
+  //
+
+  themes: {},
+
+  /**
+    Finds a theme by name within this theme (the theme must have
+    previously been added to this theme or a base theme by using addTheme, or
+    been registered as a root theme).
+
+    If the theme found is not a root theme, this will specialize the theme so
+    that it includes all class names for this theme.
+  */
+  find: function(themeName) {
+    if (this === SC.Theme) return this.themes[themeName];
+    var theme;
+
+    // if there is a private theme (invisible subtheme) by that name, use it
+    theme = this._privateThemes[themeName];
+    if (theme) return theme;
+
+    // if there is a specialized version (the theme extended with our class names)
+    // return that one
+    theme = this._specializedThemes[themeName];
+    if (theme) return theme;
+
+    // otherwise, we may need to specialize one.
+    theme = this.themes[themeName];
+    if (theme && !this._specializedThemes[themeName]) {
+      return (this._specializedThemes[themeName] = theme.create({ classNames: this.classNames }));
+    }
+
+    // and finally, if it is a root theme, we do nothing to it.
+    theme = SC.Theme.themes[themeName];
+    if (theme) return theme;
+
+    return null;
+  },
+
+  /**
+    Adds a child theme to the theme. This allows the theme to be located
+    by SproutCore views and such later.
+
+    Each theme is registered in the "themes" property by name. Calling
+    find(name) will return the theme with the given name.
+
+    Because the themes property is an object begetted from (based on) any
+    parent theme's "themes" property, if the theme cannot be found in this
+    theme, it will be found in any parent themes.
+  */
+  addTheme: function(theme) {
+    this.themes[theme.name] = theme;
+  },
+
+  /**
+    Adds a renderer to the theme. The renderer's name will be used to
+    keep track of it and identify it later.
+
+    The biggest responsibility of addRenderer is to ensure that renderer()
+    can be used to instantiate that renderer. If a renderer is not instantiated
+    through renderer(), it will not know its theme's classNames.
+  */
+  addRenderer: function(renderer) {
+    this[renderer.name] = renderer;
+  },
+
+   /**
+     Finds the named renderer and instantiates it, returning the result.
+     It also ensures it is using a version of the renderer specialized for
+     this theme. It keeps a cache of specialized versions of the renderer.
+
+     Any arguments after the name are passed on to the instantiated
+     renderer.
+   */
+  renderer: function(name) {
+    var renderer = this._specializedRenderers[name], base = this[name];
+    if (!renderer || renderer._specializedFrom !== base) {
+      if (!base) return null;
+
+      renderer = base.extend({ classNames: this.classNames, theme: this });
+    }
+
+    var args = SC.$A(arguments);
+    args.shift();
+    renderer = renderer.create.apply(renderer, args);
+    return renderer;
+  }
+};
+
+// SproutCore _always_ has its base theme. This is not quite
+// optimal, but the reasoning is because of test running: the
+// test runner, when running foundation unit tests, cannot load
+// the theme. As such, foundation must include default versions of
+// all of its renderers, and it does so in BaseTheme. All SproutCore
+// controls have renderers in BaseTheme.
+SC.BaseTheme = SC.Theme.create({
+  name: '' // it is a base class, and doesn't need a class name or such
+});
+
+// however, SproutCore does need a default theme, even if no
+// actual theme is loaded.
+SC.Theme.themes['sc-base'] = SC.BaseTheme;
+SC.defaultTheme = 'sc-base';

data/lib/frameworks/sproutcore/frameworks/core_foundation/system/timer.js

@@ -0,0 +1,548 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @class
+
+  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 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
+  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.
+
+  ## 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.
+
+
+  @extends SC.Object
+  @author Charles Jolley
+  @version 1.0
+  @since version 1.0
+*/
+SC.Timer = SC.Object.extend(
+/** @scope SC.Timer.prototype */ {
+
+  /**
+    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
+    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
+    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
+    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.
+
+    @type {Boolean}
+  */
+  isPaused: NO,
+
+  /**
+    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.
+
+    @field
+    @type {Boolean}
+  */
+  isValid: YES,
+
+  /**
+    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
+    cannot fire again.
+
+    @property {Time}
+  */
+  fireTime: function() {
+    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; }
+
+    // fire interval after start.
+    var interval = this.get('interval'), last = this.get('lastFireTime');
+    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 ;
+    }
+
+    // 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.
+
+    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,
+    // 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
+    // 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() {
+    this.beginPropertyChanges();
+    this.set('isValid', NO);
+    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() {
+
+    // this will cause the fireTime to recompute
+    var last = Date.now();
+    this.set('lastFireTime', last);
+
+    var next = this.get('fireTime');
+
+    // now perform the fire action unless paused.
+    if (!this.get('isPaused')) this.performAction() ;
+
+     // reschedule the timer if needed...
+     if (next > last) {
+       this.schedule();
+     } else {
+       this.invalidate();
+     }
+  },
+
+  /**
+    Actually fires the action. You can override this method if you need
+    to change how the timer fires its action.
+  */
+  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) ;
+
+    // otherwise, action should be a string.  If it has a period, treat it
+    // like a property path.
+    } else if (typeOfAction === SC.T_STRING) {
+      if (this.action.indexOf('.') >= 0) {
+        var path = this.action.split('.') ;
+        var property = path.pop() ;
+
+        var target = SC.objectForPropertyPath(path, window) ;
+        var action = target.get ? target.get(property) : target[property];
+        if (action && SC.typeOf(action) == SC.T_FUNCTION) {
+          action.call(target, this) ;
+        } else {
+          throw '%@: Timer could not find a function at %@'.fmt(this, this.action) ;
+        }
+
+      // otherwise, try to execute action direction on target or send down
+      // responder chain.
+      } else {
+        SC.RootResponder.responder.sendAction(this.action, this.target, this);
+      }
+    }
+  },
+
+  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,
+    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
+    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 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
+    // 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 ;
+      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.
+    return value is the new "root" timer.
+  */
+  removeFromTimerQueue: function(timerQueueRoot) {
+    var prev = this._timerQueuePrevious, next = this._timerQueueNext ;
+
+    if (!prev && !next && timerQueueRoot !== this) return timerQueueRoot ; // not in a queue...
+
+    // else, patch up to remove...
+    if (prev) prev._timerQueueNext = next ;
+    if (next) next._timerQueuePrevious = prev ;
+    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 ;
+    while(beforeNode && beforeNode._timerQueueRunTime < runTime) {
+      afterNode = beforeNode ;
+      beforeNode = beforeNode._timerQueueNext;
+    }
+
+    if (afterNode) {
+      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
+    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.
+  */
+  collectExpiredTimers: function(timers, now) {
+    if (this._timerQueueRunTime > now) return this ; // not expired!
+    timers.push(this);  // add to queue.. fixup next. assume we are root.
+    var next = this._timerQueueNext ;
+    this._timerQueueNext = null;
+    if (next) next._timerQueuePrevious = null;
+    return next ? next.collectExpiredTimers(timers, now) : null;
+  }
+
+}) ;
+
+/** @scope SC.Timer */
+
+/*
+  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
+  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.
+*/
+SC.Timer.schedule = function(props) {
+  // get the timer.
+  var timer ;
+  if (!props || SC.none(props.isPooled) || props.isPooled) {
+    timer = this.timerFromPool(props);
+  } else timer = this.create(props);
+  return timer.schedule();
+} ;
+
+/**
+  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.
+*/
+SC.Timer.timerFromPool = function(props) {
+  var timers = this._timerPool;
+  if (!timers) timers = this._timerPool = [] ;
+  var timer = timers.pop();
+  if (!timer) timer = this.create();
+  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.
+*/
+SC.Timer.returnTimerToPool = function(timer) {
+  if (!this._timerPool) this._timerPool = [];
+
+  this._timerPool.push(timer);
+  return this ;
+};
+
+