1page.title=Checkboxes
2
3@jd:body
4
5<div id="qv-wrapper">
6<div id="qv">
7<h2>In this document</h2>
8<ol>
9  <li><a href="#HandlingEvents">Responding to Click Events</a></li>
10</ol>
11
12<h2>Key classes</h2>
13<ol>
14  <li>{@link android.widget.CheckBox}</li>
15</ol>
16</div>
17</div>
18
19<p>Checkboxes allow the user to select one or more options from a set. Typically, you should
20present each checkbox option in a vertical list.</p>
21
22<img src="{@docRoot}images/ui/checkboxes.png" alt="" />
23
24<p>To create each checkbox option, create a {@link android.widget.CheckBox} in your layout. Because
25a set of checkbox options allows the user to select multiple items, each checkbox is managed
26separately and you must register a click listener for each one.</p>
27
28<h2 id="HandlingEvents">Responding to Click Events</h2>
29
30<p>When the user selects a checkbox, the {@link android.widget.CheckBox} object receives an
31on-click event.</p>
32
33<p>To define the click event handler for a checkbox, add the <code><a
34href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the
35<code>&lt;CheckBox&gt;</code> element in your XML
36layout. The value for this attribute must be the name of the method you want to call in response
37to a click event. The {@link android.app.Activity} hosting the layout must then implement the
38corresponding method.</p>
39
40<p>For example, here are a couple {@link android.widget.CheckBox} objects in a list:</p>
41
42<pre>
43&lt;?xml version="1.0" encoding="utf-8"?>
44&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
45    android:orientation="vertical"
46    android:layout_width="fill_parent"
47    android:layout_height="fill_parent">
48    &lt;CheckBox android:id="&#64;+id/checkbox_meat"
49        android:layout_width="wrap_content"
50        android:layout_height="wrap_content"
51        android:text="&#64;string/meat"
52        android:onClick="onCheckboxClicked"/>
53    &lt;CheckBox android:id="&#64;+id/checkbox_cheese"
54        android:layout_width="wrap_content"
55        android:layout_height="wrap_content"
56        android:text="&#64;string/cheese"
57        android:onClick="onCheckboxClicked"/>
58&lt;/LinearLayout>
59</pre>
60
61<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles the
62click event for both checkboxes:</p>
63
64<pre>
65public void onCheckboxClicked(View view) {
66    // Is the view now checked?
67    boolean checked = ((CheckBox) view).isChecked();
68    
69    // Check which checkbox was clicked
70    switch(view.getId()) {
71        case R.id.checkbox_meat:
72            if (checked)
73                // Put some meat on the sandwich
74            else
75                // Remove the meat
76            break;
77        case R.id.checkbox_cheese:
78            if (checked)
79                // Cheese me
80            else
81                // I'm lactose intolerant
82            break;
83        // TODO: Veggie sandwich
84    }
85}
86</pre>
87
88<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute
89must have a signature exactly as shown above. Specifically, the method must:</p>
90<ul>
91  <li>Be public</li>
92  <li>Return void</li>
93  <li>Define a {@link android.view.View} as its only parameter (this will be the {@link
94android.view.View} that was clicked)</li>
95</ul>
96
97<p class="note"><strong>Tip:</strong> If you need to change the checkbox state
98yourself (such as when loading a saved {@link android.preference.CheckBoxPreference}),
99use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link
100android.widget.CompoundButton#toggle()} method.</p>