sproutcore 0.9.1 → 0.9.2

data/frameworks/sproutcore/foundation/string.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // SproutCore -- JavaScript Application Framework
-// copyright 2006-2007, Sprout Systems, Inc. and contributors.
+// copyright 2006-2008, Sprout Systems, Inc. and contributors.
 // ==========================================================================
 
 // These are basic enhancements to the string class used throughout 
@@ -28,7 +28,7 @@ Object.extend(String.prototype,{
     
     // first, replace any ORDERED replacements.
     var str = this.gsub(/%@([0-9]+)/, function(m) {
-      return args[parseInt(m[1],0)-1] || ''; 
+      return (args[parseInt(m[1],0)-1] || '').toString(); 
     }) ;
 
     // now, replace any remaining %@ items.  Use this indexOf() method b/c
@@ -42,7 +42,9 @@ Object.extend(String.prototype,{
      loc = idx + 2 ; // 2 to skip '%@'.
      
      // add in replacement.
-     ret.push(args.shift()) ;
+     var value = args.shift() ;
+     if (value && value.toString) value = value.toString() ;
+     ret.push(value) ;
     }
     
     // include any remaining bits of the string.

data/frameworks/sproutcore/foundation/timer.js

@@ -0,0 +1,371 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2008 Sprout Systems, Inc.
+// ========================================================================
+
+require('Core') ;
+
+/**
+  @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,
+  
+  /**
+    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: function() {
+    return !this._invalid ;
+  }.property('isPaused'),
+  
+  /**
+    Returns the next time offset when the property will fire.
+    
+    This property changes automatically after a timer has fired.  If the 
+    timer is invalid this will return 0.
+    
+    @field
+    @type {Number}
+  */
+  fireTime: function() {
+    if (this._invalid || !this.get('isValid')) return 0;
+
+    var now = Date.now() ;
+    var start = this.get('startTime') || now ;
+    if (this.until && this.until > 0 && now >= this.until) return 0;
+
+    var interval = this.get('interval') ;
+    var cycle = Math.ceil(((now - start) / interval)+0.01) ;
+    if ((cycle > 1) && !this.repeats) return 0 ;
+
+    if (cycle < 1) cycle = 1 ;
+    return start + (cycle * interval) ;
+  }.property(),
+  
+  /**
+    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.propertyWillChange('isValid') ;
+    this._invalid = YES ;
+    SC.runLoop.cancelTimer(this) ;
+    this.propertyDidChange('isValid') ;
+    this.action = this.target = null ; // avoid memory leaks
+    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() {
+    if (this.get('isPaused') === NO) {
+      this.performAction() ;
+    }
+    
+    (this.repeats && (this.get('fireTime')>0)) ? this.schedule() : this.invalidate() ;
+  },
+
+  /**
+    Actually fires the action. You can override this method if you need
+    to change how the timer fires its action.
+  */
+  performAction: function() {
+    // if the action is a function, just try to call it.
+    if ($type(this.action) == 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 (this.action.indexOf('.') >= 0) {
+      var path = this.action.split('.') ;
+      var property = path.pop() ;
+
+      var target = SC.Object.objectForPropertyPath(path, window) ;
+      var action = (target.get) ? target.get(property) : target[property];
+      if (action && $type(action) == 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.app.sendAction(this.action, this.target, this) ;
+  },
+  
+  /**
+    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._invalid) {
+      this.set('isScheduled', YES) ;
+      SC.runLoop.scheduleTimer(this, this.get('fireTime')) ;
+    }
+    return this ;
+  },
+  
+  init: function() {
+    arguments.callee.base.call(this) ;
+    
+    // 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() ;
+    }
+    
+    // if start time was not set, get it from the run loop.
+    if (!this.startTime) this.startTime = SC.runLoop.get('startTime') ;
+  },
+  
+  // if the paused state changes, notify the runloop so that it can 
+  // reschedule its timeout.
+  _isPausedObserver: function() {
+    SC.runLoop.timerPausedStateDidChange(this) ;
+  }
+  
+}) ;
+
+/**
+  @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().
+  
+  @params {Hash} props Any properties you want to set on the timer.
+  @returns {SC.Timer} new timer instance.
+*/
+SC.Timer.schedule = function(props) {
+  return this.create(props).schedule() ;
+} ;
+
+

data/frameworks/sproutcore/foundation/undo_manager.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // SproutCore -- JavaScript Application Framework
-// copyright 2006-2007, Sprout Systems, Inc. and contributors.
+// copyright 2006-2008, Sprout Systems, Inc. and contributors.
 // ==========================================================================
 
 require('Core');

data/frameworks/sproutcore/foundation/unittest.js

@@ -1,8 +1,8 @@
 // script.aculo.us unittest.js v1.8.0, Tue Nov 06 15:01:40 +0300 2007
 
-// Copyright (c) 2005-2007 Thomas Fuchs (http://script.aculo.us, http://mir.aculo.us)
-//           (c) 2005-2007 Jon Tirsen (http://www.tirsen.com)
-//           (c) 2005-2007 Michael Schuerig (http://www.schuerig.de/michael/)
+// Copyright (c) 2005-2008 Thomas Fuchs (http://script.aculo.us, http://mir.aculo.us)
+//           (c) 2005-2008 Jon Tirsen (http://www.tirsen.com)
+//           (c) 2005-2008 Michael Schuerig (http://www.schuerig.de/michael/)
 //
 // script.aculo.us is freely distributable under the terms of an MIT-style license.
 // For details, see the script.aculo.us web site: http://script.aculo.us/

data/frameworks/sproutcore/foundation/utils.js

@@ -1,9 +1,9 @@
 // ==========================================================================
 // SproutCore -- JavaScript Application Framework
-// copyright 2006-2007, Sprout Systems, Inc. and contributors.
+// copyright 2006-2008, Sprout Systems, Inc. and contributors.
 // ==========================================================================
 
-// These are helpful utility functions.
+// These are helpful utility functions for calculating range and rect values
 
 
 Object.extend(SC, 
@@ -66,12 +66,171 @@ Object.extend(SC,
     @returns {Boolean} true if rects match
    */
   rectsEqual: function(r1, r2, delta) {
+    if (!r1 || !r2) return (r1 == r2) ;
+    
     if (delta == null) delta = 0.1;
     if (Math.abs(r1.y - r2.y) > delta) return false ; 
     if (Math.abs(r1.x - r2.x) > delta) return false ; 
     if (Math.abs(r1.width - r2.width) > delta) return false ; 
     if (Math.abs(r1.height - r2.height) > delta) return false ; 
     return true ;
+  },
+  
+  /** Returns the insersection between two rectangles. 
+  
+    @param r1 {Rect} The first rect
+    @param r2 {Rect} the second rect
+    @returns {Rect} the intersection rect.  width || height will be 0 if they do not interset.
+  */
+  intersectRects: function(r1, r2) {
+    // find all four edges
+    var ret = {
+      x: Math.max(SC.minX(r1), SC.minX(r2)),
+      y: Math.max(SC.minY(r1), SC.minY(r2)),
+      width: Math.min(SC.maxX(r1), SC.maxX(r2)),
+      height: Math.min(SC.maxY(r1), SC.maxY(r2))
+    } ;
+    
+    // convert edges to w/h
+    ret.width = Math.max(0, ret.width - ret.x) ;
+    ret.height = Math.max(0, ret.height - ret.y) ;
+    return ret ;
+  },
+  
+  /** Returns the union between two rectangles
+  
+    @param r1 {Rect} The first rect
+    @param r2 {Rect} The second rect
+    @returns {Rect} The union rect.
+  */
+  unionRects: function(r1, r2) {
+    // find all four edges
+    var ret = {
+      x: Math.min(SC.minX(r1), SC.minX(r2)),
+      y: Math.min(SC.minY(r1), SC.minY(r2)),
+      width: Math.max(SC.maxX(r1), SC.maxX(r2)),
+      height: Math.max(SC.maxY(r1), SC.maxX(r2))
+    } ;
+    
+    // convert edges to w/h
+    ret.width = Math.max(0, ret.width - ret.x) ;
+    ret.height = Math.max(0, ret.height - ret.y) ;
+    return ret ;
+  },
+  
+  /** Duplicates the passed rect.  
+  
+    This is faster than Object.clone(). 
+    
+    @param r {Rect} The rect to clone.
+    @returns {Rect} The cloned rect
+  */
+  cloneRect: function(r) {
+    return { x: r.x, y: r.y, width: r.width, height: r.height } ;
+  },
+  
+  
+  /** Finds the absolute viewportOffset for a given element.
+    This method is more accurate than the version provided by prototype.
+    
+    @param el The DOM element
+    @returns {Point} A hash with x,y offsets.
+  */
+  viewportOffset: function(el) {
+    var valueL = 0 ; var valueT = 0;
+
+    // add up all the offsets for the element.
+    var element = el ;
+    do {
+      valueT += (element.offsetTop  || 0) + (element.clientTop  || 0);
+      valueL += (element.offsetLeft || 0) + (element.clientLeft || 0);
+
+      // bizarely for FireFox if your offsetParent has a border, then it can 
+      // impact the offset. 
+      if (SC.Platform.Firefox) {
+        var overflow = Element.getStyle(element, 'overflow') ;
+        if (overflow !== 'visible') {
+          var left = parseInt(Element.getStyle(element, 'borderLeftWidth'),0) || 0 ;
+          var top = parseInt(Element.getStyle(element, 'borderTopWidth'),0) || 0 ;
+          if (el !== element) {
+            left *= 2; top *= 2 ;
+          }
+          valueL += left; valueT += top ;
+        }
+      }
+
+      // Safari fix
+      if (element.offsetParent == document.body &&
+        Element.getStyle(element, 'position') == 'absolute') break;
+
+
+
+    } while (element = element.offsetParent);
+
+    element = el;
+    do {
+      if (!Prototype.Browser.Opera || element.tagName == 'BODY') {
+        valueT -= element.scrollTop  || 0;
+        valueL -= element.scrollLeft || 0;
+      }
+    } while (element = element.parentNode);
+
+    return { x: valueL, y: valueT } ;
+  },
+  
+  /** A Point at {0,0} */
+  ZERO_POINT: { x: 0, y: 0 },
+  
+  /** A zero length range at zero. */
+  ZERO_RANGE: { start: 0, length: 0 },
+
+  RANGE_NOT_FOUND: { start: 0, length: -1 },
+  
+  /** Returns true if the passed index is in the specified range */
+  valueInRange: function(value, range) {
+    return (range > 0) && (value >= range.start) && (value < (range.start + range.length));  
+  },
+  
+  /** Returns first value of the range. */
+  minRange: function(range) { return range.start; },
+  
+  /** Returns the first value outside of the range. */
+  maxRange: function(range) { return (range.length < 0) ? -1 : (range.start + range.length); },
+  
+  /** Returns the union of two ranges.  If one range is null, the other
+   range will be returned.  */
+  unionRanges: function(r1, r2) { 
+    if ((r1 == null) || (r1.length < 0)) return r2 ;
+    if ((r2 == null) || (r2.length < 0)) return r1 ;
+    
+    var min = Math.min(r1.start, r2.start) ;
+    var max = Math.max(SC.maxRange(r1), SC.maxRange(r2)) ;
+    return { start: min, length: max - min } ;
+  },
+  
+  /** Returns the intersection of the two ranges or SC.RANGE_NOT_FOUND */
+  intersectRanges: function(r1, r2) {
+    if ((r1 == null) || (r2 == null)) return SC.RANGE_NOT_FOUND ;
+    if ((r1.length < 0) || (r2.length < 0)) return SC.RANGE_NOT_FOUND;
+    var min = Math.max(SC.minRange(r1), SC.minRange(r2)) ;
+    var max = Math.min(SC.maxRange(r1), SC.maxRange(r2)) ;
+    if (max < min) return SC.RANGE_NOT_FOUND ;
+    return { start: min, length: max-min };
+  },
+  
+  /** Returns a clone of the range. */
+  cloneRange: function(r) { 
+    return { start: r.start, length: r.length }; 
+  },
+  
+  /** Returns true if the two passed ranges are equal.  A null value is
+    treated like RANGE_NOT_FOUND.
+  */
+  rangesEqual: function(r1, r2) {
+    if (r1===r2) return true ;
+    if (r1 == null) return r2.length < 0 ;
+    if (r2 == null) return r1.length < 0 ;
+    return (r1.start == r2.start) && (r1.length == r2.length) ;
   }
   
 }) ;