sproutcore 1.10.3.1 → 1.11.0.rc1

data/lib/frameworks/sproutcore/frameworks/core_foundation/child_view_layouts/vertical_stack_layout.js

@@ -11,11 +11,15 @@ SC.mixin(SC.View,
 
   /**
     This child layout plugin automatically positions the view's child views in a
-    vertical stack and optionally adjusts the parent view's height to fit.  It
-    does this by checking the height of each child view and positioning the
-    following child view accordingly.  By default any time that a child view's
-    height changes, the view will use this plugin to re-adjust all other child
-    views and its own height appropriately.
+    vertical stack and optionally adjusts the view's height to fit.  It does this
+    by checking the height of each child view and positioning the following child
+    view accordingly.  Afterwards, by default, any time that a child view's
+    height or visibility changes, the view will use this plugin to re-adjust all
+    following child views' positions and potentially its own height appropriately.
+
+    This allows you to stack absolutely positioned views that dynamically change
+    their height and/or visibility without having to resort to using browser
+    flow layout.
 
     A typical usage scenario is a long "form" made of multiple subsection
     views.  If we want to adjust the height of a subsection, to make space for
@@ -34,27 +38,38 @@ SC.mixin(SC.View,
           // The order of child views is important!
           childViews: ['sectionA', 'sectionB', 'sectionC'],
 
-          // Actual layout will become { left: 10, right: 10, top: 20, height: 270 }
-          layout: { left: 10, right: 10, top: 20 }, // Don't need to specify layout.height, this is automatic.
+          // The view will resize itself to fit its children.
+          // i.e. We don't need to specify layout.height, this is automatic.
+          // The actual layout will become { left: 10, right: 10, top: 20, height: 270 } initially.
+          layout: { left: 10, right: 10, top: 20 },
 
           sectionA: SC.View.design({
-            // Actual layout will become { left: 0, right: 0, top: 0, height: 100 }
-            layout: { height: 100 } // Don't need to specify layout.top, this is automatic.
+
+            // We don't need to specify layout.top, this is automatic.
+            // The actual layout will become { left: 0, right: 0, top: 0, height: 100 } initially.
+            layout: { height: 100 }
+
           }),
 
           sectionB: SC.View.design({
-            // Actual layout will become { border: 1, left: 0, right: 0, top: 100, height: 50 }
-            layout: { border: 1, height: 50 } // Don't need to specify layout.top, this is automatic.
+
+            // We don't need to specify layout.top, this is automatic.
+            // The actual layout will become { border: 1, left: 0, right: 0, top: 100, height: 50 } initially.
+            layout: { border: 1, height: 50 }
+
           }),
 
           sectionC: SC.View.design({
-            // Actual layout will become { left: 10, right: 10, top: 150, height: 120 }
-            layout: { left: 10, right: 10, height: 120 } // Don't need to specify layout.top, this is automatic.
+
+            // We don't need to specify layout.top, this is automatic.
+            // The actual layout will become { left: 10, right: 10, top: 150, height: 120 } initially.
+            layout: { left: 10, right: 10, height: 120 }
+
           })
 
         });
 
-    ## Modify all child view layouts with `childViewLayoutOptions`
+    ## Modify the default behavior with `childViewLayoutOptions`
 
     To modify the plugin behavior for all child view layouts, you can set the
     following child view layout options in `childViewLayoutOptions` on the view:
@@ -81,30 +96,44 @@ SC.mixin(SC.View,
           // The order of child views is important!
           childViews: ['sectionA', 'sectionB', 'sectionC'],
 
-          // Actual layout will become { left: 10, right: 10, top: 20, height: 310 }
+          // The actual layout will become { left: 10, right: 10, top: 20, height: 310 } initially.
           layout: { left: 10, right: 10, top: 20 }, // Don't need to specify layout.height, this is automatic.
 
           sectionA: SC.View.design({
-            // Actual layout will become { left: 0, right: 0, top: 10, height: 100 }
-            layout: { height: 100 } // Don't need to specify layout.top, this is automatic.
+
+            // We don't need to specify layout.top, this is automatic.
+            // The actual layout will become { left: 0, right: 0, top: 10, height: 100 } initially.
+            layout: { height: 100 }
+
           }),
 
           sectionB: SC.View.design({
-            // Actual layout will become { border: 1, left: 0, right: 0, top: 115, height: 50 }
-            layout: { border: 1, height: 50 } // Don't need to specify layout.top, this is automatic.
+
+            // We don't need to specify layout.top, this is automatic.
+            // The actual layout will become { border: 1, left: 0, right: 0, top: 115, height: 50 } initially.
+            layout: { border: 1, height: 50 }
+
           }),
 
           sectionC: SC.View.design({
-            // Actual layout will become { left: 10, right: 10, top: 170, height: 120 }
-            layout: { left: 10, right: 10, height: 120 } // Don't need to specify layout.top, this is automatic.
+
+            // We don't need to specify layout.top, this is automatic.
+            // The actual layout will become { left: 10, right: 10, top: 170, height: 120 } initially.
+            layout: { left: 10, right: 10, height: 120 }
+
           })
 
         });
 
     If `resizeToFit` is set to `false`, the view will not adjust itself to fit
     its child views.  This means that when `resizeToFit` is false, the view should
-    specify its height component in its layout.  This also means that you can
-    ignore the last child view's layout height if you want the last child view
+    specify its height component in its layout. A direct effect is the possibility for
+    the child views to automatically extend or shrink in order to fill the empty, unclaimed space.
+    This available space is shared between the children not specifying a fixed height
+    and their final dimension is calculated proportionally to the value of the
+    property `fillRatio`.
+    For simplicity, when none of the children specifies `fillRatio`,
+    you can ignore the last child view's layout height if you want the last child view
     to stretch to fill the parent view.
 
     For example,
@@ -129,18 +158,37 @@ SC.mixin(SC.View,
           layout: { left: 10, right: 10, top: 20, height: 500 }, // Need to specify layout.height.
 
           sectionA: SC.View.design({
-            // Actual layout will become { left: 0, right: 0, top: 10, height: 100 }
-            layout: { height: 100 } // Don't need to specify layout.top, this is automatic.
+
+            // We don't need to specify layout.top, this is automatic. This child will not stretch, its height is set.
+            // The actual layout will become { left: 0, right: 0, top: 10, height: 100 } initially.
+            layout: { height: 100 }
+
           }),
 
           sectionB: SC.View.design({
-            // Actual layout will become { border: 1, left: 0, right: 0, top: 115, height: 50 }
-            layout: { border: 1, height: 50 } // Don't need to specify layout.top, this is automatic.
+
+            // The unclaimed space so far is 500 - 10 - 100 - 5 - 5 - 20, or 360px. This space will be shared between
+            // the two last sections, because we won't specity a height on them.
+            // This view will get 1/3 of the available space, because the other flexibile view has a ratio of 2.
+            fillRatio: 1,
+
+            // This section will take 1/3 * 360px = 120px.
+            // Actual layout will become { border: 1, left: 0, right: 0, top: 115, bottom: 265 }, in other words, height == 120
+            // We don't need to specify layout.top, layout.bottom or layout.height, this is automatic.
+            layout: { border: 1 }
+
           }),
 
           sectionC: SC.View.design({
-            // Actual layout will become { left: 10, right: 10, top: 170, bottom: 20 }
-            layout: { left: 10, right: 10 } // Don't need to specify layout.top, layout.bottom or layout.height, this is automatic.
+
+            // This view will get 2/3 of the available space, because the other flexibile view has a ratio of 1.
+            fillRatio: 2,
+
+            // This section will take 2/3 * 360px = 240px.
+            // Actual layout will become { left: 10, right: 10, top: 240, bottom: 20 }, in other words, height == 240
+            // We don't need to specify layout.top, layout.bottom or layout.height, this is automatic.
+            layout: { left: 10, right: 10 }
+
           })
 
         });
@@ -155,6 +203,7 @@ SC.mixin(SC.View,
       - useAbsoluteLayout - Don't include this child view in automatic layout, use absolute positioning based on the child view's `layout` property.
       - useStaticLayout - Don't include this child view in automatic layout.  This child view uses relative positioning and is not eligible for automatic layout.
       - isVisible - Non-visible child views are not included in the stack.
+      - fillRatio - When the parent view is configured with a fixed dimension, children not specifying a height but specifying fillRatio will be resized to fill the unclaimed space proportionally to this ratio.
 
     For example,
 
@@ -220,6 +269,17 @@ SC.mixin(SC.View,
     /** @private Properties to observe on child views that affect the overall child view layout. */
     childLayoutProperties: ['marginBefore', 'marginAfter', 'isVisible'],
 
+    /** @private When resizeToFit is false, then we need to know when the view's frame changes. */
+    layoutDependsOnSize: function (view) {
+      var options = view.get('childViewLayoutOptions');
+
+      if (options) {
+        return SC.none(options.resizeToFit) ? false : !options.resizeToFit;
+      } else {
+        return false;
+      }
+    },
+
     /** @private */
     layoutChildViews: function (view) {
       var childViews = view.get('childViews'),
@@ -228,14 +288,96 @@ SC.mixin(SC.View,
         lastMargin = 0, // Used to avoid adding spacing to the final margin.
         marginAfter = options.paddingBefore || 0,
         paddingAfter = options.paddingAfter || 0,
-        position = 0,
+        topPosition = 0,
+        provisionedSpace = 0,
+        autoFillAvailableSpace = 0,
+        totalAvailableSpace = 0,
+        totalFillAvailableSpaceRatio = 0,
         spacing = options.spacing || 0,
+        childView,
+        fillRatio,
+        layout,
+        marginBefore,
         i, len;
 
+      // if the view is not configured to resize to fit content, then we give a chance to the children to fill the available space
+      // we make a 1st pass to check the conditions, to evaluate the available space and the proportions between children
+      if (!resizeToFit) {
+
+        totalAvailableSpace = view.get('frame').height;
+
+        // if the view is not configured to resize and it doesn't have yet a height, it doesn't make sense to layout children
+        if (!totalAvailableSpace) {
+          return;
+        }
+
+        for (i = 0, len = childViews.get('length'); i < len; i++) {
+          childView = childViews.objectAt(i);
+
+          // Ignore child views with useAbsoluteLayout true, useStaticLayout true or that are not visible.
+          if (!childView.get('isVisible') ||
+            childView.get('useAbsoluteLayout') ||
+            childView.get('useStaticLayout')) {
+            continue;
+          }
+
+          layout = childView.get('layout');
+
+          // Determine the top margin.
+          marginBefore = childView.get('marginBefore') || 0;
+          provisionedSpace += Math.max(marginAfter, marginBefore);
+
+          // if the height is not set, let's check if is possible to resize the view
+          if (SC.none(layout.height)) {
+            fillRatio = childView.get('fillRatio');
+
+            if (!SC.none(fillRatio)) {
+              totalFillAvailableSpaceRatio += fillRatio;
+            } else {
+              // if none of the child views has fillRatio defined, allow the last one to stretch and fill the available space.
+              if (i == len - 1 && totalFillAvailableSpaceRatio === 0) {
+                totalFillAvailableSpaceRatio = 1;
+              }
+              //@if(debug)
+              // Add some developer support.
+              else {
+                // even if we don't have a height set, as last instance we accept the presence of minHeight
+                if (SC.none(layout.minHeight))
+                {
+                  SC.warn('Developer Warning: The SC.View.VERTICAL_STACK plugin requires that each childView layout contains at least a height or has a configured fillRatio. The layout may also optionally contain left and right, left and width, right and width or centerX and width. The childView %@ has an invalid layout/fillRatio: %@'.fmt(childView, SC.stringFromLayout(layout)));
+                  return;
+                }
+              }
+              //@endif
+            }
+          } else {
+            provisionedSpace += childView.getPath('borderFrame.height');
+          }
+
+          // Determine the right margin.
+          lastMargin = childView.get('marginAfter') || 0;
+          marginAfter = lastMargin || spacing;
+        }
+
+        // consider the end padding when calculating the provisionedSpace
+        if (provisionedSpace !== 0 || totalFillAvailableSpaceRatio !== 0) {
+          provisionedSpace += Math.max(lastMargin, paddingAfter);
+        }
+
+        autoFillAvailableSpace = Math.max(0, totalAvailableSpace - provisionedSpace);
+      }
+
+      // reset the references for the effective layout
+      lastMargin = 0;
+      marginAfter = options.paddingBefore || 0;
+      paddingAfter = options.paddingAfter || 0;
+
       for (i = 0, len = childViews.get('length'); i < len; i++) {
-        var childView = childViews.objectAt(i),
-          layout,
-          marginBefore;
+        var height,
+          adjustTop,
+          adjustBottom;
+
+        childView = childViews.objectAt(i);
 
         // Ignore child views with useAbsoluteLayout true, useStaticLayout true or that are not visible.
         if (!childView.get('isVisible') ||
@@ -245,39 +387,83 @@ SC.mixin(SC.View,
         }
 
         layout = childView.get('layout');
+
         //@if(debug)
-        // Add some developer support.
-        if (SC.none(layout.height) && (i < len - 1 || resizeToFit)) {
-          SC.warn('Developer Warning: The SC.View.VERTICAL_STACK plugin requires that each childView layout contains at least a height and optionally also left and right, left and width, right and width or centerX and width.  The childView %@ has an invalid layout: %@'.fmt(childView, SC.stringFromLayout(layout)));
+        // Add some developer support. The case of !resizeToFit was already checked above
+        if (resizeToFit && SC.none(layout.height) && SC.none(layout.minHeight)) {
+          SC.warn('Developer Warning: The SC.View.VERTICAL_STACK plugin, when configured with resizeToFit, requires that each childView layout contains at least a height/minHeight and optionally also left and right, left and width, right and width or centerX and width.  The childView %@ has an invalid layout: %@'.fmt(childView, SC.stringFromLayout(layout)));
           return;
         }
         //@endif
 
         // Determine the top margin.
         marginBefore = childView.get('marginBefore') || 0;
-        position += Math.max(marginAfter, marginBefore);
+        topPosition += Math.max(marginAfter, marginBefore);
+
+        // Try to avoid useless adjustments top or bottom or top then bottom.
+        // The required adjustments will be merged into a single call
+        adjustTop = layout.top !== topPosition;
 
-        if (layout.top !== position) {
-          childView.adjust('top', position);
+        childView.beginPropertyChanges();
+        if (!resizeToFit && !layout.height) {
+          var bottomPosition;
+
+          fillRatio = childView.get('fillRatio');
+
+          // if the last child doesn't define fillRatio, default it to 1 as above during the 1st pass
+          if (i == len - 1 && SC.none(fillRatio)) {
+            fillRatio = 1;
+          }
 
-          // Allow the last child view to stretch.
-          if (!resizeToFit && !layout.height && !layout.bottom) {
-            childView.adjust('bottom', paddingAfter);
+          // we should get here only in two cases: 1. child defines fillRatio, 2. child defines a minHeight
+          // if both defined, we prefer to handle fillRatio, the other case being handled below by the normal adjustment to top
+          if (!SC.none(fillRatio)) {
+            var currentAvailableSpaceRatio = (fillRatio / totalFillAvailableSpaceRatio);
+
+            // calculate the height according to fillRatio and totalFillAvailableSpaceRatio
+            // but set the "bottom" position so any subsequent layout is not considering the height as fixed
+            height = Math.ceil(autoFillAvailableSpace * currentAvailableSpaceRatio);
+
+            // INCOMPLETE: We need to flag this view as constrained and re-compute all the auto-fill amounts
+            // Constrain the height to the maximum height allowed.
+            // var maxHeight = layout.maxHeight;
+            // if (!SC.none(maxHeight)) {
+            //   // Constrain the height according to maxHeight. Which frees up additional available space for further child views.
+            //   if (height > maxHeight) {
+            //     height = maxHeight;
+            //   }
+            // }
+
+            // Determine the bottom position. If the position overflows (i.e. goes negative) because of rounding up, stop at 0.
+            bottomPosition = Math.max(0, totalAvailableSpace - topPosition - height);
+            adjustBottom = layout.bottom !== bottomPosition;
+
+            if (adjustBottom) {
+              childView.adjust('bottom', bottomPosition);
+            }
           }
         }
-        position += childView.getPath('borderFrame.height');
 
-        // Determine the bottom margin.
+        if (adjustTop) {
+          childView.adjust('top', topPosition);
+        }
+        childView.endPropertyChanges();
+
+        topPosition += childView.getPath('borderFrame.height');
+
+        // Determine the right margin.
         lastMargin = childView.get('marginAfter') || 0;
         marginAfter = lastMargin || spacing;
       }
 
-      // Adjust our frame to fit as well, this ensures that scrolling works.
       // If the current size is 0 (all children are hidden), it doesn't make sense to add the padding
-      if (position !== 0)
-        position += Math.max(lastMargin, paddingAfter);
-      if (resizeToFit && view.getPath('layout.height') !== position) {
-        view.adjust('height', position);
+      if (topPosition !== 0) {
+        topPosition += Math.max(lastMargin, paddingAfter);
+      }
+
+      // Adjust our frame to fit as well, this ensures that scrolling works.
+      if (resizeToFit && view.getPath('layout.height') !== topPosition) {
+        view.adjust('height', topPosition);
       }
     }
 

data/lib/frameworks/sproutcore/frameworks/core_foundation/controllers/array.js

@@ -353,8 +353,6 @@ SC.ArrayController = SC.Controller.extend(SC.Array, SC.SelectionSupport,
     this should be the same as the content property, but sometimes we need to
     generate something different because the content is not a regular array.
 
-    Passing YES to the force parameter will force this value to be recomputed.
-
     @returns {SC.Array} observable or null
   */
   _scac_observableContent: function () {
@@ -432,6 +430,17 @@ SC.ArrayController = SC.Controller.extend(SC.Array, SC.SelectionSupport,
   },
 
   _scac_arrayContentWillChange: function (start, removed, added) {
+    // Repoint arguments if orderBy is present. (If orderBy is present, we can't be sure how any content change
+    // translates into an arrangedObject change without calculating the order, which is a complex, potentially
+    // expensive operation, so we simply invalidate everything.)
+    if (this.get('orderBy')) {
+      var len = this.get('length');
+      start = 0;
+      added = len + added - removed;
+      removed = len;
+    }
+
+    // Continue.
     this.arrayContentWillChange(start, removed, added);
     if (this._kvo_enumerable_property_chains) {
       var removedObjects = this.slice(start, start + removed);
@@ -441,16 +450,20 @@ SC.ArrayController = SC.Controller.extend(SC.Array, SC.SelectionSupport,
 
   _scac_arrayContentDidChange: function (start, removed, added) {
     this._scac_cached = NO;
-    this.arrayContentDidChange(start, removed, added);
 
-    // If the start & length are provided, we can also indicate if the firstObject
-    // or lastObject properties changed, thus making them independently observable.
-    if (!SC.none(start)) {
-      if (start === 0) this.notifyPropertyChange('firstObject');
-      var length = added + removed;
-      if (!SC.none(length) && start + length >= this.get('length') - 1) this.notifyPropertyChange('lastObject');
+    // Repoint arguments if orderBy is present. (If orderBy is present, we can't be sure how any content change
+    // translates into an arrangedObject change without calculating the order, which is a complex, potentially
+    // expensive operation, so we simply invalidate everything.)
+    if (this.get('orderBy')) {
+      var len = this.get('length');
+      start = 0;
+      added = len + added - removed;
+      removed = len;
     }
 
+    // Notify range, firstObject, lastObject and '[]' observers.
+    this.arrayContentDidChange(start, removed, added);
+
     if (this._kvo_enumerable_property_chains) {
       var addedObjects = this.slice(start, start + added);
       this.setupEnumerablePropertyChains(addedObjects);
@@ -532,7 +545,6 @@ SC.ArrayController = SC.Controller.extend(SC.Array, SC.SelectionSupport,
     this._scac_contentStatusDidChange();
 
     this.arrayContentDidChange(0, 0, newlen);
-    this.enumerableContentDidChange(0, newlen - 1);
     this.updateSelectionAfterContentChange();
   }.observes('content'),
 
@@ -549,14 +561,12 @@ SC.ArrayController = SC.Controller.extend(SC.Array, SC.SelectionSupport,
         oldlen  = this._scac_length;
 
     this._scac_length = newlen;
-    this.beginPropertyChanges();
     this._scac_cached = NO; // invalidate
     // If this is an unordered enumerable, we have no way
     // of knowing which indices changed. Instead, we just
     // invalidate the whole array.
+    this.arrayContentWillChange(0, oldlen, newlen);
     this.arrayContentDidChange(0, oldlen, newlen);
-    this.enumerableContentDidChange(0, oldlen - 1);
-    this.endPropertyChanges();
     this.updateSelectionAfterContentChange();
   }.observes('orderBy'),