sproutcore 0.9.1 → 0.9.2

data/frameworks/sproutcore/mixins/delegate_support.js

@@ -0,0 +1,66 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2008 Sprout Systems, Inc.
+// ========================================================================
+
+/**
+  @namespace
+  
+  Support methods for the Delegate design pattern.
+  
+  The Delegate design pattern makes it easy to delegate a portion of your 
+  application logic to another object.  This is most often used in views to 
+  delegate various application-logic decisions to controllers in order to 
+  avoid having to bake application-logic directly into the view itself.
+  
+  The methods provided by this mixin make it easier to implement this pattern
+  but they are not required to support delegates.
+  
+  h2. The Pattern
+  
+  The delegate design pattern typically means that you provide a property,
+  usually ending in "delegate", that can be set to another object in the 
+  system.  
+  
+  When events occur or logic decisions need to be made that you would prefer
+  to delegate, you can call methods on the delegate if it is set.  If the 
+  delegate is not set, you should provide some default functionality instead.
+  
+  Note that typically delegates are not observable, hence it is not necessary
+  to use get() to retrieve the value of the delegate.
+  
+*/
+SC.DelegateSupport = {  
+  
+  /**
+    Invokes the named method on the delegate that you pass.  If no delegate
+    is defined or if the delegate does not implement the method, then a 
+    method of the same name on the receiver will be called instead.  
+    
+    You can pass any arguments you want to pass onto the delegate after the
+    delegate and methodName.
+    
+    @param {Object} delegate a delegate object.  May be null.
+    @param {String} methodName a method name
+    @param {*} args (OPTIONAL) any additional arguments
+    
+    @returns value returned by delegate
+  */
+  invokeDelegateMethod: function(delegate, methodName, args) {
+    args = $A(arguments); args = args.slice(2, args.length) ;
+    if (!delegate || !delegate[methodName]) delegate = this ;
+    return delegate[methodName].apply(delegate, args) ;
+  },
+  
+  /**
+    Gets the named property from the delegate if the delegate exists and it
+    defines the property.  Otherwise, gets the property from the receiver.
+    
+    @param {Object} delegate the delegate or null
+    @param {String} key the property to get.
+  */
+  getDelegateProperty: function(delegate, key) {
+    return (delegate && (delegate[key] != null)) ? delegate.get(key) : this.get(key) ;
+  }
+  
+};

data/frameworks/sproutcore/{foundation → mixins}/observable.js

@@ -1,11 +1,11 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 /**
-  @namespace Implements Key-Value Observing
-
+  @namespace 
+  
   Key-Value Observing is one of the fundamental ways that models, controllers
   and views communicate with each other in a SproutCore application.  Any 
   object that has this module applied to it can be used in KVO-operations.
@@ -160,6 +160,15 @@ SC.Observable = {
     return ret ;
   },  
 
+  /**
+    sets the property only if the passed value is different from the
+    current value.  Depending on how expensive a get() is on this property,
+    this may be more efficient.
+  */
+  setIfChanged: function(key, value) {
+    return (this.get(key) != value) ? this.set(key, value) : value ;
+  },
+  
   /**  
     use this to automatically navigate a property path.
   */
