Home | History | Annotate | Download | only in notify-user
      1 page.title=Updating Notifications
      2 page.tags=notifications
      3 helpoutsWidget=true
      4 
      5 trainingnavtop=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="https://material.google.com/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>
     62 mNotificationManager =
     63         (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
     64 // Sets an ID for the notification, so it can be updated
     65 int notifyID = 1;
     66 mNotifyBuilder = new NotificationCompat.Builder(this)
     67     .setContentTitle("New Message")
     68     .setContentText("You've received new messages.")
     69     .setSmallIcon(R.drawable.ic_notify_status)
     70 numMessages = 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