Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Radio.html
index 594fe4b..77f2bba 100644 (file)
+<!DOCTYPE html>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.2.0
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-<div id="cls-Ext.form.Radio"></div>/**
- * @class Ext.form.Radio
- * @extends Ext.form.Checkbox
- * Single radio field.  Same as Checkbox, but provided as a convenience for automatically setting the input type.
- * Radio grouping is handled automatically by the browser if you give each radio in a group the same name.
- * @constructor
- * Creates a new Radio
- * @param {Object} config Configuration options
- * @xtype radio
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-form-field-Radio'>/**
+</span> * @class Ext.form.field.Radio
+ * @extends Ext.form.field.Checkbox
+
+Single radio field. Similar to checkbox, but automatically handles making sure only one radio is checked
+at a time within a group of radios with the same name.
+
+__Labeling:__
+In addition to the {@link Ext.form.Labelable standard field labeling options}, radio buttons
+may be given an optional {@link #boxLabel} which will be displayed immediately to the right of the input. Also
+see {@link Ext.form.RadioGroup} for a convenient method of grouping related radio buttons.
+
+__Values:__
+The main value of a Radio field is a boolean, indicating whether or not the radio is checked.
+
+The following values will check the radio:
+* `true`
+* `'true'`
+* `'1'`
+* `'on'`
+
+Any other value will uncheck it.
+
+In addition to the main boolean value, you may also specify a separate {@link #inputValue}. This will be sent
+as the parameter value when the form is {@link Ext.form.Basic#submit submitted}. You will want to set this
+value if you have multiple radio buttons with the same {@link #name}, as is almost always the case.
+{@img Ext.form.Radio/Ext.form.Radio.png Ext.form.Radio component}
+__Example usage:__
+
+    Ext.create('Ext.form.Panel', {
+        title      : 'Order Form',
+        width      : 300,
+        bodyPadding: 10,
+        renderTo   : Ext.getBody(),
+        items: [
+            {
+                xtype      : 'fieldcontainer',
+                fieldLabel : 'Size',
+                defaultType: 'radiofield',
+                defaults: {
+                    flex: 1
+                },
+                layout: 'hbox',
+                items: [
+                    {
+                        boxLabel  : 'M',
+                        name      : 'size',
+                        inputValue: 'm',
+                        id        : 'radio1'
+                    }, {
+                        boxLabel  : 'L',
+                        name      : 'size',
+                        inputValue: 'l',
+                        id        : 'radio2'
+                    }, {
+                        boxLabel  : 'XL',
+                        name      : 'size',
+                        inputValue: 'xl',
+                        id        : 'radio3'
+                    }
+                ]
+            },
+            {
+                xtype      : 'fieldcontainer',
+                fieldLabel : 'Color',
+                defaultType: 'radiofield',
+                defaults: {
+                    flex: 1
+                },
+                layout: 'hbox',
+                items: [
+                    {
+                        boxLabel  : 'Blue',
+                        name      : 'color',
+                        inputValue: 'blue',
+                        id        : 'radio4'
+                    }, {
+                        boxLabel  : 'Grey',
+                        name      : 'color',
+                        inputValue: 'grey',
+                        id        : 'radio5'
+                    }, {
+                        boxLabel  : 'Black',
+                        name      : 'color',
+                        inputValue: 'black',
+                        id        : 'radio6'
+                    }
+                ]
+            }
+        ],
+        bbar: [
+            {
+                text: 'Smaller Size',
+                handler: function() {
+                    var radio1 = Ext.getCmp('radio1'),
+                        radio2 = Ext.getCmp('radio2'),
+                        radio3 = Ext.getCmp('radio3');
+
+                    //if L is selected, change to M
+                    if (radio2.getValue()) {
+                        radio1.setValue(true);
+                        return;
+                    }
+
+                    //if XL is selected, change to L
+                    if (radio3.getValue()) {
+                        radio2.setValue(true);
+                        return;
+                    }
+
+                    //if nothing is set, set size to S
+                    radio1.setValue(true);
+                }
+            },
+            {
+                text: 'Larger Size',
+                handler: function() {
+                    var radio1 = Ext.getCmp('radio1'),
+                        radio2 = Ext.getCmp('radio2'),
+                        radio3 = Ext.getCmp('radio3');
+
+                    //if M is selected, change to L
+                    if (radio1.getValue()) {
+                        radio2.setValue(true);
+                        return;
+                    }
+
+                    //if L is selected, change to XL
+                    if (radio2.getValue()) {
+                        radio3.setValue(true);
+                        return;
+                    }
+
+                    //if nothing is set, set size to XL
+                    radio3.setValue(true);
+                }
+            },
+            '-',
+            {
+                text: 'Select color',
+                menu: {
+                    indent: false,
+                    items: [
+                        {
+                            text: 'Blue',
+                            handler: function() {
+                                var radio = Ext.getCmp('radio4');
+                                radio.setValue(true);
+                            }
+                        },
+                        {
+                            text: 'Grey',
+                            handler: function() {
+                                var radio = Ext.getCmp('radio5');
+                                radio.setValue(true);
+                            }
+                        },
+                        {
+                            text: 'Black',
+                            handler: function() {
+                                var radio = Ext.getCmp('radio6');
+                                radio.setValue(true);
+                            }
+                        }
+                    ]
+                }
+            }
+        ]
+    });
+
+
+ * @docauthor Robert Dougan &lt;rob@sencha.com&gt;
+ * @markdown
  */
