add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / form / RadioGroup.js

/**\r
 * A {@link Ext.form.FieldContainer field container} which has a specialized layout for arranging\r
 * {@link Ext.form.field.Radio} controls into columns, and provides convenience {@link Ext.form.field.Field}\r
 * methods for {@link #getValue getting}, {@link #setValue setting}, and {@link #validate validating} the\r
 * group of radio buttons as a whole.\r
 *\r
 * # Validation\r
 *\r
 * Individual radio buttons themselves have no default validation behavior, but\r
 * sometimes you want to require a user to select one of a group of radios. RadioGroup\r
 * allows this by setting the config `{@link #allowBlank}:false`; when the user does not check at\r
 * one of the radio buttons, the entire group will be highlighted as invalid and the\r
 * {@link #blankText error message} will be displayed according to the {@link #msgTarget} config.\r
 *\r
 * # Layout\r
 *\r
 * The default layout for RadioGroup makes it easy to arrange the radio buttons into\r
 * columns; see the {@link #columns} and {@link #vertical} config documentation for details. You may also\r
 * use a completely different layout by setting the {@link #cfg-layout} to one of the \r
 * other supported layout types; for instance you may wish to use a custom arrangement \r
 * of hbox and vbox containers. In that case the Radio components at any depth will \r
 * still be managed by the RadioGroup's validation.\r
 *\r
 * # Example usage\r
 *\r
 *     @example\r
 *     Ext.create('Ext.form.Panel', {\r
 *         title: 'RadioGroup Example',\r
 *         width: 300,\r
 *         height: 125,\r
 *         bodyPadding: 10,\r
 *         renderTo: Ext.getBody(),\r
 *         items:[{\r
 *             xtype: 'radiogroup',\r
 *             fieldLabel: 'Two Columns',\r
 *             // Arrange radio buttons into two columns, distributed vertically\r
 *             columns: 2,\r
 *             vertical: true,\r
 *             items: [\r
 *                 { boxLabel: 'Item 1', name: 'rb', inputValue: '1' },\r
 *                 { boxLabel: 'Item 2', name: 'rb', inputValue: '2', checked: true},\r
 *                 { boxLabel: 'Item 3', name: 'rb', inputValue: '3' },\r
 *                 { boxLabel: 'Item 4', name: 'rb', inputValue: '4' },\r
 *                 { boxLabel: 'Item 5', name: 'rb', inputValue: '5' },\r
 *                 { boxLabel: 'Item 6', name: 'rb', inputValue: '6' }\r
 *             ]\r
 *         }]\r
 *     });\r
 *\r
 */\r
