Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 1 | page.title=Toggle Buttons |
Scott Main | 64461bf | 2013-04-11 19:32:08 -0700 | [diff] [blame] | 2 | page.tags="switch","togglebutton" |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 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} |
| 26 | object. Android 4.0 (API level 14) introduces another kind of toggle button called a switch that |
| 27 | provides 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} |
| 40 | controls are subclasses of {@link android.widget.CompoundButton} and function in the same manner, so |
| 41 | you 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}, |
| 46 | the object receives an on-click event.</p> |
| 47 | |
| 48 | <p>To define the click event handler, add the <code><a |
| 49 | href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the |
| 50 | <code><ToggleButton></code> or <code><Switch></code> element in your XML |
| 51 | layout. The value for this attribute must be the name of the method you want to call in response |
| 52 | to a click event. The {@link android.app.Activity} hosting the layout must then implement the |
| 53 | corresponding method.</p> |
| 54 | |
| 55 | <p>For example, here's a {@link android.widget.ToggleButton} with the <code><a |
| 56 | href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute:</p> |
| 57 | |
| 58 | <pre> |
| 59 | <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 |
| 69 | click event:</p> |
| 70 | |
| 71 | <pre> |
| 72 | public 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 |
| 85 | must 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 |
| 90 | android.view.View} that was clicked)</li> |
| 91 | </ul> |
| 92 | |
| 93 | <p class="note"><strong>Tip:</strong> If you need to change the state |
| 94 | yourself, |
| 95 | use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link |
| 96 | android.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 pragmatically rather than in an XML layout. This |
| 103 | might be necessary if you instantiate the {@link android.widget.ToggleButton} or {@link |
| 104 | android.widget.Switch} at runtime or you need to |
| 105 | declare the click behavior in a {@link android.app.Fragment} subclass.</p> |
| 106 | |
| 107 | <p>To declare the event handler programmatically, create an {@link |
| 108 | android.widget.CompoundButton.OnCheckedChangeListener} object and assign it to the button by calling |
| 109 | {@link |
| 110 | android.widget.CompoundButton#setOnCheckedChangeListener}. For example:</p> |
| 111 | |
| 112 | <pre> |
| 113 | ToggleButton toggle = (ToggleButton) findViewById(R.id.togglebutton); |
| 114 | toggle.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> |