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