Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Component5.html
index dff6515..25c9fa7 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>
   <pre class="prettyprint lang-js"><span id='Ext-layout-component-Component'>/**
 </span> * @class Ext.layout.component.Component
  * @extends Ext.layout.Layout
+ *
+ * This class is intended to be extended or created via the {@link Ext.Component#componentLayout layout}
+ * configuration property.  See {@link Ext.Component#componentLayout} for additional details.
+ *
  * @private
- * &lt;p&gt;This class is intended to be extended or created via the &lt;tt&gt;&lt;b&gt;{@link Ext.Component#componentLayout layout}&lt;/b&gt;&lt;/tt&gt;
- * configuration property.  See &lt;tt&gt;&lt;b&gt;{@link Ext.Component#componentLayout}&lt;/b&gt;&lt;/tt&gt; for additional details.&lt;/p&gt;
  */
-
 Ext.define('Ext.layout.component.Component', {
 
     /* Begin Definitions */
@@ -50,13 +51,13 @@ Ext.define('Ext.layout.component.Component', {
                     left: 0,
                     bottom: 0,
                     right: 0
-                }; 
+                };
             }
         }
         me.callParent(arguments);
     },
 
-    beforeLayout : function(width, height, isSetSize, layoutOwner) {
+    beforeLayout : function(width, height, isSetSize, callingContainer) {
         this.callParent(arguments);
 
         var me = this,
@@ -67,14 +68,16 @@ Ext.define('Ext.layout.component.Component', {
             ownerElChild = owner.el.child,
             layoutCollection;
 
-        /*
-         * Do not layout calculatedSized components for fixedLayouts unless the ownerCt == layoutOwner
-         * fixedLayouts means layouts which are never auto/auto in the sizing that comes from their ownerCt.
-         * Currently 3 layouts MAY be auto/auto (Auto, Border, and Box)
-         * The reason for not allowing component layouts is to stop component layouts from things such as Updater and
-         * form Validation.
-         */
-        if (!isSetSize &amp;&amp; !(Ext.isNumber(width) &amp;&amp; Ext.isNumber(height)) &amp;&amp; ownerCt &amp;&amp; ownerCt.layout &amp;&amp; ownerCt.layout.fixedLayout &amp;&amp; ownerCt != layoutOwner) {
+        // Cache the size we began with so we can see if there has been any effect.
+        me.previousComponentSize = me.lastComponentSize;
+
+        // Do not allow autoing of any dimensions which are fixed
+        if (!isSetSize
+            &amp;&amp; ((!Ext.isNumber(width) &amp;&amp; owner.isFixedWidth()) ||
+                (!Ext.isNumber(height) &amp;&amp; owner.isFixedHeight()))
+            // unless we are being told to do so by the ownerCt's layout
+            &amp;&amp; callingContainer &amp;&amp; callingContainer !== ownerCt) {
+            
             me.doContainerLayout();
             return false;
         }
@@ -95,9 +98,7 @@ Ext.define('Ext.layout.component.Component', {
         }
 
         if (isVisible &amp;&amp; this.needsLayout(width, height)) {
-            me.rawWidth = width;
-            me.rawHeight = height;
-            return owner.beforeComponentLayout(width, height, isSetSize, layoutOwner);
+            return owner.beforeComponentLayout(width, height, isSetSize, callingContainer);
         }
         else {
             return false;
@@ -107,21 +108,33 @@ Ext.define('Ext.layout.component.Component', {
 <span id='Ext-layout-component-Component-method-needsLayout'>    /**
 </span>    * Check if the new size is different from the current size and only
     * trigger a layout if it is necessary.
-    * @param {Mixed} width The new width to set.
-    * @param {Mixed} height The new height to set.
+    * @param {Number} width The new width to set.
+    * @param {Number} height The new height to set.
     */
     needsLayout : function(width, height) {
-        this.lastComponentSize = this.lastComponentSize || {
-            width: -Infinity,
-            height: -Infinity
-        };
-        return (this.childrenChanged || this.lastComponentSize.width !== width || this.lastComponentSize.height !== height);
+        var me = this,
+            widthBeingChanged,
+            heightBeingChanged;
+            me.lastComponentSize = me.lastComponentSize || {
+                width: -Infinity,
+                height: -Infinity
+            };
+
+        // If autoWidthing, or an explicitly different width is passed, then the width is being changed.
+        widthBeingChanged  = !Ext.isDefined(width)  || me.lastComponentSize.width  !== width;
+
+        // If autoHeighting, or an explicitly different height is passed, then the height is being changed.
+        heightBeingChanged = !Ext.isDefined(height) || me.lastComponentSize.height !== height;
+
+
+        // isSizing flag added to prevent redundant layouts when going up the layout chain
+        return !me.isSizing &amp;&amp; (me.childrenChanged || widthBeingChanged || heightBeingChanged);
     },
 
 <span id='Ext-layout-component-Component-method-setElementSize'>    /**
 </span>    * Set the size of any element supporting undefined, null, and values.
-    * @param {Mixed} width The new width to set.
-    * @param {Mixed} height The new height to set.
+    * @param {Number} width The new width to set.
+    * @param {Number} height The new height to set.
     */
     setElementSize: function(el, width, height) {
         if (width !== undefined &amp;&amp; height !== undefined) {
@@ -137,7 +150,7 @@ Ext.define('Ext.layout.component.Component', {
 
 <span id='Ext-layout-component-Component-method-getTarget'>    /**
 </span>     * Returns the owner component's resize element.
-     * @return {Ext.core.Element}
+     * @return {Ext.Element}
      */
      getTarget : function() {
          return this.owner.el;
@@ -146,7 +159,7 @@ Ext.define('Ext.layout.component.Component', {
 <span id='Ext-layout-component-Component-method-getRenderTarget'>    /**
 </span>     * &lt;p&gt;Returns the element into which rendering must take place. Defaults to the owner Component's encapsulating element.&lt;/p&gt;
      * May be overridden in Component layout managers which implement an inner element.
-     * @return {Ext.core.Element}
+     * @return {Ext.Element}
      */
     getRenderTarget : function() {
         return this.owner.el;
@@ -154,8 +167,8 @@ Ext.define('Ext.layout.component.Component', {
 
 <span id='Ext-layout-component-Component-method-setTargetSize'>    /**
 </span>    * Set the size of the target element.
-    * @param {Mixed} width The new width to set.
-    * @param {Mixed} height The new height to set.
+    * @param {Number} width The new width to set.
+    * @param {Number} height The new height to set.
     */
     setTargetSize : function(width, height) {
         var me = this;
@@ -207,7 +220,7 @@ Ext.define('Ext.layout.component.Component', {
                     right: body.getMargin('r'),
                     bottom: body.getMargin('b'),
                     left: body.getMargin('l')
-                } 
+                }
             };
         }
         return this.targetInfo;
@@ -217,9 +230,14 @@ Ext.define('Ext.layout.component.Component', {
     doOwnerCtLayouts: function() {
         var owner = this.owner,
             ownerCt = owner.ownerCt,
-            ownerCtComponentLayout, ownerCtContainerLayout;
-
-        if (!ownerCt) {
+            ownerCtComponentLayout, ownerCtContainerLayout,
+            curSize = this.lastComponentSize,
+            prevSize = this.previousComponentSize,
+            widthChange  = (prevSize &amp;&amp; curSize &amp;&amp; Ext.isNumber(curSize.width )) ? curSize.width  !== prevSize.width  : true,
+            heightChange = (prevSize &amp;&amp; curSize &amp;&amp; Ext.isNumber(curSize.height)) ? curSize.height !== prevSize.height : true;
+
+        // If size has not changed, do not inform upstream layouts
+        if (!ownerCt || (!widthChange &amp;&amp; !heightChange)) {
             return;
         }
 
@@ -228,11 +246,15 @@ Ext.define('Ext.layout.component.Component', {
 
         if (!owner.floating &amp;&amp; ownerCtComponentLayout &amp;&amp; ownerCtComponentLayout.monitorChildren &amp;&amp; !ownerCtComponentLayout.layoutBusy) {
             if (!ownerCt.suspendLayout &amp;&amp; ownerCtContainerLayout &amp;&amp; !ownerCtContainerLayout.layoutBusy) {
-                // AutoContainer Layout and Dock with auto in some dimension
-                if (ownerCtContainerLayout.bindToOwnerCtComponent === true) {
+
+                // If the owning Container may be adjusted in any of the the dimension which have changed, perform its Component layout
+                if (((widthChange &amp;&amp; !ownerCt.isFixedWidth()) || (heightChange &amp;&amp; !ownerCt.isFixedHeight()))) {
+                    // Set the isSizing flag so that the upstream Container layout (called after a Component layout) can omit this component from sizing operations
+                    this.isSizing = true;
                     ownerCt.doComponentLayout();
+                    this.isSizing = false;
                 }
-                // Box Layouts
+                // Execute upstream Container layout
                 else if (ownerCtContainerLayout.bindToOwnerCtContainer === true) {
                     ownerCtContainerLayout.layout();
                 }
@@ -249,7 +271,7 @@ Ext.define('Ext.layout.component.Component', {
 
         // Run the container layout if it exists (layout for child items)
         // **Unless automatic laying out is suspended, or the layout is currently running**
-        if (!owner.suspendLayout &amp;&amp; layout &amp;&amp; layout.isLayout &amp;&amp; !layout.layoutBusy) {
+        if (!owner.suspendLayout &amp;&amp; layout &amp;&amp; layout.isLayout &amp;&amp; !layout.layoutBusy &amp;&amp; !layout.isAutoDock) {
             layout.layout();
         }