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