Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Container.html
index c0657f8..97ae671 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>
 </head>
 <body onload="prettyPrint(); highlight();">
   <pre class="prettyprint lang-js"><span id='Ext-container-Container'>/**
-</span> * @class Ext.container.Container
- * @extends Ext.container.AbstractContainer
- * &lt;p&gt;Base class for any {@link Ext.Component} that may contain other Components. Containers handle the
- * basic behavior of containing items, namely adding, inserting and removing items.&lt;/p&gt;
- *
- * &lt;p&gt;The most commonly used Container classes are {@link Ext.panel.Panel}, {@link Ext.window.Window} and {@link Ext.tab.Panel}.
- * If you do not need the capabilities offered by the aforementioned classes you can create a lightweight
- * Container to be encapsulated by an HTML element to your specifications by using the
- * &lt;code&gt;&lt;b&gt;{@link Ext.Component#autoEl autoEl}&lt;/b&gt;&lt;/code&gt; config option.&lt;/p&gt;
- *
- * {@img Ext.Container/Ext.Container.png Ext.Container component} 
- * &lt;p&gt;The code below illustrates how to explicitly create a Container:&lt;pre&gt;&lt;code&gt;
-// explicitly create a Container
-Ext.create('Ext.container.Container', {
-    layout: {
-        type: 'hbox'
-    },
-    width: 400,
-    renderTo: Ext.getBody(),
-    border: 1,
-    style: {borderColor:'#000000', borderStyle:'solid', borderWidth:'1px'},
-    defaults: {
-        labelWidth: 80,
-        // implicitly create Container by specifying xtype
-        xtype: 'datefield',
-        flex: 1,
-        style: {
-            padding: '10px'
-        }
-    },
-    items: [{
-        xtype: 'datefield',
-        name: 'startDate',
-        fieldLabel: 'Start date'
-    },{
-        xtype: 'datefield',
-        name: 'endDate',
-        fieldLabel: 'End date'
-    }]
-});
-&lt;/code&gt;&lt;/pre&gt;&lt;/p&gt;
- *
- * &lt;p&gt;&lt;u&gt;&lt;b&gt;Layout&lt;/b&gt;&lt;/u&gt;&lt;/p&gt;
- * &lt;p&gt;Container classes delegate the rendering of child Components to a layout
- * manager class which must be configured into the Container using the
- * &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt; configuration property.&lt;/p&gt;
- * &lt;p&gt;When either specifying child &lt;code&gt;{@link #items}&lt;/code&gt; of a Container,
- * or dynamically {@link #add adding} Components to a Container, remember to
- * consider how you wish the Container to arrange those child elements, and
- * whether those child elements need to be sized using one of Ext's built-in
- * &lt;b&gt;&lt;code&gt;{@link #layout}&lt;/code&gt;&lt;/b&gt; schemes. By default, Containers use the
- * {@link Ext.layout.container.Auto Auto} scheme which only
- * renders child components, appending them one after the other inside the
- * Container, and &lt;b&gt;does not apply any sizing&lt;/b&gt; at all.&lt;/p&gt;
- * &lt;p&gt;A common mistake is when a developer neglects to specify a
- * &lt;b&gt;&lt;code&gt;{@link #layout}&lt;/code&gt;&lt;/b&gt; (e.g. widgets like GridPanels or
- * TreePanels are added to Containers for which no &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt;
- * has been specified). If a Container is left to use the default
- * {Ext.layout.container.Auto Auto} scheme, none of its
- * child components will be resized, or changed in any way when the Container
- * is resized.&lt;/p&gt;
- * &lt;p&gt;Certain layout managers allow dynamic addition of child components.
- * Those that do include {@link Ext.layout.container.Card},
- * {@link Ext.layout.container.Anchor}, {@link Ext.layout.container.VBox}, {@link Ext.layout.container.HBox}, and
- * {@link Ext.layout.container.Table}. For example:&lt;pre&gt;&lt;code&gt;
-//  Create the GridPanel.
-var myNewGrid = new Ext.grid.Panel({
-    store: myStore,
-    headers: myHeaders,
-    title: 'Results', // the title becomes the title of the tab
-});
-
-myTabPanel.add(myNewGrid); // {@link Ext.tab.Panel} implicitly uses {@link Ext.layout.container.Card Card}
-myTabPanel.{@link Ext.tab.Panel#setActiveTab setActiveTab}(myNewGrid);
- * &lt;/code&gt;&lt;/pre&gt;&lt;/p&gt;
- * &lt;p&gt;The example above adds a newly created GridPanel to a TabPanel. Note that
- * a TabPanel uses {@link Ext.layout.container.Card} as its layout manager which
- * means all its child items are sized to {@link Ext.layout.container.Fit fit}
- * exactly into its client area.
- * &lt;p&gt;&lt;b&gt;&lt;u&gt;Overnesting is a common problem&lt;/u&gt;&lt;/b&gt;.
- * An example of overnesting occurs when a GridPanel is added to a TabPanel
- * by wrapping the GridPanel &lt;i&gt;inside&lt;/i&gt; a wrapping Panel (that has no
- * &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt; specified) and then add that wrapping Panel
- * to the TabPanel. The point to realize is that a GridPanel &lt;b&gt;is&lt;/b&gt; a
- * Component which can be added directly to a Container. If the wrapping Panel
- * has no &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt; configuration, then the overnested
- * GridPanel will not be sized as expected.&lt;p&gt;
- *
- * &lt;p&gt;&lt;u&gt;&lt;b&gt;Adding via remote configuration&lt;/b&gt;&lt;/u&gt;&lt;/p&gt;
- *
- * &lt;p&gt;A server side script can be used to add Components which are generated dynamically on the server.
- * An example of adding a GridPanel to a TabPanel where the GridPanel is generated by the server
- * based on certain parameters:
- * &lt;/p&gt;&lt;pre&gt;&lt;code&gt;
-// execute an Ajax request to invoke server side script:
-Ext.Ajax.request({
-    url: 'gen-invoice-grid.php',
-    // send additional parameters to instruct server script
-    params: {
-        startDate: Ext.getCmp('start-date').getValue(),
-        endDate: Ext.getCmp('end-date').getValue()
-    },
-    // process the response object to add it to the TabPanel:
-    success: function(xhr) {
-        var newComponent = eval(xhr.responseText); // see discussion below
-        myTabPanel.add(newComponent); // add the component to the TabPanel
-        myTabPanel.setActiveTab(newComponent);
-    },
-    failure: function() {
-        Ext.Msg.alert(&quot;Grid create failed&quot;, &quot;Server communication failure&quot;);
-    }
-});
-&lt;/code&gt;&lt;/pre&gt;
- * &lt;p&gt;The server script needs to return a JSON representation of a configuration object, which, when decoded
- * will return a config object with an {@link Ext.Component#xtype xtype}. The server might return the following
- * JSON:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
-{
-    &quot;xtype&quot;: 'grid',
-    &quot;title&quot;: 'Invoice Report',
-    &quot;store&quot;: {
-        &quot;model&quot;: 'Invoice',
-        &quot;proxy&quot;: {
-            &quot;type&quot;: 'ajax',
-            &quot;url&quot;: 'get-invoice-data.php',
-            &quot;reader&quot;: {
-                &quot;type&quot;: 'json'
-                &quot;record&quot;: 'transaction',
-                &quot;idProperty&quot;: 'id',
-                &quot;totalRecords&quot;: 'total'
-            })
-        },
-        &quot;autoLoad&quot;: {
-            &quot;params&quot;: {
-                &quot;startDate&quot;: '01/01/2008',
-                &quot;endDate&quot;: '01/31/2008'
-            }
-        }
-    },
-    &quot;headers&quot;: [
-        {&quot;header&quot;: &quot;Customer&quot;, &quot;width&quot;: 250, &quot;dataIndex&quot;: 'customer', &quot;sortable&quot;: true},
-        {&quot;header&quot;: &quot;Invoice Number&quot;, &quot;width&quot;: 120, &quot;dataIndex&quot;: 'invNo', &quot;sortable&quot;: true},
-        {&quot;header&quot;: &quot;Invoice Date&quot;, &quot;width&quot;: 100, &quot;dataIndex&quot;: 'date', &quot;renderer&quot;: Ext.util.Format.dateRenderer('M d, y'), &quot;sortable&quot;: true},
-        {&quot;header&quot;: &quot;Value&quot;, &quot;width&quot;: 120, &quot;dataIndex&quot;: 'value', &quot;renderer&quot;: 'usMoney', &quot;sortable&quot;: true}
-    ]
-}
-&lt;/code&gt;&lt;/pre&gt;
- * &lt;p&gt;When the above code fragment is passed through the &lt;code&gt;eval&lt;/code&gt; function in the success handler
- * of the Ajax request, the result will be a config object which, when added to a Container, will cause instantiation
- * of a GridPanel. &lt;b&gt;Be sure that the Container is configured with a layout which sizes and positions the child items to your requirements.&lt;/b&gt;&lt;/p&gt;
- * &lt;p&gt;Note: since the code above is &lt;i&gt;generated&lt;/i&gt; by a server script, the &lt;code&gt;autoLoad&lt;/code&gt; params for
- * the Store, the user's preferred date format, the metadata to allow generation of the Model layout, and the ColumnModel
- * can all be generated into the code since these are all known on the server.&lt;/p&gt;
- *
- * @xtype container
+</span> * Base class for any Ext.Component that may contain other Components. Containers handle the basic behavior of
+ * containing items, namely adding, inserting and removing items.
+ *
+ * The most commonly used Container classes are Ext.panel.Panel, Ext.window.Window and
+ * Ext.tab.Panel. If you do not need the capabilities offered by the aforementioned classes you can create a
+ * lightweight Container to be encapsulated by an HTML element to your specifications by using the
+ * {@link Ext.Component#autoEl autoEl} config option.
+ *
+ * The code below illustrates how to explicitly create a Container:
+ *
+ *     @example
+ *     // Explicitly create a Container
+ *     Ext.create('Ext.container.Container', {
+ *         layout: {
+ *             type: 'hbox'
+ *         },
+ *         width: 400,
+ *         renderTo: Ext.getBody(),
+ *         border: 1,
+ *         style: {borderColor:'#000000', borderStyle:'solid', borderWidth:'1px'},
+ *         defaults: {
+ *             labelWidth: 80,
+ *             // implicitly create Container by specifying xtype
+ *             xtype: 'datefield',
+ *             flex: 1,
+ *             style: {
+ *                 padding: '10px'
+ *             }
+ *         },
+ *         items: [{
+ *             xtype: 'datefield',
+ *             name: 'startDate',
+ *             fieldLabel: 'Start date'
+ *         },{
+ *             xtype: 'datefield',
+ *             name: 'endDate',
+ *             fieldLabel: 'End date'
+ *         }]
+ *     });
+ *
+ * ## Layout
+ *
+ * Container classes delegate the rendering of child Components to a layout manager class which must be configured into
+ * the Container using the `{@link #layout}` configuration property.
+ *
+ * When either specifying child `{@link #items}` of a Container, or dynamically {@link #add adding} Components to a
+ * Container, remember to consider how you wish the Container to arrange those child elements, and whether those child
+ * elements need to be sized using one of Ext's built-in `{@link #layout}` schemes. By default, Containers use the
+ * {@link Ext.layout.container.Auto Auto} scheme which only renders child components, appending them one after the other
+ * inside the Container, and **does not apply any sizing** at all.
+ *
+ * A common mistake is when a developer neglects to specify a `{@link #layout}` (e.g. widgets like GridPanels or
+ * TreePanels are added to Containers for which no `{@link #layout}` has been specified). If a Container is left to
+ * use the default {@link Ext.layout.container.Auto Auto} scheme, none of its child components will be resized, or changed in
+ * any way when the Container is resized.
+ *
+ * Certain layout managers allow dynamic addition of child components. Those that do include
+ * Ext.layout.container.Card, Ext.layout.container.Anchor, Ext.layout.container.VBox,
+ * Ext.layout.container.HBox, and Ext.layout.container.Table. For example:
+ *
+ *     //  Create the GridPanel.
+ *     var myNewGrid = new Ext.grid.Panel({
+ *         store: myStore,
+ *         headers: myHeaders,
+ *         title: 'Results', // the title becomes the title of the tab
+ *     });
+ *
+ *     myTabPanel.add(myNewGrid); // {@link Ext.tab.Panel} implicitly uses {@link Ext.layout.container.Card Card}
+ *     myTabPanel.{@link Ext.tab.Panel#setActiveTab setActiveTab}(myNewGrid);
+ *
+ * The example above adds a newly created GridPanel to a TabPanel. Note that a TabPanel uses {@link
+ * Ext.layout.container.Card} as its layout manager which means all its child items are sized to {@link
+ * Ext.layout.container.Fit fit} exactly into its client area.
+ *
+ * **_Overnesting is a common problem_**. An example of overnesting occurs when a GridPanel is added to a TabPanel by
+ * wrapping the GridPanel _inside_ a wrapping Panel (that has no `{@link #layout}` specified) and then add that
+ * wrapping Panel to the TabPanel. The point to realize is that a GridPanel **is** a Component which can be added
+ * directly to a Container. If the wrapping Panel has no `{@link #layout}` configuration, then the overnested
+ * GridPanel will not be sized as expected.
+ *
+ * ## Adding via remote configuration
+ *
+ * A server side script can be used to add Components which are generated dynamically on the server. An example of
+ * adding a GridPanel to a TabPanel where the GridPanel is generated by the server based on certain parameters:
+ *
+ *     // execute an Ajax request to invoke server side script:
+ *     Ext.Ajax.request({
+ *         url: 'gen-invoice-grid.php',
+ *         // send additional parameters to instruct server script
+ *         params: {
+ *             startDate: Ext.getCmp('start-date').getValue(),
+ *             endDate: Ext.getCmp('end-date').getValue()
+ *         },
+ *         // process the response object to add it to the TabPanel:
+ *         success: function(xhr) {
+ *             var newComponent = eval(xhr.responseText); // see discussion below
+ *             myTabPanel.add(newComponent); // add the component to the TabPanel
+ *             myTabPanel.setActiveTab(newComponent);
+ *         },
+ *         failure: function() {
+ *             Ext.Msg.alert(&quot;Grid create failed&quot;, &quot;Server communication failure&quot;);
+ *         }
+ *     });
+ *
+ * The server script needs to return a JSON representation of a configuration object, which, when decoded will return a
+ * config object with an {@link Ext.Component#xtype xtype}. The server might return the following JSON:
+ *
+ *     {
+ *         &quot;xtype&quot;: 'grid',
+ *         &quot;title&quot;: 'Invoice Report',
+ *         &quot;store&quot;: {
+ *             &quot;model&quot;: 'Invoice',
+ *             &quot;proxy&quot;: {
+ *                 &quot;type&quot;: 'ajax',
+ *                 &quot;url&quot;: 'get-invoice-data.php',
+ *                 &quot;reader&quot;: {
+ *                     &quot;type&quot;: 'json'
+ *                     &quot;record&quot;: 'transaction',
+ *                     &quot;idProperty&quot;: 'id',
+ *                     &quot;totalRecords&quot;: 'total'
+ *                 })
+ *             },
+ *             &quot;autoLoad&quot;: {
+ *                 &quot;params&quot;: {
+ *                     &quot;startDate&quot;: '01/01/2008',
+ *                     &quot;endDate&quot;: '01/31/2008'
+ *                 }
+ *             }
+ *         },
+ *         &quot;headers&quot;: [
+ *             {&quot;header&quot;: &quot;Customer&quot;, &quot;width&quot;: 250, &quot;dataIndex&quot;: 'customer', &quot;sortable&quot;: true},
+ *             {&quot;header&quot;: &quot;Invoice Number&quot;, &quot;width&quot;: 120, &quot;dataIndex&quot;: 'invNo', &quot;sortable&quot;: true},
+ *             {&quot;header&quot;: &quot;Invoice Date&quot;, &quot;width&quot;: 100, &quot;dataIndex&quot;: 'date', &quot;renderer&quot;: Ext.util.Format.dateRenderer('M d, y'), &quot;sortable&quot;: true},
+ *             {&quot;header&quot;: &quot;Value&quot;, &quot;width&quot;: 120, &quot;dataIndex&quot;: 'value', &quot;renderer&quot;: 'usMoney', &quot;sortable&quot;: true}
+ *         ]
+ *     }
+ *
+ * When the above code fragment is passed through the `eval` function in the success handler of the Ajax request, the
+ * result will be a config object which, when added to a Container, will cause instantiation of a GridPanel. **Be sure
+ * that the Container is configured with a layout which sizes and positions the child items to your requirements.**
+ *
+ * **Note:** since the code above is _generated_ by a server script, the `autoLoad` params for the Store, the user's
+ * preferred date format, the metadata to allow generation of the Model layout, and the ColumnModel can all be generated
+ * into the code since these are all known on the server.
  */
 Ext.define('Ext.container.Container', {
     extend: 'Ext.container.AbstractContainer',
@@ -178,8 +168,8 @@ Ext.define('Ext.container.Container', {
 
 <span id='Ext-container-Container-method-getChildByElement'>    /**
 </span>     * Return the immediate child Component in which the passed element is located.
-     * @param el The element to test.
-     * @return {Component} The child item which contains the passed element.
+     * @param {Ext.Element/HTMLElement/String} el The element to test (or ID of element).
+     * @return {Ext.Component} The child item which contains the passed element.
      */
     getChildByElement: function(el) {
         var item,