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