1page.title=Toasts
2@jd:body
3
4<div id="qv-wrapper">
5  <div id="qv">    
6    <h2>In this document</h2>
7    <ol>
8      <li><a href="#Basics">The Basics</a></li>
9      <li><a href="#Positioning">Positioning your Toast</a></li>
10      <li><a href="#CustomToastView">Creating a Custom Toast View</a></li>
11    </ol>
12    
13    <h2>Key classes</h2>
14    <ol>
15      <li>{@link android.widget.Toast}</li>
16    </ol>
17  </div>
18</div>
19
20<p>A toast provides simple feedback about an operation in a small popup.
21It only fills the amount of space required for the message and the current
22activity remains visible and interactive. 
23For example, navigating away from an email before you send it triggers a 
24"Draft saved" toast to let you know that you can continue editing later. 
25Toasts automatically disappear after a timeout.</p>
26
27<img src="{@docRoot}images/toast.png" alt="" />
28
29<p>If user response to a status message is required, consider instead using a 
30<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notification</a>.</p>
31
32
33<h2 id="Basics">The Basics</h2>
34
35<p>First, instantiate a {@link android.widget.Toast}
36object with one of the {@link android.widget.Toast#makeText(Context,int,int) makeText()} methods.
37This method takes three parameters: the application {@link android.content.Context},
38the text message, and the duration for the toast. It returns a properly initialized Toast
39object. You can display the toast notification with {@link android.widget.Toast#show()},
40as shown in the following example:</p>
41
42<pre>
43Context context = getApplicationContext();
44CharSequence text = "Hello toast!";
45int duration = Toast.LENGTH_SHORT;
46
47Toast toast = Toast.makeText(context, text, duration);
48toast.show();
49</pre>
50
51<p>This example demonstrates everything you need for most toast notifications.
52You should rarely need anything else. You may, however, want to position the 
53toast differently or even use your own layout instead of a simple text message. 
54The following sections describe how you can do these things.</p>
55
56<p>You can also chain your methods and avoid holding on to the Toast object, like this:</p>
57<pre>Toast.makeText(context, text, duration).show();</pre>
58
59
60<h2 id="Positioning">Positioning your Toast</h2>
61
62<p>A standard toast notification appears near the bottom of the screen, centered horizontally.
63You can change this position with the {@link android.widget.Toast#setGravity(int,int,int)}
64method. This accepts three parameters: a {@link android.view.Gravity} constant, 
65an x-position offset, and a y-position offset.</p>
66
67<p>For example, if you decide that the toast should appear in the top-left corner, you can set the
68gravity like this:</p>
69<pre>
70toast.setGravity(Gravity.TOP|Gravity.LEFT, 0, 0);
71</pre>
72
73<p>If you want to nudge the position to the right, increase the value of the second parameter. 
74To nudge it down, increase the value of the last parameter.
75
76
77<h2 id="CustomToastView">Creating a Custom Toast View</h2>
78
79<p>If a simple text message isn't enough, you can create a customized layout for your
80toast notification. To create a custom layout, define a View layout,
81in XML or in your application code, and pass the root {@link android.view.View} object
82to the {@link android.widget.Toast#setView(View)} method.</p>
83
84<p>For example, you can create the layout for the toast visible in the screenshot to the right
85with the following XML (saved as <em>toast_layout.xml</em>):</p>
86<pre>
87&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
88              android:id="@+id/toast_layout_root"
89              android:orientation="horizontal"
90              android:layout_width="fill_parent"
91              android:layout_height="fill_parent"
92              android:padding="8dp"
93              android:background="#DAAA"
94              >
95    &lt;ImageView android:src="@drawable/droid"
96               android:layout_width="wrap_content"
97               android:layout_height="wrap_content"
98               android:layout_marginRight="8dp"
99               />
100    &lt;TextView android:id="@+id/text"
101              android:layout_width="wrap_content"
102              android:layout_height="wrap_content"
103              android:textColor="#FFF"
104              />
105&lt;/LinearLayout>
106</pre> 
107
108<p>Notice that the ID of the LinearLayout element is "toast_layout_root". You must use this
109ID to inflate the layout from the XML, as shown here:</p>
110
111<pre>
112LayoutInflater inflater = getLayoutInflater();
113View layout = inflater.inflate(R.layout.custom_toast,
114                               (ViewGroup) findViewById(R.id.toast_layout_root));
115
116TextView text = (TextView) layout.findViewById(R.id.text);
117text.setText("This is a custom toast");
118
119Toast toast = new Toast(getApplicationContext());
120toast.setGravity(Gravity.CENTER_VERTICAL, 0, 0);
121toast.setDuration(Toast.LENGTH_LONG);
122toast.setView(layout);
123toast.show();
124</pre>
125
126<p>First, retrieve the {@link android.view.LayoutInflater} with 
127{@link android.app.Activity#getLayoutInflater()} 
128(or {@link android.content.Context#getSystemService(String) getSystemService()}),
129and then inflate the layout from XML using 
130{@link android.view.LayoutInflater#inflate(int, ViewGroup)}. The first parameter
131is the layout resource ID and the second is the root View. You can use
132this inflated layout to find more View objects in the layout, so now capture and 
133define the content for the ImageView and TextView elements. Finally, create
134a new Toast with {@link android.widget.Toast#Toast(Context)} and set some properties
135of the toast, such as the gravity and duration. Then call
136{@link android.widget.Toast#setView(View)} and pass it the inflated layout.
137You can now display the toast with your custom layout by calling 
138{@link android.widget.Toast#show()}.</p>
139
140<p class="note"><strong>Note:</strong> Do not use the public constructor for a Toast 
141unless you are going to define the layout with {@link android.widget.Toast#setView(View)}.
142If you do not have a custom layout to use, you must use
143{@link android.widget.Toast#makeText(Context,int,int)} to create the Toast.</p>
144
145