Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Box.html
index a9a27f2..8f8ea26 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
@@ -28,7 +28,7 @@ Ext.define('Ext.layout.container.Box', {
     alias: ['layout.box'],
     extend: 'Ext.layout.container.Container',
     alternateClassName: 'Ext.layout.BoxLayout',
-    
+
     requires: [
         'Ext.layout.container.boxOverflow.None',
         'Ext.layout.container.boxOverflow.Menu',
@@ -40,7 +40,7 @@ Ext.define('Ext.layout.container.Box', {
     /* End Definitions */
 
 <span id='Ext-layout-container-Box-cfg-animate'>    /**
-</span>     * @cfg {Mixed} animate
+</span>     * @cfg {Boolean/Number/Object} animate
      * &lt;p&gt;If truthy, child Component are &lt;i&gt;animated&lt;/i&gt; into position whenever the Container
      * is layed out. If this option is numeric, it is used as the animation duration in milliseconds.&lt;/p&gt;
      * &lt;p&gt;May be set as a property at any time.&lt;/p&gt;
@@ -71,9 +71,6 @@ Ext.define('Ext.layout.container.Box', {
      * &lt;li&gt;If there are four values, they apply to the top, right, bottom, and
      * left, respectively.&lt;/li&gt;
      * &lt;/ul&gt;&lt;/div&gt;
-     * &lt;p&gt;Defaults to:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
-     * {top:0, right:0, bottom:0, left:0}
-     * &lt;/code&gt;&lt;/pre&gt;
      */
     defaultMargins: {
         top: 0,
@@ -97,7 +94,6 @@ Ext.define('Ext.layout.container.Box', {
      * &lt;li&gt;If there are four values, they apply to the top, right, bottom, and
      * left, respectively.&lt;/li&gt;
      * &lt;/ul&gt;&lt;/div&gt;
-     * &lt;p&gt;Defaults to: &lt;code&gt;&quot;0&quot;&lt;/code&gt;&lt;/p&gt;
      */
     padding: '0',
     // documented in subclasses
@@ -136,10 +132,18 @@ Ext.define('Ext.layout.container.Box', {
     // availableSpaceOffset is used to adjust the availableWidth, typically used
     // to reserve space for a scrollbar
     availableSpaceOffset: 0,
-    
+
     // whether or not to reserve the availableSpaceOffset in layout calculations
     reserveOffset: true,
-    
+
+<span id='Ext-layout-container-Box-cfg-shrinkToFit'>    /**
+</span>     * @cfg {Boolean} shrinkToFit
+     * True (the default) to allow fixed size components to shrink (limited to their
+     * minimum size) to avoid overflow. False to preserve fixed sizes even if they cause
+     * overflow.
+     */
+    shrinkToFit: true,
+
 <span id='Ext-layout-container-Box-cfg-clearInnerCtOnLayout'>    /**
 </span>     * @cfg {Boolean} clearInnerCtOnLayout
      */
@@ -176,7 +180,7 @@ Ext.define('Ext.layout.container.Box', {
 <span id='Ext-layout-container-Box-method-getChildBox'>    /**
 </span>     * @private
      * Returns the current size and positioning of the passed child item.
-     * @param {Component} child The child Component to calculate the box for
+     * @param {Ext.Component} child The child Component to calculate the box for
      * @return {Object} Object containing box measurements for the child. Properties are left,top,width,height.
      */
     getChildBox: function(child) {
@@ -193,7 +197,7 @@ Ext.define('Ext.layout.container.Box', {
 <span id='Ext-layout-container-Box-method-calculateChildBox'>    /**
 </span>     * @private
      * Calculates the size and positioning of the passed child item.
-     * @param {Component} child The child Component to calculate the box for
+     * @param {Ext.Component} child The child Component to calculate the box for
      * @return {Object} Object containing box measurements for the child. Properties are left,top,width,height.
      */
     calculateChildBox: function(child) {
@@ -244,7 +248,7 @@ Ext.define('Ext.layout.container.Box', {
             availPerpendicularSize = mmax(0, perpendicularSize - paddingPerpendicular),
 
             innerCtBorderWidth = me.innerCt.getBorderWidth(me.perpendicularLT + me.perpendicularRB),
-            
+
             isStart = me.pack == 'start',
             isCenter = me.pack == 'center',
             isEnd = me.pack == 'end',
@@ -260,16 +264,21 @@ Ext.define('Ext.layout.container.Box', {
             minSizes = [],
             calculatedWidth,
 
-            i, child, childParallel, childPerpendicular, childMargins, childSize, minParallel, tmpObj, shortfall, 
-            tooNarrow, availableSpace, minSize, item, length, itemIndex, box, oldSize, newSize, reduction, diff, 
-            flexedBoxes, remainingSpace, remainingFlex, flexedSize, parallelMargins, calcs, offset, 
+            i, child, childParallel, childPerpendicular, childMargins, childSize, minParallel, tmpObj, shortfall,
+            tooNarrow, availableSpace, minSize, item, length, itemIndex, box, oldSize, newSize, reduction, diff,
+            flexedBoxes, remainingSpace, remainingFlex, flexedSize, parallelMargins, calcs, offset,
             perpendicularMargins, stretchSize;
 
         //gather the total flex of all flexed items and the width taken up by fixed width items
         for (i = 0; i &lt; visibleCount; i++) {
             child = visibleItems[i];
             childPerpendicular = child[perpendicularPrefix];
-            me.layoutItem(child);
+            if (!child.flex || !(me.align == 'stretch' || me.align == 'stretchmax')) {
+                if (child.componentLayout.initialized !== true) {
+                    me.layoutItem(child);
+                }
+            }
+
             childMargins = child.margins;
             parallelMargins = childMargins[me.parallelBefore] + childMargins[me.parallelAfter];
 
@@ -305,14 +314,20 @@ Ext.define('Ext.layout.container.Box', {
             }
 
             // Track the maximum perpendicular size for use by the stretch and stretchmax align config values.
-            maxSize = mmax(maxSize, childPerpendicular + childMargins[me.perpendicularLeftTop] + childMargins[me.perpendicularRightBottom]);
+            // Ensure that the tracked maximum perpendicular size takes into account child min[Width|Height] settings!
+            maxSize = mmax(maxSize, mmax(childPerpendicular, child[perpendicularMinString]||0) + childMargins[me.perpendicularLeftTop] + childMargins[me.perpendicularRightBottom]);
 
             tmpObj[parallelPrefix] = childParallel || undefinedValue;
+            tmpObj.dirtySize = child.componentLayout.lastComponentSize ? (tmpObj[parallelPrefix] !== child.componentLayout.lastComponentSize[parallelPrefix]) : false;
             tmpObj[perpendicularPrefix] = childPerpendicular || undefinedValue;
             boxes.push(tmpObj);
         }
-        shortfall = desiredSize - parallelSize;
-        tooNarrow = minimumSize &gt; parallelSize;
+
+        // Only calculate parallel overflow indicators if we are not auto sizing
+        if (!me.autoSize) {
+            shortfall = desiredSize - parallelSize;
+            tooNarrow = minimumSize &gt; parallelSize;
+        }
 
         //the space available to the flexed items
         availableSpace = mmax(0, parallelSize - nonFlexSize - paddingParallel - (me.reserveOffset ? me.availableSpaceOffset : 0));
@@ -344,8 +359,7 @@ Ext.define('Ext.layout.container.Box', {
                         box = boxes[i];
                         box.dirtySize = box.dirtySize || box[parallelPrefix] != minSize;
                         box[parallelPrefix] = minSize;
-                    }
-                    else {
+                    } else if (me.shrinkToFit) {
                         minSizes.push({
                             minSize: minSize,
                             available: boxes[i][parallelPrefix] - minSize,
@@ -381,6 +395,7 @@ Ext.define('Ext.layout.container.Box', {
                     box[parallelPrefix] = newSize;
                     shortfall -= reduction;
                 }
+                tooNarrow = (shortfall &gt; 0);
             }
             else {
                 remainingSpace = availableSpace;
@@ -493,7 +508,7 @@ Ext.define('Ext.layout.container.Box', {
             }
         };
     },
-    
+
     onRemove: function(comp){
         this.callParent(arguments);
         if (this.overflowHandler) {
@@ -594,10 +609,12 @@ Ext.define('Ext.layout.container.Box', {
         me.updateChildBoxes(boxes);
         me.handleTargetOverflow(targetSize);
     },
+    
+    animCallback: Ext.emptyFn,
 
 <span id='Ext-layout-container-Box-method-updateChildBoxes'>    /**
 </span>     * Resizes and repositions each child component
-     * @param {Array} boxes The box measurements
+     * @param {Object[]} boxes The box measurements
      */
     updateChildBoxes: function(boxes) {
         var me = this,
@@ -685,6 +702,7 @@ Ext.define('Ext.layout.container.Box', {
                 // When we've animated all changed boxes into position, clear our busy flag and call the callback.
                 length -= 1;
                 if (!length) {
+                    me.animCallback(anim);
                     me.layoutBusy = false;
                     if (Ext.isFunction(animCallback)) {
                         animCallback();
@@ -727,7 +745,7 @@ Ext.define('Ext.layout.container.Box', {
      * again immediately afterwards, giving a performance hit.
      * Subclasses should provide an implementation.
      * @param {Object} currentSize The current height and width of the innerCt
-     * @param {Array} calculations The new box calculations of all items to be laid out
+     * @param {Object} calculations The new box calculations of all items to be laid out
      */
     updateInnerCtSize: function(tSize, calcs) {
         var me = this,
@@ -781,7 +799,7 @@ Ext.define('Ext.layout.container.Box', {
      * target. Having a Box layout inside such a target is therefore not recommended.
      * @param {Object} previousTargetSize The size and height of the layout target before we just laid out
      * @param {Ext.container.Container} container The container
-     * @param {Ext.core.Element} target The target element
+     * @param {Ext.Element} target The target element
      * @return True if the layout overflowed, and was reflowed in a secondary onLayout call.
      */
     handleTargetOverflow: function(previousTargetSize) {
@@ -847,6 +865,8 @@ Ext.define('Ext.layout.container.Box', {
         margins.right  += itemEl.getMargin('r');
         margins.bottom += itemEl.getMargin('b');
         margins.left   += itemEl.getMargin('l');
+        margins.height  = margins.top  + margins.bottom;
+        margins.width   = margins.left + margins.right;
         style.marginTop = style.marginRight = style.marginBottom = style.marginLeft = '0';
 
         // Item must reference calculated margins.
@@ -857,7 +877,7 @@ Ext.define('Ext.layout.container.Box', {
 </span>     * @private
      */
     destroy: function() {
-        Ext.destroy(this.overflowHandler);
+        Ext.destroy(this.innerCt, this.overflowHandler);
         this.callParent(arguments);
     }
 });</pre>