Skip to content

Commit a880436

Browse files
labtopiaAndroid Git Automerger
labtopia
authored and
Android Git Automerger
committed
am b7863a3: Merge "Doc update: new Notify User AU class" into jb-dev-docs
* commit 'b7863a3ce4db964322783ff7e84acc5713e04d1d': Doc update: new Notify User AU class
2 parents 2f9947e + b7863a3 commit a880436

File tree

10 files changed

+1006
-24
lines changed

10 files changed

+1006
-24
lines changed

‎docs/downloads/training/NotifyUser.zip‎

128 KB
Binary file not shown.

‎docs/html/images/training/notifications-bigview.png‎

19.7 KB
Loading

‎docs/html/images/training/notifications-normalview.png‎

5.74 KB
Loading

‎docs/html/training/notify-user/build-notification.jd‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
page.title=Building a Notification
2+
parent.title=Notifying the User
3+
parent.link=index.html
4+
5+
trainingnavtop=true
6+
next.title=Preserving Navigation when Starting an Activity
7+
next.link=navigation.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="#builder">Create a Notification Builder</a></li>
18+
<li><a href="#action">Define the Notification's Action</a></li>
19+
<li><a href="#click">Set the Notification's Click Behavior</a></li>
20+
<li><a href="#notify">Issue the Notification</a></li>
21+
</ol>
22+
23+
<!-- other docs (NOT javadocs) -->
24+
<h2>You should also read</h2>
25+
26+
<ul>
27+
<li>
28+
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
29+
</li>
30+
<li>
31+
<a href="{@docRoot}guide/components/intents-filters.html">
32+
Intents and Intent Filters
33+
</a>
34+
</li>
35+
<li>
36+
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
37+
</li>
38+
</ul>
39+
40+
41+
</div>
42+
</div>
43+
44+
45+
<p>This lesson explains how to create and issue a notification.</p>
46+
47+
<p>The examples in this class are based on the
48+
{@link android.support.v4.app.NotificationCompat.Builder} class.
49+
{@link android.support.v4.app.NotificationCompat.Builder}
50+
is in the <a href="{@docRoot}">Support Library</a>. You should use
51+
{@link android.support.v4.app.NotificationCompat} and its subclasses,
52+
particularly {@link android.support.v4.app.NotificationCompat.Builder}, to
53+
provide the best notification support for a wide range of platforms. </p>
54+
55+
<h2 id="builder">Create a Notification Builder</h2>
56+
57+
<p>When creating a notification, specify the UI content and actions with a
58+
{@link android.support.v4.app.NotificationCompat.Builder} object. At bare minimum,
59+
a {@link android.support.v4.app.NotificationCompat.Builder Builder}
60+
object must include the following:</p>
61+
62+
<ul>
63+
<li>
64+
A small icon, set by
65+
{@link android.support.v4.app.NotificationCompat.Builder#setSmallIcon setSmallIcon()}
66+
</li>
67+
<li>
68+
A title, set by
69+
{@link android.support.v4.app.NotificationCompat.Builder#setContentTitle setContentTitle()}
70+
</li>
71+
<li>
72+
Detail text, set by
73+
{@link android.support.v4.app.NotificationCompat.Builder#setContentText setContentText()}
74+
</li>
75+
</ul>
76+
<p> For example: </p>
77+
<pre>
78+
NotificationCompat.Builder mBuilder =
79+
new NotificationCompat.Builder(this)
80+
.setSmallIcon(R.drawable.notification_icon)
81+
.setContentTitle(&quot;My notification&quot;)
82+
.setContentText(&quot;Hello World!&quot;);
83+
</pre>
84+
85+
<h2 id="action">Define the Notification's Action</h2>
86+
87+
88+
<p>Although actions are optional, you should add at least one action to your
89+
notification. An action takes users directly from the notification to an
90+
{@link android.app.Activity} in your application, where they can look at the
91+
event that caused the notification or do further work. Inside a notification, the action itself is
92+
defined by a {@link android.app.PendingIntent} containing an {@link
93+
android.content.Intent} that starts an {@link android.app.Activity} in your
94+
application.</p>
95+
96+
<p>How you construct the {@link android.app.PendingIntent} depends on what type
97+
of {@link android.app.Activity} you're starting. When you start an {@link
98+
android.app.Activity} from a notification, you must preserve the user's expected
99+
navigation experience. In the snippet below, clicking the notification opens a
100+
new activity that effectively extends the behavior of the notification. In this
101+
case there is no need to create an artificial back stack (see
102+
<a href="navigation.html">Preserving Navigation when Starting an Activity</a> for
103+
more information):</p>
104+
105+
<pre>Intent resultIntent = new Intent(this, ResultActivity.class);
106+
...
107+
// Because clicking the notification opens a new ("special") activity, there's
108+
// no need to create an artificial back stack.
109+
PendingIntent resultPendingIntent =
110+
PendingIntent.getActivity(
111+
this,
112+
0,
113+
resultIntent,
114+
PendingIntent.FLAG_UPDATE_CURRENT
115+
);
116+
</pre>
117+
118+
<h2 id="click">Set the Notification's Click Behavior</h2>
119+
120+
<p>
121+
To associate the {@link android.app.PendingIntent} created in the previous
122+
step with a gesture, call the appropriate method of {@link
123+
android.support.v4.app.NotificationCompat.Builder}. For example, to start an
124+
activity when the user clicks the notification text in the notification drawer,
125+
add the {@link android.app.PendingIntent} by calling {@link
126+
android.support.v4.app.NotificationCompat.Builder#setContentIntent
127+
setContentIntent()}. For example:</p>
128+
129+
<pre>PendingIntent resultPendingIntent;
130+
...
131+
mBuilder.setContentIntent(resultPendingIntent);</pre>
132+
133+
<h2 id="notify">Issue the Notification</h2>
134+
135+
<p>To issue the notification:</p>
136+
<ul>
137+
<li>Get an instance of {@link android.app.NotificationManager}.</li>
138+
139+
<li>Use the {@link android.app.NotificationManager#notify notify()} method to issue the
140+
notification. When you call {@link android.app.NotificationManager#notify notify()}, specify a notification ID.
141+
You can use this ID to update the notification later on. This is described in more detail in
142+
<a href="managing.html">Managing Notifications</a>.</li>
143+
144+
<li>Call {@link
145+
android.support.v4.app.NotificationCompat.Builder#build() build()}, which
146+
returns a {@link android.app.Notification} object containing your
147+
specifications.</li>
148+
149+
<p>For example:</p>
150+
151+
<pre>
152+
// Sets an ID for the notification
153+
int mNotificationId = 001;
154+
// Gets an instance of the NotificationManager service
155+
NotificationManager mNotifyMgr =
156+
(NotificationManager) getSystemService(NOTIFICATION_SERVICE);
157+
// Builds the notification and issues it.
158+
mNotifyMgr.notify(mNotificationId, builder.build());
159+
</pre>
160+

‎docs/html/training/notify-user/display-progress.jd‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
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+
...
84+
mNotifyManager =
85+
(NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
86+
mBuilder = new NotificationCompat.Builder(this);
87+
mBuilder.setContentTitle("Picture Download")
88+
.setContentText("Download in progress")
89+
.setSmallIcon(R.drawable.ic_notification);
90+
// Start a lengthy operation in a background thread
91+
new Thread(
92+
new Runnable() {
93+
&#64;Override
94+
public void run() {
95+
int incr;
96+
// Do the "lengthy" operation 20 times
97+
for (incr = 0; incr &lt;= 100; incr+=5) {
98+
// Sets the progress indicator to a max value, the
99+
// current completion percentage, and "determinate"
100+
// state
101+
mBuilder.setProgress(100, incr, false);
102+
// Displays the progress bar for the first time.
103+
mNotifyManager.notify(0, mBuilder.build());
104+
// Sleeps the thread, simulating an operation
105+
// that takes time
106+
try {
107+
// Sleep for 5 seconds
108+
Thread.sleep(5*1000);
109+
} catch (InterruptedException e) {
110+
Log.d(TAG, "sleep failure");
111+
}
112+
}
113+
// When the loop is finished, updates the notification
114+
mBuilder.setContentText("Download complete")
115+
// Removes the progress bar
116+
.setProgress(0,0,false);
117+
mNotifyManager.notify(ID, mBuilder.build());
118+
}
119+
}
120+
// Starts the thread by calling the run() method in its Runnable
121+
).start();
122+
</pre>
123+
<p>
124+
The resulting notifications are shown in figure 1. On the left side is a snapshot of the
125+
notification during the operation; on the right side is a snapshot of it after the operation
126+
has finished.
127+
</p>
128+
<img
129+
id="figure1"
130+
src="{@docRoot}images/ui/notifications/progress_bar_summary.png"
131+
height="84"
132+
alt="" />
133+
<p class="img-caption">
134+
<strong>Figure 1.</strong> The progress bar during and after the operation.</p>
135+
<!-- ------------------------------------------------------------------------------------------ -->
136+
<h2 id="ActivityIndicator">Display a Continuing Activity Indicator</h2>
137+
<p>
138+
To display a continuing (indeterminate) activity indicator, add it to your notification with
139+
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress(0, 0, true)}
140+
and issue the notification. The first two arguments are ignored, and the third argument
141+
declares that the indicator is indeterminate. The result is an indicator
142+
that has the same style as a progress bar, except that its animation is ongoing.
143+
</p>
144+
<p>
145+
Issue the notification at the beginning of the operation. The animation will run until you
146+
modify your notification. When the operation is done, call
147+
{@link android.support.v4.app.NotificationCompat.Builder#setProgress
148+
setProgress(0, 0, false)} and then update the notification to remove the activity indicator.
149+
Always do this; otherwise, the animation will run even when the operation is complete. Also
150+
remember to change the notification text to indicate that the operation is complete.
151+
</p>
152+
<p>
153+
To see how continuing activity indicators work, refer to the preceding snippet. Locate the following lines:
154+
</p>
155+
<pre>
156+
// Sets the progress indicator to a max value, the current completion
157+
// percentage, and "determinate" state
158+
mBuilder.setProgress(100, incr, false);
159+
// Issues the notification
160+
mNotifyManager.notify(0, mBuilder.build());
161+
</pre>
162+
<p>
163+
Replace the lines you've found with the following lines. Notice that the third parameter
164+
in the {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}
165+
call is set to {@code true} to indicate that the progress bar is
166+
indeterminate:
167+
</p>
168+
<pre>
169+
// Sets an activity indicator for an operation of indeterminate length
170+
mBuilder.setProgress(0, 0, true);
171+
// Issues the notification
172+
mNotifyManager.notify(0, mBuilder.build());
173+
</pre>
174+
<p>
175+
The resulting indicator is shown in figure 2:
176+
</p>
177+
<img
178+
id="figure2"
179+
src="{@docRoot}images/ui/notifications/activity_indicator.png"
180+
height="99"
181+
alt="" />
182+
<p class="img-caption"><strong>Figure 2.</strong> An ongoing activity indicator.</p>

0 commit comments

Comments
 (0)