| page.title=Creating Toast Notifications |
| parent.title=Notifying the User |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>Key classes</h2> |
| <ol> |
| <li>{@link android.widget.Toast}</li> |
| </ol> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#Basics">The Basics</a></li> |
| <li><a href="#Position">Positioning your Toast</a></li> |
| <li><a href="#CustomToastView">Creating a Custom Toast View</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>A toast notification is a message that pops up on the surface of the window. |
| It only fills the amount of space required for the message and the user's current |
| activity remains visible and interactive. The notification automatically fades in and |
| out, and does not accept interaction events.</p> |
| |
| <p>The screenshot below shows an example toast notification from the Alarm application. |
| Once an alarm is turned on, a toast is displayed to assure you that the |
| alarm was set.</p> |
| <img src="{@docRoot}images/toast.png" alt="" /> |
| |
| <p>A toast can be created and displayed from an {@link android.app.Activity} or |
| {@link android.app.Service}. If you create a toast notification from a Service, it |
| appears in front of the Activity currently in focus.</p> |
| |
| <p>If user response to the notification is required, consider using a |
| <a href="notifications.html">Status Bar Notification</a>.</p> |
| |
| |
| <h2 id="Basics">The Basics</h2> |
| |
| <p>First, instantiate a {@link android.widget.Toast} |
| object with one of the {@link android.widget.Toast#makeText(Context,int,int) makeText()} methods. |
| This method takes three parameters: the application {@link android.content.Context}, |
| the text message, and the duration for the toast. It returns a properly initialized Toast |
| object. You can display the toast notification with {@link android.widget.Toast#show()}, |
| as shown in the following example:</p> |
| |
| <pre> |
| Context context = getApplicationContext(); |
| CharSequence text = "Hello toast!"; |
| int duration = Toast.LENGTH_SHORT; |
| |
| Toast toast = Toast.makeText(context, text, duration); |
| toast.show(); |
| </pre> |
| |
| <p>This example demonstrates everything you need for most toast notifications. |
| You should rarely need anything else. You may, however, want to position the |
| toast differently or even use your own layout instead of a simple text message. |
| The following sections describe how you can do these things.</p> |
| |
| <p>You can also chain your methods and avoid holding on to the Toast object, like this:</p> |
| <pre>Toast.makeText(context, text, duration).show();</pre> |
| |
| |
| <h2 id="Positioning">Positioning your Toast</h2> |
| |
| <p>A standard toast notification appears near the bottom of the screen, centered horizontally. |
| You can change this position with the {@link android.widget.Toast#setGravity(int,int,int)} |
| method. This accepts three parameters: a {@link android.view.Gravity} constant, |
| an x-position offset, and a y-position offset.</p> |
| |
| <p>For example, if you decide that the toast should appear in the top-left corner, you can set the |
| gravity like this:</p> |
| <pre> |
| toast.setGravity(Gravity.TOP|Gravity.LEFT, 0, 0); |
| </pre> |
| |
| <p>If you want to nudge the position to the right, increase the value of the second parameter. |
| To nudge it down, increase the value of the last parameter. |
| |
| |
| <h2 id="CustomToastView">Creating a Custom Toast View</h2> |
| |
| <img src="{@docRoot}images/custom_toast.png" alt="" style="float:right" /> |
| |
| <p>If a simple text message isn't enough, you can create a customized layout for your |
| toast notification. To create a custom layout, define a View layout, |
| in XML or in your application code, and pass the root {@link android.view.View} object |
| to the {@link android.widget.Toast#setView(View)} method.</p> |
| |
| <p>For example, you can create the layout for the toast visible in the screenshot to the right |
| with the following XML (saved as <em>toast_layout.xml</em>):</p> |
| <pre> |
| <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" |
| android:id="@+id/toast_layout_root" |
| android:orientation="horizontal" |
| android:layout_width="fill_parent" |
| android:layout_height="fill_parent" |
| android:padding="10dp" |
| android:background="#DAAA" |
| > |
| <ImageView android:id="@+id/image" |
| android:layout_width="wrap_content" |
| android:layout_height="fill_parent" |
| android:layout_marginRight="10dp" |
| /> |
| <TextView android:id="@+id/text" |
| android:layout_width="wrap_content" |
| android:layout_height="fill_parent" |
| android:textColor="#FFF" |
| /> |
| </LinearLayout> |
| </pre> |
| |
| <p>Notice that the ID of the LinearLayout element is "toast_layout". You must use this |
| ID to inflate the layout from the XML, as shown here:</p> |
| |
| <pre> |
| LayoutInflater inflater = getLayoutInflater(); |
| View layout = inflater.inflate(R.layout.toast_layout, |
| (ViewGroup) findViewById(R.id.toast_layout_root)); |
| |
| ImageView image = (ImageView) layout.findViewById(R.id.image); |
| image.setImageResource(R.drawable.android); |
| TextView text = (TextView) layout.findViewById(R.id.text); |
| text.setText("Hello! This is a custom toast!"); |
| |
| Toast toast = new Toast(getApplicationContext()); |
| toast.setGravity(Gravity.CENTER_VERTICAL, 0, 0); |
| toast.setDuration(Toast.LENGTH_LONG); |
| toast.setView(layout); |
| toast.show(); |
| </pre> |
| |
| <p>First, retrieve the {@link android.view.LayoutInflater} with |
| {@link android.app.Activity#getLayoutInflater()} |
| (or {@link android.content.Context#getSystemService(String) getSystemService()}), |
| and then inflate the layout from XML using |
| {@link android.view.LayoutInflater#inflate(int, ViewGroup)}. The first parameter |
| is the layout resource ID and the second is the root View. You can use |
| this inflated layout to find more View objects in the layout, so now capture and |
| define the content for the ImageView and TextView elements. Finally, create |
| a new Toast with {@link android.widget.Toast#Toast(Context)} and set some properties |
| of the toast, such as the gravity and duration. Then call |
| {@link android.widget.Toast#setView(View)} and pass it the inflated layout. |
| You can now display the toast with your custom layout by calling |
| {@link android.widget.Toast#show()}.</p> |
| |
| <p class="note"><strong>Note:</strong> Do not use the public constructor for a Toast |
| unless you are going to define the layout with {@link android.widget.Toast#setView(View)}. |
| If you do not have a custom layout to use, you must use |
| {@link android.widget.Toast#makeText(Context,int,int)} to create the Toast.</p> |
| |