Merge "docs: updates for changes to notification APIs" into klp-modular-dev

you should include the following imports in your project code:</p>

you should include the following imports in your project code:</p>

<pre>

<pre>

import android.preview.support.wearable.notifications.*;

import android.support.wearable.notifications.*;

import android.preview.support.v4.app.NotificationManagerCompat;

import android.support.wearable.app.NotificationManagerCompat;

import android.support.v4.app.NotificationCompat;

import android.support.v4.app.NotificationCompat;

</pre>

</pre>

<p>For example, here's some code that creates and issues a notification using the

<p>For example, here's some code that creates and issues a notification using the

{@link android.support.v4.app.NotificationCompat} APIs combined with the new

{@link android.support.v4.app.NotificationCompat} APIs combined with the new

<a href="{@docRoot}reference/android/preview/support/v4/app/NotificationManagerCompat.html">

<a href="{@docRoot}reference/android/support/wearable/app/NotificationManagerCompat.html">

<code>NotificationManagerCompat</code></a> API:</p>

<code>NotificationManagerCompat</code></a> API:</p>

  you can add additional pages of content that users can view by swiping to the left, or add the ability

  you can add additional pages of content that users can view by swiping to the left, or add the ability

for users to deliver your app a text response using voice input.</p>

for users to deliver your app a text response using voice input.</p>

<p>To use these new APIs, pass your instance of

<p>To use these new APIs:</p>

{@link android.support.v4.app.NotificationCompat.Builder} to the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#WearableNotifications.Builder(android.content.Context)"> <code>WearableNotifications.Builder()</code></a> constructor. You can then add new

<ol>

features to your notification using the

  <li>Create an instance of

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html"

{@link android.support.v4.app.NotificationCompat.Builder}, setting the

  ><code>WearableNotifications.Builder</code></a> methods. For example:</p>

desired properties for your notification.</li>

  <li>Create a

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#WearableNotificationOptions.Builder(android.content.Context)"> <code>WearableNotificationOptions.Builder</code></a>, setting the wearable-specific options for the notication.</li>

  <li>Call <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#WearableNotificationOptions.Builder#applyTo"><code>WearableNotificationOptions.Builder.applyTo()</code>

  </a>, passing in the {@link android.support.v4.app.NotificationCompat.Builder}. This applies

  the wearable options to the notification.</li>

</ol>

<p>

For example, the following code calls the

 <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#setHintHideIcon(boolean)">

  <code>setHintHideIcon()</code></a> method to remove the app icon from the notification card.

</p>

<pre>

<pre>

// Create a NotificationCompat.Builder for standard notification features

// Create a NotificationCompat.Builder for standard notification features

NotificationCompat.Builder notificationBuilder =

 NotificationCompat.Builder builder = new NotificationCompat.Builder(mContext)

        new NotificationCompat.Builder(mContext)

         .setContentTitle("New mail from " + sender)

        .setContentTitle("New mail from " + sender.toString())

         .setContentText(subject)

         .setContentText(subject)

         .setSmallIcon(R.drawable.new_mail);

         .setSmallIcon(R.drawable.new_mail);

// Create a WearablesNotificationOptions.Builder to add functionality for wearables

// Create a WearablesNotification.Builder to add special functionality for wearables

 Notification notif = new WearableNotificationOptions.Builder()

Notification notification =

         <b>.setHintHideIcon(true)</b>

        new WearableNotifications.Builder(notificationBuilder)

         .build()

        .setHintHideIcon(true)

         .applyTo(builder); //apply wearable options to to the original notification

        .build();

         .build()

</pre>

</pre>

<p>The <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#setBigActionIcon(int)">

<p>The

  <code>setHintHideIcon()</code></a> method removes your app icon from the notification card.

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#setHintHideIcon(boolean)">

  This method is just one example of new notification features available from the

  <code>setHintHideIcon()</code></a> method is just one example of new notification features available with the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html"

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html"

  ><code>WearableNotifications.Builder</code></a> class.</p>

  ><code>WearableNotificationOptions.Builder</code></a> class.

