docs/source/Checkbox.html

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