163 lines
6.7 KiB
Plaintext
163 lines
6.7 KiB
Plaintext
page.title=Creating Toast Notifications
|
|
parent.title=Notifying the User
|
|
parent.link=index.html
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
<h2>Quickview</h2>
|
|
<ol>
|
|
<li>A toast is a message that appears on the surface of the screen for a moment, but it
|
|
does not take focus (or pause the current activity), so it cannot accept user input</li>
|
|
<li>You can customize the toast layout to include images</li>
|
|
</ol>
|
|
|
|
<h2>In this document</h2>
|
|
<ol>
|
|
<li><a href="#Basics">The Basics</a></li>
|
|
<li><a href="#Positioning">Positioning your Toast</a></li>
|
|
<li><a href="#CustomToastView">Creating a Custom Toast View</a></li>
|
|
</ol>
|
|
|
|
<h2>Key classes</h2>
|
|
<ol>
|
|
<li>{@link android.widget.Toast}</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>
|
|
|