</p>

<p>When you want to deliver your notifications, be certain to always use the

  <a href="{@docRoot}reference/android/preview/support/v4/app/NotificationManagerCompat.html">

<p>When you want to deliver your notifications, always use the

    <code>NotificationManagerCompat</code></a> API:</p>

  <a href="{@docRoot}reference/android/support/wearable/app/NotificationManagerCompat.html">

  <code>NotificationManagerCompat</code></a> API instead of

  {@link android.app.NotificationManager}:</p>

<pre>

<pre>

// Get an instance of the NotificationManager service

// Get an instance of the NotificationManager service

NotificationManagerCompat notificationManager =

NotificationManagerCompat notificationManager =

        NotificationManagerCompat.from(this);

        NotificationManagerCompat.from(this);

// Build the notification and issues it with notification manager.

// Issue the notification with notification manager.

notificationManager.notify(notificationId, notification);

notificationManager.notify(notificationId, notif);

</pre>

</pre>

<p>If you instead use the framework's {@link android.app.NotificationManager}, some

features from <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html"><code>WearableNotifications.Builder</code></a>

<p>If you use the framework's {@link android.app.NotificationManager}, some

will not work.</p>

features from <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html"><code>WearableNotificationOptions.Builder</code></a>

do not work.</p>

<p>To continue enhancing your notifications for wearables using

<p>To continue enhancing your notifications for wearables using

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html"

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html"

  ><code>WearableNotifications.Builder</code></a> and other APIs in the

  ><code>WearableNotificationOptions.Builder</code></a> and other APIs in the

  preview support library, see the following developer guides:</p>

  preview support library, see the following developer guides:</p>

  <dl>

  <dl>

<a href="{@docRoot}wear/design/index.html#NotificationPages">Design Principles of Android

<a href="{@docRoot}wear/design/index.html#NotificationPages">Design Principles of Android

Wear</a>.</p>

Wear</a>.</p>

<p>To create a notification with multiple pages:</p>

<p>When creating a notification with multiple pages, start by creating the main notification

<ol>

(the first page) the way you'd like the notification to appear on a phone

    <li>Create the main notification (the first page) the way you'd like the notification to appear on a phone

or tablet. Then, add pages one at a time with the

    or tablet.</li>

<a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#addPage(android.app.Notification)">

    <li>Add pages one at a time with the

<a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#addPage(android.app.Notification)">

<code>addPage()</code></a> method, or add multiple pages in a {@link java.util.Collection} with the

<code>addPage()</code></a> method, or add multiple pages in a {@link java.util.Collection} with the

<a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#addPages(java.util.Collection<android.app.Notification>)">

<a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#addPages(java.util.Collection<android.app.Notification>)">

<code>addPages()</code></a> method.</p>

<code>addPages()</code></a> method.</li>

    <li>Apply the pages to the main notification with the

    <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.html#applyTo(android.support.v4.app.NotificationCompat.Builder)"

    ><code>applyTo()</code></a> method.</li>

</ol>

<p>For example, here's some code that adds a second page to a notification:</p>

<p>For example, here's some code that adds a second page to a notification:</p>

        .setStyle(secondPageStyle)

        .setStyle(secondPageStyle)

        .build();

        .build();

// Create main notification and add the second page

// Add second page with wearable options and apply to main notification

Notification twoPageNotification =

Notification twoPageNotification =

        new WearableNotifications.Builder(notificationBuilder)

        new WearableNotificationsOptions.Builder()

        .addPage(secondPageNotification)

        .addPage(secondPageNotification)

        .build()

        .applyTo(notificationBuilder)

        .build();

        .build();

</pre>

</pre>

</body>

</body>

</html>

</html>

<h2 id="RemoteInput">Define the Remote Input</h2>

<h2 id="RemoteInput">Define the Remote Input</h2>

<p>To create an action that supports voice input, first create an instance of