@@ -339,6 +348,19 @@ SC.Observable = {
   addProbe: function(key) { this.addObserver(key,logChange); },
   removeProbe: function(key) { this.removeObserver(key,logChange); },
 
+  /**
+    Logs the named properties to the console.
+    
+    @param propertyNames one or more property names
+  */
+  logProperty: function() {
+    var props = $A(arguments) ;
+    for(var idx=0;idx<props.length; idx++) {
+      var prop = props[idx] ;
+      console.log('%@:%@: '.fmt(this._guid, prop), this.get(prop)) ;
+    }
+  },
+  
   /**  
     This method will listen for the observed value to change one time and 
     then will remove itself.  You can also set an optional timeout that
@@ -355,13 +377,13 @@ SC.Observable = {
     var handler = function(theTarget,theKey,theValue,didTimeout) {
       func(theTarget,theKey,theValue,didTimeout) ;
       target.removeObserver(key,handler) ;
-      if (timeoutObject) { clearTimeout(timeoutObject); }
+      if (timeoutObject) { timeoutObject.invalidate(); }
     } ;
 
     target.addObserver(key,handler) ;
-    if (timeout) timeoutObject = setTimeout(function() {
+    if (timeout) timeoutObject = function() {
       handler(target,key,target.get(key),true) ;
-    }, timeout) ;
+    }.invokeLater(this, timeout) ;
 
     handler.cancel = function() { target.removeObserver(key,handler); } ;
     return handler ;
@@ -510,3 +532,151 @@ SC.Observable = {
   }
     
 } ;
+
+// ........................................................................
+// FUNCTION ENHANCEMENTS
+//
+// Enhance function.
+Object.extend(Function.prototype,{
+  
+  // Declare a function as a property.  This makes it something that can be
+  // accessed via get/set.
+  property: function() {
+    this.dependentKeys = $A(arguments) ; 
+    this.isProperty = true; return this; 
+  },
+  
+  // Declare that a function should observe an object at the named path.  Note
+  // that the path is used only to construct the observation one time.
+  observes: function(propertyPaths) { 
+    this.propertyPaths = $A(arguments); 
+    return this;
+  },
+  
+  typeConverter: function() {
+    this.isTypeConverter = true; return this ;
+  },
+  
+  /**
+    Creates a timer that will execute the function after a specified 
+    period of time.
+    
+    If you pass an optional set of arguments, the arguments will be passed
+    to the function as well.  Otherwise the function should have the 
+    signature:
+    
+    {{{
+      function functionName(timer)
+    }}}
+
+    @param interval {Number} the time to wait, in msec
+    @param target {Object} optional target object to use as this
+    @returns {SC.Timer} scheduled timer
+  */
+  invokeLater: function(target, interval) {
+    if (interval === undefined) interval = 1 ;
+    var f = this;
+    if (arguments.length > 2) {
+      var args =$A(arguments).slice(2,arguments.length);
+      args.unshift(target);
+      f = f.bind.apply(f, args) ;
+    }
+    return SC.Timer.schedule({ target: target, action: f, interval: interval });
+  }    
+  
+}) ;
+
+// ........................................................................
+// OBSERVER QUEUE
+//
+// This queue is used to hold observers when the object you tried to observe
+// does not exist yet.  This queue is flushed just before any property 
+// notification is sent.
+SC.Observers = {
+  queue: {},
+  
+  addObserver: function(propertyPath, func) {
+    // try to get the tuple for this.
+    if (typeof(propertyPath) == "string") {
+      var tuple = SC.Object.tupleForPropertyPath(propertyPath) ;
+    } else {
+      var tuple = propertyPath; 
+    }
+    
+    if (tuple) {
+      tuple[0].addObserver(tuple[1],func) ;
+    } else {
+      var ary = this.queue[propertyPath] || [] ;
+      ary.push(func) ;
+      this.queue[propertyPath] = ary ;
+    }
+  },
+  
+  removeObserver: function(propertyPath, func) {
+    var tuple = SC.Object.tupleForPropertyPath(propertyPath) ;
+    if (tuple) {
+      tuple[0].removeObserver(tuple[1],func) ;
+    }
+    
+    var ary = this.queue[propertyPath] ;
+    if (ary) {
+      ary = ary.without(func) ;
+      this.queue[propertyPath] = ary ;
+    }
+  },
+  
+  flush: function() {
+    var newQueue = {} ;
+    for(var path in this.queue) {
+      var funcs = this.queue[path] ;
+      var tuple = SC.Object.tupleForPropertyPath(path) ;
+      if (tuple) {
+        var loc = funcs.length ;
+        while(--loc >= 0) {
+          var func = funcs[loc] ;
+          tuple[0].addObserver(tuple[1],func) ;
+        }
+      } else newQueue[path] = funcs ;
+    }
+    
+    // set queue to remaining items
+    this.queue = newQueue ; 
+  }
+} ;
+
+// ........................................................................
+// NOTIFCATION QUEUE
+//
+// Property notifications are placed into this queue first and then processed
+// to keep the stack size down.
+SC.NotificationQueue = {
+  queue: [],
+  maxFlush: 5000, // max time you can spend flushing before we reschedule.
+  _flushing: false,
+  add: function(target, func, args) { this.queue.push([target, func, args]);},
+  flush: function(force) {
+    if (this._flushing && !force) return ;
+    this._flushing = true ;
+    
+    var start = new Date().getTime() ;
+    var now = start ;
+    var n = null ;
+    while(((now - start) < this.maxFlush) && (n = this.queue.pop())) { 
+      try {
+        var t = n[0] || n[1] ;
+        n[1].apply(t,n[2]) ;
+      }
+      catch(e) {
+        console.log("Exception while notify("+n[2]+"): " + e) ;
+      } // catch  
+      now = Date.now() ;
+    }
+    this._flushing = false ;
+    
+    if (this.queue.length > 0) { 
+      this.invokeLater(this._reflush, 1) ;
+    }
+  },
+  
+  _reflush: function() { SC.NotificationQueue.flush(); }
+} ;

