1page.title=Buttons
2page.tags=button,imagebutton
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
31occurs 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
36button in your layout in three ways:</p>
37<ul>
38  <li>With text, using the {@link android.widget.Button} class:
39<pre>
40&lt;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&lt;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
57href="{@docRoot}reference/android/widget/TextView.html#attr_android:drawableLeft">{@code
58android:drawableLeft}</a> attribute:
59<pre>
60&lt;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
73an on-click event.</p>
74
75<p>To define the click event handler for a button, add the {@link
76android.R.attr#onClick android:onClick} attribute to the {@code &lt;Button&gt;} element in your XML
77layout. The value for this attribute must be the name of the method you want to call in response
78to a click event. The {@link android.app.Activity} hosting the layout must then implement the
79corresponding method.</p>
80
81<p>For example, here's a layout with a button using {@link
82android.R.attr#onClick android:onClick}:</p>
83
84<pre>
85&lt;?xml version="1.0" encoding="utf-8"?>
86&lt;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
95the click event:</p>
96
97<pre>
98/** Called when the user touches the button */
99public 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
105a 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
110android.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 programmatically rather than in an XML layout. This
117might be necessary if you instantiate the {@link android.widget.Button} at runtime or you need to
118declare the click behavior in a {@link android.app.Fragment} subclass.</p>
119
120<p>To declare the event handler programmatically, create an {@link
121android.view.View.OnClickListener} object and assign it to the button by calling {@link
122android.view.View#setOnClickListener}. For example:</p>
123
124<pre>
125Button button = (Button) findViewById(R.id.button_send);
126button.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
137another, because devices by different manufacturers often have different default styles for
138input controls.</p>
139
140<p>You can control exactly how your controls are styled using a theme that you apply to your
141entire application. For instance, to ensure that all devices running Android 4.0 and higher use
142the Holo theme in your app, declare {@code android:theme="@android:style/Theme.Holo"} in your
143manifest's {@code &lt;application&gt;} element. Also read the blog post, <a
144href="http://android-developers.blogspot.com/2012/01/holo-everywhere.html">Holo Everywhere</a>
145for 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
148android.R.attr#background android:background} attribute with a drawable or color resource.
149Alternatively, you can apply a <em>style</em> for the button, which works in a manner similar to
150HTML styles to define multiple style properties such as the background, font, size, and others.
151For more information about applying styles, see <a
152href="{@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
158basic buttons except that they have no borders or background but still change appearance during
159different states, such as when clicked.</p>
160
161<p>To create a borderless button, apply the {@link android.R.attr#borderlessButtonStyle}
162style to the button. For example:</p>
163
164<pre>
165&lt;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
179background. Instead of supplying a simple bitmap or color, however, your background should be a
180state 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
183for 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
189focused button states.
190    <p>To ensure that your images fit buttons of various sizes, create the bitmaps as <a
191href="{@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
194your project. Be sure each bitmap is named properly to reflect the button state that they each
195represent, such as {@code button_default.9.png}, {@code button_pressed.9.png}, and {@code
196button_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&lt;?xml version="1.0" encoding="utf-8"?>
201&lt;selector xmlns:android="http://schemas.android.com/apk/res/android">
202    &lt;item android:drawable="@drawable/button_pressed"
203          android:state_pressed="true" />
204    &lt;item android:drawable="@drawable/button_focused"
205          android:state_focused="true" />
206    &lt;item android:drawable="@drawable/button_default" />
207&lt;/selector>
208</pre>
209  <p>This defines a single drawable resource, which will change its image based on the current
210state of the button.</p>
211<ul>
212  <li>The first <code>&lt;item></code> defines the bitmap to use when the button is
213pressed (activated).</li>
214  <li>The second <code>&lt;item></code> defines the bitmap to use when the button is
215focused (when the button is highlighted using the trackball or directional
216pad).</li>
217  <li>The third <code>&lt;item></code> defines the bitmap to use when the button is in the
218default state (it's neither pressed nor focused).</li>
219</ul>
220  <p class="note"><strong>Note:</strong> The order of the <code>&lt;item></code> elements is
221important. When this drawable is referenced, the  <code>&lt;item></code> elements are traversed
222in-order to determine which one is appropriate for the current button state. Because the default
223bitmap 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
226drawable resource and when referenced by a {@link android.widget.Button} for its background,
227the 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&lt;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
242other button states, read about <a
243href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">State List
244Drawable</a>.</p>
245