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