sproutcore 0.9.3 → 0.9.4

data/frameworks/sproutcore/mixins/array.js

@@ -28,7 +28,7 @@ SC.OUT_OF_RANGE_EXCEPTION = "Index out of range" ;
 SC.Array = {
 
 /**
-  @property {Number} length
+  @field {Number} length
   
   Your array must support the length property.  your replace methods should
   set this property whenever it changes.
@@ -92,7 +92,7 @@ SC.Array = {
   },
   
   /**
-    @property []
+    @field []
 
     This is the handler for the special array content property.  If you get
     this property, it will return this.  If you set this property it a new 

data/frameworks/sproutcore/mixins/observable.js

@@ -197,7 +197,7 @@ SC.Observable = {
     this may be more efficient.
   */
   setIfChanged: function(key, value) {
-    return (this.get(key) != value) ? this.set(key, value) : value ;
+    return (this.get(key) !== value) ? this.set(key, value) : value ;
   },
   
   /**  
@@ -236,6 +236,9 @@ SC.Observable = {
   
   /**  
     Increments the value of a property.
+    
+    @param key {String} property name
+    @returns {Number} new value of property
   */
   incrementProperty: function(key) { 
     return this.set(key,(this.get(key) || 0)+1); 
@@ -243,25 +246,35 @@ SC.Observable = {
 
   /**  
     decrements a property
+    
+    @param key {String} property name
+    @returns {Number} new value of property
   */
   decrementProperty: function(key) {
     return this.set(key,(this.get(key) || 0) - 1 ) ;
   },
 
   /**  
-    inverts a property.  Property should be a bool.
+    Inverts a property.  Property should be a bool.
+    
+    @param key {String} property name
+    @param value {Object} optional parameter for "true" value
+    @param alt {Object} optional parameter for "false" value
+    @returns {Object} new value
   */
   toggleProperty: function(key,value,alt) { 
     if (value === undefined) value = true ;
     if (alt == undefined) alt = false ;
     value = (this.get(key) == value) ? alt : value ;
-    this.set(key,value);
+    return this.set(key,value);
   },
 
   /**  
-  This is a generic property handler.  If you define it, it will be called
-  when the named property is not yet set in the object.  The default does
-  nothing.
+    Called whenever you try to get or set an undefined property.
+    
+    This is a generic property handler.  If you define it, it will be called
+    when the named property is not yet set in the object.  The default does
+    nothing.
   */
   unknownProperty: function(key,value) {
     if (!(value === undefined)) { this[key] = value; }
@@ -269,18 +282,55 @@ SC.Observable = {
   },
 
   /**  
-    Override to receive generic observation notices.
+    Generic property observer called whenever a property on the receiver 
+    changes.
+    
+    If you need to observe a large number of properties on your object, it
+    is sometimes more efficient to implement this observer only and then to
+    handle requests yourself.  Although this observer will be triggered 
+    more often than an observer registered on a specific property, it also
+    does not need to be registered which can make it faster to setup your 
+    object instance.
+    
+    You will often implement this observer using a switch statement on the
+    key parameter, taking appropriate action. 
+    
+    @param observer {null} no longer used; usually null
+    @param target {Object} the target of the change.  usually this
+    @param key {String} the name of the property that changed
+    @param value {Object} the new value of the property.
+    @returns {void}
   */
   propertyObserver: function(observer,target,key,value) {},
 
   /**  
-    You can wrap property changes with these methods to cause notifications
-    to be delivered only after groups are closed.
+    Begins a grouping of property changes.
+    
+    You can use this method to group property changes so that notifications
+    will not be sent until the changes are finished.  If you plan to make a 
+    large number of changes to an object at one time, you should call this 
+    method at the beginning of the changes to suspend change notifications.
+    When you are done making changes, all endPropertyChanges() to allow 
+    notification to resume.
+    
+    @returns {void}
   */
   beginPropertyChanges: function() {
     this._kvo().changes++ ;
   },
 
+  /**  
+    Ends a grouping of property changes.
+    
+    You can use this method to group property changes so that notifications
+    will not be sent until the changes are finished.  If you plan to make a 
+    large number of changes to an object at one time, you should call 
+    beginsPropertyChanges() at the beginning of the changes to suspend change 
+    notifications. When you are done making changes, call this method to allow 
+    notification to resume.
+    
+    @returns {void}
+  */
   endPropertyChanges: function() {
     var kvo = this._kvo() ;  kvo.changes--;
     if (kvo.changes <= 0) this._notifyPropertyObservers() ;
@@ -289,16 +339,18 @@ SC.Observable = {
   /**  
     Notify the observer system that a property is about to change.
 
-    Sometimes you need to change a value directly or indirectly without actually
-    calling get() or set() on it.  In this case, you can use this method and 
-    propertyDidChange() instead.  Calling these two methods together will notify all
-    observers that the property has potentially changed value.
+    Sometimes you need to change a value directly or indirectly without 
+    actually calling get() or set() on it.  In this case, you can use this 
+    method and propertyDidChange() instead.  Calling these two methods 
+    together will notify all observers that the property has potentially 
+    changed value.
     
-    Note that you must always call propertyWillChange and propertyDidChange as a pair.
-    If you do not, it may get the property change groups out of order and cause
-    notifications to be delivered more often than you would like.
+    Note that you must always call propertyWillChange and propertyDidChange as 
+    a pair.  If you do not, it may get the property change groups out of order 
+    and cause notifications to be delivered more often than you would like.
     
     @param key {String} The property key that is about to change.
+    @returns {void}
   */
   propertyWillChange: function(key) {
     this._kvo().changes++ ;
@@ -307,17 +359,19 @@ SC.Observable = {
   /**  
     Notify the observer system that a property has just changed.
 
-    Sometimes you need to change a value directly or indirectly without actually
-    calling get() or set() on it.  In this case, you can use this method and 
-    propertyWillChange() instead.  Calling these two methods together will notify all
-    observers that the property has potentially changed value.
+    Sometimes you need to change a value directly or indirectly without 
+    actually calling get() or set() on it.  In this case, you can use this 
+    method and propertyWillChange() instead.  Calling these two methods 
+    together will notify all observers that the property has potentially 
+    changed value.
     
-    Note that you must always call propertyWillChange and propertyDidChange as a pair.
-    If you do not, it may get the property change groups out of order and cause
-    notifications to be delivered more often than you would like.
+    Note that you must always call propertyWillChange and propertyDidChange as 
+    a pair. If you do not, it may get the property change groups out of order 
+    and cause notifications to be delivered more often than you would like.
     
     @param key {String} The property key that has just changed.
     @param value {Object} The new value of the key.  May be null.
+    @returns {void}
   */
   propertyDidChange: function(key,value) {
     this._kvo().changed[key] = value ;
@@ -328,9 +382,10 @@ SC.Observable = {
   /**
     Convenience method to call propertyWillChange/propertyDidChange.
     
-    Sometimes you need to notify observers that a property has changed value without
-    actually changing this value.  In those cases, you can use this method as a 
-    convenience instead of calling propertyWillChange() and propertyDidChange().
+    Sometimes you need to notify observers that a property has changed value 
+    without actually changing this value.  In those cases, you can use this 
+    method as a convenience instead of calling propertyWillChange() and 
+    propertyDidChange().
     
     @param key {String} The property key that has just changed.
     @param value {Object} The new value of the key.  May be null.
@@ -342,16 +397,36 @@ SC.Observable = {
   },
   
   /**  
-    This may be a simpler way to notify of changes if you are making a major
-    update or don't know exactly which properties have changed.  This ignores
-    property gorups.
+    Notifies all of observers of a property changes.
+    
+    Sometimes when you make a major update to your object, it is cheaper to
+    simply notify all observers that their property might have changed than
+    to figure out specifically which properties actually did change.
+    
+    In those cases, you can simply call this method to notify all property
+    observers immediately.  Note that this ignores property groups.
+    
+    @returns {void}
   */
   allPropertiesDidChange: function() {
     this._notifyPropertyObservers(true) ;
   },
 
   /**  
-    Add an observer
+    Adds an observer on a property.
+    
+    This is the core method used to register an observer for a property.
+    The observer can be either a simple function or an object and a method.
+    
+    Once you call this method, anytime the key's value is set, your observer
+    will be notified.  Note that the observers are triggered anytime the
+    value is set, regardless of whether it has actually changed.  Your
+    observer should be prepared to handle that.
+    
+    @param key {String} the key to observer
+    @param target {Object} the object holding the action to call.  May benull.
+    @param action {String,Function} the action to call.
+    @returns {void}
   */
   addObserver: function(key,func) {
     var kvo = this._kvo() ;
@@ -376,6 +451,28 @@ SC.Observable = {
 
   },
 
+  removeObserver: function(key,func) {
+    var kvo = this._kvo() ;
+
+    // if the key contains a '.', this is a chained observer.
+    key = key.toString() ;
+    var parts = key.split('.') ;
+    if (parts.length > 1) {
+      var chainObservers = kvo.chainObserver[key] || [] ;
+      var newObservers = [] ;
+      chainObservers.each(function(co) {
+        if (co.masterFunc != func) newObservers.push(co) ;
+      }) ;
+      kvo.chainObservers[key] = newObservers ;
+
+    // otherwise, just like a normal observer.
+    } else {
+      var observers = kvo.observers[key] || [] ;
+      observers = observers.without(func) ;
+      kvo.observers[key] = observers ;
+    }
+  },
+
   addProbe: function(key) { this.addObserver(key,logChange); },
   removeProbe: function(key) { this.removeObserver(key,logChange); },
 
@@ -420,28 +517,6 @@ SC.Observable = {
     return handler ;
   },
 
-  removeObserver: function(key,func) {
-    var kvo = this._kvo() ;
-
-    // if the key contains a '.', this is a chained observer.
-    key = key.toString() ;
-    var parts = key.split('.') ;
-    if (parts.length > 1) {
-      var chainObservers = kvo.chainObserver[key] || [] ;
-      var newObservers = [] ;
-      chainObservers.each(function(co) {
-        if (co.masterFunc != func) newObservers.push(co) ;
-      }) ;
-      kvo.chainObservers[key] = newObservers ;
-
-    // otherwise, just like a normal observer.
-    } else {
-      var observers = kvo.observers[key] || [] ;
-      observers = observers.without(func) ;
-      kvo.observers[key] = observers ;
-    }
-  },
-
   /**
     Use this to indicate that one key changes if other keys it depends on 
     change.

data/frameworks/sproutcore/panes/dialog.js

@@ -8,7 +8,7 @@ require('panes/overlay') ;
 SC.DIALOG_PANE = 'dialog';
 SC.DialogPaneView = SC.OverlayPaneView.extend({
   
-  emptyElement: '<div class="pane dialog-pane"><div class="pane-wrapper"><div class="pane-root"></div></div>',
+  emptyElement: '<div class="pane dialog-pane"><div class="shadow pane-wrapper"><div class="pane-root"></div><div class="top-left-edge"></div><div class="top-edge"></div><div class="top-right-edge"></div><div class="right-edge"></div><div class="bottom-right-edge"></div><div class="bottom-edge"></div><div class="bottom-left-edge"></div><div class="left-edge"></div></div></div>',
   
   layer: 200
 

data/frameworks/sproutcore/panes/overlay.js

@@ -189,8 +189,12 @@ SC.OverlayPaneView = SC.PaneView.extend({
       if (content) {
         content.resizeWithOldParentSize(this.get('size')) ;
         
-        // compute padding we need to add.
-        var padding = this.get('size').width - this.get('innerFrame').width;
+        // compute space we need to add for border/padding
+        var padding = 0;
+        this.getEach('styleBorderLeftWidth', 'styleBorderRightWidth', 'stylePaddingLeft', 'stylePaddingRight').each(function(x) { padding += x || 0; });
+        this.recacheFrames() ;
+        content.recacheFrames() ;
+        
         this.set('size', { width: (content.get('size').width + padding) });
         this.owner.positionPane() ;
         this.owner.setStyle({ visibility: 'visible' }) ;

data/frameworks/sproutcore/panes/pane.js

@@ -1,9 +1,36 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2008 Sprout Systems, Inc.
+// ========================================================================
+
 require('views/view');
 
 SC.KEYVIEW_SELECTING_NONE      = 0;
 SC.KEYVIEW_SELECTING_NEXT      = 1;
 SC.KEYVIEW_SELECTING_PREVIOUS  = 2;
 
+/**
+  @class
+  
+  A PaneView provides the root view context for a popup, menu, dialog, sheet,
+  widget or a window itself.  The responder chain, which is used to route 
+  keyboard and mouse events, always terminates with a pane view.
+  
+  You can use PaneViews to display various pop-up widgets as well as to 
+  implement your own behaviors.
+  
+  To use a pane, you typically just create a view and set its paneType 
+  property to the name of the type of pane view you want it to display in.
+  Whenever you set the view's isVisible property to true, it will display
+  inside of the pane view automatically.
+  
+  You will rarely use the SC.PaneView directly.  Instead, you should use
+  one of the subclasses included in SproutCore or create your own.
+  
+  @extends SC.View
+  @since SproutCore 1.0
+*/
+  
 SC.PaneView = SC.View.extend({
 
   // panes do not belong to other panes...

data/frameworks/sproutcore/views/collection/collection.js

@@ -2203,7 +2203,7 @@ SC.CollectionView = SC.View.extend(
   // -- update layout on all item views.
   // -- optional: determine the first item view that does not match.
   //
-  _contentPropertyObserver: function(target, key, value, rev) {
+  _contentPropertyObserver: function(target, key, value, rev) {    
     if (!this._updatingContent && (!rev || (rev != this._contentPropertyRevision))) {
       this._contentPropertyRevision = rev ;
       this._updatingContent = true ;

data/frameworks/sproutcore/views/collection/grid.js

@@ -97,21 +97,6 @@ SC.GridView = SC.CollectionView.extend(
     SC.Benchmark.end('SC.GridView.layoutItemViewsFor') ;
   },
 
-  computeFrame: function() {
-    var content = this.get('content') ;
-    var rows = (content) ? content.get('length') : 0 ;
-    var rowHeight = this.get('rowHeight') || 20 ;
-
-    var parent = this.get('parentNode') ;
-    var f = (parent) ? parent.get('innerFrame') : { width: 100, height: 100 } ;
-
-    f.x = f.y = 0;
-    f.height = Math.max(f.height, rows * rowHeight) ;
-//    console.log('computeFrame(%@)'.fmt($H(f).inspect())) ;
-    return f ;
-  },
-  
-    
   /** @private */
   layoutItemViewsFor: function(parentView, startingView) {
     SC.Benchmark.start('SC.GridView.layoutItemViewsFor') ;
@@ -165,6 +150,9 @@ SC.GridView = SC.CollectionView.extend(
 
     var parent = this.get('parentNode') ;
     var f = (parent) ? parent.get('innerFrame') : { width: 0, height: 0 };
+
+    //console.log('computeFrame(%@)'.fmt($I(f))) ;
+
     var itemsPerRow = (columnWidth <= 0) ? 1 : (f.width / columnWidth) ;
     var rows = Math.ceil(count / itemsPerRow) ;
 

data/frameworks/sproutcore/views/collection/source_list.js

@@ -264,12 +264,17 @@ SC.SourceListView = SC.CollectionView.extend(
 
       var rowHeight = this.get('rowHeight') || 0 ;
 
+
       // layout relative to top of group.  Leave open row for title
-      var range = this.groupRangeForContentIndex(contentIndex) ;
-      contentIndex = (contentIndex - range.start) ;
-      
-      var groupValue = this.groupValueAtContentIndex(range.start) ;
-      if (groupValue != null) contentIndex++ ;
+      if(this.get("groupBy"))
+      {
+        
+        var range = this.groupRangeForContentIndex(contentIndex) ;
+        contentIndex = (contentIndex - range.start) ;
+
+        var groupValue = this.groupValueAtContentIndex(range.start) ;
+        if (groupValue != null) contentIndex++ ;
+      }
 
       var f = { 
         x: 0, 

data/frameworks/sproutcore/views/field/select_field.js

@@ -157,7 +157,10 @@ SC.SelectFieldView = SC.FieldView.extend(
    var valueKey = this.get('valueKey') ;
    var objects = this.get('objects') ;
    var fieldValue = this.get('value') ;
-
+   
+   // get the localization flag.
+   var shouldLocalize = this.get('localize'); 
+   
    // convert fieldValue to guid, if it is an object.
    if (!valueKey && fieldValue) fieldValue = fieldValue._guid ;
    if ((fieldValue == null) || (fieldValue == '')) fieldValue = '***' ;
@@ -169,7 +172,7 @@ SC.SelectFieldView = SC.FieldView.extend(
 
      var emptyName = this.get('emptyName') ;
      if (emptyName) {
-       if (this.get('localize')) emptyName = emptyName.loc() ;
+       if (shouldLocalize) emptyName = emptyName.loc() ;
        html.push('<option value="***">%@</option>'.fmt(emptyName)) ;
        html.push('<option disabled="disabled"></option>') ;
      }
@@ -181,6 +184,12 @@ SC.SelectFieldView = SC.FieldView.extend(
          // either get the name from the object or convert object to string.
          var name = (nameKey) ? ((object.get) ? object.get(nameKey) : object[nameKey]) : object.toString() ;
 
+         // localize name if specified.
+         if(shouldLocalize)
+         {
+           name = name.loc();
+         }
+
          // get the value using the valueKey or the object if no valueKey.
          // then convert to a string or use _guid if one of available.
          var value = (valueKey) ? ((object.get) ? object.get(valueKey) : object[valueKey]) : object ;