<p>To create an action that supports voice input, first create an instance of

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html">

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html">

<code>RemoteInput</code></a> using the

<code>RemoteInput</code></a> using the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> APIs.

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> APIs.

    The

    The

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> constructor takes a string that the system

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> constructor takes a string that the system

    will use as a key for the {@link android.content.Intent} extra that carries the reply message

    will use as a key for the {@link android.content.Intent} extra that carries the reply message

    to your app on the handheld.</p>

    to your app on the handheld.</p>

<p>For example, here's how to create a new

<p>For example, here's how to create a new

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html">

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html">

<code>RemoteInput</code></a> object that provides a custom

<code>RemoteInput</code></a> object that provides a custom

    label for the voice input prompt:</p>

    label for the voice input prompt:</p>

<p>In addition to allowing voice input, you can

<p>In addition to allowing voice input, you can

    provide up to five text responses that the user can select for quick replies. Call

    provide up to five text responses that the user can select for quick replies. Call

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.Builder.html#setChoices(java.lang.String[])"><code>setChoices()</code></a> and pass it a string array.</p>

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html#setChoices(java.lang.String[])"><code>setChoices()</code></a> and pass it a string array.</p>

<p>For example, you may define some responses in a resource array:</p>

<p>For example, you may define some responses in a resource array:</p>

</pre>

</pre>

<p>Then, inflate the string array and add it to the

<p>Then, inflate the string array and add it to the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a>:</p>

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a>:</p>

<pre>

<pre>

String replyLabel = getResources().getString(R.string.reply_label);

String replyLabel = getResources().getString(R.string.reply_label);

<p>If "Reply" is your notification's primary action (defined by the {@link

<p>If "Reply" is your notification's primary action (defined by the {@link

android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}

android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}

method), then you should attach the

method), then you should attach the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the main action using

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the main action using

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#addRemoteInputForContentIntent(android.preview.support.wearable.notifications.RemoteInput)">

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#addRemoteInputForContentIntent(android.support.wearable.notifications.RemoteInput)">

<code>addRemoteInputForContentIntent()</code></a>. For example:</p>

<code>addRemoteInputForContentIntent()</code></a>. For example:</p>

<pre>

<pre>

        .setLabel(replyLabel)

        .setLabel(replyLabel)

        .build();

        .build();

// Create wearable notification and add remote input

// Add remote input to wearable options and apply to notification

Notification replyNotification =

Notification replyNotification =

        new WearableNotifications.Builder(replyNotificationBuilder)

        new WearableNotificationOptions.Builder()

        .addRemoteInputForContentIntent(remoteInput)

        .addRemoteInputForContentIntent(remoteInput)

        .build()

        .applyTo(replyNotificationBuilder)

        .build();

        .build();

</pre>

</pre>

<p>By using

<p>By using

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#addRemoteInputForContentIntent(android.preview.support.wearable.notifications.RemoteInput)">

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#addRemoteInputForContentIntent(android.support.wearable.notifications.RemoteInput)">

<code>addRemoteInputForContentIntent()</code></a> to add the

<code>addRemoteInputForContentIntent()</code></a> to add the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> object to the notification's primary action,

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> object to the notification's primary action,

the button that normally appears as an "Open" action becomes the "Reply" action

the button that normally appears as an "Open" action becomes the "Reply" action

and starts the voice input UI when users select it on Android Wear.</p>

and starts the voice input UI when users select it on Android Wear.</p>

<p>If the "Reply" action is not your notification's primary action and you want to enable

<p>If the "Reply" action is not your notification's primary action and you want to enable

voice input for a secondary action, add the

voice input for a secondary action, add the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to a new action button defined by an

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to a new action button defined by an

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html">

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">

<code>Action</code></a> object.</p>

<code>Action</code></a> object.</p>

<p>You should instantiate the

<p>You should instantiate the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html">

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">

<code>Action</code></a> with the

<code>WearableAction</code></a> with the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.Builder.html"><code>Action.Builder()</code></a>

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.Builder.html"><code>WearableAction.Builder()</code></a>

