docs/source/Checkbox.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-form.field.Checkbox-method-constructor'><span id='Ext-form.field.Checkbox'>/**
   2 </span></span> * @class Ext.form.field.Checkbox
   3  * @extends Ext.form.field.Base
   4
   5 Single checkbox field. Can be used as a direct replacement for traditional checkbox fields. Also serves as a
   6 parent class for {@link Ext.form.field.Radio radio buttons}.
   7
   8 __Labeling:__ In addition to the {@link Ext.form.Labelable standard field labeling options}, checkboxes
   9 may be given an optional {@link #boxLabel} which will be displayed immediately after checkbox. Also see
  10 {@link Ext.form.CheckboxGroup} for a convenient method of grouping related checkboxes.
  11
  12 __Values:__
  13 The main value of a checkbox is a boolean, indicating whether or not the checkbox is checked.
  14 The following values will check the checkbox:
  15 * `true`
  16 * `'true'`
  17 * `'1'`
  18 * `'on'`
  19
  20 Any other value will uncheck the checkbox.
  21
  22 In addition to the main boolean value, you may also specify a separate {@link #inputValue}. This will be
  23 sent as the parameter value when the form is {@link Ext.form.Basic#submit submitted}. You will want to set
  24 this value if you have multiple checkboxes with the same {@link #name}. If not specified, the value `on`
  25 will be used.
  26 {@img Ext.form.Checkbox/Ext.form.Checkbox.png Ext.form.Checkbox Checkbox component}
  27 __Example usage:__
  28
  29     Ext.create('Ext.form.Panel', {
  30         bodyPadding: 10,
  31         width      : 300,
  32         title      : 'Pizza Order',
  33         items: [
  34             {
  35                 xtype      : 'fieldcontainer',
  36                 fieldLabel : 'Toppings',
  37                 defaultType: 'checkboxfield',
  38                 items: [
  39                     {
  40                         boxLabel  : 'Anchovies',
  41                         name      : 'topping',
  42                         inputValue: '1',
  43                         id        : 'checkbox1'
  44                     }, {
  45                         boxLabel  : 'Artichoke Hearts',
  46                         name      : 'topping',
  47                         inputValue: '2',
  48                         checked   : true,
  49                         id        : 'checkbox2'
  50                     }, {
  51                         boxLabel  : 'Bacon',
  52                         name      : 'topping',
  53                         inputValue: '3',
  54                         id        : 'checkbox3'
  55                     }
  56                 ]
  57             }
  58         ],
  59         bbar: [
  60             {
  61                 text: 'Select Bacon',
  62                 handler: function() {
  63                     var checkbox = Ext.getCmp('checkbox3');
  64                     checkbox.setValue(true);
  65                 }
  66             },
  67             '-',
  68             {
  69                 text: 'Select All',
  70                 handler: function() {
  71                     var checkbox1 = Ext.getCmp('checkbox1'),
  72                         checkbox2 = Ext.getCmp('checkbox2'),
  73                         checkbox3 = Ext.getCmp('checkbox3');
  74
  75                     checkbox1.setValue(true);
  76                     checkbox2.setValue(true);
  77                     checkbox3.setValue(true);
  78                 }
  79             },
  80             {
  81                 text: 'Deselect All',
  82                 handler: function() {
  83                     var checkbox1 = Ext.getCmp('checkbox1'),
  84                         checkbox2 = Ext.getCmp('checkbox2'),
  85                         checkbox3 = Ext.getCmp('checkbox3');
  86
  87                     checkbox1.setValue(false);
  88                     checkbox2.setValue(false);
  89                     checkbox3.setValue(false);
  90                 }
  91             }
  92         ],
  93         renderTo: Ext.getBody()
  94     });
  95
  96  * @constructor
  97  * Creates a new Checkbox
  98  * @param {Object} config Configuration options
  99  * @xtype checkboxfield
 100  * @docauthor Robert Dougan &lt;rob@sencha.com&gt;
 101  * @markdown
 102  */
 103 Ext.define('Ext.form.field.Checkbox', {
 104     extend: 'Ext.form.field.Base',
 105     alias: ['widget.checkboxfield', 'widget.checkbox'],
 106     alternateClassName: 'Ext.form.Checkbox',
 107     requires: ['Ext.XTemplate', 'Ext.form.CheckboxManager'],
 108
 109     fieldSubTpl: [
 110         '&lt;tpl if=&quot;boxLabel &amp;&amp; boxLabelAlign == \'before\'&quot;&gt;',
 111             '&lt;label class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
 112         '&lt;/tpl&gt;',
 113         // Creates not an actual checkbox, but a button which is given aria role=&quot;checkbox&quot; and
 114         // styled with a custom checkbox image. This allows greater control and consistency in
 115         // styling, and using a button allows it to gain focus and handle keyboard nav properly.
 116         '&lt;input type=&quot;button&quot; id=&quot;{id}&quot; ',
 117             '&lt;tpl if=&quot;tabIdx&quot;&gt;tabIndex=&quot;{tabIdx}&quot; &lt;/tpl&gt;',
 118             'class=&quot;{fieldCls} {typeCls}&quot; autocomplete=&quot;off&quot; hidefocus=&quot;true&quot; /&gt;',
 119         '&lt;tpl if=&quot;boxLabel &amp;&amp; boxLabelAlign == \'after\'&quot;&gt;',
 120             '&lt;label class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
 121         '&lt;/tpl&gt;',
 122         {
 123             disableFormats: true,
 124             compiled: true
 125         }
 126     ],
 127
 128     isCheckbox: true,
 129
 130 <span id='Ext-form.field.Checkbox-cfg-focusCls'>    /**
 131 </span>     * @cfg {String} focusCls The CSS class to use when the checkbox receives focus
 132      * (defaults to &lt;tt&gt;'x-form-cb-focus'&lt;/tt&gt;)
 133      */
 134     focusCls: Ext.baseCSSPrefix + 'form-cb-focus',
 135
 136 <span id='Ext-form.field.Checkbox-cfg-fieldCls'>    /**
 137 </span>     * @cfg {String} fieldCls The default CSS class for the checkbox (defaults to &lt;tt&gt;'x-form-field'&lt;/tt&gt;)
 138      */
 139
 140 <span id='Ext-form.field.Checkbox-cfg-fieldBodyCls'>    /**
 141 </span>     * @cfg {String} fieldBodyCls
 142      * An extra CSS class to be applied to the body content element in addition to {@link #fieldBodyCls}.
 143      * Defaults to 'x-form-cb-wrap.
 144      */
 145     fieldBodyCls: Ext.baseCSSPrefix + 'form-cb-wrap',
 146
 147 <span id='Ext-form.field.Checkbox-cfg-checked'>    /**
 148 </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;)
 149      */
 150     checked: false,
 151
 152 <span id='Ext-form.field.Checkbox-cfg-checkedCls'>    /**
 153 </span>     * @cfg {String} checkedCls The CSS class added to the component's main element when it is in the checked state.
 154      */
 155     checkedCls: Ext.baseCSSPrefix + 'form-cb-checked',
 156
 157 <span id='Ext-form.field.Checkbox-cfg-boxLabel'>    /**
 158 </span>     * @cfg {String} boxLabel An optional text label that will appear next to the checkbox. Whether it appears before
 159      * or after the checkbox is determined by the {@link #boxLabelAlign} config (defaults to after).
 160      */
 161
 162 <span id='Ext-form.field.Checkbox-cfg-boxLabelCls'>    /**
 163 </span>     * @cfg {String} boxLabelCls The CSS class to be applied to the {@link #boxLabel} element
 164      */
 165     boxLabelCls: Ext.baseCSSPrefix + 'form-cb-label',
 166
 167 <span id='Ext-form.field.Checkbox-cfg-boxLabelAlign'>    /**
 168 </span>     * @cfg {String} boxLabelAlign The position relative to the checkbox where the {@link #boxLabel} should
 169      * 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;.
 170      */
 171     boxLabelAlign: 'after',
 172
 173 <span id='Ext-form.field.Checkbox-cfg-inputValue'>    /**
 174 </span>     * @cfg {String} inputValue The value that should go into the generated input element's value attribute and
 175      * 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;.
 176      */
 177     inputValue: 'on',
 178
 179 <span id='Ext-form.field.Checkbox-cfg-uncheckedValue'>    /**
 180 </span>     * @cfg {String} uncheckedValue If configured, this will be submitted as the checkbox's value during form
 181      * submit if the checkbox is unchecked. By default this is undefined, which results in nothing being
 182      * submitted for the checkbox field when the form is submitted (the default behavior of HTML checkboxes).
 183      */
 184
 185 <span id='Ext-form.field.Checkbox-cfg-handler'>    /**
 186 </span>     * @cfg {Function} handler A function called when the {@link #checked} value changes (can be used instead of
 187      * handling the {@link #change change event}). The handler is passed the following parameters:
 188      * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
 189      * &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;
 190      * &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;
 191      * &lt;/ul&gt;&lt;/div&gt;
 192      */
 193
 194 <span id='Ext-form.field.Checkbox-cfg-scope'>    /**
 195 </span>     * @cfg {Object} scope An object to use as the scope ('this' reference) of the {@link #handler} function
 196      * (defaults to this Checkbox).
 197      */
 198
 199     // private overrides
 200     checkChangeEvents: [],
 201     inputType: 'checkbox',
 202     ariaRole: 'checkbox',
 203
 204     // private
 205     onRe: /^on$/i,
 206
 207     initComponent: function(){
 208         this.callParent(arguments);
 209         this.getManager().add(this);
 210     },
 211
 212     initValue: function() {
 213         var me = this,
 214             checked = !!me.checked;
 215
 216 <span id='Ext-form.field.Checkbox-property-originalValue'>        /**
 217 </span>         * The original value of the field as configured in the {@link #checked} configuration, or
 218          * as loaded by the last form load operation if the form's {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}
 219          * setting is &lt;code&gt;true&lt;/code&gt;.
 220          * @type Mixed
 221          * @property originalValue
 222          */
 223         me.originalValue = me.lastValue = checked;
 224
 225         // Set the initial checked state
 226         me.setValue(checked);
 227     },
 228
 229     // private
 230     onRender : function(ct, position) {
 231         var me = this;
 232         Ext.applyIf(me.renderSelectors, {
 233 <span id='Ext-form.field.Checkbox-property-boxLabelEl'>            /**
 234 </span>             * @property boxLabelEl
 235              * @type Ext.core.Element
 236              * A reference to the label element created for the {@link #boxLabel}. Only present if the
 237              * component has been rendered and has a boxLabel configured.
 238              */
 239             boxLabelEl: 'label.' + me.boxLabelCls
 240         });
 241         Ext.applyIf(me.subTplData, {
 242             boxLabel: me.boxLabel,
 243             boxLabelCls: me.boxLabelCls,
 244             boxLabelAlign: me.boxLabelAlign
 245         });
 246
 247         me.callParent(arguments);
 248     },
 249
 250     initEvents: function() {
 251         var me = this;
 252         me.callParent();
 253         me.mon(me.inputEl, 'click', me.onBoxClick, me);
 254     },
 255
 256 <span id='Ext-form.field.Checkbox-method-onBoxClick'>    /**
 257 </span>     * @private Handle click on the checkbox button
 258      */
 259     onBoxClick: function(e) {
 260         var me = this;
 261         if (!me.disabled &amp;&amp; !me.readOnly) {
 262             this.setValue(!this.checked);
 263         }
 264     },
 265
 266 <span id='Ext-form.field.Checkbox-method-getRawValue'>    /**
 267 </span>     * Returns the checked state of the checkbox.
 268      * @return {Boolean} True if checked, else false
 269      */
 270     getRawValue: function() {
 271         return this.checked;
 272     },
 273
 274 <span id='Ext-form.field.Checkbox-method-getValue'>    /**
 275 </span>     * Returns the checked state of the checkbox.
 276      * @return {Boolean} True if checked, else false
 277      */
 278     getValue: function() {
 279         return this.checked;
 280     },
 281
 282 <span id='Ext-form.field.Checkbox-method-getSubmitValue'>    /**
 283 </span>     * Returns the submit value for the checkbox which can be used when submitting forms.
 284      * @return {Boolean/null} True if checked; otherwise either the {@link #uncheckedValue} or null.
 285      */
 286     getSubmitValue: function() {
 287         return this.checked ? this.inputValue : (this.uncheckedValue || null);
 288     },
 289
 290     getModelData: function() {
 291         return this.getSubmitData();
 292     },
 293
 294 <span id='Ext-form.field.Checkbox-method-setRawValue'>    /**
 295 </span>     * Sets the checked state of the checkbox.
 296      * @param {Boolean/String} value The following values will check the checkbox:
 297      * &lt;code&gt;true, 'true', '1', or 'on'&lt;/code&gt;, as well as a String that matches the {@link #inputValue}.
 298      * Any other value will uncheck the checkbox.
 299      * @return {Boolean} the new checked state of the checkbox
 300      */
 301     setRawValue: function(value) {
 302         var me = this,
 303             inputEl = me.inputEl,
 304             inputValue = me.inputValue,
 305             checked = (value === true || value === 'true' || value === '1' ||
 306                       ((Ext.isString(value) &amp;&amp; inputValue) ? value == inputValue : me.onRe.test(value)));
 307
 308         if (inputEl) {
 309             inputEl.dom.setAttribute('aria-checked', checked);
 310             me[checked ? 'addCls' : 'removeCls'](me.checkedCls);
 311         }
 312
 313         me.checked = me.rawValue = checked;
 314         return checked;
 315     },
 316
 317 <span id='Ext-form.field.Checkbox-method-setValue'>    /**
 318 </span>     * Sets the checked state of the checkbox, and invokes change detection.
 319      * @param {Boolean/String} checked The following values will check the checkbox:
 320      * &lt;code&gt;true, 'true', '1', or 'on'&lt;/code&gt;, as well as a String that matches the {@link #inputValue}.
 321      * Any other value will uncheck the checkbox.
 322      * @return {Ext.form.field.Checkbox} this
 323      */
 324     setValue: function(checked) {
 325         var me = this;
 326
 327         // If an array of strings is passed, find all checkboxes in the group with the same name as this
 328         // one and check all those whose inputValue is in the array, unchecking all the others. This is to
 329         // facilitate setting values from Ext.form.Basic#setValues, but is not publicly documented as we
 330         // don't want users depending on this behavior.
 331         if (Ext.isArray(checked)) {
 332             me.getManager().getByName(me.name).each(function(cb) {
 333                 cb.setValue(Ext.Array.contains(checked, cb.inputValue));
 334             });
 335         } else {
 336             me.callParent(arguments);
 337         }
 338
 339         return me;
 340     },
 341
 342     // private
 343     valueToRaw: function(value) {
 344         // No extra conversion for checkboxes
 345         return value;
 346     },
 347
 348 <span id='Ext-form.field.Checkbox-method-onChange'>    /**
 349 </span>     * @private
 350      * Called when the checkbox's checked state changes. Invokes the {@link #handler} callback
 351      * function if specified.
 352      */
 353     onChange: function(newVal, oldVal) {
 354         var me = this,
 355             handler = me.handler;
 356         if (handler) {
 357             handler.call(me.scope || me, me, newVal);
 358         }
 359         me.callParent(arguments);
 360     },
 361
 362     // inherit docs
 363     getManager: function() {
 364         return Ext.form.CheckboxManager;
 365     },
 366
 367     onEnable: function() {
 368         var me = this,
 369             inputEl = me.inputEl;
 370         me.callParent();
 371         if (inputEl) {
 372             // Can still be disabled if the field is readOnly
 373             inputEl.dom.disabled = me.readOnly;
 374         }
 375     },
 376
 377     setReadOnly: function(readOnly) {
 378         var me = this,
 379             inputEl = me.inputEl;
 380         if (inputEl) {
 381             // Set the button to disabled when readonly
 382             inputEl.dom.disabled = readOnly || me.disabled;
 383         }
 384         me.readOnly = readOnly;
 385     },
 386
 387 <span id='Ext-form.field.Checkbox-method-getBodyNaturalWidth'>    /**
 388 </span>     * @protected Calculate and return the natural width of the bodyEl. It's possible that the initial
 389      * rendering will cause the boxLabel to wrap and give us a bad width, so we must prevent wrapping
 390      * while measuring.
 391      */
 392     getBodyNaturalWidth: function() {
 393         var me = this,
 394             bodyEl = me.bodyEl,
 395             ws = 'white-space',
 396             width;
 397         bodyEl.setStyle(ws, 'nowrap');
 398         width = bodyEl.getWidth();
 399         bodyEl.setStyle(ws, '');
 400         return width;
 401     }
 402
 403 });
 404 </pre></pre></body></html>