Merge "Doc update: new Notify User AU class" into jb-dev-docs

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("My notification")

    .setContentText("Hello World!");

</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>

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() {

        @Override

        public void run() {

            int incr;

            // Do the "lengthy" operation 20 times

            for (incr = 0; incr <= 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>