constructor, which takes an icon and text label for the action button, plus the

constructor, which takes an icon and text label for the action button, plus the

{@link android.app.PendingIntent}

{@link android.app.PendingIntent}

the system should use to invoke your app when the user selects the action. For example:</p>

the system should use to invoke your app when the user selects the action. For example:</p>

        .build();

        .build();

// Create the notification action

// Create the notification action

Action replyAction = new Action.Builder(R.drawable.ic_message,

WearableAction replyAction = new WearableAction.Builder(R.drawable.ic_message,

        "Reply", pendingIntent)

        "Reply", pendingIntent)

        .addRemoteInput(remoteInput)

        .addRemoteInput(remoteInput)

        .build();

        .build();

<p>After you add the

<p>After you add the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html">

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">

<code>Action</code></a>, add the

<code>Wearablection</code></a>, set the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html">

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">

<code>Action</code></a> to the

<code>WearableAction</code></a> on the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html"><code>WearableNotifications.Builder</code></a> using

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html"><code>WearableNotifications.Builder</code></a> using

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#addAction(Action)"><code>addAction()</code></a>.

  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationsOptions.Builder.html#addAction(Action)"><code>addAction()</code></a>.

For example:</p>

For example:</p>

<pre>

<pre>

                .setContentTitle("New message");

                .setContentTitle("New message");

// Create the notification action and add remote input

// Create the notification action and add remote input

Action replyAction = new Action.Builder(R.drawable.ic_message,

WearableAction replyAction = new WearableAction.Builder(R.drawable.ic_message,

        "Reply", pendingIntent)

        "Reply", pendingIntent)

        .addRemoteInput(remoteInput)

        .addRemoteInput(remoteInput)

        .build();

        .build();

// Create wearable notification and add action

// Create wearable notification and add action

Notification replyNotification =

Notification replyNotification =

        new WearableNotifications.Builder(replyNotificationBuilder)

        new WearableNotificationOptions.Builder()

                .addAction(replyAction)

                .addAction(replyAction)

                .build()

                .applyTo(replyNotificationBuilder)

                .build();

                .build();

</pre>

</pre>

<p>Now, when the user selects "Reply" from an Android wearable, the system prompts the user

<p>Now, when the user selects "Reply" from an Android wearable, the system prompts the user

    for voice input (and shows the list of pre-defined replies, if provided).

    for voice input (and shows the list of pre-defined replies, if provided).

    Once the user completes a response, the system invokes

    Once the user completes a response, the system invokes

    the {@link android.content.Intent} attached to the action and adds the

    the {@link android.content.Intent} attached to the action and adds the

<code>EXTRA_VOICE_REPLY</code> extra (the string

<code>EXTRA_VOICE_REPLY</code> extra (the string

    you passed to the

    you passed to the

  <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> constructor)

  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> constructor)

  with the user's message as the string value.</p>

  with the user's message as the string value.</p>

<h2 id="ObtainInput">Obtaining the Voice Input as a String</h2>

<p>To obtain the user's voice input, call

<a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html#getResultsFromIntent(Intent)"><code>getResultsFromIntent()</code></a>,

passing in the "Reply" action's intent. This method returns

a {@link android.os.Bundle} that represents the intent's extras. You can then query the

{@link android.os.Bundle} to obtain the user's voice input string.

</p>

<p>

The following code shows a method that accepts an intent and returns the voice input string,

which is referenced by the <code>EXTRA_VOICE_REPLY</code> key that is used in the previous examples:

</p>

<pre>

/**

 * Obtain the intent that started this activity by calling

 * Activity.getIntent() and pass it into this method to

 * get the associated voice input string.

 */

private String getMessageText(Intent intent) {

    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);

        if (remoteInput != null) {

            return remoteInput.getString(Intent.EXTRA_VOICE_REPLY);

        }

    }

    return null;

}

</pre>

</body>

</body>

</html>

</html>