am 8419fcdf: am b8b3645a: AI 147803: add docs and images for docs on Toast

 * A class that represents how a persistent notification is to be presented to

 * the user using the {@link android.app.NotificationManager}.

 *

 * <p>For a guide to creating notifications, see the

 * <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Creating Status 

 * Bar Notifications</a> document in the Dev Guide.</p>

 */

public class Notification implements Parcelable

{

    /**

     * Use the default notification vibrate. This will ignore any given

     * {@link #vibrate}.

     * {@link #vibrate}. Using phone vibration requires the 

     * {@link android.Manifest.permission#VIBRATE VIBRATE} permission.

     * 

     * @see #defaults

     */ 

    /**

     * The pattern with which to vibrate. This pattern will repeat if {@link

     * #FLAG_INSISTENT} bit is set in the {@link #flags} field.

     * The pattern with which to vibrate. 

     * 

     * <p>

     * To vibrate the default pattern, see {@link #defaults}.

    /**

     * Bit to be bitwise-ored into the {@link #flags} field that if set,

     * the audio and vibration will be repeated until the notification is

     * cancelled.

     *

     * <p>

     * NOTE: This notion will change when we have decided exactly

     * what the UI will be.

     * </p>

     * the audio will be repeated until the notification is

     * cancelled or the notification window is opened.

     */

    public static final int FLAG_INSISTENT          = 0x00000004;

          <ul>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/declaring-layout.html">Declaring Layout</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html">Creating Menus</a></li>

     <!--       <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html">Creating Dialogs</a></li>  -->

            <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html">Creating Dialogs</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/ui-events.html">Handling UI Events</a></li>

     <!--       <li><a href="<?cs var:toroot ?>guide/topics/ui/notifiers/index.html">Notifying the User</a></li> -->

            <li><a href="<?cs var:toroot ?>guide/topics/ui/notifiers/index.html">Notifying the User</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/themes.html">Applying Styles and Themes</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/custom-components.html">Building Custom Components</a></li>

            <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html">Binding to Data with AdapterView</a></li>

page.title=Notifying the User

@jd:body

<div id="qv-wrapper">

  <div id="qv">

    <h2>In this document</h2>

    <ol>

      <li><a href="#Toast">Toast Notification</a></li>

      <li><a href="#StatusBarNotification">Status Bar Notification</a></li>

      <li><a href="#Dialog">Dialog Notification</a></li>

    </ol>

    <h2>More about</h2>

    <ol>

      <li><a href="toasts.html">Creating Toast Notifications</a></li>

      <li><a href="notifications.html">Creating Status Bar Notifications</a></li>

      <li><a href="{@docRoot}guide/topics/ui/dialogs.html">Creating Dialogs</a></li>

    </ol>

  </div>

</div>

<p>Several types of situations may arise that require you to notify the user 

about an event that occurs in your application. Some events require the user to respond

and others do not. For example:</p>

<ul>

  <li>When an event such as saving a file is complete, a small message

should appear to confirm that the save was successful.</li>

  <li>If the application is running in the background and needs the user's attention, 

the application should create a notificaiton that allows the user to respond at 

his or her convenience.</li>

  <li>If the application is 

performing work that the user must wait for (such as loading a file), 

the application should show a hovering progress wheel or bar.</li>

</ul>

<p>Each of these notification tasks can be achieved using a different technique:</p>

<ul>

  <li>A <a href="#Toast">Toast Notification</a>, for brief messages that come 

  from the background.</li>

  <li>A <a href="#StatusBar">Status Bar Notification</a>, for persistent reminders 

  that come from the background and request the user's response.</li>

  <li>A <a href="#Dialog">Dialog Notification</a>, for Activity-related notifications.</li>

</ul>

<p>This document summarizes each of these techniques for notifying the user and includes

links to full documentation.</p>

<h2 id="Toast">Toast Notification</h2>

<img src="{@docRoot}images/toast.png" alt="" style="float:right" />

<p>A toast notificaiton 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. Because a toast can be created from a background 

{@link android.app.Service}, it appears even if the application isn't visible.</p>

<p>A toast is best for short text messages, such as "File saved,"

when you're fairly certain the user is paying attention 

to the screen. A toast can not accept user interaction events; if you'd like

the user to respond and take action, consider using a 

<a href="#StatusBar">Status Bar Notification</a> instead.</p>

<p>For more information, refer to <a href="toasts.html">Creating Toast Notifications</a>.</p>

<h2 id="StatusBar">Status Bar Notification</h2>

<img src="{@docRoot}images/notifications_window.png" alt="" style="float:right; clear:right;" />

<p>A status bar notification adds an icon to the system's status bar 

(with an optional ticker-text message) and an expanded message in the "Notifications" window.

When the user selects the expanded message, Android fires an 

{@link android.content.Intent} that is defined by the notification (usually to launch an 

{@link android.app.Activity}).

You can also configure the notification to alert the user with a sound, a vibration, and flashing

lights on the device.</p>

<p>This kind of notification is ideal when your application is working in

a background {@link android.app.Service} and needs to 

notify the user about an event. If you need to alert the user about an event that occurs 

while your Activity is still in focus, consider using a 

<a href="#Dialog">Dialog Notification</a> instead.</p>

<p>For more information, refer to 

<a href="notifications.html">Creating Status Bar Notifications</a>.</p>

<h2 id="Dialog">Dialog Notification</h2>

<img src="{@docRoot}images/dialog_progress_spinning.png" alt="" style="float:right" />

<p>A dialog is usually a small window that appears in front of the current Activity.

The underlying Activity loses focus and the dialog accepts all user interaction. 

Dialogs are normally used

for notifications and short activities that directly relate to the application in progress.</p>

<p>You should use a dialog when you need to show a progress bar or a short

message that requires confirmation from the user (such as an alert with "OK" and "Cancel" buttons). 

You can use also use dialogs as integral componenents

in your application's UI and for other purposes besides notifications.

For a complete discussion on all the available types of dialogs, 

including its uses for notifications, refer to 

<a href="{@docRoot}guide/topics/ui/dialogs.html">Creating Dialogs</a>.</p>

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 notificaiton 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>