Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / AbstractPanel.html
index 0ecf849..d5a145e 100644 (file)
   </script>
 </head>
 <body onload="prettyPrint(); highlight();">
-  <pre class="prettyprint lang-js"><span id='Ext-panel-AbstractPanel-method-constructor'><span id='Ext-panel-AbstractPanel'>/**
-</span></span> * @class Ext.panel.AbstractPanel
+  <pre class="prettyprint lang-js"><span id='Ext-panel-AbstractPanel'>/**
+</span> * @class Ext.panel.AbstractPanel
  * @extends Ext.container.Container
  * &lt;p&gt;A base class which provides methods common to Panel classes across the Sencha product range.&lt;/p&gt;
  * &lt;p&gt;Please refer to sub class's documentation&lt;/p&gt;
- * @constructor
- * @param {Object} config The config object
  */
 Ext.define('Ext.panel.AbstractPanel', {
 
@@ -51,7 +49,7 @@ Ext.define('Ext.panel.AbstractPanel', {
      * A shortcut to add or remove the border on the body of a panel. This only applies to a panel which has the {@link #frame} configuration set to `true`.
      * Defaults to &lt;code&gt;undefined&lt;/code&gt;.
      */
-    
+
 <span id='Ext-panel-AbstractPanel-cfg-bodyStyle'>    /**
 </span>     * @cfg {String/Object/Function} bodyStyle
      * Custom CSS styles to be applied to the panel's body element, which can be supplied as a valid CSS style string,
@@ -65,7 +63,7 @@ bodyStyle: {
 }
      * &lt;/code&gt;&lt;/pre&gt;
      */
-    
+
 <span id='Ext-panel-AbstractPanel-cfg-bodyCls'>    /**
 </span>     * @cfg {String/Array} bodyCls
      * A CSS class, space-delimited string of classes, or array of classes to be applied to the panel's body element.
@@ -80,6 +78,36 @@ bodyCls: ['foo', 'bar']
 
     componentLayout: 'dock',
 
+<span id='Ext-panel-AbstractPanel-cfg-defaultDockWeights'>    /**
+</span>     * @cfg {Object} defaultDockWeights
+     * This object holds the default weights applied to dockedItems that have no weight. These start with a
+     * weight of 1, to allow negative weights to insert before top items and are odd numbers
+     * so that even weights can be used to get between different dock orders.
+     * 
+     * To make default docking order match border layout, do this:
+     * &lt;pre&gt;&lt;code&gt;
+Ext.panel.AbstractPanel.prototype.defaultDockWeights = { top: 1, bottom: 3, left: 5, right: 7 };&lt;/code&gt;&lt;/pre&gt;
+     * Changing these defaults as above or individually on this object will effect all Panels.
+     * To change the defaults on a single panel, you should replace the entire object:
+     * &lt;pre&gt;&lt;code&gt;
+initComponent: function () {
+    // NOTE: Don't change members of defaultDockWeights since the object is shared.
+    this.defaultDockWeights = { top: 1, bottom: 3, left: 5, right: 7 };
+
+    this.callParent();
+}&lt;/code&gt;&lt;/pre&gt;
+     *
+     * To change only one of the default values, you do this:
+     * &lt;pre&gt;&lt;code&gt;
+initComponent: function () {
+    // NOTE: Don't change members of defaultDockWeights since the object is shared.
+    this.defaultDockWeights = Ext.applyIf({ top: 10 }, this.defaultDockWeights);
+
+    this.callParent();
+}&lt;/code&gt;&lt;/pre&gt;
+     */
+    defaultDockWeights: { top: 1, left: 3, right: 5, bottom: 7 },
+
     renderTpl: ['&lt;div class=&quot;{baseCls}-body&lt;tpl if=&quot;bodyCls&quot;&gt; {bodyCls}&lt;/tpl&gt; {baseCls}-body-{ui}&lt;tpl if=&quot;uiCls&quot;&gt;&lt;tpl for=&quot;uiCls&quot;&gt; {parent.baseCls}-body-{parent.ui}-{.}&lt;/tpl&gt;&lt;/tpl&gt;&quot;&lt;tpl if=&quot;bodyStyle&quot;&gt; style=&quot;{bodyStyle}&quot;&lt;/tpl&gt;&gt;&lt;/div&gt;'],
 
     // TODO: Move code examples into product-specific files. The code snippet below is Touch only.
@@ -100,12 +128,12 @@ var panel = new Ext.panel.Panel({
     }]
 });&lt;/code&gt;&lt;/pre&gt;
      */
-     
+
     border: true,
 
     initComponent : function() {
         var me = this;
-        
+
         me.addEvents(
 <span id='Ext-panel-AbstractPanel-event-bodyresize'>            /**
 </span>             * @event bodyresize
@@ -124,17 +152,17 @@ var panel = new Ext.panel.Panel({
         Ext.applyIf(me.renderSelectors, {
             body: '.' + me.baseCls + '-body'
         });
-        
-        //!frame 
+
+        //!frame
         //!border
-        
+
         if (me.frame &amp;&amp; me.border &amp;&amp; me.bodyBorder === undefined) {
             me.bodyBorder = false;
         }
         if (me.frame &amp;&amp; me.border &amp;&amp; (me.bodyBorder === false || me.bodyBorder === 0)) {
             me.manageBodyBorders = true;
         }
-        
+
         me.callParent();
     },
 
@@ -142,7 +170,7 @@ var panel = new Ext.panel.Panel({
     initItems : function() {
         var me = this,
             items = me.dockedItems;
-            
+
         me.callParent();
         me.dockedItems = Ext.create('Ext.util.MixedCollection', false, me.getComponentId);
         if (items) {
@@ -216,9 +244,9 @@ var panel = new Ext.panel.Panel({
         delete me.bodyStyle;
         return styles.length ? styles.join(';') : undefined;
     },
-    
+
 <span id='Ext-panel-AbstractPanel-method-initBodyCls'>    /**
-</span>     * Parse the {@link bodyCls} config if available to create a comma-delimited string of 
+</span>     * Parse the {@link bodyCls} config if available to create a comma-delimited string of
      * CSS classes to be applied to the body element.
      * @return {String} The CSS class(es)
      * @private
@@ -227,7 +255,7 @@ var panel = new Ext.panel.Panel({
         var me = this,
             cls = '',
             bodyCls = me.bodyCls;
-        
+
         if (bodyCls) {
             Ext.each(bodyCls, function(v) {
                 cls += &quot; &quot; + v;
@@ -236,7 +264,7 @@ var panel = new Ext.panel.Panel({
         }
         return cls.length &gt; 0 ? cls : undefined;
     },
-    
+
 <span id='Ext-panel-AbstractPanel-method-initRenderData'>    /**
 </span>     * Initialized the renderData to be used when rendering the renderTpl.
      * @return {Object} Object with keys and values that are going to be applied to the renderTpl
@@ -282,6 +310,9 @@ var panel = new Ext.panel.Panel({
             item.onAdded(me, i);
             me.onDockedAdd(item);
         }
+
+        // Set flag which means that beforeLayout will not veto the layout due to the size not changing
+        me.componentLayout.childrenChanged = true;
         if (me.rendered &amp;&amp; !me.suspendLayout) {
             me.doComponentLayout();
         }
@@ -312,7 +343,7 @@ var panel = new Ext.panel.Panel({
         var me = this,
             layout,
             hasLayout;
-            
+
         if (!me.dockedItems.contains(item)) {
             return item;
         }
@@ -335,8 +366,11 @@ var panel = new Ext.panel.Panel({
         if (hasLayout &amp;&amp; !autoDestroy) {
             layout.afterRemove(item);
         }
-        
-        if (!this.destroying) {
+
+
+        // Set flag which means that beforeLayout will not veto the layout due to the size not changing
+        me.componentLayout.childrenChanged = true;
+        if (!me.destroying &amp;&amp; !me.suspendLayout) {
             me.doComponentLayout();
         }
 
@@ -350,9 +384,7 @@ var panel = new Ext.panel.Panel({
      */
     getDockedItems : function(cqSelector) {
         var me = this,
-            // Start with a weight of 1, so users can provide &lt;= 0 to come before top items
-            // Odd numbers, so users can provide a weight to come in between if desired
-            defaultWeight = { top: 1, left: 3, right: 5, bottom: 7 },
+            defaultWeight = me.defaultDockWeights,
             dockedItems;
 
         if (me.dockedItems &amp;&amp; me.dockedItems.items.length) {
@@ -365,7 +397,6 @@ var panel = new Ext.panel.Panel({
 
             Ext.Array.sort(dockedItems, function(a, b) {
                 // Docked items are ordered by their visual representation by default (t,l,r,b)
-                // TODO: Enforce position ordering, and have weights be sub-ordering within positions?
                 var aw = a.weight || defaultWeight[a.dock],
                     bw = b.weight || defaultWeight[b.dock];
                 if (Ext.isNumber(aw) &amp;&amp; Ext.isNumber(bw)) {
@@ -373,57 +404,123 @@ var panel = new Ext.panel.Panel({
                 }
                 return 0;
             });
-            
+
             return dockedItems;
         }
         return [];
     },
-    
+
     // inherit docs
     addUIClsToElement: function(cls, force) {
-        var me = this;
-        
-        me.callParent(arguments);
-        
+        var me = this,
+            result = me.callParent(arguments),
+            classes = [Ext.baseCSSPrefix + cls, me.baseCls + '-body-' + cls, me.baseCls + '-body-' + me.ui + '-' + cls],
+            array, i;
+
         if (!force &amp;&amp; me.rendered) {
-            me.body.addCls(Ext.baseCSSPrefix + cls);
-            me.body.addCls(me.baseCls + '-body-' + cls);
-            me.body.addCls(me.baseCls + '-body-' + me.ui + '-' + cls);
+            if (me.bodyCls) {
+                me.body.addCls(me.bodyCls);
+            } else {
+                me.body.addCls(classes);
+            }
+        } else {
+            if (me.bodyCls) {
+                array = me.bodyCls.split(' ');
+
+                for (i = 0; i &lt; classes.length; i++) {
+                    if (!Ext.Array.contains(array, classes[i])) {
+                        array.push(classes[i]);
+                    }
+                }
+
+                me.bodyCls = array.join(' ');
+            } else {
+                me.bodyCls = classes.join(' ');
+            }
         }
+
+        return result;
     },
-    
+
     // inherit docs
     removeUIClsFromElement: function(cls, force) {
-        var me = this;
-        
-        me.callParent(arguments);
-        
+        var me = this,
+            result = me.callParent(arguments),
+            classes = [Ext.baseCSSPrefix + cls, me.baseCls + '-body-' + cls, me.baseCls + '-body-' + me.ui + '-' + cls],
+            array, i;
+
         if (!force &amp;&amp; me.rendered) {
-            me.body.removeCls(Ext.baseCSSPrefix + cls);
-            me.body.removeCls(me.baseCls + '-body-' + cls);
-            me.body.removeCls(me.baseCls + '-body-' + me.ui + '-' + cls);
+            if (me.bodyCls) {
+                me.body.removeCls(me.bodyCls);
+            } else {
+                me.body.removeCls(classes);
+            }
+        } else {
+            if (me.bodyCls) {
+                array = me.bodyCls.split(' ');
+
+                for (i = 0; i &lt; classes.length; i++) {
+                    Ext.Array.remove(array, classes[i]);
+                }
+
+                me.bodyCls = array.join(' ');
+            }
         }
+
+        return result;
     },
-    
+
     // inherit docs
     addUIToElement: function(force) {
-        var me = this;
-        
+        var me = this,
+            cls = me.baseCls + '-body-' + me.ui,
+            array;
+
         me.callParent(arguments);
-        
+
         if (!force &amp;&amp; me.rendered) {
-            me.body.addCls(me.baseCls + '-body-' + me.ui);
+            if (me.bodyCls) {
+                me.body.addCls(me.bodyCls);
+            } else {
+                me.body.addCls(cls);
+            }
+        } else {
+            if (me.bodyCls) {
+                array = me.bodyCls.split(' ');
+
+                if (!Ext.Array.contains(array, cls)) {
+                    array.push(cls);
+                }
+
+                me.bodyCls = array.join(' ');
+            } else {
+                me.bodyCls = cls;
+            }
         }
     },
-    
+
     // inherit docs
     removeUIFromElement: function() {
-        var me = this;
-        
+        var me = this,
+            cls = me.baseCls + '-body-' + me.ui,
+            array;
+
         me.callParent(arguments);
-        
+
         if (me.rendered) {
-            me.body.removeCls(me.baseCls + '-body-' + me.ui);
+            if (me.bodyCls) {
+                me.body.removeCls(me.bodyCls);
+            } else {
+                me.body.removeCls(cls);
+            }
+        } else {
+            if (me.bodyCls) {
+                array = me.bodyCls.split(' ');
+                Ext.Array.remove(array, cls);
+                me.bodyCls = array.join(' ');
+            } else {
+                me.bodyCls = cls;
+            }
         }
     },
 
@@ -439,7 +536,7 @@ var panel = new Ext.panel.Panel({
             ln = dockedItems.length,
             i = 0,
             item;
-        
+
         // Find the index where we go from top/left docked items to right/bottom docked items
         for (; i &lt; ln; i++) {
             item = dockedItems[i];
@@ -447,11 +544,11 @@ var panel = new Ext.panel.Panel({
                 break;
             }
         }
-        
+
         // Return docked items in the top/left position before our container items, and
         // return right/bottom positioned items after our container items.
         // See AbstractDock.renderItems() for more information.
-        return dockedItems.splice(0, i).concat(items).concat(dockedItems);
+        return Ext.Array.splice(dockedItems, 0, i).concat(items).concat(dockedItems);
     },
 
     beforeDestroy: function(){
@@ -465,7 +562,7 @@ var panel = new Ext.panel.Panel({
         }
         this.callParent();
     },
-    
+
     setBorder: function(border) {
         var me = this;
         me.border = (border !== undefined) ? border : true;