1 page.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. 21 It only fills the amount of space required for the message and the current 22 activity remains visible and interactive. 23 For 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. 25 Toasts 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} 36 object with one of the {@link android.widget.Toast#makeText(Context,int,int) makeText()} methods. 37 This method takes three parameters: the application {@link android.content.Context}, 38 the text message, and the duration for the toast. It returns a properly initialized Toast 39 object. You can display the toast notification with {@link android.widget.Toast#show()}, 40 as shown in the following example:</p> 41 42 <pre> 43 Context context = getApplicationContext(); 44 CharSequence text = "Hello toast!"; 45 int duration = Toast.LENGTH_SHORT; 46 47 Toast toast = Toast.makeText(context, text, duration); 48 toast.show(); 49 </pre> 50 51 <p>This example demonstrates everything you need for most toast notifications. 52 You should rarely need anything else. You may, however, want to position the 53 toast differently or even use your own layout instead of a simple text message. 54 The 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. 63 You can change this position with the {@link android.widget.Toast#setGravity(int,int,int)} 64 method. This accepts three parameters: a {@link android.view.Gravity} constant, 65 an 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 68 gravity like this:</p> 69 <pre> 70 toast.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. 74 To 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> 80 If a simple text message isn't enough, you can create a customized layout 81 for your toast notification. To create a custom layout, define a View 82 layout, in XML or in your application code, and pass the root {@link 83 android.view.View} object to the {@link android.widget.Toast#setView(View)} 84 method. 85 </p> 86 87 <p> 88 For example, you can create the layout for the toast visible in the 89 screenshot to the right with the following XML (saved as 90 <em>layout/custom_toast.xml</em>): 91 </p> 92 <pre> 93 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 94 android:id="@+id/custom_toast_container" 95 android:orientation="horizontal" 96 android:layout_width="fill_parent" 97 android:layout_height="fill_parent" 98 android:padding="8dp" 99 android:background="#DAAA" 100 > 101 <ImageView android:src="@drawable/droid" 102 android:layout_width="wrap_content" 103 android:layout_height="wrap_content" 104 android:layout_marginRight="8dp" 105 /> 106 <TextView android:id="@+id/text" 107 android:layout_width="wrap_content" 108 android:layout_height="wrap_content" 109 android:textColor="#FFF" 110 /> 111 </LinearLayout> 112 </pre> 113 114 <p> 115 Notice that the ID of the LinearLayout element is "custom_toast_container". 116 You must use this ID and the ID of the XML layout file "custom_toast" to 117 inflate the layout, as shown here: 118 </p> 119 120 <pre> 121 LayoutInflater inflater = getLayoutInflater(); 122 View layout = inflater.inflate(R.layout.custom_toast, 123 (ViewGroup) findViewById(R.id.custom_toast_container)); 124 125 TextView text = (TextView) layout.findViewById(R.id.text); 126 text.setText("This is a custom toast"); 127 128 Toast toast = new Toast(getApplicationContext()); 129 toast.setGravity(Gravity.CENTER_VERTICAL, 0, 0); 130 toast.setDuration(Toast.LENGTH_LONG); 131 toast.setView(layout); 132 toast.show(); 133 </pre> 134 135 <p>First, retrieve the {@link android.view.LayoutInflater} with 136 {@link android.app.Activity#getLayoutInflater()} 137 (or {@link android.content.Context#getSystemService(String) getSystemService()}), 138 and then inflate the layout from XML using 139 {@link android.view.LayoutInflater#inflate(int, ViewGroup)}. The first parameter 140 is the layout resource ID and the second is the root View. You can use 141 this inflated layout to find more View objects in the layout, so now capture and 142 define the content for the ImageView and TextView elements. Finally, create 143 a new Toast with {@link android.widget.Toast#Toast(Context)} and set some properties 144 of the toast, such as the gravity and duration. Then call 145 {@link android.widget.Toast#setView(View)} and pass it the inflated layout. 146 You can now display the toast with your custom layout by calling 147 {@link android.widget.Toast#show()}.</p> 148 149 <p class="note"><strong>Note:</strong> Do not use the public constructor for a Toast 150 unless you are going to define the layout with {@link android.widget.Toast#setView(View)}. 151 If you do not have a custom layout to use, you must use 152 {@link android.widget.Toast#makeText(Context,int,int)} to create the Toast.</p> 153 154
