blob: 02597c84ca8cb41fe73ebaecfe563a20cd362e12 [file] [log] [blame]
Scott Main50e990c2012-06-21 17:14:39 -07001page.title=Buttons
Joe Fernandez33baa5a2013-11-14 11:41:19 -08002page.tags=button,imagebutton
Scott Main50e990c2012-06-21 17:14:39 -07003@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 pragmatically 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
Joe Fernandez33baa5a2013-11-14 11:41:19 -0800244Drawable</a>.</p>