blob: d24a4960a98722039b2f91925ca46dc926d767e9 [file] [log] [blame]
page.title=Building a Notification
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<li><a href="#builder">Create a Notification Builder</a></li>
<li><a href="#action">Define the Notification's Action</a></li>
<li><a href="#click">Set the Notification's Click Behavior</a></li>
<li><a href="#notify">Issue the Notification</a></li>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
<a href="{@docRoot}guide/components/intents-filters.html">
Intents and Intent Filters
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
<p>This lesson explains how to create and issue a notification.</p>
<p>The examples in this class are based on the
{@link} class.
is in the <a href="{@docRoot}">Support Library</a>. You should use
{@link} and its subclasses,
particularly {@link}, to
provide the best notification support for a wide range of platforms. </p>
<h2 id="builder">Create a Notification Builder</h2>
<p>When creating a notification, specify the UI content and actions with a
{@link} object. At bare minimum,
a {@link Builder}
object must include the following:</p>
A small icon, set by
{@link setSmallIcon()}
A title, set by
{@link setContentTitle()}
Detail text, set by
{@link setContentText()}
<p> For example: </p>
NotificationCompat.Builder mBuilder =
new NotificationCompat.Builder(this)
.setContentTitle(&quot;My notification&quot;)
.setContentText(&quot;Hello World!&quot;);
<h2 id="action">Define the Notification's Action</h2>
<p>Although actions are optional, you should add at least one action to your
notification. An action takes users directly from the notification to an
{@link} in your application, where they can look at the
event that caused the notification or do further work. Inside a notification, the action itself is
defined by a {@link} containing an {@link
android.content.Intent} that starts an {@link} in your
<p>How you construct the {@link} depends on what type
of {@link} you're starting. When you start an {@link} from a notification, you must preserve the user's expected
navigation experience. In the snippet below, clicking the notification opens a
new activity that effectively extends the behavior of the notification. In this
case there is no need to create an artificial back stack (see
<a href="navigation.html">Preserving Navigation when Starting an Activity</a> for
more information):</p>
<pre>Intent resultIntent = new Intent(this, ResultActivity.class);
// Because clicking the notification opens a new ("special") activity, there's
// no need to create an artificial back stack.
PendingIntent resultPendingIntent =
<h2 id="click">Set the Notification's Click Behavior</h2>
To associate the {@link} created in the previous
step with a gesture, call the appropriate method of {@link}. For example, to start an
activity when the user clicks the notification text in the notification drawer,
add the {@link} by calling {@link
setContentIntent()}. For example:</p>
<pre>PendingIntent resultPendingIntent;
<h2 id="notify">Issue the Notification</h2>
<p>To issue the notification:</p>
<li>Get an instance of {@link}.</li>
<li>Use the {@link notify()} method to issue the
notification. When you call {@link notify()}, specify a notification ID.
You can use this ID to update the notification later on. This is described in more detail in
<a href="managing.html">Managing Notifications</a>.</li>
<li>Call {@link build()}, which
returns a {@link} object containing your
<p>For example:</p>
NotificationCompat.Builder mBuilder;
// Sets an ID for the notification
int mNotificationId = 001;
// Gets an instance of the NotificationManager service
NotificationManager mNotifyMgr =
(NotificationManager) getSystemService(NOTIFICATION_SERVICE);
// Builds the notification and issues it.