1page.title=Toggle Buttons
2page.tags=switch,togglebutton
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>
10    <ol>
11      <li><a href="#ClickListener">Using an OnCheckedChangeListener</a></li>
12    </ol>
13  </li>
14</ol>
15  <h2>Key classes</h2>
16  <ol>
17    <li>{@link android.widget.ToggleButton}</li>
18    <li>{@link android.widget.Switch}</li>
19  </ol>
20</div>
21</div>
22
23<p>A toggle button allows the user to change a setting between two states.</p>
24
25<p>You can add a basic toggle button to your layout with the {@link android.widget.ToggleButton}
26object. Android 4.0 (API level 14) introduces another kind of toggle button called a switch that
27provides a slider control, which you can add with a {@link android.widget.Switch} object.</p>
28
29<div style="float:left;width:200px">
30<img src="{@docRoot}images/ui/togglebutton.png" alt="" />
31<p class="img-caption"><em>Toggle buttons</em></p>
32</div>
33
34<div style="float:left;width:200px;margin-top:24px">
35<img src="{@docRoot}images/ui/switch.png" alt="" />
36<p class="img-caption"><em>Switches (in Android 4.0+)</em></p>
37</div>
38
39<p style="clear:left">The {@link android.widget.ToggleButton} and {@link android.widget.Switch}
40controls are subclasses of {@link android.widget.CompoundButton} and function in the same manner, so
41you can implement their behavior the same way.</p>
42
43<h2 id="HandlingEvents">Responding to Click Events</h2>
44
45<p>When the user selects a {@link android.widget.ToggleButton} and {@link android.widget.Switch},
46the object receives an on-click event.</p>
47
48<p>To define the click event handler, add the <code><a
49href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the
50<code>&lt;ToggleButton&gt;</code> or <code>&lt;Switch&gt;</code> element in your XML
51layout. The value for this attribute must be the name of the method you want to call in response
52to a click event. The {@link android.app.Activity} hosting the layout must then implement the
53corresponding method.</p>
54
55<p>For example, here's a {@link android.widget.ToggleButton} with the <code><a
56href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute:</p>
57
58<pre>
59&lt;ToggleButton 
60    android:id="@+id/togglebutton"
61    android:layout_width="wrap_content"
62    android:layout_height="wrap_content"
63    android:textOn="Vibrate on"
64    android:textOff="Vibrate off"
65    android:onClick="onToggleClicked"/>
66</pre>
67
68<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles the
69click event:</p>
70
71<pre>
72public void onToggleClicked(View view) {
73    // Is the toggle on?
74    boolean on = ((ToggleButton) view).isChecked();
75    
76    if (on) {
77        // Enable vibrate
78    } else {
79        // Disable vibrate
80    }
81}
82</pre>
83
84<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute
85must have a signature exactly as shown above. Specifically, the method must:</p>
86<ul>
87  <li>Be public</li>
88  <li>Return void</li>
89  <li>Define a {@link android.view.View} as its only parameter (this will be the {@link
90android.view.View} that was clicked)</li>
91</ul>
92
93<p class="note"><strong>Tip:</strong> If you need to change the state
94yourself,
95use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link
96android.widget.CompoundButton#toggle()} method to change the state.</p>
97
98
99
100<h3 id="ClickListener">Using an OnCheckedChangeListener</h3>
101
102<p>You can also declare a click event handler programmatically rather than in an XML layout. This
103might be necessary if you instantiate the {@link android.widget.ToggleButton} or {@link
104android.widget.Switch} at runtime or you need to
105declare the click behavior in a {@link android.app.Fragment} subclass.</p>
106
107<p>To declare the event handler programmatically, create an {@link
108android.widget.CompoundButton.OnCheckedChangeListener} object and assign it to the button by calling
109{@link
110android.widget.CompoundButton#setOnCheckedChangeListener}. For example:</p>
111
112<pre>
113ToggleButton toggle = (ToggleButton) findViewById(R.id.togglebutton);
114toggle.setOnCheckedChangeListener(new CompoundButton.OnCheckedChangeListener() {
115    public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) {
116        if (isChecked) {
117            // The toggle is enabled
118        } else {
119            // The toggle is disabled
120        }
121    }
122});
123</pre>
124