Home | History | Annotate | Download | only in notify-user
      1 page.title=Displaying Progress in a Notification
      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="#FixedProgress">Display a Fixed-duration progress Indicator</a></li>
     16   <li><a href="#ActivityIndicator">Display a Continuing Activity Indicator</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 
     40 
     41 
     42 <p>
     43     Notifications can include an animated progress indicator that shows users the status
     44     of an ongoing operation. If you can estimate how long the operation takes and how much of it
     45     is complete at any time, use the "determinate" form of the indicator
     46     (a progress bar). If you can't estimate the length of the operation, use the
     47     "indeterminate" form of the indicator (an activity indicator).
     48 </p>
     49 <p>
     50     Progress indicators are displayed with the platform's implementation of the
     51     {@link android.widget.ProgressBar} class.
     52 </p>
     53 <p>
     54     To use a progress indicator, call
     55     {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}. The
     56     determinate and indeterminate forms are described in the following sections.
     57 </p>
     58 <!-- ------------------------------------------------------------------------------------------ -->
     59 <h2 id="FixedProgress">Display a Fixed-duration Progress Indicator</h2>
     60 <p>
     61     To display a determinate progress bar, add the bar to your notification by calling
     62     {@link android.support.v4.app.NotificationCompat.Builder#setProgress
     63     setProgress(max, progress, false)} and then issue the notification.
     64     The third argument is a boolean that indicates whether the
     65     progress bar is indeterminate (<strong>true</strong>) or determinate (<strong>false</strong>).
     66     As your operation proceeds,
     67     increment <code>progress</code>, and update the notification. At the end of the operation,
     68     <code>progress</code> should equal <code>max</code>. A common way to call
     69     {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}
     70     is to set <code>max</code> to 100 and then increment <code>progress</code> as a
     71     "percent complete" value for the operation.
     72 </p>
     73 <p>
     74     You can either leave the progress bar showing when the operation is done, or remove it. In
     75     either case, remember to update the notification text to show that the operation is complete.
     76     To remove the progress bar, call
     77     {@link android.support.v4.app.NotificationCompat.Builder#setProgress
     78     setProgress(0, 0, false)}. For example:
     79 </p>
     80 <pre>
     81 int id = 1;
     82 ...
     83 mNotifyManager =
     84         (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
     85 mBuilder = new NotificationCompat.Builder(this);
     86 mBuilder.setContentTitle("Picture Download")
     87     .setContentText("Download in progress")
     88     .setSmallIcon(R.drawable.ic_notification);
     89 // Start a lengthy operation in a background thread
     90 new Thread(
     91     new Runnable() {
     92         &#64;Override
     93         public void run() {
     94             int incr;
     95             // Do the "lengthy" operation 20 times
     96             for (incr = 0; incr &lt;= 100; incr+=5) {
     97                     // Sets the progress indicator to a max value, the
     98                     // current completion percentage, and "determinate"
     99                     // state
    100                     mBuilder.setProgress(100, incr, false);
    101                     // Displays the progress bar for the first time.
    102                     mNotifyManager.notify(id, mBuilder.build());
    103                         // Sleeps the thread, simulating an operation
    104                         // that takes time
    105                         try {
    106                             // Sleep for 5 seconds
    107                             Thread.sleep(5*1000);
    108                         } catch (InterruptedException e) {
    109                             Log.d(TAG, "sleep failure");
    110                         }
    111             }
    112             // When the loop is finished, updates the notification
    113             mBuilder.setContentText("Download complete")
    114             // Removes the progress bar
    115                     .setProgress(0,0,false);
    116             mNotifyManager.notify(id, mBuilder.build());
    117         }
    118     }
    119 // Starts the thread by calling the run() method in its Runnable
    120 ).start();
    121 </pre>
    122 <p>
    123     The resulting notifications are shown in figure 1. On the left side is a snapshot of the
    124     notification during the operation; on the right side is a snapshot of it after the operation
    125     has finished.
    126 </p>
    127 <img
    128     id="figure1"
    129     src="{@docRoot}images/ui/notifications/progress_bar_summary.png"
    130     height="84"
    131     alt="" />
    132 <p class="img-caption">
    133 <strong>Figure 1.</strong> The progress bar during and after the operation.</p>
    134 <!-- ------------------------------------------------------------------------------------------ -->
    135 <h2 id="ActivityIndicator">Display a Continuing Activity Indicator</h2>
    136 <p>
    137     To display a continuing (indeterminate) activity indicator, add it to your notification with
    138     {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress(0, 0, true)}
    139     and issue the notification. The first two arguments are ignored, and the third argument
    140     declares that the indicator is indeterminate. The result is an indicator
    141     that has the same style as a progress bar, except that its animation is ongoing.
    142 </p>
    143 <p>
    144     Issue the notification at the beginning of the operation. The animation will run until you
    145     modify your notification. When the operation is done, call
    146     {@link android.support.v4.app.NotificationCompat.Builder#setProgress
    147     setProgress(0, 0, false)} and then update the notification to remove the activity indicator.
    148     Always do this; otherwise, the animation will run even when the operation is complete. Also
    149     remember to change the notification text to indicate that the operation is complete.
    150 </p>
    151 <p>
    152     To see how continuing activity indicators work, refer to the preceding snippet. Locate the following lines:
    153 </p>
    154 <pre>
    155 // Sets the progress indicator to a max value, the current completion
    156 // percentage, and "determinate" state
    157 mBuilder.setProgress(100, incr, false);
    158 // Issues the notification
    159 mNotifyManager.notify(id, mBuilder.build());
    160 </pre>
    161 <p>
    162     Replace the lines you've found with the following lines. Notice that the third parameter
    163     in the {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}
    164     call is set to {@code true} to indicate that the progress bar is
    165     indeterminate:
    166 </p>
    167 <pre>
    168  // Sets an activity indicator for an operation of indeterminate length
    169 mBuilder.setProgress(0, 0, true);
    170 // Issues the notification
    171 mNotifyManager.notify(id, mBuilder.build());
    172 </pre>
    173 <p>
    174     The resulting indicator is shown in figure 2:
    175 </p>
    176 <img
    177     id="figure2"
    178     src="{@docRoot}images/ui/notifications/activity_indicator.png"
    179     height="99"
    180     alt="" />
    181 <p class="img-caption"><strong>Figure 2.</strong> An ongoing activity indicator.</p>
    182