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