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
diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java
index 51fddb1..9834c75 100644
--- a/core/java/android/app/Notification.java
+++ b/core/java/android/app/Notification.java
@@ -34,6 +34,9 @@
* 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 @@
/**
* 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 @@
/**
- * 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}.
@@ -228,13 +231,8 @@
/**
* 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;
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 39f4abf..5367cb2 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/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>
diff --git a/docs/html/guide/topics/ui/notifiers/index.jd b/docs/html/guide/topics/ui/notifiers/index.jd
new file mode 100644
index 0000000..5b37f5b6
--- /dev/null
+++ b/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>
+
+
+
diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd
new file mode 100644
index 0000000..e6fa48fe
--- /dev/null
+++ b/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 —
+ 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>
+<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"
+ >
+ <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="#000"
+ />
+</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>
+
+
+
+
diff --git a/docs/html/guide/topics/ui/notifiers/toasts.jd b/docs/html/guide/topics/ui/notifiers/toasts.jd
new file mode 100644
index 0000000..a800c3c
--- /dev/null
+++ b/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>
+<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>
+
diff --git a/docs/html/images/custom_message.png b/docs/html/images/custom_message.png
new file mode 100755
index 0000000..ea7c716
--- /dev/null
+++ b/docs/html/images/custom_message.png
Binary files differ
diff --git a/docs/html/images/custom_toast.png b/docs/html/images/custom_toast.png
new file mode 100755
index 0000000..230625a
--- /dev/null
+++ b/docs/html/images/custom_toast.png
Binary files differ
diff --git a/docs/html/images/notifications_window.png b/docs/html/images/notifications_window.png
new file mode 100755
index 0000000..78e0c8a
--- /dev/null
+++ b/docs/html/images/notifications_window.png
Binary files differ
diff --git a/docs/html/images/status_bar.png b/docs/html/images/status_bar.png
new file mode 100755
index 0000000..420bb03
--- /dev/null
+++ b/docs/html/images/status_bar.png
Binary files differ
diff --git a/docs/html/images/toast.png b/docs/html/images/toast.png
new file mode 100644
index 0000000..223048a
--- /dev/null
+++ b/docs/html/images/toast.png
Binary files differ
