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