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