AI 147803: add docs and images for docs on Toast and Notification docs

also edit the Notification class doc
  BUG=1800118

Automated import of CL 147803

core/java/android/app/Notification.java

@@ -34,6 +34,9 @@ import android.widget.RemoteViews;
  * 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
 {
@@ -52,7 +55,8 @@ 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
      */ 
@@ -149,8 +153,7 @@ public class Notification implements Parcelable
 
     
     /**
-     * The pattern with which to vibrate. This pattern will repeat if {@link
+     * The pattern with which to vibrate. 
-     * #FLAG_INSISTENT} bit is set in the {@link #flags} field.
      * 
      * <p>
      * To vibrate the default pattern, see {@link #defaults}.
@@ -228,13 +231,8 @@ public class Notification implements Parcelable
 
     /**
      * Bit to be bitwise-ored into the {@link #flags} field that if set,
-     * the audio and vibration will be repeated until the notification is
+     * the audio will be repeated until the notification is
-     * cancelled.
+     * cancelled or the notification window is opened.
-     *
-     * <p>
-     * NOTE: This notion will change when we have decided exactly
-     * what the UI will be.
-     * </p>
      */
     public static final int FLAG_INSISTENT          = 0x00000004;
 

docs/html/guide/guide_toc.cs

@@ -19,9 +19,9 @@
           <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>

docs/html/guide/topics/ui/notifiers/index.jd

@@ -0,0 +1,107 @@
+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>
+
+
+

docs/html/guide/topics/ui/notifiers/notifications.jd

@@ -0,0 +1,432 @@
+page.title=Creating Status Bar 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.app.Notification}</li>
+      <li>{@link android.app.NotificationManager}</li>
+    </ol>
+    <h2>In this document</h2>
+    <ol>
+      <li><a href="#Basics">The Basics</a></li>
+      <li><a href="#ManageYourNotifications">Managing your Notifications</a></li>
+      <li><a href="#CreateANotification">Creating a Notification</a>
+        <ol>
+          <li><a href="#Update">Updating the notification</a></li>
+          <li><a href="#Sound">Adding a sound</a></li>
+          <li><a href="#Vibration">Adding vibration</a></li>
+          <li><a href="#Lights">Adding flashing lights</a></li>
+          <li><a href="#More">More features</a></li>
+        </ol>
+      </li>
+      <li><a href="#CustomExpandedView">Creating a Custom Expanded View</a></li>
+    </ol>
+  </div>
+</div>
+
+<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>A status bar notification should be used for any case in
+which a background Service needs to alert the user about an event that requires a response. A background Service 
+<strong>should never</strong> launch an Activity on its own in order to receive user interaction.
+The Service should instead create a status bar notification that will launch the Activity
+when selected by the user.</p>
+
+<p>The screenshot below shows the status bar with a notification icon on the left side.</p>
+<img src="{@docRoot}images/status_bar.png" alt="" />
+
+<p>The next screenshot shows the notification's expanded message in the "Notifications" window.
+The user can reveal the Notifications window by pulling down the status bar
+(or selecting <em>Notifications</em> from the Home options menu).</p>
+<img src="{@docRoot}images/notifications_window.png" alt="" />
+
+
+<h2 id="Basics">The Basics</h2>
+
+<p>An {@link android.app.Activity} or {@link android.app.Service} can initiate a status bar 
+notification. Because an Activity can perform actions only while it is
+active and in focus, you should create your status bar notifications from a 
+Service. This way, the notification can be created from the background, 
+while the user is using another application or
+while the device is asleep. To create a notification, you must use two
+classes: {@link android.app.Notification} and {@link android.app.NotificationManager}.</p>
+
+<p>Use an instance of the {@link android.app.Notification} class to define the properties of your 
+status bar notification, such as the status bar icon, the expanded message, and extra settings such 
+as a sound to play. The {@link android.app.NotificationManager} is an Android system service that 
+executes and manages all Notifications. You do not instantiate the NotificationManager. In order
+to give it your Notification, you must retrieve a reference to the NotificationManager with
+{@link android.app.Activity#getSystemService(String) getSystemService()} and 
+then, when you want to notify the user, pass it your Notification object with 
+{@link android.app.NotificationManager#notify(int,Notification) notify()}. </p>
+
+<p>To create a status bar notification:</p>
+<ol>
+  <li>Get a reference to the NotificationManager:
+<pre>
+String ns = Context.NOTIFICATION_SERVICE;
+NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns);
+</pre>
+  </li>
+  <li>Instantiate the Notification:
+<pre>
+int icon = R.drawable.notification_icon;
+CharSequence tickerText = "Hello";
+long when = System.currentTimeMillis();
+
+Notification notification = new Notification(icon, tickerText, when);
+</pre>
+  </li>
+  <li>Define the Notification's expanded message and Intent:
+<pre>
+Context context = getApplicationContext();
+CharSequence contentTitle = "My notification";
+CharSequence contentText = "Hello World!";
+Intent notificationIntent = new Intent(this, MyClass.class);
+PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
+
+notification.setLatestEventInfo(context, contentTitle, contentText, contentIntent);
+</pre>
+  </li>
+  <li>Pass the Notification to the NotificationManager:
+<pre>
+private static final int HELLO_ID = 1;
+
+mNotificationManager.notify(HELLO_ID, notification);
+</pre>
+  <p>That's it. Your user has now been notified.</p>
+  </li>
+</ol>
+
+
+<h2 id="ManageYourNotifications">Managing your Notifications</h2>
+
+<p>The {@link android.app.NotificationManager} is a system service that manages all
+notifications. You must retrieve a reference to it with the
+{@link android.app.Activity#getSystemService(String) getSystemService()} method. 
+For example:</p>
+<pre>
+String ns = Context.NOTIFICATION_SERVICE;
+NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns);
+</pre>
+
+<p>When you want to send your status bar notification, pass the Notification object
+to the NotificationManager with {@link android.app.NotificationManager#notify(int,Notification)}. 
+The first parameter is the unique ID for the Notification and the second is the Notification object.
+The ID uniquely identifies the Notification from within your
+application. This is necessary if you need to update the Notification or (if
+your application manages different kinds of Notifications) select the appropriate action
+when the user returns to your application via the Intent defined in the Notification.</p>
+
+<p>To clear the status bar notification when the user selects it from the Notifications
+window, add the "FLAG_AUTO_CANCEL" flag to your Notification object. You can also clear it
+manually with {@link android.app.NotificationManager#cancel(int)}, passing it the notification ID,
+or clear all your Notifications with {@link android.app.NotificationManager#cancelAll()}.</p>
+
+
+<h2 id="CreateANotification">Creating a Notification</h2>
+
+<p>A {@link android.app.Notification} object defines the details of the notification
+message that is displayed in the status bar and "Notifications" window, and any other
+alert settings, such as sounds and blinking lights.</p>
+
+<p>A status bar notification <em>requires</em> all of the following:</p>
+<ul>
+  <li>An icon for the status bar</li>
+  <li>A title and expanded message for the expanded view (unless you define a 
+    <a href="#CustomExpandedView">custom expanded view</a>)</li>
+  <li>A {@link android.app.PendingIntent}, to be fired when the notification is selected</li>
+</ul>
+<p>Optional settings for the status bar notification include:</p>
+<ul>
+  <li>A ticker-text message for the status bar</li>
+  <li>An alert sound</li>
+  <li>A vibrate setting</li>
+  <li>A flashing LED setting</li>
+</ul>
+
+<p>The starter-kit for a new Notification includes the 
+{@link android.app.Notification#Notification(int,CharSequence,long)} constructor and the 
+{@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent)} 
+method. These define all the required settings for a Notification. 
+The following snippet demonstrates a basic Notification setup:</p>
+<pre>
+int icon = R.drawable.notification_icon;        // icon from resources
+CharSequence tickerText = "Hello";              // ticker-text
+long when = System.currentTimeMillis();         // notification time
+Context context = getApplicationContext();      // application Context
+CharSequence contentTitle = "My notification";  // expanded message title
+CharSequence contentText = "Hello World!";      // expanded message text
+
+Intent notificationIntent = new Intent(this, MyClass.class);
+PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
+
+// the next two lines initialize the Notification, using the configurations above
+Notification notification = new Notification(icon, tickerText, when);
+notification.setLatestEventInfo(context, contentTitle, contentText, contentIntent);
+</pre>
+
+
+<h3 id="Updating">Updating the notification</h3>
+
+<p>You can update the information in your status bar notification as events 
+continue to occur in your application. For example, when a new SMS text message arrives 
+before previous messages have been read, the Messaging application updates the existing 
+notification to display the total number of new messages received.
+This practice of updating an existing Notification is much better than adding new Notifications 
+to the NotificationManager because it avoids clutter in the Notifications window.</p>
+
+<p>Because each notification is uniquely identified
+by the NotificationManager with an integer ID, you can revise the notification by calling
+{@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent)
+setLatestEventInfo()} with new values, change some field values of the Notification, and then call
+{@link android.app.NotificationManager#notify(int,Notification) notify()} again.</p>
+
+<p>You can revise each property with the object member fields
+(except for the Context and the expanded message title and text). You should always 
+revise the text message when you update the notification by calling
+{@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent)
+setLatestEventInfo()} with new values for <var>contentTitle</var> and <var>contentText</var>. 
+Then call {@link android.app.NotificationManager#notify(int,Notification) notify()} to update the 
+notification. (Of course, if you've created a <a href="#CustomExpandedView">custom expanded 
+view</a>, then updating these title and text values has no effect.)</p>
+
+
+<h3 id="Sound">Adding a sound</h3>
+
+<p>You can alert the user with the default notification sound 
+(which is defined by the user) or with a sound specified by your application.</p>
+
+<p>To use the user's default sound, add "DEFAULT_SOUND" to the <var>defaults</var> field:</p>
+<pre>
+notification.defaults |= Notification.DEFAULT_SOUND;
+</pre>
+
+<p>To use a different sound with your notifications, pass a Uri reference to the
+<var>sound</var> field.
+The following example uses a known audio file saved to the device SD card:</p>
+<pre>
+notification.sound = Uri.parse("file:///sdcard/notification/ringer.mp3");
+</pre>
+
+<p>In the next example, the audio file is chosen from the internal 
+{@link android.provider.MediaStore.Audio.Media MediaStore}'s {@link android.content.ContentProvider}:</p>
+<pre>
+notification.sound = Uri.withAppendedPath(Audio.Media.INTERNAL_CONTENT_URI, "6");
+</pre>
+
+<p>In this case, the exact ID of the media file ("6") is known and appended to the content 
+{@link android.net.Uri}. If you don't know the exact ID, you must query all the
+media available in the MediaStore with a {@link android.content.ContentResolver}. 
+See the <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>
+documentation for more information on using a ContentResolver.</p>
+
+<p>If you want the sound to continuously repeat until the user responds to the notification
+or the notification is cancelled, add "FLAG_INSISTENT" to the <var>flags</var> field.</p>
+
+<p class="note"><strong>Note:</strong> If the <var>defaults</var> field includes 
+"DEFAULT_SOUND", then the default sound overrides any sound defined by the <var>sound</var> field.</p>
+
+
+<h3 id="Vibration">Adding vibration</h3>
+
+<p>You can alert the user with the the default 
+vibration pattern or with a vibration pattern defined by your application.</p>
+
+<p>To use the default pattern, add "DEFAULT_VIBRATE" to the <var>defaults</var> field:</p>
+<pre>
+notification.defaults |= Notification.DEFAULT_VIBRATE;
+</pre>
+
+<p>To define your own vibration pattern, pass an array of <em>long</em> values to the
+<var>vibrate</var> field:</p>
+<pre>
+long[] vibrate = {0,100,200,300};
+notification.vibrate = vibrate;
+</pre>
+
+<p>The long array defines the alternating pattern for the length of vibration off and on
+(in milliseconds). The first value is how long to wait (off) before beginning, the second 
+value is the length of the first vibration, the third is the next length off, and so on. 
+The pattern can be as long as you like, but it can't be set to repeat.
+</p>
+
+<p class="note"><strong>Note:</strong> If the <var>defaults</var> field includes 
+"DEFAULT_VIBRATE", then the default vibration overrides any vibration defined by the 
+<var>vibrate</var> field.</p>
+
+
+<h3 id="Lights">Adding flashing lights</h3>
+
+<p>To alert the user by flashing LED lights, you can implement the default 
+light pattern (if available), or define your own color and pattern for the lights.</p>
+
+<p>To use the default light setting, add "DEFAULT_LIGHTS" to the <var>defaults</var> field:</p>
+<pre>
+notification.defaults |= Notification.DEFAULT_LIGHTS;
+</pre>
+
+<p>To define your own color and pattern, define a value for the <var>ledARGB</var> field
+(for the color), the <var>ledOffMS</var> field (length of time, in milliseconds, to 
+keep the light off), the <var>ledOnMS</var> (length of time, in milliseconds, to keep the light on), 
+and also add "FLAG_SHOW_LIGHTS" to the <var>flags</var> field:</p>
+<pre>
+notification.ledARGB = 0xff00ff00;
+notification.ledOnMS = 300;
+notification.ledOffMS = 1000;
+notification.flags |= Notification.FLAG_SHOW_LIGHTS;
+</pre>
+
+<p>In this example, the green light repeatedly flashes on for 300 milliseconds and 
+turns off for one second. Not every color in the spectrum is supported by the 
+device LEDs, and not every device supports the same colors, so the hardware 
+estimates to the best of its ability. Green is the most common notification color.</p>
+
+
+<h3 id="More">More features</h3>
+
+<p>You can add several more features to your notifications
+using Notification fields and flags. Some useful features include the following:</p>
+
+<dl>
+  <dt>"FLAG_AUTO_CANCEL" flag</dt>
+  <dd>Add this to the <var>flags</var> field to automatically cancel the notification
+  after it is selected from the Notifications window.</dd>
+  <dt>"FLAG_INSISTENT" flag</dt>
+  <dd>Add this to the <var>flags</var> field to repeat the audio until the
+  user responds.</dd>
+  <dt>"FLAG_ONGOING_EVENT" flag</dt>
+  <dd>Add this to the <var>flags</var> field to group the notification under the "Ongoing"
+  title in the Notifications window. This indicates that the application is on-going &mdash;
+  its processes is still running in the background, even when the application is not 
+  visible (such as with music or a phone call).</dd>
+  <dt>"FLAG_NO_CLEAR" flag</dt>
+  <dd>Add this to the <var>flags</var> field to indicate that the notification should 
+  <em>not</em> be cleared by the "Clear notifications" button. This is particularly useful if 
+  your notification is on-going.</dd>
+  <dt><var>number</var> field</dt>
+  <dd>This value indicates the current number of events represented by the notification.
+  The appropriate number is overlayed on top of the status bar icon.
+  If you intend to use this field, then you must start with "1" when the Notification is first
+  created. (If you change the value from zero to anything greater during an update, the number
+  is not shown.)</dd>
+  <dt><var>iconLevel</var> field</dt>
+  <dd>This value indicates the current level of a 
+  {@link android.graphics.drawable.LevelListDrawable} that is used for the notification icon.
+  You can animate the icon in the status bar by changing this value to correlate with the 
+  drawable's defined in a LevelListDrawable. See the {@link android.graphics.drawable.LevelListDrawable}
+  reference for more information.</dd>
+</dl>
+
+<p>See the {@link android.app.Notification} class reference for more information about additional 
+features that you can customize for your application.</p>
+
+
+<h2 id="CustomExpandedView">Creating a Custom Expanded View</h2>
+
+<img src="{@docRoot}images/custom_message.png" alt="" style="float:right;" />
+
+<p>By default, the expanded view used in the "Notifications" window includes a basic title and text 
+message. These are defined by the <var>contentTitle</var> and <var>contentText</var>
+parameters of the {@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent)
+setLatestEventInfo()} method. However, you can also define a custom layout for the expanded view using 
+{@link android.widget.RemoteViews}. The screenshot to the right shows an example of a
+custom expanded view that uses an ImageView and TextView in a LinearLayout.</p>
+
+<p>To define your own layout for the expanded message,
+instantiate a {@link android.widget.RemoteViews} object and
+pass it to the <var>contentView</var> field of your Notification. Pass the
+{@link android.app.PendingIntent} to the <var>contentIntent</var> field.</p>
+
+<p>Creating a custom expanded view is best understood with an example:</p>
+
+<ol>
+  <li>Create the XML layout for the expanded view.
+    For example, create a layout file called <code>custom_notification_layout.xml</code> and 
+    build it like so:
+<pre>
+&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+              android:orientation="horizontal"
+              android:layout_width="fill_parent"
+              android:layout_height="fill_parent"
+              android:padding="3dp"
+              >
+    &lt;ImageView android:id="@+id/image"
+              android:layout_width="wrap_content"
+              android:layout_height="fill_parent"
+              android:layout_marginRight="10dp"
+              />
+    &lt;TextView android:id="@+id/text"
+              android:layout_width="wrap_content"
+              android:layout_height="fill_parent"
+              android:textColor="#000"
+              />
+&lt;/LinearLayout>
+</pre>
+
+    <p>This layout is used for the expanded view,
+    but the content of the ImageView and TextView still needs to be defined by the applicaiton.
+    RemoteViews offers some convenient methods that allow you to define this content...</p>
+  </li>
+
+  <li>In the application code, use the RemoveViews 
+    methods to define the image and text. Then pass the RemoteViews object to the <var>contentView</var>
+    field of the Notification, as shown in this example:
+<pre>
+RemoteViews contentView = new RemoteViews(getPackageName(), R.layout.custom_notification_layout);
+contentView.setImageViewResource(R.id.image, R.drawable.notification_image);
+contentView.setTextViewText(R.id.text, "Hello, this message is in a custom expanded view");
+notification.contentView = contentView;
+</pre>
+
+    <p>As shown here, pass the applicaiton's package name and the layout 
+    resource ID to the RemoteViews constructor. Then, define the content for the ImageView and TextView,
+    using the {@link android.widget.RemoteViews#setImageViewResource(int, int) setImageViewResource()}
+    and {@link android.widget.RemoteViews#setTextViewText(int, CharSequence) setTextViewText()}.
+    In each case, pass the reference ID of the appropriate View object that you want to set, along with
+    the value for that View. Finally, the RemoteViews object is passed to the Notification in the 
+    <var>contentView</var> field.</p>
+  </li>
+
+  <li>Because you don't need the
+    {@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent)
+    setLatestEventInfo()} method when using a custom view, you must define the Intent for the Notification
+    with the <var>contentIntent</var> field, as in this example:
+<pre>
+Intent notificationIntent = new Intent(this, MyClass.class);
+PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
+notification.contentIntent = contentIntent;
+</pre>
+  </li>
+  
+  <li>The notification can now be sent as usual:
+    <pre>mNotificationManager.notify(CUSTOM_VIEW_ID, notification);</pre>
+  </li>
+</ol>
+
+
+<p>The RemoteViews class also includes methods that you can use to easily add a 
+{@link android.widget.Chronometer} or {@link android.widget.ProgressBar} 
+in your notification's expanded view. For more information about creating custom layouts with 
+RemoteViews, refer to the {@link android.widget.RemoteViews} class reference.</p>
+
+<p class="warning"><strong>Note:</strong>
+When creating a custom expanded view, you must take special care to ensure that your 
+custom layout functions properly in different device orientations and resolutions. While this 
+advice applies to all View layouts created on Android, it is especially important in this case
+because your layout real estate is very restricted. So don't make your custom layout too 
+complex and be sure to test it in various configurations.</p>
+
+
+
+

docs/html/guide/topics/ui/notifiers/toasts.jd

@@ -0,0 +1,154 @@
+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>
+&lt;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"
+              >
+    &lt;ImageView android:id="@+id/image"
+               android:layout_width="wrap_content"
+               android:layout_height="fill_parent"
+               android:layout_marginRight="10dp"
+               />
+    &lt;TextView android:id="@+id/text"
+              android:layout_width="wrap_content"
+              android:layout_height="fill_parent"
+              android:textColor="#FFF"
+              />
+&lt;/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>
+