1page.title=Radio Buttons
2parent.title=Input Controls
3parent.link=../controls.html
4@jd:body
5
6<div id="qv-wrapper">
7<div id="qv">
8<h2>In this document</h2>
9<ol>
10  <li><a href="#HandlingEvents">Responding to Click Events</a></li>
11</ol>
12
13<h2>Key classes</h2>
14<ol>
15  <li>{@link android.widget.RadioButton}</li>
16  <li>{@link android.widget.RadioGroup}</li>
17</ol>
18</div>
19</div>
20
21<p>Radio buttons allow the user to select one option from a set. You should use radio buttons for
22optional sets that are mutually exclusive if you think that the user needs to see all available
23options side-by-side. If it's not necessary to show all options side-by-side, use a <a
24href="{@docRoot}guide/topics/ui/controls/spinner.html">spinner</a> instead.</p>
25
26<img src="{@docRoot}images/ui/radiobuttons.png" alt="" />
27
28<p>To create each radio button option, create a {@link android.widget.RadioButton} in your layout.
29However, because radio buttons are mutually exclusive, you must group them together inside a
30{@link android.widget.RadioGroup}. By grouping them together, the system ensures that only one
31radio button can be selected at a time.</p>
32
33<h2 id="HandlingEvents">Responding to Click Events</h2>
34
35<p>When the user selects one of the radio buttons, the corresponding {@link
36android.widget.RadioButton} object receives an on-click event.</p>
37
38<p>To define the click event handler for a button, add the <code><a
39href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the
40<code>&lt;RadioButton&gt;</code> element in your XML
41layout. The value for this attribute must be the name of the method you want to call in response
42to a click event. The {@link android.app.Activity} hosting the layout must then implement the
43corresponding method.</p>
44
45<p>For example, here are a couple {@link android.widget.RadioButton} objects:</p>
46
47<pre>
48&lt;?xml version="1.0" encoding="utf-8"?>
49&lt;RadioGroup xmlns:android="http://schemas.android.com/apk/res/android"
50    android:layout_width="fill_parent"
51    android:layout_height="wrap_content"
52    android:orientation="vertical">
53    &lt;RadioButton android:id="@+id/radio_pirates"
54        android:layout_width="wrap_content"
55        android:layout_height="wrap_content"
56        android:text="@string/pirates"
57        android:onClick="onRadioButtonClicked"/>
58    &lt;RadioButton android:id="@+id/radio_ninjas"
59        android:layout_width="wrap_content"
60        android:layout_height="wrap_content"
61        android:text="@string/ninjas"
62        android:onClick="onRadioButtonClicked"/>
63&lt;/RadioGroup>
64</pre>
65
66<p class="note"><strong>Note:</strong> The {@link android.widget.RadioGroup} is a subclass of
67{@link android.widget.LinearLayout} that has a vertical orientation by default.</p>
68
69<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles the
70click event for both radio buttons:</p>
71
72<pre>
73public void onRadioButtonClicked(View view) {
74    // Is the button now checked?
75    boolean checked = ((RadioButton) view).isChecked();
76    
77    // Check which radio button was clicked
78    switch(view.getId()) {
79        case R.id.radio_pirates:
80            if (checked)
81                // Pirates are the best
82            break;
83        case R.id.radio_ninjas:
84            if (checked)
85                // Ninjas rule
86            break;
87    }
88}
89</pre>
90
91<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute
92must have a signature exactly as shown above. Specifically, the method must:</p>
93<ul>
94  <li>Be public</li>
95  <li>Return void</li>
96  <li>Define a {@link android.view.View} as its only parameter (this will be the {@link
97android.view.View} that was clicked)</li>
98</ul>
99
100<p class="note"><strong>Tip:</strong> If you need to change the radio button state
101yourself (such as when loading a saved {@link android.preference.CheckBoxPreference}),
102use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link
103android.widget.CompoundButton#toggle()} method.</p>
104