1page.title=Displaying Progress in a Notification
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="#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="{@docRoot}design/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>
81int id = 1;
82...
83mNotifyManager =
84        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
85mBuilder = new NotificationCompat.Builder(this);
86mBuilder.setContentTitle("Picture Download")
87    .setContentText("Download in progress")
88    .setSmallIcon(R.drawable.ic_notification);
89// Start a lengthy operation in a background thread
90new 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
157mBuilder.setProgress(100, incr, false);
158// Issues the notification
159mNotifyManager.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
169mBuilder.setProgress(0, 0, true);
170// Issues the notification
171mNotifyManager.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