Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / src / form / RadioGroup.js
1 /*
2
3 This file is part of Ext JS 4
4
5 Copyright (c) 2011 Sencha Inc
6
7 Contact:  http://www.sencha.com/contact
8
9 GNU General Public License Usage
10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
11
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
13
14 */
15 /**
16  * A {@link Ext.form.FieldContainer field container} which has a specialized layout for arranging
17  * {@link Ext.form.field.Radio} controls into columns, and provides convenience {@link Ext.form.field.Field}
18  * methods for {@link #getValue getting}, {@link #setValue setting}, and {@link #validate validating} the
19  * group of radio buttons as a whole.
20  *
21  * # Validation
22  *
23  * Individual radio buttons themselves have no default validation behavior, but
24  * sometimes you want to require a user to select one of a group of radios. RadioGroup
25  * allows this by setting the config `{@link #allowBlank}:false`; when the user does not check at
26  * one of the radio buttons, the entire group will be highlighted as invalid and the
27  * {@link #blankText error message} will be displayed according to the {@link #msgTarget} config.</p>
28  *
29  * # Layout
30  *
31  * The default layout for RadioGroup makes it easy to arrange the radio buttons into
32  * columns; see the {@link #columns} and {@link #vertical} config documentation for details. You may also
33  * use a completely different layout by setting the {@link #layout} to one of the other supported layout
34  * types; for instance you may wish to use a custom arrangement of hbox and vbox containers. In that case
35  * the Radio components at any depth will still be managed by the RadioGroup's validation.
36  *
37  * {@img Ext.form.RadioGroup/Ext.form.RadioGroup.png Ext.form.RadioGroup component}
38  *
39  * # Example usage
40  *
41  *     Ext.create('Ext.form.Panel', {
42  *         title: 'RadioGroup Example',
43  *         width: 300,
44  *         height: 125,
45  *         bodyPadding: 10,
46  *         renderTo: Ext.getBody(),        
47  *         items:[{            
48  *             xtype: 'radiogroup',
49  *             fieldLabel: 'Two Columns',
50  *             // Arrange radio buttons into two columns, distributed vertically
51  *             columns: 2,
52  *             vertical: true,
53  *             items: [
54  *                 {boxLabel: 'Item 1', name: 'rb', inputValue: '1'},
55  *                 {boxLabel: 'Item 2', name: 'rb', inputValue: '2', checked: true},
56  *                 {boxLabel: 'Item 3', name: 'rb', inputValue: '3'},
57  *                 {boxLabel: 'Item 4', name: 'rb', inputValue: '4'},
58  *                 {boxLabel: 'Item 5', name: 'rb', inputValue: '5'},
59  *                 {boxLabel: 'Item 6', name: 'rb', inputValue: '6'}
60  *             ]
61  *         }]
62  *     });
63  *
64  */
65 Ext.define('Ext.form.RadioGroup', {
66     extend: 'Ext.form.CheckboxGroup',
67     alias: 'widget.radiogroup',
68
69     /**
70      * @cfg {Array} items An Array of {@link Ext.form.field.Radio Radio}s or Radio config objects
71      * to arrange in the group.
72      */
73     /**
74      * @cfg {Boolean} allowBlank True to allow every item in the group to be blank (defaults to true).
75      * If allowBlank = false and no items are selected at validation time, {@link #blankText} will
76      * be used as the error text.
77      */
78     allowBlank : true,
79     /**
80      * @cfg {String} blankText Error text to display if the {@link #allowBlank} validation fails
81      * (defaults to 'You must select one item in this group')
82      */
83     blankText : 'You must select one item in this group',
84     
85     // private
86     defaultType : 'radiofield',
87     
88     // private
89     groupCls : Ext.baseCSSPrefix + 'form-radio-group',
90
91     getBoxes: function() {
92         return this.query('[isRadio]');
93     }
94
95 });
96