Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Checkbox.html
index 0dee554..258a2a4 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-field-Checkbox'>/**
-</span> * @class Ext.form.field.Checkbox
- * @extends Ext.form.field.Base
-
-Single checkbox field. Can be used as a direct replacement for traditional checkbox fields. Also serves as a
-parent class for {@link Ext.form.field.Radio radio buttons}.
-
-__Labeling:__ In addition to the {@link Ext.form.Labelable standard field labeling options}, checkboxes
-may be given an optional {@link #boxLabel} which will be displayed immediately after checkbox. Also see
-{@link Ext.form.CheckboxGroup} for a convenient method of grouping related checkboxes.
-
-__Values:__
-The main value of a checkbox is a boolean, indicating whether or not the checkbox is checked.
-The following values will check the checkbox:
-* `true`
-* `'true'`
-* `'1'`
-* `'on'`
-
-Any other value will uncheck the checkbox.
-
-In addition to the main boolean value, you may also specify a separate {@link #inputValue}. This will be
-sent as the parameter value when the form is {@link Ext.form.Basic#submit submitted}. You will want to set
-this value if you have multiple checkboxes with the same {@link #name}. If not specified, the value `on`
-will be used.
-{@img Ext.form.Checkbox/Ext.form.Checkbox.png Ext.form.Checkbox Checkbox component}
-__Example usage:__
-
-    Ext.create('Ext.form.Panel', {
-        bodyPadding: 10,
-        width      : 300,
-        title      : 'Pizza Order',
-        items: [
-            {
-                xtype      : 'fieldcontainer',
-                fieldLabel : 'Toppings',
-                defaultType: 'checkboxfield',
-                items: [
-                    {
-                        boxLabel  : 'Anchovies',
-                        name      : 'topping',
-                        inputValue: '1',
-                        id        : 'checkbox1'
-                    }, {
-                        boxLabel  : 'Artichoke Hearts',
-                        name      : 'topping',
-                        inputValue: '2',
-                        checked   : true,
-                        id        : 'checkbox2'
-                    }, {
-                        boxLabel  : 'Bacon',
-                        name      : 'topping',
-                        inputValue: '3',
-                        id        : 'checkbox3'
-                    }
-                ]
-            }
-        ],
-        bbar: [
-            {
-                text: 'Select Bacon',
-                handler: function() {
-                    var checkbox = Ext.getCmp('checkbox3');
-                    checkbox.setValue(true);
-                }
-            },
-            '-',
-            {
-                text: 'Select All',
-                handler: function() {
-                    var checkbox1 = Ext.getCmp('checkbox1'),
-                        checkbox2 = Ext.getCmp('checkbox2'),
-                        checkbox3 = Ext.getCmp('checkbox3');
-
-                    checkbox1.setValue(true);
-                    checkbox2.setValue(true);
-                    checkbox3.setValue(true);
-                }
-            },
-            {
-                text: 'Deselect All',
-                handler: function() {
-                    var checkbox1 = Ext.getCmp('checkbox1'),
-                        checkbox2 = Ext.getCmp('checkbox2'),
-                        checkbox3 = Ext.getCmp('checkbox3');
-
-                    checkbox1.setValue(false);
-                    checkbox2.setValue(false);
-                    checkbox3.setValue(false);
-                }
-            }
-        ],
-        renderTo: Ext.getBody()
-    });
-
- * @docauthor Robert Dougan &lt;rob@sencha.com&gt;
- * @markdown
+</span> * @docauthor Robert Dougan &lt;rob@sencha.com&gt;
+ *
+ * Single checkbox field. Can be used as a direct replacement for traditional checkbox fields. Also serves as a
+ * parent class for {@link Ext.form.field.Radio radio buttons}.
+ *
+ * # Labeling
+ *
+ * In addition to the {@link Ext.form.Labelable standard field labeling options}, checkboxes
+ * may be given an optional {@link #boxLabel} which will be displayed immediately after checkbox. Also see
+ * {@link Ext.form.CheckboxGroup} for a convenient method of grouping related checkboxes.
+ *
+ * # Values
+ *
+ * The main value of a checkbox is a boolean, indicating whether or not the checkbox is checked.
+ * The following values will check the checkbox:
+ *
+ * - `true`
+ * - `'true'`
+ * - `'1'`
+ * - `'on'`
+ *
+ * Any other value will uncheck the checkbox.
+ *
+ * In addition to the main boolean value, you may also specify a separate {@link #inputValue}. This will be
+ * sent as the parameter value when the form is {@link Ext.form.Basic#submit submitted}. You will want to set
+ * this value if you have multiple checkboxes with the same {@link #name}. If not specified, the value `on`
+ * will be used.
+ *
+ * # Example usage
+ *
+ *     @example
+ *     Ext.create('Ext.form.Panel', {
+ *         bodyPadding: 10,
+ *         width: 300,
+ *         title: 'Pizza Order',
+ *         items: [
+ *             {
+ *                 xtype: 'fieldcontainer',
+ *                 fieldLabel: 'Toppings',
+ *                 defaultType: 'checkboxfield',
+ *                 items: [
+ *                     {
+ *                         boxLabel  : 'Anchovies',
+ *                         name      : 'topping',
+ *                         inputValue: '1',
+ *                         id        : 'checkbox1'
+ *                     }, {
+ *                         boxLabel  : 'Artichoke Hearts',
+ *                         name      : 'topping',
+ *                         inputValue: '2',
+ *                         checked   : true,
+ *                         id        : 'checkbox2'
+ *                     }, {
+ *                         boxLabel  : 'Bacon',
+ *                         name      : 'topping',
+ *                         inputValue: '3',
+ *                         id        : 'checkbox3'
+ *                     }
+ *                 ]
+ *             }
+ *         ],
+ *         bbar: [
+ *             {
+ *                 text: 'Select Bacon',
+ *                 handler: function() {
+ *                     Ext.getCmp('checkbox3').setValue(true);
+ *                 }
+ *             },
+ *             '-',
+ *             {
+ *                 text: 'Select All',
+ *                 handler: function() {
+ *                     Ext.getCmp('checkbox1').setValue(true);
+ *                     Ext.getCmp('checkbox2').setValue(true);
+ *                     Ext.getCmp('checkbox3').setValue(true);
+ *                 }
+ *             },
+ *             {
+ *                 text: 'Deselect All',
+ *                 handler: function() {
+ *                     Ext.getCmp('checkbox1').setValue(false);
+ *                     Ext.getCmp('checkbox2').setValue(false);
+ *                     Ext.getCmp('checkbox3').setValue(false);
+ *                 }
+ *             }
+ *         ],
+ *         renderTo: Ext.getBody()
+ *     });
  */
 Ext.define('Ext.form.field.Checkbox', {
     extend: 'Ext.form.field.Base',
@@ -119,9 +111,10 @@ Ext.define('Ext.form.field.Checkbox', {
     alternateClassName: 'Ext.form.Checkbox',
     requires: ['Ext.XTemplate', 'Ext.form.CheckboxManager'],
 
+    // note: {id} here is really {inputId}, but {cmpId} is available
     fieldSubTpl: [
         '&lt;tpl if=&quot;boxLabel &amp;&amp; boxLabelAlign == \'before\'&quot;&gt;',
-            '&lt;label class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
+            '&lt;label id=&quot;{cmpId}-boxLabelEl&quot; class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
         '&lt;/tpl&gt;',
         // Creates not an actual checkbox, but a button which is given aria role=&quot;checkbox&quot; and
         // styled with a custom checkbox image. This allows greater control and consistency in
@@ -130,7 +123,7 @@ Ext.define('Ext.form.field.Checkbox', {
             '&lt;tpl if=&quot;tabIdx&quot;&gt;tabIndex=&quot;{tabIdx}&quot; &lt;/tpl&gt;',
             'class=&quot;{fieldCls} {typeCls}&quot; autocomplete=&quot;off&quot; hidefocus=&quot;true&quot; /&gt;',
         '&lt;tpl if=&quot;boxLabel &amp;&amp; boxLabelAlign == \'after\'&quot;&gt;',
-            '&lt;label class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
+            '&lt;label id=&quot;{cmpId}-boxLabelEl&quot; class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
         '&lt;/tpl&gt;',
         {
             disableFormats: true,
@@ -141,72 +134,79 @@ Ext.define('Ext.form.field.Checkbox', {
     isCheckbox: true,
 
 <span id='Ext-form-field-Checkbox-cfg-focusCls'>    /**
-</span>     * @cfg {String} focusCls The CSS class to use when the checkbox receives focus
-     * (defaults to &lt;tt&gt;'x-form-cb-focus'&lt;/tt&gt;)
+</span>     * @cfg {String} [focusCls='x-form-cb-focus']
+     * The CSS class to use when the checkbox receives focus
      */
     focusCls: Ext.baseCSSPrefix + 'form-cb-focus',
 
 <span id='Ext-form-field-Checkbox-cfg-fieldCls'>    /**
-</span>     * @cfg {String} fieldCls The default CSS class for the checkbox (defaults to &lt;tt&gt;'x-form-field'&lt;/tt&gt;)
+</span>     * @cfg {String} [fieldCls='x-form-field']
+     * The default CSS class for the checkbox
      */
 
 <span id='Ext-form-field-Checkbox-cfg-fieldBodyCls'>    /**
-</span>     * @cfg {String} fieldBodyCls
+</span>     * @cfg {String} [fieldBodyCls='x-form-cb-wrap']
      * An extra CSS class to be applied to the body content element in addition to {@link #fieldBodyCls}.
-     * Defaults to 'x-form-cb-wrap.
+     * .
      */
     fieldBodyCls: Ext.baseCSSPrefix + 'form-cb-wrap',
 
 <span id='Ext-form-field-Checkbox-cfg-checked'>    /**
-</span>     * @cfg {Boolean} checked &lt;tt&gt;true&lt;/tt&gt; if the checkbox should render initially checked (defaults to &lt;tt&gt;false&lt;/tt&gt;)
+</span>     * @cfg {Boolean} checked
+     * true if the checkbox should render initially checked
      */
     checked: false,
 
 <span id='Ext-form-field-Checkbox-cfg-checkedCls'>    /**
-</span>     * @cfg {String} checkedCls The CSS class added to the component's main element when it is in the checked state.
+</span>     * @cfg {String} [checkedCls='x-form-cb-checked']
+     * The CSS class added to the component's main element when it is in the checked state.
      */
     checkedCls: Ext.baseCSSPrefix + 'form-cb-checked',
 
 <span id='Ext-form-field-Checkbox-cfg-boxLabel'>    /**
-</span>     * @cfg {String} boxLabel An optional text label that will appear next to the checkbox. Whether it appears before
-     * or after the checkbox is determined by the {@link #boxLabelAlign} config (defaults to after).
+</span>     * @cfg {String} boxLabel
+     * An optional text label that will appear next to the checkbox. Whether it appears before or after the checkbox is
+     * determined by the {@link #boxLabelAlign} config.
      */
 
 <span id='Ext-form-field-Checkbox-cfg-boxLabelCls'>    /**
-</span>     * @cfg {String} boxLabelCls The CSS class to be applied to the {@link #boxLabel} element
+</span>     * @cfg {String} [boxLabelCls='x-form-cb-label']
+     * The CSS class to be applied to the {@link #boxLabel} element
      */
     boxLabelCls: Ext.baseCSSPrefix + 'form-cb-label',
 
 <span id='Ext-form-field-Checkbox-cfg-boxLabelAlign'>    /**
-</span>     * @cfg {String} boxLabelAlign The position relative to the checkbox where the {@link #boxLabel} should
-     * appear. Recognized values are &lt;tt&gt;'before'&lt;/tt&gt; and &lt;tt&gt;'after'&lt;/tt&gt;. Defaults to &lt;tt&gt;'after'&lt;/tt&gt;.
+</span>     * @cfg {String} boxLabelAlign
+     * The position relative to the checkbox where the {@link #boxLabel} should appear. Recognized values are 'before'
+     * and 'after'.
      */
     boxLabelAlign: 'after',
 
 <span id='Ext-form-field-Checkbox-cfg-inputValue'>    /**
-</span>     * @cfg {String} inputValue The value that should go into the generated input element's value attribute and
-     * should be used as the parameter value when submitting as part of a form. Defaults to &lt;tt&gt;&quot;on&quot;&lt;/tt&gt;.
+</span>     * @cfg {String} inputValue
+     * The value that should go into the generated input element's value attribute and should be used as the parameter
+     * value when submitting as part of a form.
      */
     inputValue: 'on',
 
 <span id='Ext-form-field-Checkbox-cfg-uncheckedValue'>    /**
-</span>     * @cfg {String} uncheckedValue If configured, this will be submitted as the checkbox's value during form
-     * submit if the checkbox is unchecked. By default this is undefined, which results in nothing being
-     * submitted for the checkbox field when the form is submitted (the default behavior of HTML checkboxes).
+</span>     * @cfg {String} uncheckedValue
+     * If configured, this will be submitted as the checkbox's value during form submit if the checkbox is unchecked. By
+     * default this is undefined, which results in nothing being submitted for the checkbox field when the form is
+     * submitted (the default behavior of HTML checkboxes).
      */
 
 <span id='Ext-form-field-Checkbox-cfg-handler'>    /**
-</span>     * @cfg {Function} handler A function called when the {@link #checked} value changes (can be used instead of
-     * handling the {@link #change change event}). The handler is passed the following parameters:
-     * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
-     * &lt;li&gt;&lt;b&gt;checkbox&lt;/b&gt; : Ext.form.field.Checkbox&lt;div class=&quot;sub-desc&quot;&gt;The Checkbox being toggled.&lt;/div&gt;&lt;/li&gt;
-     * &lt;li&gt;&lt;b&gt;checked&lt;/b&gt; : Boolean&lt;div class=&quot;sub-desc&quot;&gt;The new checked state of the checkbox.&lt;/div&gt;&lt;/li&gt;
-     * &lt;/ul&gt;&lt;/div&gt;
+</span>     * @cfg {Function} handler
+     * A function called when the {@link #checked} value changes (can be used instead of handling the {@link #change
+     * change event}).
+     * @cfg {Ext.form.field.Checkbox} handler.checkbox The Checkbox being toggled.
+     * @cfg {Boolean} handler.checked The new checked state of the checkbox.
      */
 
 <span id='Ext-form-field-Checkbox-cfg-scope'>    /**
-</span>     * @cfg {Object} scope An object to use as the scope ('this' reference) of the {@link #handler} function
-     * (defaults to this Checkbox).
+</span>     * @cfg {Object} scope
+     * An object to use as the scope ('this' reference) of the {@link #handler} function (defaults to this Checkbox).
      */
 
     // private overrides
@@ -227,11 +227,9 @@ Ext.define('Ext.form.field.Checkbox', {
             checked = !!me.checked;
 
 <span id='Ext-form-field-Checkbox-property-originalValue'>        /**
-</span>         * The original value of the field as configured in the {@link #checked} configuration, or
-         * as loaded by the last form load operation if the form's {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}
-         * setting is &lt;code&gt;true&lt;/code&gt;.
-         * @type Mixed
-         * @property originalValue
+</span>         * @property {Object} originalValue
+         * The original value of the field as configured in the {@link #checked} configuration, or as loaded by the last
+         * form load operation if the form's {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad} setting is `true`.
          */
         me.originalValue = me.lastValue = checked;
 
@@ -242,15 +240,14 @@ Ext.define('Ext.form.field.Checkbox', {
     // private
     onRender : function(ct, position) {
         var me = this;
-        Ext.applyIf(me.renderSelectors, {
-<span id='Ext-form-field-Checkbox-property-boxLabelEl'>            /**
-</span>             * @property boxLabelEl
-             * @type Ext.core.Element
-             * A reference to the label element created for the {@link #boxLabel}. Only present if the
-             * component has been rendered and has a boxLabel configured.
-             */
-            boxLabelEl: 'label.' + me.boxLabelCls
-        });
+
+<span id='Ext-form-field-Checkbox-property-boxLabelEl'>        /**
+</span>         * @property {Ext.Element} boxLabelEl
+         * A reference to the label element created for the {@link #boxLabel}. Only present if the component has been
+         * rendered and has a boxLabel configured.
+         */
+        me.addChildEls('boxLabelEl');
+
         Ext.applyIf(me.subTplData, {
             boxLabel: me.boxLabel,
             boxLabelCls: me.boxLabelCls,
@@ -294,7 +291,7 @@ Ext.define('Ext.form.field.Checkbox', {
 
 <span id='Ext-form-field-Checkbox-method-getSubmitValue'>    /**
 </span>     * Returns the submit value for the checkbox which can be used when submitting forms.
-     * @return {Boolean/null} True if checked; otherwise either the {@link #uncheckedValue} or null.
+     * @return {Boolean/Object} True if checked; otherwise either the {@link #uncheckedValue} or null.
      */
     getSubmitValue: function() {
         var unchecked = this.uncheckedValue,
@@ -304,8 +301,9 @@ Ext.define('Ext.form.field.Checkbox', {
 
 <span id='Ext-form-field-Checkbox-method-setRawValue'>    /**
 </span>     * Sets the checked state of the checkbox.
-     * @param {Boolean/String} value The following values will check the checkbox:
-     * &lt;code&gt;true, 'true', '1', or 'on'&lt;/code&gt;, as well as a String that matches the {@link #inputValue}.
+     *
+     * @param {Boolean/String/Number} value The following values will check the checkbox:
+     * `true, 'true', '1', 1, or 'on'`, as well as a String that matches the {@link #inputValue}.
      * Any other value will uncheck the checkbox.
      * @return {Boolean} the new checked state of the checkbox
      */
@@ -313,8 +311,8 @@ Ext.define('Ext.form.field.Checkbox', {
         var me = this,
             inputEl = me.inputEl,
             inputValue = me.inputValue,
-            checked = (value === true || value === 'true' || value === '1' ||
-                      ((Ext.isString(value) &amp;&amp; inputValue) ? value == inputValue : me.onRe.test(value)));
+            checked = (value === true || value === 'true' || value === '1' || value === 1 ||
+                (((Ext.isString(value) || Ext.isNumber(value)) &amp;&amp; inputValue) ? value == inputValue : me.onRe.test(value)));
 
         if (inputEl) {
             inputEl.dom.setAttribute('aria-checked', checked);
@@ -327,9 +325,8 @@ Ext.define('Ext.form.field.Checkbox', {
 
 <span id='Ext-form-field-Checkbox-method-setValue'>    /**
 </span>     * Sets the checked state of the checkbox, and invokes change detection.
-     * @param {Boolean/String} checked The following values will check the checkbox:
-     * &lt;code&gt;true, 'true', '1', or 'on'&lt;/code&gt;, as well as a String that matches the {@link #inputValue}.
-     * Any other value will uncheck the checkbox.
+     * @param {Boolean/String} checked The following values will check the checkbox: `true, 'true', '1', or 'on'`, as
+     * well as a String that matches the {@link #inputValue}. Any other value will uncheck the checkbox.
      * @return {Ext.form.field.Checkbox} this
      */
     setValue: function(checked) {
@@ -370,6 +367,12 @@ Ext.define('Ext.form.field.Checkbox', {
         me.callParent(arguments);
     },
 
+    // inherit docs
+    beforeDestroy: function(){
+        this.callParent();
+        this.getManager().removeAtKey(this.id);
+    },
+
     // inherit docs
     getManager: function() {
         return Ext.form.CheckboxManager;
@@ -395,11 +398,8 @@ Ext.define('Ext.form.field.Checkbox', {
         me.readOnly = readOnly;
     },
 
-<span id='Ext-form-field-Checkbox-method-getBodyNaturalWidth'>    /**
-</span>     * @protected Calculate and return the natural width of the bodyEl. It's possible that the initial
-     * rendering will cause the boxLabel to wrap and give us a bad width, so we must prevent wrapping
-     * while measuring.
-     */
+    // Calculates and returns the natural width of the bodyEl. It's possible that the initial rendering will
+    // cause the boxLabel to wrap and give us a bad width, so we must prevent wrapping while measuring.
     getBodyNaturalWidth: function() {
         var me = this,
             bodyEl = me.bodyEl,