Home | History | Annotate | Download | only in controls 
      1 page.title=Checkboxes
      2 parent.title=Input Controls
      3 parent.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
     21 present 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
     26 a set of checkbox options allows the user to select multiple items, each checkbox is managed
     27 separately 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
     32 on-click event.</p>
     33 
     34 <p>To define the click event handler for a checkbox, add the <code><a
     35 href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the
     36 <code>&lt;CheckBox&gt;</code> element in your XML
     37 layout. The value for this attribute must be the name of the method you want to call in response
     38 to a click event. The {@link android.app.Activity} hosting the layout must then implement the
     39 corresponding 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
     63 click event for both checkboxes:</p>
     64 
     65 <pre>
     66 public 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
     90 must 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
     95 android.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
     99 yourself (such as when loading a saved {@link android.preference.CheckBoxPreference}),
    100 use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link
    101 android.widget.CompoundButton#toggle()} method.</p>