drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am d60ea46f: am a880436f: am b7863a3c: Merge "Doc update: new Notify User AU class" into jb-dev-docs

Browse Source 
* commit 'd60ea46fe7a9856ca592ff7dea79aa8ce80f5e66':
  Doc update: new Notify User AU class
This commit is contained in:
kmccormick@google.com
2012-11-27 16:56:03 -08:00
committed by Android Git Automerger
parent d29457e403 d60ea46fe7
commit 58d55b0456
10 changed files with 1006 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/downloads/training/NotifyUser.zip Normal file
View File

Binary file not shown.

BIN
docs/html/images/training/notifications-bigview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/html/images/training/notifications-normalview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.7 KiB

160
docs/html/training/notify-user/build-notification.jd Normal file
View File

@ -0,0 +1,160 @@
page.title=Building a Notification
parent.title=Notifying the User
parent.link=index.html
trainingnavtop=true
next.title=Preserving Navigation when Starting an Activity
next.link=navigation.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#builder">Create a Notification Builder</a></li>
<li><a href="#action">Define the Notification's Action</a></li>
<li><a href="#click">Set the Notification's Click Behavior</a></li>
<li><a href="#notify">Issue the Notification</a></li>
</ol>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<ul>
<li>
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
</li>
<li>
<a href="{@docRoot}guide/components/intents-filters.html">
Intents and Intent Filters
</a>
</li>
<li>
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
</li>
</ul>
</div>
</div>
<p>This lesson explains how to create and issue a notification.</p>
<p>The examples in this class are based on the
{@link android.support.v4.app.NotificationCompat.Builder} class.
{@link android.support.v4.app.NotificationCompat.Builder}
is in the <a href="{@docRoot}">Support Library</a>. You should use
{@link android.support.v4.app.NotificationCompat} and its subclasses,
particularly {@link android.support.v4.app.NotificationCompat.Builder}, to
provide the best notification support for a wide range of platforms. </p>
<h2 id="builder">Create a Notification Builder</h2>
<p>When creating a notification, specify the UI content and actions with a
{@link android.support.v4.app.NotificationCompat.Builder} object. At bare minimum,
a {@link android.support.v4.app.NotificationCompat.Builder Builder}
object must include the following:</p>
<ul>
<li>
A small icon, set by
{@link android.support.v4.app.NotificationCompat.Builder#setSmallIcon setSmallIcon()}
</li>
<li>
A title, set by
{@link android.support.v4.app.NotificationCompat.Builder#setContentTitle setContentTitle()}
</li>
<li>
Detail text, set by
{@link android.support.v4.app.NotificationCompat.Builder#setContentText setContentText()}
</li>
</ul>
<p> For example: </p>
<pre>
NotificationCompat.Builder mBuilder =
new NotificationCompat.Builder(this)
.setSmallIcon(R.drawable.notification_icon)
.setContentTitle(&quot;My notification&quot;)
.setContentText(&quot;Hello World!&quot;);
</pre>
<h2 id="action">Define the Notification's Action</h2>
<p>Although actions are optional, you should add at least one action to your
notification. An action takes users directly from the notification to an
{@link android.app.Activity} in your application, where they can look at the
event that caused the notification or do further work. Inside a notification, the action itself is
defined by a {@link android.app.PendingIntent} containing an {@link
android.content.Intent} that starts an {@link android.app.Activity} in your
application.</p>
<p>How you construct the {@link android.app.PendingIntent} depends on what type
of {@link android.app.Activity} you're starting. When you start an {@link
android.app.Activity} from a notification, you must preserve the user's expected
navigation experience. In the snippet below, clicking the notification opens a
new activity that effectively extends the behavior of the notification. In this
case there is no need to create an artificial back stack (see
<a href="navigation.html">Preserving Navigation when Starting an Activity</a> for
more information):</p>
<pre>Intent resultIntent = new Intent(this, ResultActivity.class);
...
// Because clicking the notification opens a new ("special") activity, there's
// no need to create an artificial back stack.
PendingIntent resultPendingIntent =
PendingIntent.getActivity(
this,
0,
resultIntent,
PendingIntent.FLAG_UPDATE_CURRENT
);
</pre>
<h2 id="click">Set the Notification's Click Behavior</h2>
<p>
To associate the {@link android.app.PendingIntent} created in the previous
step with a gesture, call the appropriate method of {@link
android.support.v4.app.NotificationCompat.Builder}. For example, to start an
activity when the user clicks the notification text in the notification drawer,
add the {@link android.app.PendingIntent} by calling {@link
android.support.v4.app.NotificationCompat.Builder#setContentIntent
setContentIntent()}. For example:</p>
<pre>PendingIntent resultPendingIntent;
...
mBuilder.setContentIntent(resultPendingIntent);</pre>
<h2 id="notify">Issue the Notification</h2>
<p>To issue the notification:</p>
<ul>
<li>Get an instance of {@link android.app.NotificationManager}.</li>
<li>Use the {@link android.app.NotificationManager#notify notify()} method to issue the
notification. When you call {@link android.app.NotificationManager#notify notify()}, specify a notification ID.
You can use this ID to update the notification later on. This is described in more detail in
<a href="managing.html">Managing Notifications</a>.</li>
<li>Call {@link
android.support.v4.app.NotificationCompat.Builder#build() build()}, which
returns a {@link android.app.Notification} object containing your
specifications.</li>
<p>For example:</p>
<pre>
// Sets an ID for the notification
int mNotificationId = 001;
// Gets an instance of the NotificationManager service
NotificationManager mNotifyMgr =
(NotificationManager) getSystemService(NOTIFICATION_SERVICE);
// Builds the notification and issues it.
mNotifyMgr.notify(mNotificationId, builder.build());
</pre>

182
docs/html/training/notify-user/display-progress.jd Normal file
View File

@ -0,0 +1,182 @@
page.title=Displaying Progress in a Notification
parent.title=Notifying the User
parent.link=index.html
trainingnavtop=true
previous.title=Using Expanded Notification Styles
previous.link=expanded.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#FixedProgress">Display a Fixed-duration progress Indicator</a></li>
<li><a href="#ActivityIndicator">Display a Continuing Activity Indicator</a></li>
</ol>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<ul>
<li>
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
</li>
<li>
<a href="{@docRoot}guide/components/intents-filters.html">
Intents and Intent Filters
</a>
</li>
<li>
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
</li>
</ul>
</div>
</div>
<p>
Notifications can include an animated progress indicator that shows users the status
of an ongoing operation. If you can estimate how long the operation takes and how much of it
is complete at any time, use the "determinate" form of the indicator
(a progress bar). If you can't estimate the length of the operation, use the
"indeterminate" form of the indicator (an activity indicator).
</p>
<p>
Progress indicators are displayed with the platform's implementation of the
{@link android.widget.ProgressBar} class.
</p>
<p>
To use a progress indicator, call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}. The
determinate and indeterminate forms are described in the following sections.
</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="FixedProgress">Display a Fixed-duration Progress Indicator</h2>
<p>
To display a determinate progress bar, add the bar to your notification by calling
{@link android.support.v4.app.NotificationCompat.Builder#setProgress
setProgress(max, progress, false)} and then issue the notification.
The third argument is a boolean that indicates whether the
progress bar is indeterminate (<strong>true</strong>) or determinate (<strong>false</strong>).
As your operation proceeds,
increment <code>progress</code>, and update the notification. At the end of the operation,
<code>progress</code> should equal <code>max</code>. A common way to call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}
is to set <code>max</code> to 100 and then increment <code>progress</code> as a
"percent complete" value for the operation.
</p>
<p>
You can either leave the progress bar showing when the operation is done, or remove it. In
either case, remember to update the notification text to show that the operation is complete.
To remove the progress bar, call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress
setProgress(0, 0, false)}. For example:
</p>
<pre>
...
mNotifyManager =
(NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
mBuilder = new NotificationCompat.Builder(this);
mBuilder.setContentTitle("Picture Download")
.setContentText("Download in progress")
.setSmallIcon(R.drawable.ic_notification);
// Start a lengthy operation in a background thread
new Thread(
new Runnable() {
&#64;Override
public void run() {
int incr;
// Do the "lengthy" operation 20 times
for (incr = 0; incr &lt;= 100; incr+=5) {
// Sets the progress indicator to a max value, the
// current completion percentage, and "determinate"
// state
mBuilder.setProgress(100, incr, false);
// Displays the progress bar for the first time.
mNotifyManager.notify(0, mBuilder.build());
// Sleeps the thread, simulating an operation
// that takes time
try {
// Sleep for 5 seconds
Thread.sleep(5*1000);
} catch (InterruptedException e) {
Log.d(TAG, "sleep failure");
}
}
// When the loop is finished, updates the notification
mBuilder.setContentText("Download complete")
// Removes the progress bar
.setProgress(0,0,false);
mNotifyManager.notify(ID, mBuilder.build());
}
}
// Starts the thread by calling the run() method in its Runnable
).start();
</pre>
<p>
The resulting notifications are shown in figure 1. On the left side is a snapshot of the
notification during the operation; on the right side is a snapshot of it after the operation
has finished.
</p>
<img
id="figure1"
src="{@docRoot}images/ui/notifications/progress_bar_summary.png"
height="84"
alt="" />
<p class="img-caption">
<strong>Figure 1.</strong> The progress bar during and after the operation.</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="ActivityIndicator">Display a Continuing Activity Indicator</h2>
<p>
To display a continuing (indeterminate) activity indicator, add it to your notification with
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress(0, 0, true)}
and issue the notification. The first two arguments are ignored, and the third argument
declares that the indicator is indeterminate. The result is an indicator
that has the same style as a progress bar, except that its animation is ongoing.
</p>
<p>
Issue the notification at the beginning of the operation. The animation will run until you
modify your notification. When the operation is done, call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress
setProgress(0, 0, false)} and then update the notification to remove the activity indicator.
Always do this; otherwise, the animation will run even when the operation is complete. Also
remember to change the notification text to indicate that the operation is complete.
</p>
<p>
To see how continuing activity indicators work, refer to the preceding snippet. Locate the following lines:
</p>
<pre>
// Sets the progress indicator to a max value, the current completion
// percentage, and "determinate" state
mBuilder.setProgress(100, incr, false);
// Issues the notification
mNotifyManager.notify(0, mBuilder.build());
</pre>
<p>
Replace the lines you've found with the following lines. Notice that the third parameter
in the {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}
call is set to {@code true} to indicate that the progress bar is
indeterminate:
</p>
<pre>
// Sets an activity indicator for an operation of indeterminate length
mBuilder.setProgress(0, 0, true);
// Issues the notification
mNotifyManager.notify(0, mBuilder.build());
</pre>
<p>
The resulting indicator is shown in figure 2:
</p>
<img
id="figure2"
src="{@docRoot}images/ui/notifications/activity_indicator.png"
height="99"
alt="" />
<p class="img-caption"><strong>Figure 2.</strong> An ongoing activity indicator.</p>

167
docs/html/training/notify-user/expanded.jd Normal file
View File

@ -0,0 +1,167 @@
page.title=Using Big View Styles
Styles parent.title=Notifying the User
parent.link=index.html
trainingnavtop=true
next.title=Displaying Progress in a Notification
next.link=display-progress.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#activity">Set Up the Notification to Launch a New Activity</a></li>
<li><a href="#big-view">Construct the Big View</a></li>
</ol>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<ul>
<li>
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
</li>
<li>
<a href="{@docRoot}guide/components/intents-filters.html">
Intents and Intent Filters
</a>
</li>
<li>
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
</li>
</ul>
</div>
</div>
<p>Notifications in the notification drawer appear in two main visual styles,
normal view and big view. The big view of a notification only appears when the
notification is expanded. This happens when the notification is at the top of
the drawer, or the user clicks the notification. </p>
<p>Big views were introduced in
Android 4.1, and they're not supported on older devices. This lesson describes
how to incorporate big view notifications into your app while still providing
full functionality via the normal view. See the <a
href="{@docRoot}guide/topics/ui/notifiers/notifications.html#BigNotify">
Notifications API guide</a> for more discussion of big views.</p>
<p>Here is an example of a normal view: </p>
<img src="{@docRoot}images/training/notifications-normalview.png" width="300" height="58" alt="normal view" />
<p class="img-caption">
<strong>Figure 1.</strong> Normal view notification.
</p>
<p>Here is an example of a big view:</p>
<img src="{@docRoot}images/training/notifications-bigview.png" width="300" height="143" alt="big view" />
<p class="img-caption">
<strong>Figure 2.</strong> Big view notification.
</p>
<p> In the sample application shown in this lesson, both the normal view and the
big view give users access to same functionality:</p>
<ul>
<li>The ability to snooze or dismiss the notification.</li>
<li>A way to view the reminder text the user set as part of the timer.</li>
</ul>
<p>The normal view provides these features through a new activity that launches
when the user clicks the notification. Keep this in mind as you design your notifications&mdash;first
provide the functionality in the normal view, since
this is how many users will interact with the notification.</p>
<h2 id="activity">Set Up the Notification to Launch a New Activity</h2>
<p>The sample application uses an {@link android.app.IntentService} subclass ({@code PingService})
to construct and issue the notification.</p>
<p>In this snippet, the
{@link android.app.IntentService} method
{@link android.app.IntentService#onHandleIntent onHandleIntent()} specifies the new activity
that will be launched if the user
clicks the notification itself. The method
{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}
defines a pending intent that should be fired when the user
clicks the notification, thereby launching the activity.</p>
<pre>Intent resultIntent = new Intent(this, ResultActivity.class);
resultIntent.putExtra(CommonConstants.EXTRA_MESSAGE, msg);
resultIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK |
Intent.FLAG_ACTIVITY_CLEAR_TASK);
// Because clicking the notification launches a new ("special") activity,
// there's no need to create an artificial back stack.
PendingIntent resultPendingIntent =
PendingIntent.getActivity(
this,
0,
resultIntent,
PendingIntent.FLAG_UPDATE_CURRENT
);
// This sets the pending intent that should be fired when the user clicks the
// notification. Clicking the notification launches a new activity.
builder.setContentIntent(resultPendingIntent);
</pre>
<h2 id="big-view">Construct the Big View</h2>
<p>This snippet shows how to set up the buttons that will appear in the big view:</p>
<pre>
// Sets up the Snooze and Dismiss action buttons that will appear in the
// big view of the notification.
Intent dismissIntent = new Intent(this, PingService.class);
dismissIntent.setAction(CommonConstants.ACTION_DISMISS);
PendingIntent piDismiss = PendingIntent.getService(this, 0, dismissIntent, 0);
Intent snoozeIntent = new Intent(this, PingService.class);
snoozeIntent.setAction(CommonConstants.ACTION_SNOOZE);
PendingIntent piSnooze = PendingIntent.getService(this, 0, snoozeIntent, 0);
</pre>
<p>This snippet shows how to construct the
{@link android.support.v4.app.NotificationCompat.Builder Builder} object.
It sets the style for the big
view to be "big text," and sets its content to be the reminder message. It uses
{@link android.support.v4.app.NotificationCompat.Builder#addAction addAction()}
to add the <strong>Snooze</strong> and <strong>Dismiss</strong> buttons (and
their associated pending intents) that will appear in the notification's
big view:</p>
<pre>// Constructs the Builder object.
NotificationCompat.Builder builder =
new NotificationCompat.Builder(this)
.setSmallIcon(R.drawable.ic_stat_notification)
.setContentTitle(getString(R.string.notification))
.setContentText(getString(R.string.ping))
.setDefaults(Notification.DEFAULT_ALL) // requires VIBRATE permission
/*
* Sets the big view "big text" style and supplies the
* text (the user's reminder message) that will be displayed
* in the detail area of the expanded notification.
* These calls are ignored by the support library for
* pre-4.1 devices.
*/
.setStyle(new NotificationCompat.BigTextStyle()
.bigText(msg))
.addAction (R.drawable.ic_stat_dismiss,
getString(R.string.dismiss), piDismiss)
.addAction (R.drawable.ic_stat_snooze,
getString(R.string.snooze), piSnooze);
</pre>

102
docs/html/training/notify-user/index.jd Normal file
View File

@ -0,0 +1,102 @@
page.title=Notifying the User
trainingnavtop=true
startpage=true
next.title=Build a Notification
next.link=build-notification.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
<h2>Dependencies and prerequisites</h2>
<ul>
<li>Android 1.6 (API Level 4) or higher</li>
</ul>
<h2>You should also read</h2>
<ul>
<li>
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
</li>
<li>
<a href="{@docRoot}guide/components/intents-filters.html">
Intents and Intent Filters
</a>
</li>
<li>
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
</li>
</ul>
<h2>Try it out</h2>
<div class="download-box">
<a href="{@docRoot}shareables/training/NotifyUser.zip"
class="button">Download the sample</a>
<p class="filename">NotifyUser.zip</p>
</div>
</div>
</div>
<p>
A notification is a user interface element that you display outside your app's normal UI to indicate
that an event has occurred. Users can choose to view the notification while using other apps and respond
to it when it's convenient for them.
</p>
<p>
The <a href="{@docRoot}design/patterns/notifications.html">Notifications design guide</a> shows
you how to design effective notifications and when to use them. This class shows you how to
implement the most common notification designs.
</p>
<h2>Lessons</h2>
<dl>
<dt>
<strong><a href="build-notification.html">Building a Notification</a></strong>
</dt>
<dd>
Learn how to create a notification
{@link android.support.v4.app.NotificationCompat.Builder Builder}, set the
required features, and issue the notification.
</dd>
<dt>
<strong><a href="navigation.html">Preserving Navigation when Starting an Activity</a></strong>
</dt>
<dd>
Learn how to enforce the proper
navigation for an {@link android.app.Activity} started from a notification.
</dd>
<dt>
<strong>
<a href="managing.html">Updating Notifications</a>
</strong>
</dt>
<dd>
Learn how to update and remove notifications.
</dd>
<dt>
<strong>
<a href="expanded.html">Using Big View Styles</a>
</strong>
</dt>
<dd>
Learn how to create a big view within an expanded notification, while still maintaining
backward compatibility.
</dd>
<dt>
<strong>
<a href="display-progress.html">Displaying Progress in a Notification</a>
</strong>
</dt>
<dd>
Learn how to display the progress of an operation in a notification, both for
operations where you can estimate how much has been completed (determinate progress) and
operations where you don't know how much has been completed (indefinite progress).
</dd>
</dl>

107
docs/html/training/notify-user/managing.jd Normal file
View File

@ -0,0 +1,107 @@
page.title=Updating Notifications
parent.title=Notifying the User
parent.link=index.html
trainingnavtop=true
next.title=Creating Expanded Notifications
next.link=expanded.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#Updating">Modify a Notification</a></li>
<li><a href="#Removing">Remove Notifications</a></li>
</ol>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<ul>
<li>
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
</li>
<li>
<a href="{@docRoot}guide/components/intents-filters.html">
Intents and Intent Filters
</a>
</li>
<li>
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
</li>
</ul>
</div>
</div>
<p>
When you need to issue a notification multiple times for the same type of event, you
should avoid making a completely new notification. Instead, you should consider updating a
previous notification, either by changing some of its values or by adding to it, or both.
</p>
<p>
The following section describes how to update notifications and also how to remove them.
</p>
<h2 id="Updating">Modify a Notification</h2>
<p>
To set up a notification so it can be updated, issue it with a notification ID by
calling {@link android.app.NotificationManager#notify(int, Notification)
NotificationManager.notify(ID, notification)}. To update this notification once you've issued
it, update or create a {@link android.support.v4.app.NotificationCompat.Builder} object,
build a {@link android.app.Notification} object from it, and issue the
{@link android.app.Notification} with the same ID you used previously.
</p>
<p>
The following snippet demonstrates a notification that is updated to reflect the
number of events that have occurred. It stacks the notification, showing a summary:
</p>
<pre>
mNotificationManager =
(NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// Sets an ID for the notification, so it can be updated
int notifyID = 1;
mNotifyBuilder = new NotificationCompat.Builder(this)
.setContentTitle("New Message")
.setContentText("You've received new messages.")
.setSmallIcon(R.drawable.ic_notify_status)
numMessages = 0;
// Start of a loop that processes data and then notifies the user
...
mNotifyBuilder.setContentText(currentText)
.setNumber(++numMessages);
// Because the ID remains unchanged, the existing notification is
// updated.
mNotificationManager.notify(
notifyID,
mNotifyBuilder.build());
...
</pre>
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="Removing">Remove Notifications</h2>
<p>
Notifications remain visible until one of the following happens:
</p>
<ul>
<li>
The user dismisses the notification either individually or by using "Clear All" (if
the notification can be cleared).
</li>
<li>
The user touches the notification, and you called
{@link android.support.v4.app.NotificationCompat.Builder#setAutoCancel setAutoCancel()} when
you created the notification.
</li>
<li>
You call {@link android.app.NotificationManager#cancel(int) cancel()} for a specific
notification ID. This method also deletes ongoing notifications.
</li>
<li>
You call {@link android.app.NotificationManager#cancelAll() cancelAll()}, which removes
all of the notifications you previously issued.
</li>

228
docs/html/training/notify-user/navigation.jd Normal file
View File

@ -0,0 +1,228 @@
page.title=Preserving Navigation when Starting an Activity
parent.title=Notifying the User
parent.link=index.html
trainingnavtop=true
next.title=Updating Notifications
next.link=managing.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#DirectEntry">Set up a regular activity PendingIntent</a></li>
<li><a href="#ExtendedNotification">Set up a special activity PendingIntent</a></li>
</ol>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<ul>
<li>
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide
</li>
<li>
<a href="{@docRoot}guide/components/intents-filters.html">
Intents and Intent Filters
</a>
</li>
<li>
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide
</li>
</ul>
</div>
</div>
<p>
Part of designing a notification is preserving the user's expected navigation experience.
For a detailed discussion of this topic, see the
<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#NotificationResponse">Notifications</a>
API guide.
There are two general situations:
</p>
<dl>
<dt>
Regular activity
</dt>
<dd>
You're starting an {@link android.app.Activity} that's part of the application's normal
workflow.
</dd>
<dt>
Special activity
</dt>
<dd>
The user only sees this {@link android.app.Activity} if it's started from a notification.
In a sense, the {@link android.app.Activity} extends the notification by providing
information that would be hard to display in the notification itself.
</dd>
</dl>
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="DirectEntry">Set Up a Regular Activity PendingIntent</h2>
<p>
To set up a {@link android.app.PendingIntent} that starts a direct entry
{@link android.app.Activity}, follow these steps:
</p>
<ol>
<li>
Define your application's {@link android.app.Activity} hierarchy in the manifest. The final XML should look like this:
</p>
<pre>
&lt;activity
android:name=".MainActivity"
android:label="&#64;string/app_name" &gt;
&lt;intent-filter&gt;
&lt;action android:name="android.intent.action.MAIN" /&gt;
&lt;category android:name="android.intent.category.LAUNCHER" /&gt;
&lt;/intent-filter&gt;
&lt;/activity&gt;
&lt;activity
android:name=".ResultActivity"
android:parentActivityName=".MainActivity"&gt;
&lt;meta-data
android:name="android.support.PARENT_ACTIVITY"
android:value=".MainActivity"/&gt;
&lt;/activity&gt;
</pre>
</li>
<li>
Create a back stack based on the {@link android.content.Intent} that starts the
{@link android.app.Activity}. For example:
</p>
<pre>
...
Intent resultIntent = new Intent(this, ResultActivity.class);
TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
// Adds the back stack
stackBuilder.addParentStack(ResultActivity.class);
// Adds the Intent to the top of the stack
stackBuilder.addNextIntent(resultIntent);
// Gets a PendingIntent containing the entire back stack
PendingIntent resultPendingIntent =
stackBuilder.getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT);
...
NotificationCompat.Builder builder = new NotificationCompat.Builder(this);
builder.setContentIntent(resultPendingIntent);
NotificationManager mNotificationManager =
(NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
mNotificationManager.notify(id, builder.build());
</pre>
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="ExtendedNotification">Set Up a Special Activity PendingIntent</h2>
<p>
A special {@link android.app.Activity} doesn't need a back stack, so you don't have to
define its {@link android.app.Activity} hierarchy in the manifest, and you don't have
to call
{@link android.support.v4.app.TaskStackBuilder#addParentStack addParentStack()} to build a
back stack. Instead, use the manifest to set up the {@link android.app.Activity} task options,
and create the {@link android.app.PendingIntent} by calling
{@link android.app.PendingIntent#getActivity getActivity()}:
</p>
<ol>
<li>
In your manifest, add the following attributes to the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element for the {@link android.app.Activity}:
<dl>
<dt>
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#nm">android:name</a>="<i>activityclass</i>"</code>
</dt>
<dd>
The activity's fully-qualified class name.
</dd>
<dt>
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">android:taskAffinity</a>=""</code>
</dt>
<dd>
Combined with the
{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK FLAG_ACTIVITY_NEW_TASK} flag
that you set in code, this ensures that this {@link android.app.Activity} doesn't
go into the application's default task. Any existing tasks that have the
application's default affinity are not affected.
</dd>
<dt>
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#exclude">android:excludeFromRecents</a>="true"</code>
</dt>
<dd>
Excludes the new task from <i>Recents</i>, so that the user can't accidentally
navigate back to it.
</dd>
</dl>
<p>
This snippet shows the element:
</p>
<pre>
&lt;activity
android:name=".ResultActivity"
...
android:launchMode="singleTask"
android:taskAffinity=""
android:excludeFromRecents="true"&gt;
&lt;/activity&gt;
...
</pre>
</li>
<li>
Build and issue the notification:
<ol style="list-style-type: lower-alpha;">
<li>
Create an {@link android.content.Intent} that starts the
{@link android.app.Activity}.
</li>
<li>
Set the {@link android.app.Activity} to start in a new, empty task by calling
{@link android.content.Intent#setFlags setFlags()} with the flags
{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK FLAG_ACTIVITY_NEW_TASK}
and
{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK FLAG_ACTIVITY_CLEAR_TASK}.
</li>
<li>
Set any other options you need for the {@link android.content.Intent}.
</li>
<li>
Create a {@link android.app.PendingIntent} from the {@link android.content.Intent}
by calling {@link android.app.PendingIntent#getActivity getActivity()}.
You can then use this {@link android.app.PendingIntent} as the argument to
{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent
setContentIntent()}.
</li>
</ol>
<p>
The following code snippet demonstrates the process:
</p>
<pre>
// Instantiate a Builder object.
NotificationCompat.Builder builder = new NotificationCompat.Builder(this);
// Creates an Intent for the Activity
Intent notifyIntent =
new Intent(new ComponentName(this, ResultActivity.class));
// Sets the Activity to start in a new, empty task
notifyIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK |
Intent.FLAG_ACTIVITY_CLEAR_TASK);
// Creates the PendingIntent
PendingIntent notifyIntent =
PendingIntent.getActivity(
this,
0,
notifyIntent,
PendingIntent.FLAG_UPDATE_CURRENT
);
// Puts the PendingIntent into the notification builder
builder.setContentIntent(notifyIntent);
// Notifications are issued by sending them to the
// NotificationManager system service.
NotificationManager mNotificationManager =
(NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// Builds an anonymous Notification object from the builder, and
// passes it to the NotificationManager
mNotificationManager.notify(id, builder.build());
</pre>
</li>
</ol>

84
docs/html/training/training_toc.cs
View File

@ -417,7 +417,6 @@
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/efficient-downloads/index.html"
@ -602,6 +601,66 @@
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/notify-user/index.html"
description=
"How to display messages called notifications outside of
your application's UI."
>Notifying the User</a>
</div>
<ul>
<li>
<a href="<?cs var:toroot ?>training/notify-user/build-notification.html">
Building a Notification
</a>
</li>
<li>
<a href="<?cs var:toroot ?>training/notify-user/navigation.html">
Preserving Navigation when Starting an Activity
</a>
</li>
<li>
<a href="<?cs var:toroot ?>training/notify-user/managing.html">
Updating Notifications
</a>
</li>
<li>
<a href="<?cs var:toroot ?>training/notify-user/expanded.html">
Using Big View Styles
</a>
</li>
<li>
<a href="<?cs var:toroot ?>training/notify-user/display-progress.html">
Displaying Progress in a Notification
</a>
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/search/index.html"
description=
"How to properly add a search interface to your app and create a searchable database."
>Adding Search Functionality</a>
</div>
<ul>
<li><a href="<?cs var:toroot ?>training/search/setup.html">
Setting up the Search Interface
</a>
</li>
<li><a href="<?cs var:toroot ?>training/search/search.html">
Storing and Searching for Data
</a>
</li>
<li><a href="<?cs var:toroot ?>training/search/backward-compat.html">
Remaining Backward Compatible
</a>
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
@ -661,29 +720,6 @@
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/search/index.html"
description=
"How to properly add a search interface to your app and create a searchable database."
>Adding Search Functionality</a>
</div>
<ul>
<li><a href="<?cs var:toroot ?>training/search/setup.html">
Setting up the Search Interface
</a>
</li>
<li><a href="<?cs var:toroot ?>training/search/search.html">
Storing and Searching for Data
</a>
</li>
<li><a href="<?cs var:toroot ?>training/search/backward-compat.html">
Remaining Backward Compatible
</a>
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/custom-views/index.html"