1 page.title=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 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 32 occurs 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 37 button 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 58 href="{@docRoot}reference/android/widget/TextView.html#attr_android:drawableLeft">{@code 59 android: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 74 an on-click event.</p> 75 76 <p>To define the click event handler for a button, add the {@link 77 android.R.attr#onClick android:onClick} attribute to the {@code <Button>} element in your XML 78 layout. The value for this attribute must be the name of the method you want to call in response 79 to a click event. The {@link android.app.Activity} hosting the layout must then implement the 80 corresponding method.</p> 81 82 <p>For example, here's a layout with a button using {@link 83 android.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 96 the click event:</p> 97 98 <pre> 99 /** Called when the user touches the button */ 100 public 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 106 a 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 111 android.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 118 might be necessary if you instantiate the {@link android.widget.Button} at runtime or you need to 119 declare the click behavior in a {@link android.app.Fragment} subclass.</p> 120 121 <p>To declare the event handler programmatically, create an {@link 122 android.view.View.OnClickListener} object and assign it to the button by calling {@link 123 android.view.View#setOnClickListener}. For example:</p> 124 125 <pre> 126 Button button = (Button) findViewById(R.id.button_send); 127 button.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 138 another, because devices by different manufacturers often have different default styles for 139 input controls.</p> 140 141 <p>You can control exactly how your controls are styled using a theme that you apply to your 142 entire application. For instance, to ensure that all devices running Android 4.0 and higher use 143 the Holo theme in your app, declare {@code android:theme="@android:style/Theme.Holo"} in your 144 manifest's {@code <application>} element. Also read the blog post, <a 145 href="http://android-developers.blogspot.com/2012/01/holo-everywhere.html">Holo Everywhere</a> 146 for 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 149 android.R.attr#background android:background} attribute with a drawable or color resource. 150 Alternatively, you can apply a <em>style</em> for the button, which works in a manner similar to 151 HTML styles to define multiple style properties such as the background, font, size, and others. 152 For more information about applying styles, see <a 153 href="{@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 159 basic buttons except that they have no borders or background but still change appearance during 160 different states, such as when clicked.</p> 161 162 <p>To create a borderless button, apply the {@link android.R.attr#borderlessButtonStyle} 163 style 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 180 background. Instead of supplying a simple bitmap or color, however, your background should be a 181 state 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 184 for 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 190 focused button states. 191 <p>To ensure that your images fit buttons of various sizes, create the bitmaps as <a 192 href="{@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 195 your project. Be sure each bitmap is named properly to reflect the button state that they each 196 represent, such as {@code button_default.9.png}, {@code button_pressed.9.png}, and {@code 197 button_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 211 state of the button.</p> 212 <ul> 213 <li>The first <code><item></code> defines the bitmap to use when the button is 214 pressed (activated).</li> 215 <li>The second <code><item></code> defines the bitmap to use when the button is 216 focused (when the button is highlighted using the trackball or directional 217 pad).</li> 218 <li>The third <code><item></code> defines the bitmap to use when the button is in the 219 default 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 222 important. When this drawable is referenced, the <code><item></code> elements are traversed 223 in-order to determine which one is appropriate for the current button state. Because the default 224 bitmap 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 227 drawable resource and when referenced by a {@link android.widget.Button} for its background, 228 the 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 243 other button states, read about <a 244 href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">State List 245 Drawable</a>.</p>