Ext.define('Ext.form.RadioGroup', {\r
    extend: 'Ext.form.CheckboxGroup',\r
    alias: 'widget.radiogroup',\r
\r
    requires: [\r
        'Ext.form.field.Radio'\r
    ],\r
    \r
    mixins: [\r
        'Ext.util.FocusableContainer'\r
    ],\r
\r
    /**\r
     * @cfg {Ext.form.field.Radio[]/Object[]} items\r
     * An Array of {@link Ext.form.field.Radio Radio}s or Radio config objects to arrange in the group.\r
     */\r
    /**\r
     * @cfg {Boolean} allowBlank\r
     * True to allow every item in the group to be blank.\r
     * If allowBlank = false and no items are selected at validation time, {@link #blankText} will\r
     * be used as the error text.\r
     */\r
    allowBlank : true,\r
    //<locale>\r
    /**\r
     * @cfg {String} blankText\r
     * Error text to display if the {@link #allowBlank} validation fails\r
     */\r
    blankText : 'You must select one item in this group',\r
    //</locale>\r
\r
    defaultType : 'radiofield',\r
\r
    /**\r
     * @cfg {Boolean} [local=false]\r
     * By default, child {@link Ext.form.field.Radio radio} `name`s are scoped to the encapsulating {@link Ext.form.Panel form panel}\r
     * if any, of the document.\r
     *\r
     * If you are using multiple `RadioGroup`s each of which uses the same `name` configuration in child {@link Ext.form.field.Radio radio}s, configure this as `true` to scope\r
     * the names to within this `RadioGroup`\r
     */\r
    local: false,\r
\r
    defaultBindProperty: 'value',\r
\r
    /**\r
     * @private\r
     */\r
    groupCls : Ext.baseCSSPrefix + 'form-radio-group',\r
    \r
    ariaRole: 'radiogroup',\r
    \r
    initRenderData: function() {\r
        var me = this,\r
            data, ariaAttr;\r
        \r
        data = me.callParent();\r
        ariaAttr = data.ariaAttributes;\r
        \r
        if (ariaAttr) {\r
            ariaAttr['aria-required'] = !me.allowBlank;\r
            ariaAttr['aria-invalid']  = false;\r
        }\r
        \r
        return data;\r
    },\r
\r
    lookupComponent: function(config) {\r
        var result = this.callParent([config]);\r
\r
        // Local means that the exclusivity of checking by name is scoped to this RadioGroup.\r
        // So multiple RadioGroups can be used which use the same Radio names.\r
        // This enables their use as a grid widget.\r
        if (this.local) {\r
            result.formId = this.getId();\r
        }\r
        return result;\r
    },\r
    \r
    getBoxes: function(query, root) {\r
        return (root || this).query('[isRadio]' + (query||''));\r
    },\r
    \r
    checkChange: function() {\r
        var value = this.getValue(),\r
            key = Ext.Object.getKeys(value)[0];\r
            \r
        // If the value is an array we skip out here because it's during a change\r
        // between multiple items, so we never want to fire a change\r
        if (Ext.isArray(value[key])) {\r
            return;\r
        }\r
        this.callParent(arguments);    \r
    },\r
\r
    /**\r
     * Sets the value of the radio group. The radio with corresponding name and value will be set.\r
     * This method is simpler than {@link Ext.form.CheckboxGroup#setValue} because only 1 value is allowed\r
     * for each name. You can use the setValue method as:\r
     *\r
     *     var form = Ext.create('Ext.form.Panel', {\r
     *         title       : 'RadioGroup Example',\r
     *         width       : 300,\r
     *         bodyPadding : 10,\r
     *         renderTo    : Ext.getBody(),\r
     *         items       : [\r
     *             {\r
     *                 xtype      : 'radiogroup',\r
     *                 fieldLabel : 'Group',\r
     *                 items      : [\r
     *                     { boxLabel : 'Item 1', name : 'rb', inputValue : 1 },\r
     *                     { boxLabel : 'Item 2', name : 'rb', inputValue : 2 }\r
     *                 ]\r
     *             }\r
     *         ],\r
     *         tbar        : [\r
     *             {\r
     *                 text    : 'setValue on RadioGroup',\r
     *                 handler : function () {\r
     *                     form.child('radiogroup').setValue({\r
     *                         rb : 2\r
     *                     });\r
     *                 }\r
     *             }\r
     *         ]\r
     *     });\r
     *\r
     * @param {Object} value The map from names to values to be set.\r
     * @return {Ext.form.RadioGroup} this\r
     */\r
    setValue: function(value) {\r
        var cbValue, first, formId, radios,\r
            i, len, name;\r
\r
        if (Ext.isObject(value)) {\r
            Ext.suspendLayouts();\r
            first = this.items.first();\r
            formId = first ? first.getFormId() : null;\r
\r
            for (name in value) {\r
                cbValue = value[name];\r
                radios = Ext.form.RadioManager.getWithValue(name, cbValue, formId).items;\r
                len = radios.length;\r
\r
                for (i = 0; i < len; ++i) {\r
                    radios[i].setValue(true);\r
                }\r
            }\r
            Ext.resumeLayouts(true);\r
        }\r
        return this;\r
    },\r
    \r
    markInvalid: function(errors) {\r
        var ariaDom = this.ariaEl.dom;\r
        \r
        this.callParent([errors]);\r
        \r
        if (ariaDom){\r
            ariaDom.setAttribute('aria-invalid', true);\r
        }\r
    },\r
    \r
    clearInvalid: function() {\r
        var ariaDom = this.ariaEl.dom;\r
        \r
        this.callParent();\r
        \r
        if (ariaDom) {\r
            ariaDom.setAttribute('aria-invalid', false);\r
        }\r
    },\r
    \r
    privates: {\r
        getFocusables: function() {\r
            return this.getBoxes();\r
        },\r
        \r
        initDefaultFocusable: function(beforeRender) {\r
            var me = this,\r
                checked, item;\r
\r
            checked = me.getChecked();\r
        \r
            // In a Radio group, only one button is supposed to be checked\r
            //<debug>\r
            if (checked.length > 1) {\r
                Ext.log.error("RadioGroup " + me.id + " has more than one checked button");\r
            }\r
            //</debug>\r
        \r
            // If we have a checked button, it gets the initial childTabIndex,\r
            // otherwise the first button gets it\r
            if (checked.length) {\r
                item = checked[0];\r
            }\r
            else {\r
                item = me.findNextFocusableChild({\r
                    beforeRender: beforeRender,\r
                    step: 1\r
                });\r
            }\r
            \r
            if (item) {\r
                me.activateFocusable(item);\r
            }\r
            \r
            return item;\r
        },\r
        \r
        getFocusableContainerEl: function() {\r
            return this.containerEl;\r
        },\r
        \r
        onFocusableContainerFocusLeave: function() {\r
            this.clearFocusables();\r
            this.initDefaultFocusable();\r
        },\r
        \r
        doFocusableChildAdd: function(child) {\r
            var me = this,\r
                mixin = me.mixins.focusablecontainer,\r
                boxes, i, len;\r
            \r
            boxes = child.isContainer ? me.getBoxes('', child) : [child];\r
            \r
            for (i = 0, len = boxes.length; i < len; i++) {\r
                mixin.doFocusableChildAdd.call(me, boxes[i]);\r
            }\r
        },\r
        \r
        doFocusableChildRemove: function(child) {\r
            var me = this,\r
                mixin = me.mixins.focusablecontainer,\r
                boxes, i, len;\r
            \r
            boxes = child.isContainer ? me.getBoxes('', child) : [child];\r
            \r
            for (i = 0, len = boxes.length; i < len; i++) {\r
                mixin.doFocusableChildRemove.call(me, boxes[i]);\r
            }\r
        },\r
    \r
        focusChild: function(radio, forward, e) {\r
            var nextRadio = this.mixins.focusablecontainer.focusChild.apply(this, arguments);\r
        \r
            // Ctrl-arrow does not select the radio that is going to be focused\r
            if (!e.ctrlKey) {\r
                nextRadio.setValue(true);\r
            }\r
        }\r
    }\r
});\r