data/frameworks/sproutcore/mixins/scrollable.js

@@ -0,0 +1,245 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2008 Sprout Systems, Inc.
+// ========================================================================
+
+/**
+  @namespace
+
+  Any views you implement that are scrollable should include this mixin to
+  provide basic support for scrolling actions.  You can also override any 
+  of these methods as needed for your own specific behaviors.
+  
+  Often times instead of adding SC.Scrollable to your view, you should
+  place your view inside of an SC.ScrollView.  See that class for more 
+  info.
+  
+  Note that isScrollable must always be true.
+
+*/
+SC.Scrollable = {
+  
+  /** Informs the view system that the receiver is scrollable.
+  
+    Must always be true.
+  */
+  isScrollable: true,
+  
+  /** 
+    Amount to scroll one vertical line.
+  
+    Used by the default implementation of scrollDownLine() and scrollUpLine().  Defaults
+    to 20px.
+  */
+  verticalLineScroll: 20,
+  
+  /**
+    Amount to scroll one horizontal line.
+  
+    Used by the default implementation of scrollLeftLine() and scrollRightLine(). Defaults
+    to 20px.
+  */
+  horizontalLineScroll: 20,
+  
+  /**
+    Amount to scroll one vertical page.
+    
+    Used by the default implementation of scrollUpPage() and scrollDownPage(). Defaults to
+    current innerFrame height.
+  */
+  verticalPageScroll: function() {
+    return this.get('innerFrame').height ;
+  }.property('innerFrame'),
+  
+  /**
+    Amount to scroll one horizontal page.
+    
+    Used by the default implementation of scrollLeftPage() and scrollRightPage().  Defaults
+    to current innerFrame width.
+  */
+  horizontalPageScroll: function() {
+    return this.get('innerFrame').width ;  
+  }.property('innerFrame'),
+  
+  /**
+    Returns true if the receiver has enough vertical content to require 
+    scrolling.
+    
+    If you do not want to allow vertical scrolling, override this to be false 
+    and set the appropriate CSS.
+    
+  */
+  hasVerticalScroller: function() {
+    return this.get('scrollFrame').height > this.get('innerFrame').height ;
+  }.property('scrollFrame'),
+  
+  /**
+    Returns true if the receiver has enough horizontal content to require 
+    scrolling.
+    
+    If you do not want to allow horizontal scrolling, override this to be 
+    false and set the appropriate CSS.
+    
+  */
+  hasHorizontalScroller: function() {
+    return this.get('scrollFrame').width > this.get('innerFrame').width ;
+  }.property('scrollFrame'),
+
+  /**
+    Scrolls the receiver in the horizontal and vertical directions by the 
+    amount specified, if allowed.
+    
+    @param {Point} amount the amount to scroll.  Must include x, y or both
+    @returns {Point} the actual amount scrolled.
+  */
+  scrollBy: function(amount) {
+    var sf = this.get('scrollFrame') ;
+    var f = this.get('innerFrame') ;
+
+    if (!this.get('hasVerticalScroller')) amount.y = 0 ;
+    if (sf.height <= f.height) amount.y = 0 ;
+    
+    if (!this.get('hasHorizontalScroller')) amount.x = 0 ; 
+    if (sf.width <= f.width) amount.x = 0 ;
+
+    // compute new sf
+    var newSf = { x: sf.x - (amount.x || 0), y: sf.y - (amount.y || 0) } ;
+    newSf = this.set('scrollFrame', newSf) ;
+    return { x: newSf.x - sf.x, y: newSf.y - sf.y }; 
+  },
+
+  /**
+    Scrolls the receiver to the specified x,y coordinate
+  */
+  scrollTo: function(x,y) {
+    console.log('scrollTo(%@,%@)'.fmt(x,y)) ;
+    this.set('scrollFrame', { x: 0-x, y: 0-y }) ;  
+  },
+  
+  /**
+    Scroll the view to make the passed frame visible.
+    
+    Frame must be relative to the receiver's offsetParent.
+    
+    @param {SC.View} view the view you want to make visible
+  */
+  scrollToVisible: function(view) {
+
+    // get frames and convert them to proper offsets
+    var f = this.get('innerFrame') ;
+    var sf = this.get('scrollFrame') ;
+    
+    // frame of the view, relative to the top of the scroll frame
+    var vf = this.convertFrameFromView(view.get('frame'), view) ;
+    vf.x -= (f.x + sf.x); vf.y -= (f.y + sf.y);
+    
+    // first visible origin
+    var vo = { 
+      x: 0-sf.x, 
+      y: 0-sf.y, 
+      width: f.width, 
+      height: f.height 
+    };
+
+    // if top edge is not visible, shift origin
+    vo.y += Math.max(0, SC.minY(vo) - SC.minY(vf)) ;
+    vo.x += Math.max(0, SC.minX(vo) - SC.minX(vf)) ;
+
+    // if bottom edge is not visible, shift origin
+    vo.y += Math.max(0, SC.maxY(vf) - SC.maxY(vo)) ;
+    vo.x += Math.max(0, SC.maxX(vf) - SC.maxX(vo)) ;
+
+    // scroll to that origin.
+    this.scrollTo(vo.x, vo.y) ;
+  },
+  
+  /**
+    Scrolls the receiver down one line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollDownLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return this.scrollBy({ y: this.get('verticalLineScroll')*lines }).y ;
+  },
+
+  /**
+    Scrolls the receiver down up line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollUpLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return 0-this.scrollBy({ y: 0-this.get('verticalLineScroll')*lines }).y ;
+  },
+
+  /**
+    Scrolls the receiver right one line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollRightLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return this.scrollTo({ y: this.get('horizontalLineScroll')*lines }).x ;
+  },
+
+  /**
+    Scrolls the receiver left one line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollLeftLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return 0-this.scrollTo({ y: 0-this.get('horizontalLineScroll')*lines }).x ;
+  },
+
+  /**
+    Scrolls the receiver down one page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollDownPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return this.scrollBy({ y: this.get('verticalPageScroll')*pages }).y ;
+  },
+
+  /**
+    Scrolls the receiver down up page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollUpPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return 0-this.scrollBy({ y: 0-this.get('verticalPageScroll')*pages }).y ;
+  },
+
+  /**
+    Scrolls the receiver right one page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollRightPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return this.scrollTo({ y: this.get('horizontalPageScroll')*pages }).x ;
+  },
+
+  /**
+    Scrolls the receiver left one page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollLeftPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return 0-this.scrollTo({ y: 0-this.get('horizontalPageScroll')*pages }).x ;
+  }
+  
+} ;
+