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