Home | History | Annotate | Download | only in controls 
      1 page.title=Toggle Buttons
      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>
     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}
     27 object. Android 4.0 (API level 14) introduces another kind of toggle button called a switch that
     28 provides 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}
     41 controls are subclasses of {@link android.widget.CompoundButton} and function in the same manner, so
     42 you 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},
     47 the object receives an on-click event.</p>
     48 
     49 <p>To define the click event handler, add the <code><a
     50 href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the
     51 <code>&lt;ToggleButton&gt;</code> or <code>&lt;Switch&gt;</code> element in your XML
     52 layout. The value for this attribute must be the name of the method you want to call in response
     53 to a click event. The {@link android.app.Activity} hosting the layout must then implement the
     54 corresponding method.</p>
     55 
     56 <p>For example, here's a {@link android.widget.ToggleButton} with the <code><a
     57 href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute:</p>
     58 
     59 <pre>
     60 &lt;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
     70 click event:</p>
     71 
     72 <pre>
     73 public 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
     86 must 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
     91 android.view.View} that was clicked)</li>
     92 </ul>
     93 
     94 <p class="note"><strong>Tip:</strong> If you need to change the state
     95 yourself,
     96 use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link
     97 android.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
    104 might be necessary if you instantiate the {@link android.widget.ToggleButton} or {@link
    105 android.widget.Switch} at runtime or you need to
    106 declare the click behavior in a {@link android.app.Fragment} subclass.</p>
    107 
    108 <p>To declare the event handler programmatically, create an {@link
    109 android.widget.CompoundButton.OnCheckedChangeListener} object and assign it to the button by calling
    110 {@link
    111 android.widget.CompoundButton#setOnCheckedChangeListener}. For example:</p>
    112 
    113 <pre>
    114 ToggleButton toggle = (ToggleButton) findViewById(R.id.togglebutton);
    115 toggle.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