1page.title=Updating Notifications
2page.tags=notifications
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9<div id="tb-wrapper">
10<div id="tb">
11
12<!-- table of contents -->
13<h2>This lesson teaches you to</h2>
14<ol>
15  <li><a href="#Updating">Modify a Notification</a></li>
16  <li><a href="#Removing">Remove Notifications</a></li>
17</ol>
18
19<!-- other docs (NOT javadocs) -->
20<h2>You should also read</h2>
21
22<ul>
23    <li>
24        <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
25    </li>
26    <li>
27        <a href="{@docRoot}guide/components/intents-filters.html">
28        Intents and Intent Filters
29        </a>
30    </li>
31    <li>
32        <a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
33    </li>
34</ul>
35
36
37</div>
38</div>
39<p>
40    When you need to issue a notification multiple times for the same type of event, you
41    should avoid making a completely new notification. Instead, you should consider updating a
42    previous notification, either by changing some of its values or by adding to it, or both.
43</p>
44
45<p>
46    The following section describes how to update notifications and also how to remove them.
47</p>
48<h2 id="Updating">Modify a Notification</h2>
49<p>
50    To set up a notification so it can be updated, issue it with a notification ID by
51    calling {@link android.app.NotificationManager#notify(int, Notification)
52    NotificationManager.notify(ID, notification)}. To update this notification once you've issued
53    it, update or create a {@link android.support.v4.app.NotificationCompat.Builder} object,
54    build a {@link android.app.Notification} object from it, and issue the
55    {@link android.app.Notification} with the same ID you used previously.
56</p>
57<p>
58    The following snippet demonstrates a notification that is updated to reflect the
59    number of events that have occurred. It stacks the notification, showing a summary:
60</p>
61<pre>
62mNotificationManager =
63        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
64// Sets an ID for the notification, so it can be updated
65int notifyID = 1;
66mNotifyBuilder = new NotificationCompat.Builder(this)
67    .setContentTitle("New Message")
68    .setContentText("You've received new messages.")
69    .setSmallIcon(R.drawable.ic_notify_status)
70numMessages = 0;
71// Start of a loop that processes data and then notifies the user
72...
73    mNotifyBuilder.setContentText(currentText)
74        .setNumber(++numMessages);
75    // Because the ID remains unchanged, the existing notification is
76    // updated.
77    mNotificationManager.notify(
78            notifyID,
79            mNotifyBuilder.build());
80...
81</pre>
82
83<!-- ------------------------------------------------------------------------------------------ -->
84<h2 id="Removing">Remove Notifications</h2>
85<p>
86    Notifications remain visible until one of the following happens:
87</p>
88<ul>
89    <li>
90        The user dismisses the notification either individually or by using "Clear All" (if
91        the notification can be cleared).
92    </li>
93    <li>
94        The user touches the notification, and you called
95        {@link android.support.v4.app.NotificationCompat.Builder#setAutoCancel setAutoCancel()} when
96        you created the notification.
97    </li>
98    <li>
99        You call {@link android.app.NotificationManager#cancel(int) cancel()} for a specific
100        notification ID. This method also deletes ongoing notifications.
101    </li>
102    <li>
103        You call {@link android.app.NotificationManager#cancelAll() cancelAll()}, which removes
104        all of the notifications you previously issued.
105    </li>
106