radiobutton.jd revision 183bf116978e3c44292c9ead2bceb47e972624a1
150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainpage.title=Radio Buttons 250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainparent.title=Input Controls 350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainparent.link=../controls.html 450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main@jd:body 550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<div id="qv-wrapper"> 750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<div id="qv"> 850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>In this document</h2> 950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 1050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="#HandlingEvents">Responding to Click Events</a></li> 1150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 1250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 1350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>Key classes</h2> 1450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 1550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.widget.RadioButton}</li> 1650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.widget.RadioGroup}</li> 1750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 1850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</div> 1950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</div> 2050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 2150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>Radio buttons allow the user to select one option from a set. You should use radio buttons for 2250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainoptional sets that are mutually exclusive if you think that the user needs to see all available 2350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainoptions side-by-side. If it's not necessary to show all options side-by-side, use a <a 2450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainhref="{@docRoot}guide/topics/ui/controls/spinner.html">spinner</a> instead.</p> 2550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 2650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/ui/radiobuttons.png" alt="" /> 2750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 2850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>To create each radio button option, create a {@link android.widget.RadioButton} in your layout. 2950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainHowever, because radio buttons are mutually exclusive, you must group them together inside a 3050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.widget.RadioGroup}. By grouping them together, the system ensures that only one 3150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainradio button can be selected at a time.</p> 3250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 3350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="HandlingEvents">Responding to Click Events</h2> 3450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 3550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>When the user selects one of the radio buttons, the corresponding {@link 3650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.RadioButton} object receives an on-click event.</p> 3750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 3850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>To define the click event handler for a button, add the <code><a 3950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainhref="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the 4050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code><RadioButton></code> element in your XML 4150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainlayout. The value for this attribute must be the name of the method you want to call in response 4250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainto a click event. The {@link android.app.Activity} hosting the layout must then implement the 4350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincorresponding method.</p> 4450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 4550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>For example, here are a couple {@link android.widget.RadioButton} objects:</p> 4650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 4750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 4850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<?xml version="1.0" encoding="utf-8"?> 4950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<RadioGroup xmlns:android="http://schemas.android.com/apk/res/android" 5050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_width="fill_parent" 5150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_height="wrap_content" 5250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:orientation="vertical"> 5350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <RadioButton android:id="@+id/radio_pirates" 5450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_width="wrap_content" 5550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_height="wrap_content" 5650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:text="@string/pirates" 5750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:onClick="onRadioButtonClicked"/> 5850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <RadioButton android:id="@+id/radio_ninjas" 5950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_width="wrap_content" 6050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_height="wrap_content" 6150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:text="@string/ninjas" 6250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:onClick="onRadioButtonClicked"/> 6350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</RadioGroup> 6450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 6550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 6650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"><strong>Note:</strong> The {@link android.widget.RadioGroup} is a subclass of 6750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.widget.LinearLayout} that has a vertical orientation by default.</p> 6850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 6950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles the 7050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainclick event for both radio buttons:</p> 7150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 7250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 7350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainpublic void onRadioButtonClicked(View view) { 7450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Is the button now checked? 75183bf116978e3c44292c9ead2bceb47e972624a1Scott Main boolean checked = ((RadioButton) view).isChecked(); 7650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 7750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Check which radio button was clicked 7850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main switch(view.getId()) { 7950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main case R.id.radio_pirates: 8050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main if (checked) 8150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Pirates are the best 8250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main break; 8350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main case R.id.radio_ninjas: 8450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main if (checked) 8550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Ninjas rule 8650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main break; 8750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main } 8850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main} 8950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 9050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 9150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute 9250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainmust have a signature exactly as shown above. Specifically, the method must:</p> 9350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ul> 9450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Be public</li> 9550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Return void</li> 9650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>Define a {@link android.view.View} as its only parameter (this will be the {@link 9750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.view.View} that was clicked)</li> 9850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ul> 9950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 10050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"><strong>Tip:</strong> If you need to change the radio button state 10150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainyourself (such as when loading a saved {@link android.preference.CheckBoxPreference}), 10250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainuse the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link 10350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.CompoundButton#toggle()} method.</p> 104