1page.title=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 OnClickListener</a></li> 13 </ol> 14 </li> 15 <li><a href="#Style">Styling Your Button</a> 16 <ol> 17 <li><a href="#Borderless">Borderless button</a></li> 18 <li><a href="#CustomBackground">Custom background</a></li> 19 </ol> 20 </li> 21</ol> 22 <h2>Key classes</h2> 23 <ol> 24 <li>{@link android.widget.Button}</li> 25 <li>{@link android.widget.ImageButton}</li> 26 </ol> 27</div> 28</div> 29 30 31<p>A button consists of text or an icon (or both text and an icon) that communicates what action 32occurs when the user touches it.</p> 33 34<img src="{@docRoot}images/ui/button-types.png" alt="" /> 35 36<p>Depending on whether you want a button with text, an icon, or both, you can create the 37button in your layout in three ways:</p> 38<ul> 39 <li>With text, using the {@link android.widget.Button} class: 40<pre> 41<Button 42 android:layout_width="wrap_content" 43 android:layout_height="wrap_content" 44 android:text="@string/button_text" 45 ... /> 46</pre> 47 </li> 48 <li>With an icon, using the {@link android.widget.ImageButton} class: 49<pre> 50<ImageButton 51 android:layout_width="wrap_content" 52 android:layout_height="wrap_content" 53 android:src="@drawable/button_icon" 54 ... /> 55</pre> 56 </li> 57 <li>With text and an icon, using the {@link android.widget.Button} class with the <a 58href="{@docRoot}reference/android/widget/TextView.html#attr_android:drawableLeft">{@code 59android:drawableLeft}</a> attribute: 60<pre> 61<Button 62 android:layout_width="wrap_content" 63 android:layout_height="wrap_content" 64 android:text="@string/button_text" 65 android:drawableLeft="@drawable/button_icon" 66 ... /> 67</pre> 68</li> 69</ul> 70 71<h2 id="HandlingEvents">Responding to Click Events</h2> 72 73<p>When the user clicks a button, the {@link android.widget.Button} object receives 74an on-click event.</p> 75 76<p>To define the click event handler for a button, add the {@link 77android.R.attr#onClick android:onClick} attribute to the {@code <Button>} element in your XML 78layout. The value for this attribute must be the name of the method you want to call in response 79to a click event. The {@link android.app.Activity} hosting the layout must then implement the 80corresponding method.</p> 81 82<p>For example, here's a layout with a button using {@link 83android.R.attr#onClick android:onClick}:</p> 84 85<pre> 86<?xml version="1.0" encoding="utf-8"?> 87<Button xmlns:android="http://schemas.android.com/apk/res/android" 88 android:id="@+id/button_send" 89 android:layout_width="wrap_content" 90 android:layout_height="wrap_content" 91 android:text="@string/button_send" 92 android:onClick="sendMessage" /> 93</pre> 94 95<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles 96the click event:</p> 97 98<pre> 99/** Called when the user touches the button */ 100public void sendMessage(View view) { 101 // Do something in response to button click 102} 103</pre> 104 105<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute must have 106a signature exactly as shown above. Specifically, the method must:</p> 107<ul> 108 <li>Be public</li> 109 <li>Return void</li> 110 <li>Define a {@link android.view.View} as its only parameter (this will be the {@link 111android.view.View} that was clicked)</li> 112</ul> 113 114 115<h3 id="ClickListener">Using an OnClickListener</h3> 116 117<p>You can also declare the click event handler pragmatically rather than in an XML layout. This 118might be necessary if you instantiate the {@link android.widget.Button} at runtime or you need to 119declare the click behavior in a {@link android.app.Fragment} subclass.</p> 120 121<p>To declare the event handler programmatically, create an {@link 122android.view.View.OnClickListener} object and assign it to the button by calling {@link 123android.view.View#setOnClickListener}. For example:</p> 124 125<pre> 126Button button = (Button) findViewById(R.id.button_send); 127button.setOnClickListener(new View.OnClickListener() { 128 public void onClick(View v) { 129 // Do something in response to button click 130 } 131}); 132</pre> 133 134 135<h2 id="Style">Styling Your Button</h2> 136 137<p>The appearance of your button (background image and font) may vary from one device to 138another, because devices by different manufacturers often have different default styles for 139input controls.</p> 140 141<p>You can control exactly how your controls are styled using a theme that you apply to your 142entire application. For instance, to ensure that all devices running Android 4.0 and higher use 143the Holo theme in your app, declare {@code android:theme="@android:style/Theme.Holo"} in your 144manifest's {@code <application>} element. Also read the blog post, <a 145href="http://android-developers.blogspot.com/2012/01/holo-everywhere.html">Holo Everywhere</a> 146for information about using the Holo theme while supporting older devices.</p> 147 148<p>To customize individual buttons with a different background, specify the {@link 149android.R.attr#background android:background} attribute with a drawable or color resource. 150Alternatively, you can apply a <em>style</em> for the button, which works in a manner similar to 151HTML styles to define multiple style properties such as the background, font, size, and others. 152For more information about applying styles, see <a 153href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p> 154 155 156<h3 id="Borderless">Borderless button</h3> 157 158<p>One design that can be useful is a "borderless" button. Borderless buttons resemble 159basic buttons except that they have no borders or background but still change appearance during 160different states, such as when clicked.</p> 161 162<p>To create a borderless button, apply the {@link android.R.attr#borderlessButtonStyle} 163style to the button. For example:</p> 164 165<pre> 166<Button 167 android:id="@+id/button_send" 168 android:layout_width="wrap_content" 169 android:layout_height="wrap_content" 170 android:text="@string/button_send" 171 android:onClick="sendMessage" 172 style="?android:attr/borderlessButtonStyle" /> 173</pre> 174 175 176 177<h3 id="CustomBackground">Custom background</h3> 178 179<p>If you want to truly redefine the appearance of your button, you can specify a custom 180background. Instead of supplying a simple bitmap or color, however, your background should be a 181state list resource that changes appearance depending on the button's current state.</p> 182 183<p>You can define the state list in an XML file that defines three different images or colors to use 184for the different button states.</p> 185 186<p>To create a state list drawable for your button background:</p> 187 188<ol> 189 <li>Create three bitmaps for the button background that represent the default, pressed, and 190focused button states. 191 <p>To ensure that your images fit buttons of various sizes, create the bitmaps as <a 192href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-patch</a> bitmaps.</p> 193 </li> 194 <li>Place the bitmaps into the <code>res/drawable/</code> directory of 195your project. Be sure each bitmap is named properly to reflect the button state that they each 196represent, such as {@code button_default.9.png}, {@code button_pressed.9.png}, and {@code 197button_focused.9.png}.</li> 198 <li>Create a new XML file in the <code>res/drawable/</code> directory (name it something like 199<code>button_custom.xml</code>). Insert the following XML: 200<pre> 201<?xml version="1.0" encoding="utf-8"?> 202<selector xmlns:android="http://schemas.android.com/apk/res/android"> 203 <item android:drawable="@drawable/button_pressed" 204 android:state_pressed="true" /> 205 <item android:drawable="@drawable/button_focused" 206 android:state_focused="true" /> 207 <item android:drawable="@drawable/button_default" /> 208</selector> 209</pre> 210 <p>This defines a single drawable resource, which will change its image based on the current 211state of the button.</p> 212<ul> 213 <li>The first <code><item></code> defines the bitmap to use when the button is 214pressed (activated).</li> 215 <li>The second <code><item></code> defines the bitmap to use when the button is 216focused (when the button is highlighted using the trackball or directional 217pad).</li> 218 <li>The third <code><item></code> defines the bitmap to use when the button is in the 219default state (it's neither pressed nor focused).</li> 220</ul> 221 <p class="note"><strong>Note:</strong> The order of the <code><item></code> elements is 222important. When this drawable is referenced, the <code><item></code> elements are traversed 223in-order to determine which one is appropriate for the current button state. Because the default 224bitmap is last, it is only applied when the conditions <code>android:state_pressed</code> and 225<code>android:state_focused</code> have both evaluated as false.</p> 226 <p>This XML file now represents a single 227drawable resource and when referenced by a {@link android.widget.Button} for its background, 228the image displayed will change based on these three states.</p> 229</li> 230 <li>Then simply apply the drawable XML file as the button background: 231<pre> 232<Button 233 android:id="@+id/button_send" 234 android:layout_width="wrap_content" 235 android:layout_height="wrap_content" 236 android:text="@string/button_send" 237 android:onClick="sendMessage" 238 android:background="@drawable/button_custom" /> 239</pre> 240</ol> 241 242 <p>For more information about this XML syntax, including how to define a disabled, hovered, or 243other button states, read about <a 244href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">State List 245Drawable</a>.</p>
