sproutit-sproutcore 1.0.203 → 1.0.20090721145236

data/frameworks/sproutcore/frameworks/foundation/system/timer.js

@@ -1,549 +0,0 @@
-// ========================================================================
-// SproutCore -- JavaScript Application Framework
-// Copyright ©2006-2008, Sprout Systems, Inc. and contributors.
-// Portions copyright ©2008 Apple, Inc.  All rights reserved.
-// ========================================================================
-
-/**
-  @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.
-  
-  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 
-  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.
-  
-  h2. 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.
-
-  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', 
-      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.
-  
-  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 
-  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.
-  
-  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
-  @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: YES,
-  
-  /**
-    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 waht 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: YES, 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) 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 ;
-};
-
-

data/frameworks/sproutcore/frameworks/foundation/system/user_defaults.js

@@ -1,165 +0,0 @@
-// ==========================================================================
-// Project:   SproutCore - JavaScript Application Framework
-// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
-//            Portions ©2008-2009 Apple, Inc. All rights reserved.
-// License:   Licened under MIT license (see license.js)
-// ==========================================================================
-
-/**
-  @class
-  
-  The UserDefaults object provides an easy way to store user preferences in
-  your application on the local machine.  You use this by providing built-in
-  defaults using the SC.userDefaults.defaults() method.  You can also
-  implement the UserDefaultsDelegate interface to be notified whenever a
-  default is required.  
-  
-  You should also set the userDomain property on the defaults on page load.
-  This will allow the UserDefaults application to store/fetch keys from 
-  localStorage for the correct user.
-  
-  You can also set an appDomain property if you want.  This will be 
-  automatically prepended to key names with no slashes in them.
-  
-  SC.userDefaults.getPath("global:contactInfo.userName");
-  
-  @extends SC.Object
-  @since SproutCore 1.0
-*/
-SC.UserDefaults = SC.Object.extend(/** @scope SC.UserDefaults.prototype */ {
-  
-  /** 
-    the default domain for the user.  This will be used to store keys in
-    local storage.  If you do not set this property, the wrong values may be
-    returned.
-  */
-  userDomain: null,
-  
-  /**
-    The default app domain for the user.  Any keys that do not include a 
-    slash will be prefixed with this app domain key when getting/setting.
-  */
-  appDomain: null,
-  
-  /** @private
-    Defaults.  These will be used if not defined on localStorage.
-  */
-  _defaults: null,
-  
-  /**
-    Invoke this method to set the builtin defaults.  This will cause all
-    properties to change.
-  */
-  defaults: function(newDefaults) {
-    this._defaults = newDefaults ;
-    this.allPropertiesDidChange();
-  },
-  
-  /**
-    Attempts to read a user default from local storage.  If not found on 
-    localStorage, use the the local defaults, if defined.  If the key passed
-    does not include a slash, then add the appDomain or use "app/".
-    
-    @param {String} keyName
-    @returns {Object} read value
-  */
-  readDefault: function(keyName) {
-    var ret= undefined ;
-    
-    // namespace keyname
-    if (keyName.indexOf('/')) {
-      var domain = this.get('appDomain') || 'app';
-      keyName = [domain, keyName].join(':');
-    } 
-    
-    var user = this.get('userDomain') || '' ;
-    var userKeyName = [user,keyName].join('@');
-
-    // look into recently written values
-    if (this._written) ret = this._written[userKeyName];
-    
-    // attempt to read from localStorage
-    var localStorage = window.localStorage ;
-    if (!localStorage && window.globalStorage) {
-      localStorage = window.globalStorage[window.location.hostname];
-    }
-    if (localStorage) {
-      ret = localStorage[["SC.UserDefaults",userKeyName].join('@')];
-      if (!SC.none(ret)) {
-        try {
-          ret = SC.json.decode(ret);
-        } 
-        catch(e) {
-          ret = null;
-        }
-      }
-    }
-    
-    // if not found in localStorage, try to notify delegate
-    var del =this.delegate ;
-    if (del && del.userDefaultsNeedsDefault) {
-      ret = del.userDefaultsNeedsDefault(this, keyName, userKeyName);
-    }
-    
-    // if not found in localStorage or delegate, try to find in defaults
-    if ((ret===undefined) && this._defaults) {
-      ret = this._defaults[userKeyName] || this._defaults[keyName];
-    }
-    
-    return ret ;
-  },
-  
-  /**
-    Attempts to write the user default to local storage or at least saves them
-    for now.  Also notifies that the value has changed.
-    
-    @param {String} keyName
-    @param {Object} value
-    @returns {SC.UserDefault} receiver
-  */
-  writeDefault: function(keyName, value) {
-    // namespace keyname
-    if (keyName.indexOf('/')) {
-      var domain = this.get('appDomain') || 'app';
-      keyName = [domain, keyName].join(':');
-    } 
-    
-    var user = this.get('userDomain') || '' ;
-    var userKeyName = [user,keyName].join('@');
-
-    // save to local hash
-    var written = this._written ;
-    if (!written) written = this._written = {};
-    written[userKeyName] = value ;
-    
-    // save to local storage
-    var localStorage = window.localStorage ;
-    if (!localStorage && window.globalStorage) {
-      localStorage = window.globalStorage[window.location.hostname];
-    }
-    if (localStorage) {
-      localStorage[["SC.UserDefaults",userKeyName].join('@')] = SC.json.encode(value);
-    }
-    
-    // also notify delegate
-    var del = this.delegate;
-    if (del && del.userDefaultsDidChange) {
-      del.userDefaultsDidChange(this, keyName, value, userKeyName);
-    }
-    
-    return this ;
-  },
-  
-  unknownProperty: function(key, value) {
-    if (value === undefined) {
-      return this.readDefault(key) ;
-    } else {
-      this.writeDefault(key, value);
-      return value ;
-    }
-  }
-  
-});
-
-/** global user defaults. */
-SC.userDefaults = SC.UserDefaults.create();