Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / FieldContainer.html
index 082f4d2..ad22c66 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-form-FieldContainer'>/**
-</span> * @class Ext.form.FieldContainer
- * @extends Ext.container.Container
-
-FieldContainer is a derivation of {@link Ext.container.Container Container} that implements the
-{@link Ext.form.Labelable Labelable} mixin. This allows it to be configured so that it is rendered with
-a {@link #fieldLabel field label} and optional {@link #msgTarget error message} around its sub-items.
-This is useful for arranging a group of fields or other components within a single item in a form, so
-that it lines up nicely with other fields. A common use is for grouping a set of related fields under
-a single label in a form.
-
-The container's configured {@link #items} will be layed out within the field body area according to the
-configured {@link #layout} type. The default layout is `'autocontainer'`.
-
-Like regular fields, FieldContainer can inherit its decoration configuration from the
-{@link Ext.form.Panel#fieldDefaults fieldDefaults} of an enclosing FormPanel. In addition,
-FieldContainer itself can pass {@link #fieldDefaults} to any {@link Ext.form.Labelable fields}
-it may itself contain.
-
-If you are grouping a set of {@link Ext.form.field.Checkbox Checkbox} or {@link Ext.form.field.Radio Radio}
-fields in a single labeled container, consider using a {@link Ext.form.CheckboxGroup}
-or {@link Ext.form.RadioGroup} instead as they are specialized for handling those types.
-{@img Ext.form.FieldContainer/Ext.form.FieldContainer1.png Ext.form.FieldContainer component}
-__Example usage:__
-
-    Ext.create('Ext.form.Panel', {
-        title: 'FieldContainer Example',
-        width: 550,
-        bodyPadding: 10,
-    
-        items: [{
-            xtype: 'fieldcontainer',
-            fieldLabel: 'Last Three Jobs',
-            labelWidth: 100,
-    
-            // The body area will contain three text fields, arranged
-            // horizontally, separated by draggable splitters.
-            layout: 'hbox',
-            items: [{
-                xtype: 'textfield',
-                flex: 1
-            }, {
-                xtype: 'splitter'
-            }, {
-                xtype: 'textfield',
-                flex: 1
-            }, {
-                xtype: 'splitter'
-            }, {
-                xtype: 'textfield',
-                flex: 1
-            }]
-        }],
-        renderTo: Ext.getBody()
-    });
-
-__Usage of {@link #fieldDefaults}:__
-{@img Ext.form.FieldContainer/Ext.form.FieldContainer2.png Ext.form.FieldContainer component}
-
-    Ext.create('Ext.form.Panel', {
-        title: 'FieldContainer Example',
-        width: 350,
-        bodyPadding: 10,
-    
-        items: [{
-            xtype: 'fieldcontainer',
-            fieldLabel: 'Your Name',
-            labelWidth: 75,
-            defaultType: 'textfield',
-    
-            // Arrange fields vertically, stretched to full width
-            layout: 'anchor',
-            defaults: {
-                layout: '100%'
-            },
-    
-            // These config values will be applied to both sub-fields, except
-            // for Last Name which will use its own msgTarget.
-            fieldDefaults: {
-                msgTarget: 'under',
-                labelAlign: 'top'
-            },
-    
-            items: [{
-                fieldLabel: 'First Name',
-                name: 'firstName'
-            }, {
-                fieldLabel: 'Last Name',
-                name: 'lastName',
-                msgTarget: 'under'
-            }]
-        }],
-        renderTo: Ext.getBody()
-    });
-
-
- * @markdown
+</span> * FieldContainer is a derivation of {@link Ext.container.Container Container} that implements the
+ * {@link Ext.form.Labelable Labelable} mixin. This allows it to be configured so that it is rendered with
+ * a {@link #fieldLabel field label} and optional {@link #msgTarget error message} around its sub-items.
+ * This is useful for arranging a group of fields or other components within a single item in a form, so
+ * that it lines up nicely with other fields. A common use is for grouping a set of related fields under
+ * a single label in a form.
+ * 
+ * The container's configured {@link #items} will be layed out within the field body area according to the
+ * configured {@link #layout} type. The default layout is `'autocontainer'`.
+ * 
+ * Like regular fields, FieldContainer can inherit its decoration configuration from the
+ * {@link Ext.form.Panel#fieldDefaults fieldDefaults} of an enclosing FormPanel. In addition,
+ * FieldContainer itself can pass {@link #fieldDefaults} to any {@link Ext.form.Labelable fields}
+ * it may itself contain.
+ * 
+ * If you are grouping a set of {@link Ext.form.field.Checkbox Checkbox} or {@link Ext.form.field.Radio Radio}
+ * fields in a single labeled container, consider using a {@link Ext.form.CheckboxGroup}
+ * or {@link Ext.form.RadioGroup} instead as they are specialized for handling those types.
+ *
+ * # Example
+ * 
+ *     @example
+ *     Ext.create('Ext.form.Panel', {
+ *         title: 'FieldContainer Example',
+ *         width: 550,
+ *         bodyPadding: 10,
+ * 
+ *         items: [{
+ *             xtype: 'fieldcontainer',
+ *             fieldLabel: 'Last Three Jobs',
+ *             labelWidth: 100,
+ * 
+ *             // The body area will contain three text fields, arranged
+ *             // horizontally, separated by draggable splitters.
+ *             layout: 'hbox',
+ *             items: [{
+ *                 xtype: 'textfield',
+ *                 flex: 1
+ *             }, {
+ *                 xtype: 'splitter'
+ *             }, {
+ *                 xtype: 'textfield',
+ *                 flex: 1
+ *             }, {
+ *                 xtype: 'splitter'
+ *             }, {
+ *                 xtype: 'textfield',
+ *                 flex: 1
+ *             }]
+ *         }],
+ *         renderTo: Ext.getBody()
+ *     });
+ * 
+ * # Usage of fieldDefaults
+ *
+ *     @example
+ *     Ext.create('Ext.form.Panel', {
+ *         title: 'FieldContainer Example',
+ *         width: 350,
+ *         bodyPadding: 10,
+ * 
+ *         items: [{
+ *             xtype: 'fieldcontainer',
+ *             fieldLabel: 'Your Name',
+ *             labelWidth: 75,
+ *             defaultType: 'textfield',
+ * 
+ *             // Arrange fields vertically, stretched to full width
+ *             layout: 'anchor',
+ *             defaults: {
+ *                 layout: '100%'
+ *             },
+ * 
+ *             // These config values will be applied to both sub-fields, except
+ *             // for Last Name which will use its own msgTarget.
+ *             fieldDefaults: {
+ *                 msgTarget: 'under',
+ *                 labelAlign: 'top'
+ *             },
+ * 
+ *             items: [{
+ *                 fieldLabel: 'First Name',
+ *                 name: 'firstName'
+ *             }, {
+ *                 fieldLabel: 'Last Name',
+ *                 name: 'lastName',
+ *                 msgTarget: 'under'
+ *             }]
+ *         }],
+ *         renderTo: Ext.getBody()
+ *     });
+ * 
  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  */
 Ext.define('Ext.form.FieldContainer', {
@@ -145,7 +141,7 @@ Ext.define('Ext.form.FieldContainer', {
      * {@link #msgTarget}. Defaults to false.
      */
     combineErrors: false,
-    
+
     maskOnDisable: false,
 
     initComponent: function() {
@@ -180,11 +176,9 @@ Ext.define('Ext.form.FieldContainer', {
     },
 
     onRender: function() {
-        var me = this,
-            renderSelectors = me.renderSelectors,
-            applyIf = Ext.applyIf;
+        var me = this;
 
-        applyIf(renderSelectors, me.getLabelableSelectors());
+        me.onLabelableRender();
 
         me.callParent(arguments);
     },
@@ -258,8 +252,8 @@ Ext.define('Ext.form.FieldContainer', {
      * messages from them. Defaults to prepending each message by the field name and a colon. This
      * can be overridden to provide custom combined error message handling, for instance changing
      * the format of each message or sorting the array (it is sorted in order of appearance by default).
-     * @param {Array} invalidFields An Array of the sub-fields which are currently invalid.
-     * @return {Array} The combined list of error messages
+     * @param {Ext.form.field.Field[]} invalidFields An Array of the sub-fields which are currently invalid.
+     * @return {String[]} The combined list of error messages
      */
     getCombinedErrors: function(invalidFields) {
         var forEach = Ext.Array.forEach,