diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java
index 51fddb1145cbb..9834c75c58d4b 100644
--- a/core/java/android/app/Notification.java
+++ b/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}.
*
+ * For a guide to creating notifications, see the
+ * Creating Status
+ * Bar Notifications document in the Dev Guide.
*/
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
- * #FLAG_INSISTENT} bit is set in the {@link #flags} field.
+ * The pattern with which to vibrate.
*
*
* 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
- * cancelled.
- *
- *
- * NOTE: This notion will change when we have decided exactly
- * what the UI will be.
- *
+ * 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 39f4abffba63e..5367cb2e7ec55 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -19,9 +19,9 @@
- Declaring Layout
- Creating Menus
-
+ - Creating Dialogs
- Handling UI Events
-
+ - Notifying the User
- Applying Styles and Themes
- Building Custom Components
- Binding to Data with AdapterView
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 0000000000000..5b37f5b623aa5
--- /dev/null
+++ b/docs/html/guide/topics/ui/notifiers/index.jd
@@ -0,0 +1,107 @@
+page.title=Notifying the User
+@jd:body
+
+
+
+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:
+
+ - When an event such as saving a file is complete, a small message
+should appear to confirm that the save was successful.
+ - 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.
+ - 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.
+
+
+Each of these notification tasks can be achieved using a different technique:
+
+
+This document summarizes each of these techniques for notifying the user and includes
+links to full documentation.
+
+
+Toast Notification
+
+
+
+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.
+
+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
+Status Bar Notification instead.
+
+For more information, refer to Creating Toast Notifications.
+
+
+Status Bar Notification
+
+
+
+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.
+
+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
+Dialog Notification instead.
+
+For more information, refer to
+Creating Status Bar Notifications.
+
+
+Dialog Notification
+
+
+
+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.
+
+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
+Creating Dialogs.
+
+
+
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 0000000000000..e6fa48fe2385a
--- /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
+
+
+
+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.
+
+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
+should never 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.
+
+The screenshot below shows the status bar with a notification icon on the left side.
+
+
+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 Notifications from the Home options menu).
+
+
+
+The Basics
+
+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}.
+
+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()}.
+
+To create a status bar notification:
+
+ - Get a reference to the NotificationManager:
+
+String ns = Context.NOTIFICATION_SERVICE;
+NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns);
+
+
+ - Instantiate the Notification:
+
+int icon = R.drawable.notification_icon;
+CharSequence tickerText = "Hello";
+long when = System.currentTimeMillis();
+
+Notification notification = new Notification(icon, tickerText, when);
+
+
+ - Define the Notification's expanded message and Intent:
+
+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);
+
+
+ - Pass the Notification to the NotificationManager:
+
+private static final int HELLO_ID = 1;
+
+mNotificationManager.notify(HELLO_ID, notification);
+
+ That's it. Your user has now been notified.
+
+
+
+
+Managing your Notifications
+
+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:
+
+String ns = Context.NOTIFICATION_SERVICE;
+NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns);
+
+
+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.
+
+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()}.
+
+
+Creating a Notification
+
+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.
+
+A status bar notification requires all of the following:
+
+ - An icon for the status bar
+ - A title and expanded message for the expanded view (unless you define a
+ custom expanded view)
+ - A {@link android.app.PendingIntent}, to be fired when the notification is selected
+
+Optional settings for the status bar notification include:
+
+ - A ticker-text message for the status bar
+ - An alert sound
+ - A vibrate setting
+ - A flashing LED setting
+
+
+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:
+
+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);
+
+
+
+Updating the notification
+
+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.
+
+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.
+
+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 contentTitle and contentText.
+Then call {@link android.app.NotificationManager#notify(int,Notification) notify()} to update the
+notification. (Of course, if you've created a custom expanded
+view, then updating these title and text values has no effect.)
+
+
+Adding a sound
+
+You can alert the user with the default notification sound
+(which is defined by the user) or with a sound specified by your application.
+
+To use the user's default sound, add "DEFAULT_SOUND" to the defaults field:
+
+notification.defaults |= Notification.DEFAULT_SOUND;
+
+
+To use a different sound with your notifications, pass a Uri reference to the
+sound field.
+The following example uses a known audio file saved to the device SD card:
+
+notification.sound = Uri.parse("file:///sdcard/notification/ringer.mp3");
+
+
+In the next example, the audio file is chosen from the internal
+{@link android.provider.MediaStore.Audio.Media MediaStore}'s {@link android.content.ContentProvider}:
+
+notification.sound = Uri.withAppendedPath(Audio.Media.INTERNAL_CONTENT_URI, "6");
+
+
+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 Content Providers
+documentation for more information on using a ContentResolver.
+
+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 flags field.
+
+Note: If the defaults field includes
+"DEFAULT_SOUND", then the default sound overrides any sound defined by the sound field.
+
+
+Adding vibration
+
+You can alert the user with the the default
+vibration pattern or with a vibration pattern defined by your application.
+
+To use the default pattern, add "DEFAULT_VIBRATE" to the defaults field:
+
+notification.defaults |= Notification.DEFAULT_VIBRATE;
+
+
+To define your own vibration pattern, pass an array of long values to the
+vibrate field:
+
+long[] vibrate = {0,100,200,300};
+notification.vibrate = vibrate;
+
+
+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.
+
+
+Note: If the defaults field includes
+"DEFAULT_VIBRATE", then the default vibration overrides any vibration defined by the
+vibrate field.
+
+
+Adding flashing lights
+
+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.
+
+To use the default light setting, add "DEFAULT_LIGHTS" to the defaults field:
+
+notification.defaults |= Notification.DEFAULT_LIGHTS;
+
+
+To define your own color and pattern, define a value for the ledARGB field
+(for the color), the ledOffMS field (length of time, in milliseconds, to
+keep the light off), the ledOnMS (length of time, in milliseconds, to keep the light on),
+and also add "FLAG_SHOW_LIGHTS" to the flags field:
+
+notification.ledARGB = 0xff00ff00;
+notification.ledOnMS = 300;
+notification.ledOffMS = 1000;
+notification.flags |= Notification.FLAG_SHOW_LIGHTS;
+
+
+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.
+
+
+More features
+
+You can add several more features to your notifications
+using Notification fields and flags. Some useful features include the following:
+
+
+ - "FLAG_AUTO_CANCEL" flag
+ - Add this to the flags field to automatically cancel the notification
+ after it is selected from the Notifications window.
+ - "FLAG_INSISTENT" flag
+ - Add this to the flags field to repeat the audio until the
+ user responds.
+ - "FLAG_ONGOING_EVENT" flag
+ - Add this to the flags 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).
+ - "FLAG_NO_CLEAR" flag
+ - Add this to the flags field to indicate that the notification should
+ not be cleared by the "Clear notifications" button. This is particularly useful if
+ your notification is on-going.
+ - number field
+ - 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.)
+ - iconLevel field
+ - 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.
+
+
+See the {@link android.app.Notification} class reference for more information about additional
+features that you can customize for your application.
+
+
+Creating a Custom Expanded View
+
+
+
+By default, the expanded view used in the "Notifications" window includes a basic title and text
+message. These are defined by the contentTitle and contentText
+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.
+
+To define your own layout for the expanded message,
+instantiate a {@link android.widget.RemoteViews} object and
+pass it to the contentView field of your Notification. Pass the
+{@link android.app.PendingIntent} to the contentIntent field.
+
+Creating a custom expanded view is best understood with an example:
+
+
+ - Create the XML layout for the expanded view.
+ For example, create a layout file called
custom_notification_layout.xml and
+ build it like so:
+
+<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>
+
+
+ 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...
+
+
+ - In the application code, use the RemoveViews
+ methods to define the image and text. Then pass the RemoteViews object to the contentView
+ field of the Notification, as shown in this example:
+
+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;
+
+
+ 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
+ contentView field.
+
+
+ - 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 contentIntent field, as in this example:
+
+Intent notificationIntent = new Intent(this, MyClass.class);
+PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
+notification.contentIntent = contentIntent;
+
+
+
+ - The notification can now be sent as usual:
+
mNotificationManager.notify(CUSTOM_VIEW_ID, notification);
+
+
+
+
+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.
+
+Note:
+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.
+
+
+
+
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 0000000000000..a800c3c900dfd
--- /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
+
+
+
+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.
+
+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.
+
+
+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.
+
+If user response to the notification is required, consider using a
+Status Bar Notification.
+
+
+The Basics
+
+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:
+
+
+Context context = getApplicationContext();
+CharSequence text = "Hello toast!";
+int duration = Toast.LENGTH_SHORT;
+
+Toast toast = Toast.makeText(context, text, duration);
+toast.show();
+
+
+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.
+
+You can also chain your methods and avoid holding on to the Toast object, like this:
+Toast.makeText(context, text, duration).show();
+
+
+Positioning your Toast
+
+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.
+
+For example, if you decide that the toast should appear in the top-left corner, you can set the
+gravity like this:
+
+toast.setGravity(Gravity.TOP|Gravity.LEFT, 0, 0);
+
+
+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.
+
+
+
Creating a Custom Toast View
+
+
+
+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.
+
+For example, you can create the layout for the toast visible in the screenshot to the right
+with the following XML (saved as toast_layout.xml):
+
+<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>
+
+
+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:
+
+
+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();
+
+
+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()}.
+
+Note: 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.
+
diff --git a/docs/html/images/custom_message.png b/docs/html/images/custom_message.png
new file mode 100755
index 0000000000000..ea7c7160e020c
Binary files /dev/null and b/docs/html/images/custom_message.png differ
diff --git a/docs/html/images/custom_toast.png b/docs/html/images/custom_toast.png
new file mode 100755
index 0000000000000..230625a850053
Binary files /dev/null and b/docs/html/images/custom_toast.png differ
diff --git a/docs/html/images/notifications_window.png b/docs/html/images/notifications_window.png
new file mode 100755
index 0000000000000..78e0c8a52f238
Binary files /dev/null and b/docs/html/images/notifications_window.png differ
diff --git a/docs/html/images/status_bar.png b/docs/html/images/status_bar.png
new file mode 100755
index 0000000000000..420bb03be861f
Binary files /dev/null and b/docs/html/images/status_bar.png differ
diff --git a/docs/html/images/toast.png b/docs/html/images/toast.png
new file mode 100644
index 0000000000000..223048a396143
Binary files /dev/null and b/docs/html/images/toast.png differ