-Ext.form.Radio = Ext.extend(Ext.form.Checkbox, {
-    inputType: 'radio',
+Ext.define('Ext.form.field.Radio', {
+    extend:'Ext.form.field.Checkbox',
+    alias: ['widget.radiofield', 'widget.radio'],
+    alternateClassName: 'Ext.form.Radio',
+    requires: ['Ext.form.RadioManager'],
 
-    <div id="method-Ext.form.Radio-markInvalid"></div>/**
-     * Overridden and disabled. The editor element does not support standard valid/invalid marking. @hide
-     * @method
-     */
-    markInvalid : Ext.emptyFn,
-    <div id="method-Ext.form.Radio-clearInvalid"></div>/**
-     * Overridden and disabled. The editor element does not support standard valid/invalid marking. @hide
-     * @method
+    isRadio: true,
+
+<span id='Ext-form-field-Radio-cfg-uncheckedValue'>    /**
+</span>     * @cfg {String} uncheckedValue @hide
      */
-    clearInvalid : Ext.emptyFn,
 
-    <div id="method-Ext.form.Radio-getGroupValue"></div>/**
-     * If this radio is part of a group, it will return the selected value
+    // private
+    inputType: 'radio',
+    ariaRole: 'radio',
+
+<span id='Ext-form-field-Radio-method-getGroupValue'>    /**
+</span>     * If this radio is part of a group, it will return the selected value
      * @return {String}
      */
-    getGroupValue : function(){
-       var p = this.el.up('form') || Ext.getBody();
-        var c = p.child('input[name='+this.el.dom.name+']:checked', true);
-        return c ? c.value : null;
+    getGroupValue: function() {
+        var selected = this.getManager().getChecked(this.name);
+        return selected ? selected.inputValue : null;
     },
 
-    // private
-    onClick : function(){
-       if(this.el.dom.checked != this.checked){
-                       var els = this.getCheckEl().select('input[name=' + this.el.dom.name + ']');
-                       els.each(function(el){
-                               if(el.dom.id == this.id){
-                                       this.setValue(true);
-                               }else{
-                                       Ext.getCmp(el.dom.id).setValue(false);
-                               }
-                       }, this);
-               }
+<span id='Ext-form-field-Radio-method-onBoxClick'>    /**
+</span>     * @private Handle click on the radio button
+     */
+    onBoxClick: function(e) {
+        var me = this;
+        if (!me.disabled &amp;&amp; !me.readOnly) {
+            this.setValue(true);
+        }
     },
 
-    <div id="method-Ext.form.Radio-setValue"></div>/**
-     * Sets either the checked/unchecked status of this Radio, or, if a string value
+<span id='Ext-form-field-Radio-method-setValue'>    /**
+</span>     * Sets either the checked/unchecked status of this Radio, or, if a string value
      * is passed, checks a sibling Radio of the same name whose value is the value specified.
      * @param value {String/Boolean} Checked value, or the value of the sibling radio button to check.
-     * @return {Ext.form.Field} this
+     * @return {Ext.form.field.Radio} this
      */
-    setValue : function(v){
-       if (typeof v == 'boolean') {
-            Ext.form.Radio.superclass.setValue.call(this, v);
-        } else if (this.rendered) {
-            var r = this.getCheckEl().child('input[name=' + this.el.dom.name + '][value=' + v + ']', true);
-            if(r){
-                Ext.getCmp(r.id).setValue(true);
+    setValue: function(v) {
+        var me = this,
+            active;
+
+        if (Ext.isBoolean(v)) {
+            me.callParent(arguments);
+        } else {
+            active = me.getManager().getWithValue(me.name, v).getAt(0);
+            if (active) {
+                active.setValue(true);
             }
         }
-        return this;
+        return me;
     },
 
-    // private
-    getCheckEl: function(){
-        if(this.inGroup){
-            return this.el.up('.x-form-radio-group')
+<span id='Ext-form-field-Radio-method-getSubmitValue'>    /**
+</span>     * Returns the submit value for the checkbox which can be used when submitting forms.
+     * @return {Boolean/null} True if checked, null if not.
+     */
+    getSubmitValue: function() {
+        return this.checked ? this.inputValue : null;
+    },
+
+    getModelData: function() {
+        return this.getSubmitData();
+    },
+
+    // inherit docs
+    onChange: function(newVal, oldVal) {
+        var me = this;
+        me.callParent(arguments);
+
+        if (newVal) {
+            this.getManager().getByName(me.name).each(function(item){
+                if (item !== me) {
+                    item.setValue(false);
+                }
+            }, me);
         }
-        return this.el.up('form') || Ext.getBody();
+    },
+
+    // inherit docs
+    beforeDestroy: function(){
+        this.callParent();
+        this.getManager().removeAtKey(this.id);
+    },
+
+    // inherit docs
+    getManager: function() {
+        return Ext.form.RadioManager;
     }
 });
-Ext.reg('radio', Ext.form.Radio);
-</pre>    
+</pre>
 </body>
-</html>
\ No newline at end of file
+</html>