From 2728c2a93abd74ef19e550f3530ee70ea41424b3 Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Sun, 15 Jun 2014 22:00:13 -0700 Subject: [PATCH] docs: wear training classes Change-Id: I542b3bc87d3a24bf89ea9b7d8edeec224780f31b --- docs/html/training/building-wearables.jd | 8 + docs/html/training/training_toc.cs | 85 ++++- .../training/wearables/apps/bt-debugging.jd | 92 ++++++ docs/html/training/wearables/apps/creating.jd | 184 +++++++++++ docs/html/training/wearables/apps/index.jd | 72 ++++ docs/html/training/wearables/apps/layouts.jd | 131 ++++++++ .../html/training/wearables/apps/packaging.jd | 156 +++++++++ docs/html/training/wearables/apps/voice.jd | 274 +++++++++++++++ .../wearables/data-layer/accessing.jd | 59 ++++ .../training/wearables/data-layer/assets.jd | 123 +++++++ .../wearables/data-layer/data-items.jd | 124 +++++++ .../training/wearables/data-layer/events.jd | 312 ++++++++++++++++++ .../training/wearables/data-layer/index.jd | 87 +++++ .../training/wearables/data-layer/messages.jd | 99 ++++++ .../wearables/notifications/creating.jd | 295 +++++++++++++++++ .../training/wearables/notifications/index.jd | 51 +++ .../training/wearables/notifications/pages.jd | 71 ++++ .../wearables}/notifications/stacks.jd | 108 +++--- .../wearables/notifications/voice-input.jd | 175 ++++++++++ docs/html/wear/notifications/creating.jd | 305 ----------------- docs/html/wear/notifications/pages.jd | 65 ---- docs/html/wear/notifications/remote-input.jd | 241 -------------- 22 files changed, 2459 insertions(+), 658 deletions(-) create mode 100644 docs/html/training/building-wearables.jd create mode 100644 docs/html/training/wearables/apps/bt-debugging.jd create mode 100644 docs/html/training/wearables/apps/creating.jd create mode 100644 docs/html/training/wearables/apps/index.jd create mode 100644 docs/html/training/wearables/apps/layouts.jd create mode 100644 docs/html/training/wearables/apps/packaging.jd create mode 100644 docs/html/training/wearables/apps/voice.jd create mode 100644 docs/html/training/wearables/data-layer/accessing.jd create mode 100644 docs/html/training/wearables/data-layer/assets.jd create mode 100644 docs/html/training/wearables/data-layer/data-items.jd create mode 100644 docs/html/training/wearables/data-layer/events.jd create mode 100644 docs/html/training/wearables/data-layer/index.jd create mode 100644 docs/html/training/wearables/data-layer/messages.jd create mode 100644 docs/html/training/wearables/notifications/creating.jd create mode 100644 docs/html/training/wearables/notifications/index.jd create mode 100644 docs/html/training/wearables/notifications/pages.jd rename docs/html/{wear => training/wearables}/notifications/stacks.jd (54%) create mode 100644 docs/html/training/wearables/notifications/voice-input.jd delete mode 100644 docs/html/wear/notifications/creating.jd delete mode 100644 docs/html/wear/notifications/pages.jd delete mode 100644 docs/html/wear/notifications/remote-input.jd diff --git a/docs/html/training/building-wearables.jd b/docs/html/training/building-wearables.jd new file mode 100644 index 0000000000000..4fda10e1f960f --- /dev/null +++ b/docs/html/training/building-wearables.jd @@ -0,0 +1,8 @@ +page.title=Building Apps for Wearables +page.trainingcourse=true + +@jd:body + + +

These classes teach you how to build notifications in a handheld app that are automatically +synced to wearables as well as how to build apps that run on wearables.

\ No newline at end of file diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index c5dc3c5f76153..4407d304d5a4f 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -638,7 +638,6 @@ include the action bar on devices running Android 2.1 or higher." - @@ -727,6 +726,90 @@ include the action bar on devices running Android 2.1 or higher." +
  • +
    + + Building Apps for
    + Wearables +     +
    + +
    • + +
  • diff --git a/docs/html/training/wearables/apps/bt-debugging.jd b/docs/html/training/wearables/apps/bt-debugging.jd new file mode 100644 index 0000000000000..8d09c43d20aca --- /dev/null +++ b/docs/html/training/wearables/apps/bt-debugging.jd @@ -0,0 +1,92 @@ +page.title=Debugging over Bluetooth + +@jd:body + +
    +
    + + +

    This lesson teaches you to

    +
      +
    1. Set Up Devices for Debugging
      2. +
    2. Set Up a Debugging Session
      3. +
    3. Debug Your App
      4. +
    +

    You should also read

    + +
    +
    + +

    You can debug your wearable over Bluetooth by routing it's debug output to the +handheld device that's connected to your development machine.

    + +

    Setup Devices for Debugging

    +
      +
    1. Enable USB debugging on the handheld: +
        +
      • Open the Settings app and scroll to the bottom.
        • +
      • If it doesn't have a Developer Options setting, tap About Phone + (or About Tablet), scroll to the bottom, and tap the build number 7 times.
        • +
      • Go back and tap Developer Options.
        • +
      • Enable USB debugging.
        • +
      +
      2. +
    2. Enable Bluetooth debugging on the wearable: +
        +
      1. Tap the home screen twice to bring up the Wear menu.
        2. +
      2. Scroll to the bottom and tap Settings.
        3. +
      3. Scroll to the bottom. If there's no Developer Options item, tap About, + and then tap the build number 7 times.
        4. +
      4. Tap the Developer Options item.
        5. +
      5. Enable Debug over Bluetooth.
        6. +
      +
      3. +
    + +

    Set Up a Debugging Session

    +
      +
    1. On the handheld, open the Android Wear companion app.
      2. +
    2. Tap the menu on the top right and select Settings.
      3. +
    3. Enable Debugging over Bluetooth. You should see a tiny status summary appear under the + option: + 
      +Host: disconnected
+Target: connected
+
      +
      4. +
    4. Connect the handheld to your machine over USB and run: +
      +adb forward tcp:4444 localabstract:/adb-hub; adb connect localhost:4444
+
      + +

      Note: You can use any available port that you have access to.

      +
      5. +
    +

    +In the Android Wear companion app, you should see the status change to:

    +
    +Host: connected
+Target: connected
+
    + +

    Debug Your App

    + +Your wearable should show up as localhost:4444 when running adb devices. + +To run any adb command, use this format: + +
    adb -s localhost:4444 <command>
    + +

    If there are no other devices connected over TCP/IP (namely emulators), you can shorten the command +to:

    +
    +adb -e <command>
+
    +

    For example:

    +
    +adb -e logcat
+adb -e shell
+adb -e bugreport
+
    \ No newline at end of file diff --git a/docs/html/training/wearables/apps/creating.jd b/docs/html/training/wearables/apps/creating.jd new file mode 100644 index 0000000000000..145aed8bb6b6d --- /dev/null +++ b/docs/html/training/wearables/apps/creating.jd @@ -0,0 +1,184 @@ +page.title=Creating and Running a Wearable App + +@jd:body + +
    +
    +

    This lesson teaches you to

    +
      +
    1. Set Up an Android Wear Emulator
      2. +
    2. Set Up an Android Wear Device
      3. +
    3. Create a Project
      4. +
    4. Include the Correct Libraries
      5. +
    +

    Dependencies and Prerequisites

    +
      +
    • Android Studio 0.8 or later and Gradle 1.12 or later
      • +
    +
    +
    + +

    Wearable apps run directly on the wearable device, giving you access to low-level +hardware such as sensors, activities, services, and more, right +on the wearable.

    + +

    A companion handheld app that contains the +wearable app is also required when you want to publish to the Google Play store. +Wearables don't support the Google Play store, so users download the companion handheld app, +which automatically pushes the wearable app to the wearable. The handheld app is also +useful for doing heavy processing, network actions, or other work and +sending the results to the wearable. +

    + +

    This lesson goes over how to set up a device or emulator and create one project to contain +both your wearable and handheld apps. +

    + + +

    Set Up an Android Wear Emulator or Device

    +

    We recommend that you develop on real hardware so you can better +gauge the user experience. However, the emulator lets you test out different +types of screen shapes, which is useful for testing.

    + +

    Set up an Android Wear Virtual Device

    + +

    To set up an Android Wear virtual device:

    +
      +
    1. Click Tools > Android > AVD Manager.
      2. +
    2. Click Create....
      3. +
    3. Fill in the following details for the AVD you want to specify and leave the rest + of the fields with their default values: +
        +
      1. AVD Name - A name for your AVD
        2. +
      2. Device - Android Wear Round or Square device types
        3. +
      3. Target - Android 4.4W - API Level 20
        4. +
      4. CPU/ABI - Android Wear ARM (armeabi-v7a)
        5. +
      5. Keyboard - Select Hardware keyboard present
        6. +
      6. Skin - AndroidWearRound or AndroidWearSquare depending on the selected device type
        7. +
      7. Snapshot - Not selected
        8. +
      8. Use Host GPU - Selected, to support custom activities for wearable notifications
        9. +
      +
      4. +
    4. Click OK.
      5. +
    5. Start the emulator: +
        +
      1. Select the virtual device you just created.
        2. +
      2. Click Start..., then click Launch.
        3. +
      3. Wait until the emulator initializes and shows the Android Wear home screen.
        4. +
      +
      6. +
    6. Pair Your handheld with the emulator: +
        +
      1. On your handheld, install the Android Wear app from Google Play.
        2. +
      2. Connect the handheld to your machine through USB.
        3. +
      3. Forward the AVD's communication port to the connected handheld device (you must + do this every time the handheld is connected): + 
        adb -d forward tcp:5601 tcp:5601
        +
        4. +
      4. Start the Android Wear app on your handheld device and connect to the emulator.
        5. +
      5. Tap the menu on the top right corner of the Android Wear app and select + Demo Cards.
        6. +
      6. The cards you select appear as notifications on the home screen of the emulator.
        7. +
      +
      7. +
    + +

    Set Up an Android Wear Device

    +

    To set up an Android Wear device:

    +
      +
    1. Install the Android Wear app, available on Google Play, on your handheld.
      2. +
    2. Follow the app's instructions to pair your handheld with your wearable. + This allows you to test out synced handheld notifications, if you're building them.
      3. +
    3. Connect the wearable to your machine through USB, so you can install apps directly to it + as you develop.
      4. +
    + +

    Create a Project

    + +

    To begin development, create an app project that contains + wearable and handheld app modules. In Android Studio, click File > + New Project and follow the Project Wizard instructions, as described in + Creating a +Project. As you follow the wizard, enter the following information:

    + +
      +
    1. In the Configure your Project window, enter a name for your app and a package + name.
      2. +
    2. In the Form Factors window: +
        +
      • Select Phone and Tablet and select API 8: Android 2.2 (Froyo) + under Minimum SDK.
        • +
      • Select Wear and select API 20: Android 4.4 (KitKat Wear) + under Minimum SDK.
        • +
      +
      3. +
    3. In the first Add an Activity window, add a blank activity for mobile.
      4. +
    4. In the second Add an Activity window, add a blank activity for Wear. + +

      When the wizard completes, Android Studio creates a new project with two modules, mobile and + wear. You now have a project for both your handheld and wearable apps that you can create activities, + services, custom layouts, and much more in. On the handheld app, you do most of the heavy lifting, + such as network communications, intensive processing, or tasks that require long + amounts of user interaction. When these are done, + you usually notify the wearable of the results through notifications or by syncing and sending + data to the wearable.

      + +

      Note: The wear module also contains a "Hello World" activity that uses a + WatchViewStub that inflates a layout based on whether the device's screen + is round or square. The WatchViewStub class is one of the UI widgets that's provided + by the wearable support library.

      +
      5. + +

      Install the Wearable app

      + +

      When developing, you install apps directly to the wearable like with handheld apps. Use +either adb install or the Play button on Android Studio.

      + +

      When you're ready to publish your app to users, you embed the wearable app inside of the +handheld app. When users install the handheld app from Google Play, a connected wearable automatically +receives the wearable app.

      + +

      Note: The automatic installation of wearable apps +does not work when you are signing apps with a debug key and only works with release keys. See +Packaging Wearable Apps for +complete information on how to properly package wearable apps.

      + +
    5. +To install the "Hello World" app to the wearable, select wear from the Run/Debug +configuration drop-down menu and click the Play button. The activity shows up on the +wearable and prints out "Hello world!" +
    +

    Include the Correct Libraries

    + +

    As part of the Project Wizard, the correct +dependencies are imported for you in the appropriate module's build.gradle file. +However, these dependencies are not required, so read the following descriptions to find out if you need them or not:

    + +Notifications +

    The The +Android v4 support library (or v13, which includes v4) +contains the APIs to extend your existing notifications on handhelds to support wearables.

    + +

    For notifications that appear only on +the wearable (meaning, they are issued by an app that runs on the wearable), you can just use the +standard framework APIs (API Level 20) on the wearable and remove the support library +dependency in the mobile module of your project. +

    + +Wearable Data Layer +

    To sync and send data between wearables and handhelds with the Wearable Data Layer APIs, +you need the latest version of +Google Play services. +If you're not using these APIs, remove the dependency from both modules.

    + +Wearable UI support library +

    This is an unofficial library that includes UI widgets designed for wearables. We encourage you +to use them in your apps, because they exemplify best practices, but they can still +change at any time. However, if the libraries are updated, your apps won't break since they are compiled +into your app. To get new features from an updated library, you just need to +statically link the new version and update your app accordingly. +This library is only applicable if you create wearable apps. +

    + +

    In the next lessons, you'll learn how to create layouts designed for wearables as well as how +to use the various voice actions that are supported by the platform.

    diff --git a/docs/html/training/wearables/apps/index.jd b/docs/html/training/wearables/apps/index.jd new file mode 100644 index 0000000000000..c2c7f397d6dad --- /dev/null +++ b/docs/html/training/wearables/apps/index.jd @@ -0,0 +1,72 @@ +page.title=Creating Wearable Apps +@jd:body + +
    +
    +

    Dependencies and Prerequisites

    +
      +
    • Android Studio 0.8 or later and Gradle 1.12 or later
      • +
    +
    +
    + +

    +Wearable apps run directly on the device, giving you access to hardware such as sensors and the +GPU. They are fundamentally the same as apps built for other devices using the Android SDK, but +differ greatly in design and usability and the amount of functionality provided. +These are the main differences between handheld and wearable apps:

    + +
      +
    • The system enforces a timeout period. If you are displaying an activity and user's don't + interact with it, the device sleeps. When it wakes back up, the Wear home screen is displayed + instead of your activity. If you need to show something persistent, create a notification in the + context stream instead.
      • +
    • Wearable apps are relatively small in size and functionality compared to handheld apps. + They contain only what makes sense on the wearable, which is usually a small + subset of the corresponding handheld app. In general, you should carry out operations on the + handheld when possible and send the results to the wearable. +
      • +
    • Users don't download apps directly onto the wearable. Instead, you bundle + the wearable app inside the handheld app. When users install the handheld app, + the system automatically installs the wearable app. However, for development + purposes, you can still install the wearable app directly to the wearable.
      • +

    • Wearable apps can access much of the standard Android APIs, but don't support + the following APIs:

      +
        +
      • {@link android.webkit}
        • +
      • {@link android.print}
        • +
      • {@link android.app.backup}
        • +
      • {@link android.appwidget}
        • +
      • {@link android.hardware.usb}
        • +
      +

      + You can check if a wearable supports a feature by calling + {@link android.content.pm.PackageManager#hasSystemFeature hasSystemFeature()} + before trying to use an API.

      +
      • +
    + +

    Note: We recommend using Android Studio for Android Wear development +as it provides project setup, library inclusion, and packaging conveniences that aren't available +in ADT. The rest of this training assumes you're using Android Studio. +

    + +

    Lessons

    +
    +
    Creating and Running a Wearable App
    +
    Learn how to create an Android Studio project that + contains both the wearable and handheld app modules and how to run the app on a device + or emulator.
    +
    Creating Custom Layouts
    +
    Learn how to create and display custom layouts for notifications and + activities.
    +
    Adding Voice Capabilities
    +
    Learn how to launch an activity with a voice actions and how to start the + system speech recognizer app to obtain free-form voice input.
    +
    Packaging Wearable Apps
    +
    Learn how to package a wearable app inside a + handheld app. This allows the system to install the wearable app automatically when + users install the companion handheld app from the Google Play store.
    +
    Debugging over Bluetooth
    +
    Learn how to debug your wearable over Bluetooth instead of USB.
    +
    \ No newline at end of file diff --git a/docs/html/training/wearables/apps/layouts.jd b/docs/html/training/wearables/apps/layouts.jd new file mode 100644 index 0000000000000..983c3592d73be --- /dev/null +++ b/docs/html/training/wearables/apps/layouts.jd @@ -0,0 +1,131 @@ +page.title=Creating Custom Layouts + +@jd:body + + + +

    Creating layouts for wearables is the same as handheld devices, except you have to design +for the screen size and for glanceability. Do not port functionality +and the UI from a handheld app and expect a good experience. You should create custom layouts +only when necessary. Read the design guidelines +for information on how to design great wearable apps.

    + +

    Create Custom Notifications

    + +

    +In general, you should create notifications on the handheld and let them +automatically sync to the wearable. This lets you build your notifications +once and have them appear on many types of devices (not just wearables, but +eventually Auto and TV) without having to design them for different +form factors.

    + +

    If the standard notification styles don't work for you (such as +{@link android.support.v4.app.NotificationCompat.BigTextStyle} or +{@link android.support.v4.app.NotificationCompat.InboxStyle}), you can display an activity with +a custom layout. You can only create and issue custom notifications on the wearable, and the +system does not sync these notifications to the handheld.

    + +

    Note: When creating custom notifications on the wearable, you can use the +standard notification APIs (API Level 20) instead of the Support Library. +

    + +

    To create a custom notification:

    +
      +
    1. Create a layout and set it as the content view for the activity + that you want to display. +
      +public void onCreate(Bundle bundle){
+    ...
+    setContentView(R.layout.notification_activity);
+}
+
      +
      2. +
    2. Set the activity's allowEmbedded property to true + in the wearable app's Android manifest. This allows an activity that you create in your wearable + app to be displayed by the wearable's context stream process.
      3. +
      +<activity android:allowEmbedded="true" ... >
+...
+</activity>
+
      + +
    3. Create a {@link android.app.PendingIntent} for the activity that you want to display. + For example: +
      +Intent notificationIntent = new Intent(this, NotificationActivity.class);
+PendingIntent notificationPendingIntent = PendingIntent.getActivity(this, 0, notificationIntent,
+        PendingIntent.FLAG_UPDATE_CURRENT);
+
      +
      4. +
    4. Build a {@link android.app.Notification} and call + {@link android.app.Notification.WearableExtender#setDisplayIntent setDisplayIntent()} + providing the {@link android.app.PendingIntent}. The system uses this + {@link android.app.PendingIntent} to launch the activity when + users view your notification. +
      5. +
    5. Issue the notification using the + {@link android.app.NotificationManager#notify notify()} method. +

      Note: The system initially displays your notification with + a standard template. This template works well on all watchfaces. When users swipe the notification + up to view it, they'll then see your activity for the notification.

      +
      6. +
    +

    Create Layouts with the Wearable UI Library

    +

    +There's an unofficial UI library that is automatically included when you create your wearable +app with the Android Studio Project Wizard. You can also add the library to your build.gradle +file with the following dependency declaration: + +

    +dependencies {
+    compile fileTree(dir: 'libs', include: ['*.jar'])
+    compile 'com.google.android.support:wearable:+'
+    compile 'com.google.android.gms:play-services-wearable:+'
+}
+
    +This library helps you build UIs that are designed for wearables. Here are some of the major classes: +

    + +
      +
    • BoxInsetLayout - A FrameLayout that's aware of screen shape and can box its + children in the center square of a round screen.
      • +
    • CardFragment - A fragment that presents content within an expandable, + vertically scrollable card.
      • +
    • CircledImageView - An image view surrounded by a circle.
      • +
    • ConfirmationActivity - An activity that displays confirmation animations after the user + completes an action.
      • +
    • DismissOverlayView - A view for implementing long-press-to-dismiss.
      • +
    • GridViewPager - A layout manager that allows the user to both vertically and + horizontally through pages of data. You supply an implementation of a GridPagerAdapter to + generate the pages that the view shows.
      • +
    • GridPagerAdapter - An adapter that supplies pages to a GridViewPager.
      • +
    • FragmentGridPagerAdapter - An implementation of GridPagerAdapter that + represents each page as a fragment.
      • + +
    • WatchViewStub - A class that can inflate a specific layout, + depending on the shape of the device's screen.
      • +
    • WearableListView - An alternative version of ListView that is optimized for + ease of use on small screen wearable devices. It displays a vertically scrollable list of items, + and automatically snaps to the nearest item when the user stops scrolling. +
      • +
    + +

    Download the full API +reference documentation for the classes above. The documentation goes over how to use +each UI widget.

    diff --git a/docs/html/training/wearables/apps/packaging.jd b/docs/html/training/wearables/apps/packaging.jd new file mode 100644 index 0000000000000..ea29c9da1a80c --- /dev/null +++ b/docs/html/training/wearables/apps/packaging.jd @@ -0,0 +1,156 @@ +page.title=Packaging Wearable Apps + +@jd:body + +
    + +
    + +

    When publishing to users, you must package a wearable app inside of a handheld app, +because users cannot browse and install apps directly on the wearable. If packaged properly, +when users download the handheld app, the system automatically pushes the wearable app to the +paired wearable. +

    + +

    Note: This feature doesn't work when you are signing your apps with +a debug key when developing. While developing, installing apps with adb install or +Android Studio directly to the wearable is required.

    + + +

    Package with Android Studio

    +

    To properly package a wearable app in Android Studio:

    + +
      +
    1. Declare a Gradle dependency in the handheld app's build.gradle file + that points to the wearable app module: +
      +dependencies {
+   compile 'com.google.android.gms:play-services:5.0.+@aar'
+   compile files('../../prebuilt-libs/android-support-v4.jar')
+   wearApp project(':wearable')
+}
+
      +
      2. +
    2. Click Build > Generate Signed APK... and follow the on-screen instructions + to specify your release keystore and sign your app. Android Studio exports the signed + handheld app with the wearable app embedded in it automatically into your project's root folder. + +

      Alternatively, you can create a signingConfig rule in the wearable and handheld + modules' build.gradle file to sign them with your release key. Both apps must be + signed to have the automatic pushing of the wearable app work. + +

      +android {
+  ...
+  signingConfigs {
+    release {
+      keyAlias 'myAlias'
+      keyPassword 'myPw'
+      storeFile file('path/to/release.keystore')
+      storePassword 'myPw'
+    }
+  }
+  buildTypes {
+    release {
+      ...
+      signingConfig signingConfigs.release
+    }d
+  }
+  ...
+}
+
      +

      Build the handheld app by clicking the Gradle button on the right vertical toolbar of + Android Studio and running the assembleRelease task. The task is located under + Project name > Handheld module name > assembleRelease. +

      + +

      Note:This example embeds the password in your Gradle file, which might be undesirable. See +Configure signing settings +for information about how to create an environment variable for the passwords instead. +

      +
    + + +

    Signing the wearable and handheld app separately

    +

    If your build process requires signing the wearable app separately from the handheld app, +you can declare the following Gradle rule in the handheld module's build.gradle to +embed the previously-signed wearable app:

    + +
    +dependencies {
+  ...
+  wearApp files('/path/to/wearable_app.apk')
+}
+
    + +

    You then sign your handheld app in any manner you wish (either with the Android Studio +Build > Generate Signed APK... menu item or with Gradle signingConfig rules as +described in the previous section.

    + +

    Package Manually

    +

    +It's still possible to package the wearable app into the handheld app manually +if you are using another IDE or another method of building. +

    + +
      +
    1. Copy the signed wearable app into your handheld project's assets/ directory, + referred to as path/to/wearable_app.apk.
      2. +
    2. Create a res/xml/wearable_app_desc.xml file that contains the version and + path information of the wearable app: +
      +<wearableApp package="com.google.android.wearable.myapp">
+  <versionCode>1</versionCode>
+  <versionName>1.0</versionName>
+  <path>path/to/wearable_app.apk</path>
+</wearableApp>
+
      +

      +The package, versionCode, and versionName are the +same as values specified in the wearable app's AndroidManifest.xml file. +The path is the full path of wearable_app.apk, relative to the assets/ +directory. +

      +
      3. +
    3. +Add a meta-data tag to your handheld app's <application> tag to +reference the wearable_app_desc.xml file. +
      +  <meta-data android:name="com.google.android.wearable.myapp" 
+                 android:resource="@xml/wearable_app_desc"/>
+
      +
      4. +
    4. Build and sign the handheld app.
      5. +
    + +

    Turn off Asset Compression

    +

    +Many build tools automatically compress any files added to the assets/ +directory of an Android app. Because the wearable APK is already zipped, these tools re-compress the +wearable APK and the wearable app installer can no longer read the wearable app. +

    + +

    When this happens, the installation fails. On the handheld app, the PackageUpdateService +logs the following error: "this file cannot be opened as a file descriptor; it is probably compressed." + +

    To prevent this error in Android Studio, update your handheld app's build.gradle file +with the following declaration: +

    + +
    +android {
+  aaptOptions {
+    noCompress "apk"
+  }
+}
+
    + +

    If you are using another build process, ensure that you don't doubly compress the wearable app.

    \ No newline at end of file diff --git a/docs/html/training/wearables/apps/voice.jd b/docs/html/training/wearables/apps/voice.jd new file mode 100644 index 0000000000000..3dea5d734f502 --- /dev/null +++ b/docs/html/training/wearables/apps/voice.jd @@ -0,0 +1,274 @@ +page.title=Adding Voice Capabilities +@jd:body + + + +

    Voice actions are an important part of the wearable experience. They let users carry +out actions hands-free and quickly. Wear provides two types of voice actions:

    + +
    +
    System-provided
    +
    These voice actions are task-based and are built + into the Wear platform. You filter for them in the activity that you want to start when the + voice action is spoken. Examples include "Take a note" or "Set an alarm".
    +
    App-provided
    +
    These voice actions are app-based, and you declare them just like a launcher icon. + Users say "Start " to use these voice actions and an activity that you specify + starts.
    +
    + +

    Declare System-provided Voice Actions

    +

    +The Android Wear platform provides several voice intents that are based on user actions such +as "Take a note" or "Set an alarm". This allows users to say what they want to do and let +the system figure out the best activity to start.

    + +

    When users speak the voice action, your app can filter for the intent that is fired to start +an activity. If you want to start a service to do something in the background, show an activity as +a visual cue and start the service in the activity. Make sure to call +{@link android.app.Activity#finish finish()} when you want to get rid of the visual cue. +

    + +

    For example, for the "Take a note" command, declare this intent filter to start an activity +named MyNoteActivity: +

    + +
    +  <activity android:name="MyNoteActivity">
+      <intent-filter>
+          <action android:name="android.intent.action.SEND" />
+          <category android:name="com.google.android.voicesearch.SELF_NOTE" />
+      </intent-filter>
+  </activity>
+
    + +

    Here is a list of the voice intents supported by the Wear platform:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameExample PhrasesIntent
    Call a car/taxi"OK Google, get me a taxi"

    "OK Google, call me a car"    		 +
    +
    Action
    +
    + com.google.android.gms.actions.RESERVE_TAXI_RESERVATION +
    +
    +
    Take a note"OK Google, take a note"

    "OK Google, note to self"    		 +
    +
    Action
    +
    android.intent.action.SEND
    +
    Category
    +
    com.google.android.voicesearch.SELF_NOTE
    +
    Extras
    +
    android.content.Intent.EXTRA_TEXT - a string with note body
    +
    +
    Set alarm"OK Google, set an alarm for 8 AM"

    "OK Google, wake me up at 6 tomorrow"    		 +
    +
    Action
    +
    android.intent.action.SET_ALARM
    +
    Extras
    +
    android.provider.AlarmClock.EXTRA_HOUR - an integer with the hour of + the alarm. +

    android.provider.AlarmClock.EXTRA_MINUTES - + an integer with the minute of the alarm +

    (these 2 extras are optional, either none or + both are provided)

    + +
    +
    Set timer"Ok Google, set a timer for 10 minutes" +
    +
    Action
    +
    android.provider.AlarmClock.ACTION_SET_TIMER
    +
    Extras
    +
    android.provider.AlarmClock.EXTRA_LENGTH - an integer in the range of + 1 to 86400 (number of seconds in 24 hours) representing the length of the timer
    +
    +
    Start/Stop a bike ride"OK Google, start cycling"

    "OK Google, start my bike ride"

    "OK Google, stop cycling"    		 +
    +
    Action
    +
    vnd.google.fitness.TRACK
    +
    Mime Type
    +
    vnd.google.fitness.activity/biking
    +
    Extras
    +
    actionStatus - a string with the value ActiveActionStatus + when starting and CompletedActionStatus when stopping.
    +
    +
    Start/Stop a run"OK Google, track my run"

    "OK Google, start running"

    "OK Google, stop running"    		 +
    +
    Action
    +
    vnd.google.fitness.TRACK
    +
    MimeType
    +
    vnd.google.fitness.activity/running
    +
    Extras
    +
    actionStatus - a string with the value ActiveActionStatus + when starting and CompletedActionStatus when stopping
    +
    +
    Start/Stop a workout"OK Google, start a workout"

    "OK Google, track my workout"

    "OK Google, stop workout"    		 +
    +
    Action
    +
    vnd.google.fitness.TRACK
    +
    MimeType
    +
    vnd.google.fitness.activity/other
    +
    Extras
    +
    actionStatus - a string with the value ActiveActionStatus + when starting and CompletedActionStatus when stopping
    + +
    +
    Show heart rate"OK Google, what’s my heart rate?"

    "OK Google, what’s my bpm?"    		 +
    +
    Action
    +
    vnd.google.fitness.VIEW
    +
    Mime Type
    +
    vnd.google.fitness.data_type/com.google.heart_rate.bpm
    + +
    +
    Show step count"OK Google, how many steps have I taken?"

    "OK Google, what’s my step count?"    		 +
    +
    Action
    +
    vnd.google.fitness.VIEW
    +
    Mime Type
    +
    vnd.google.fitness.data_type/com.google.step_count.cumulative
    + +
    +
    + +

    +For documentation on registering for platform intents and accessing the extras information +contained in them, see Common intents. +

    + +

    Declare App-provided Voice Actions

    +

    +If none of the platform voice intents work for you, you can start your apps directly with +a "Start MyActivityName" voice action.

    + +

    Registering for a "Start" action is the same as registering +for a launcher icon on a handheld. Instead of requesting an app icon in a launcher, +your app requests a voice action instead.

    + +

    To specify the text to say after "Start", specify a label attribute for the activtiy +that you want to start. For example, this intent filter recognizes the +"Start MyRunningApp" voice action and launches StartRunActivity. +

    + +
    +<application>
+  <activity android:name="StartRunActivity" android:label="MyRunningApp">
+      <intent-filter>
+          <action android:name="android.intent.action.MAIN" />
+          <category android:name="android.intent.category.LAUNCHER" />
+      </intent-filter>
+  </activity>
+</application>
+
    + +

    Obtaining Free-form Speech Input

    +

    In addition to using voice actions to launch activities, you can also call the system's +built-in Speech Recognizer activity to obtain speech input from users. This is useful to obtain input +from users and then process it, such as doing a search or sending it as a message.

    + +In your app, you call {@link android.app.Activity#startActivityForResult startActivityForResult()} using +the {@link android.speech.RecognizerIntent#ACTION_RECOGNIZE_SPEECH} action. This starts the + and then handle the result +in {@link android.app.Activity#onActivityResult onActivityResult()}. +
    +private static final int SPEECH_REQUEST_CODE = 0;
+
+// Create an intent that can start the Speech Recognizer activity
+private void displaySpeechRecognizer() {
+    Intent intent = new Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH);
+    intent.putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL,
+            RecognizerIntent.LANGUAGE_MODEL_FREE_FORM);
+// Start the activity, the intent will be populated with the speech text
+    startActivityForResult(intent, SPEECH_REQUEST_CODE);
+}
+
+// This callback is invoked when the Speech Recognizer returns.
+// This is where you process the intent and extract the speech text from the intent.
+@Override
+protected void onActivityResult(int requestCode, int resultCode,
+        Intent data) {
+    if (requestCode == SPEECH_REQUEST && resultCode == RESULT_OK) {
+        List<String> results = data.getStringArrayListExtra(
+                RecognizerIntent.EXTRA_RESULTS);
+        String spokenText = results.get(0);
+        // Do something with spokenText
+    }
+    super.onActivityResult(requestCode, resultCode, data);
+}
+
    \ No newline at end of file diff --git a/docs/html/training/wearables/data-layer/accessing.jd b/docs/html/training/wearables/data-layer/accessing.jd new file mode 100644 index 0000000000000..4babd0a3ad328 --- /dev/null +++ b/docs/html/training/wearables/data-layer/accessing.jd @@ -0,0 +1,59 @@ +page.title=Accessing the Wearable Data Layer + +@jd:body + +
    +
    + +

    This lesson teaches you to

    +
      +
    1. Set up a Google Play services client to use the Wearable Data Layer APIs
      2. +
    + +

    Dependencies and Prerequisites

    +
      +
    1. Creating + Wearable Apps > Setting up Your Environment
      2. +
    2. Creating + Wearable Apps > Creating a Project
      3. +
    +
    +
    + +

    To call the data layer API, create an instance of +GoogleApiClient, +the main entry point for any of the Google Play services APIs. +

    + +

    +GoogleApiClient +provides a builder that makes it easy to create an instance of the client. +A minimal GoogleApiClient looks like this: +

    + +

    Note: For now, this minimal client is enough to get started. However, see +Accessing Google Play services APIs +for more information about creating aGoogleApiClient, +implementing its callbacks, and handling error cases.

    + +
    +GoogleApiClient mGoogleAppiClient = new GoogleApiClient.Builder(this)
+        .addConnectionCallbacks(new ConnectionCallbacks() {
+                @Override
+                public void onConnected(Bundle connectionHint) {
+                    Log.d(TAG, "onConnected: " + connectionHint);
+                }
+                @Override
+                public void onConnectionSuspended(int cause) {
+                    Log.d(TAG, "onConnectionSuspended: " + cause);
+                }
+        })
+        .addOnConnectionFailedListener(new OnConnectionFailedListener() {
+                @Override
+                public void onConnectionFailed(ConnectionResult result) {
+                    Log.d(TAG, "onConnectionFailed: " + result);
+                }
+            })
+        .addApi(Wearable.API)
+        .build();
+
    \ No newline at end of file diff --git a/docs/html/training/wearables/data-layer/assets.jd b/docs/html/training/wearables/data-layer/assets.jd new file mode 100644 index 0000000000000..73ebb73aaa742 --- /dev/null +++ b/docs/html/training/wearables/data-layer/assets.jd @@ -0,0 +1,123 @@ +page.title=Transferring Assets + +@jd:body + +
    +
    + +

    This lesson teaches you to

    +
      +
    1. Transfer an Asset
      2. +
    2. Receive an Asset
      3. +
    + +
    +
    + +

    +To send large blobs of binary data over the Bluetooth transport, such as images, attach an +Asset to a +data item and the put the data item into the replicated data store. +

    + +

    Assets automatically handle caching of data to prevent retransmission and conserve Bluetooth bandwidth. +A common pattern is for a handheld app to download an image, shrink it to an appropriate size +for display on the wearable, and transmit it to the wearable app as an Asset. The following examples +demonstrates this pattern. +

    + +

    Note: Although the size of data items are limited to 100KB, +assets can be as large as desired. However, transferring large assets affect the +user experience in many cases, so test your apps to ensure that they perform well +if you're transferring large assets. +

    + +

    Transfer an Asset

    +

    Create the asset using one of the create...() methods in the +Asset class. +Here, we convert a bitmap to a byte stream and then call +createFromBytes() +to create the asset. +

    + +
    +private static Asset createAssetFromBitmap(Bitmap bitmap) {
+    final ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
+    bitmap.compress(Bitmap.CompressFormat.PNG, 100, byteStream);
+    return Asset.createFromBytes(byteStream.toByteArray());
+}
+
    + +

    When you have an asset, attach it to a data item with the putAsset() method in + +DataMap +or +PutDataRequest +and then put the data item into the data store with +putDataItem(): +

    + +

    Using PutDataRequest

    +
    +Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.image);
+Asset asset = createAssetFromBitmap(bitmap);
+PutDataRequest request = PutDataRequest.create("/image");
+request.putAsset("profileImage", asset);
+Wearable.DataApi.putDataItem(mGoogleApiClient, request);
+
    + +

    Using PutDataMapRequest

    +
    +Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.image);
+Asset asset = createAssetFromBitmap(bitmap);
+PutDataMapRequest dataMap = PutDataMapRequest.create("/image");
+dataMap.getDataMap().putAsset("profileImage", asset)
+PutDataRequest request = dataMap.asPutDataRequest();
+PendingResult<DataApi.DataItemResult> pendingResult = Wearable.DataApi
+        .putDataItem(mGoogleApiClient, request);
+
    + +

    Receive assets

    + +

    +When an asset is created, you probably want to read and extract +it on other side of the connection. Here's an example of how to implement the +callback to detect an asset change and extract the Asset: +

    + +
    +@Override
+public void onDataChanged(DataEventBuffer dataEvents) {
+  for (DataEvent event : dataEvents) {
+    if (event.getType() == DataEvent.TYPE_CHANGED &&
+        event.getDataItem().getUri().getPath().equals("/image")) {
+      BundleDataItem bundleDataItem = BundleDataItem.fromDataItem(dataItem); 
+      Asset profileAsset = bundleDataItem.getData().getParcelable("profileImage");
+      Bitmap bitmap = loadBitmapFromAsset(profileAsset);
+      // Do something with the bitmap
+    }
+  }
+}
+
+public Bitmap loadBitmapFromAsset(Asset asset) {
+    if (asset == null) {
+        throw new IllegalArgumentException("Asset must be non-null");
+    }
+    ConnectionResult result =
+           mGoogleApiClient.blockingConnect(TIMEOUT_MS, TimeUnit.MILLISECONDS);
+    if (!result.isSuccess()) {
+        return null;
+    }
+    // convert asset into a file descriptor and block until it's ready
+    InputStream assetInputStream = Wearable.DataApi.getFdForAsset(
+            mGoogleApiClient, asset).await().getInputStream();
+            mGoogleApiClient.disconnect();
+
+    if (assetInputStream == null) {
+        Log.w(TAG, "Requested an unknown Asset.");
+        return null;
+    }
+    // decode the stream into a bitmap
+    return BitmapFactory.decodeStream(assetInputStream);
+}
+
    diff --git a/docs/html/training/wearables/data-layer/data-items.jd b/docs/html/training/wearables/data-layer/data-items.jd new file mode 100644 index 0000000000000..c39e37a720691 --- /dev/null +++ b/docs/html/training/wearables/data-layer/data-items.jd @@ -0,0 +1,124 @@ +page.title=Syncing Data Items + +@jd:body + +
    +
    + +

    This lesson teaches you to

    +
      +
    1. Sync Data with a Data Map
      2. +
    2. Listen for Data Item Events
      3. +
    + +
    +
    + +

    +A DataItem +defines the data interface that the system uses to synchronize data between handhelds +and wearables. A DataItem generally +consists of the following items:

    +
      +
    • Payload - A byte array, which you can set with whatever data you wish, allowing you + to do your own object serialization and deserialization. The size of the payload is limited + to 100KB.
      • +
    • Path - A unique string that must start with a forward slash (for instance, + "/path/to/data")
      • +
    + +

    +You normally don't implement DataItem +directly. Instead, you: + +

      +
    1. Create a PutDataRequest object, + specifying a string path to uniquely identify the item. +
      2. +
    2. Call setData() to set + the payload. +
      3. +
    3. Call DataApi.putDataItem() to request the system to create the data item. +
      4. +
    4. When requesting data items, the system returns objects + that properly implement the DataItem interface. +
      5. +
    + +

    +However, instead of working with raw bytes using setData(), +we recommend you use a data map, which exposes +a data item in an easy-to-use {@link android.os.Bundle}-like interface. +

    + +

    Sync Data with a Data Map

    +

    +When possible, use the DataMap class, +which lets you work with data items in the form of an Android {@link android.os.Bundle}, +so object serialization and de-serialization is done for you, and you can manipulate data with key-value pairs. +

    + +

    To use a data map:

    + +
      +
    1. Create a +PutDataMapRequest +object, setting the path of the data item. +

      Note: The path string is a unique identifier for the +data item that allows you to access it from either side of the connection. The path must begin +with a forward slash. If you're using hierarchical data in your +app, you should create a path scheme that matches the structure of the data. +

      +
      2. +
    2. Call +PutDataMapRequest.getDataMap() + to obtain a data map that you can set values on.
      3. +
    3. Set any desired values for the data map using the put...() methods, such as + putString(). +
      4. +
    4. Call PutDataMapRequest.asPutDataRequest() + to obtain a PutDataRequest object. +
      5. +
    5. Call DataApi.putDataItem() to request the system to create the data item. +

      Note: + If the handset and wearable devices are disconnected, + the data is buffered and and synced when the connection is re-established. +

      +
      6. +
    + +

    The following example shows how to create a data map, set data on it, and create it:

    + +
    +PutDataMapRequest dataMap = PutDataMapRequest.create("/count");
+dataMap.getDataMap().putInt(COUNT_KEY, count++);
+PutDataRequest request = dataMap.asPutDataRequest();
+PendingResult<DataApi.DataItemResult> pendingResult = Wearable.DataApi
+        .putDataItem(mGoogleApiClient, request);
+
    + +

    Listen for Data Item Events

    +If one side of the data layer connection changes a data item, you probably want +to be notified of any changes on the other side of the connection. +You can do this by implementing a listener for data item events. + +

    For example, here's what a typical callback looks like to carry out certain actions +when data changes.

    + +
    +@Override
+public void onDataChanged(DataEventBuffer dataEvents) {
+    for (DataEvent event : dataEvents) {
+        if (event.getType() == DataEvent.TYPE_DELETED) {
+            Log.d(TAG, "DataItem deleted: " + event.getDataItem().getUri());
+        } else if (event.getType() == DataEvent.TYPE_CHANGED) {
+             Log.d(TAG, "DataItem changed: " + event.getDataItem().getUri());
+        }
+    }
+}
+
    +

    +This is just a snippet that requires more implementation details. Learn about +how to implement a full listener service or activity in +Listening for Data Layer Events. +

    \ No newline at end of file diff --git a/docs/html/training/wearables/data-layer/events.jd b/docs/html/training/wearables/data-layer/events.jd new file mode 100644 index 0000000000000..0146c4e419769 --- /dev/null +++ b/docs/html/training/wearables/data-layer/events.jd @@ -0,0 +1,312 @@ +page.title=Handling Data Layer Events + +@jd:body + +
    + +
    + +

    When you make calls with the data layer, you can receive the status +of the call when it completes as well as listen for any changes that +the call ends up making with listeners. +

    + +

    Wait for the Status of Data Layer Calls

    + +

    You'll notice that calls to the data layer API sometimes return a +PendingResult, +such as +putDataItem(). +As soon as the PendingResult is created, +the operation is queued in the background. If you do nothing else after this, the operation +eventually completes silently. However, you'll usually want to do something with the result +after the operation completes, so the +PendingResult +lets you wait for the result status, either synchronously or asynchronously. +

    + +

    Asynchronously waiting

    +

    If your code is running on the main UI thread, do not making blocking calls +to the data layer API. You can run the calls asynchronously by adding a callback +to the PendingResult object, +which fires when the operation is completed:

    +
    +pendingResult.setResultCallback(new ResultCallback<DataItemResult>() {
+    @Override
+    public void onResult(final DataItemResult result) {
+        if(result.getStatus().isSuccess()) {
+        Log.d(TAG, "Data item set: " + result.getDataItem().getUri());
+    }
+});
+
    + +

    Synchronously waiting

    +

    If your code is running on a separate handler thread in a background service (which is the case +in a WearableListenerService), +it's fine for the calls to block. In this case, you can call +await() +on the PendingResult object, which will block until the request has completed, and return a Result +object: +

    + +
    +DataItemResult result = pendingResult.await();
+if(result.getStatus().isSuccess()) {
+    Log.d(TAG, "Data item set: " + result.getDataItem().getUri());
+}
+
    + + +

    Listen for Data Layer Events

    +

    Because the data layer synchronizes and sends data across the handheld and +wearable, you normally want to listen for important events, such as when data items +are created, messages are received, or when the wearable and handset are connected. +

    +

    To listen for data layer events, you have two options:

    + + + +

    With both these options, you override any of the data event callbacks that you care about +handling in your implementation.

    + +

    With a WearableListenerService

    + +

    +You typically create instances of this service in both your wearable and handheld apps. If you +don't care about data events in one of these apps, then you don't need to implement this +service in that particular app.

    + +

    For example, you can have a handheld app that sets and gets data item objects and a wearable app +that listens for these updates to update it's UI. The wearable never updates any of the data items, +so the handheld app doesn't listen for any data events from the wearable app.

    + +

    You can listen for the following events with +WearableListenerService:

    + +
      +
    • onDataChanged() +- Called when data item objects are created, changed, or deleted. An event on one side of a connection +triggers an this callback on both sides.
      • +
    • onMessageReceived() +- A message sent from one side of a connection triggers this callback on the other side of the connection.
      • +
    • onPeerConnected() + and onPeerDisconnected() - + Called when connection with the handheld or wearable is connected or disconnected. + Changes in connection state on one side of the connection triggers these callbacks on both sides of the connection. +
      • +
    + +

    To create a WearableListenerService:

    + +
      +
    1. Create a class that extends + WearableListenerService. +
      2. +
    2. Listen for the events that you care about, such as + onDataChanged(). +
      3. +
    3. Declare an intent filter in your Android manifest to notify the system about your + WearableListenerService. + This allows the system to bind your service as needed. +
      4. +
    + +

    The following example shows how to implement a simple + WearableListenerService: +

    + +
    +public class DataLayerListenerService extends WearableListenerService {
+
+    private static final String TAG = "DataLayerSample";
+    private static final String START_ACTIVITY_PATH = "/start-activity";
+    private static final String DATA_ITEM_RECEIVED_PATH = "/data-item-received";
+
+    @Override
+    public void onDataChanged(DataEventBuffer dataEvents) {
+        if (Log.isLoggable(TAG, Log.DEBUG)) {
+            Log.d(TAG, "onDataChanged: " + dataEvents);
+        }
+        final List events = FreezableUtils
+                .freezeIterable(dataEvents);
+
+        GoogleApiClient googleApiClient = new GoogleApiClient.Builder(this)
+                .addApi(Wearable.API)
+                .build();
+
+        ConnectionResult connectionResult =
+                googleApiClient.blockingConnect(30, TimeUnit.SECONDS);
+
+        if (!connectionResult.isSuccess()) {
+            Log.e(TAG, "Failed to connect to GoogleApiClient.");
+            return;
+        }
+
+        // Loop through the events and send a message
+        / to the node that created the data item.
+        for (DataEvent event : events) {
+            Uri uri = event.getDataItem().getUri();
+
+            // Get the node id from the host value of the URI
+            String nodeId = uri.getHost();
+            // Set the data of the message to be the bytes of the URI.
+            byte[] payload = uri.toString().getBytes();
+
+            // Send the RPC
+            Wearable.MessageApi.sendMessage(googleApiClient, nodeId,
+                    DATA_ITEM_RECEIVED_PATH, payload);
+        }
+    }
+}
+
    + +

    Here's the corresponding intent filter in the Android manifest file:

    + +
    +<service android:name=".DataLayerListenerService">
+  <intent-filter>
+      <action android:name="com.google.android.gms.wearable.BIND_LISTENER" />
+  </intent-filter>
+</service>
+
    + + +

    Permissions within Data Layer Callbacks

    + +

    In order to deliver callbacks to your application for data layer events, Google Play services +binds to your WearableListenerService, +and calls your callbacks via IPC. This has the consequence +that your callbacks inherit the permissions of the calling process.

    + +

    If you try to perform a privileged operation within a callback, the security check fails because your callback is +running with the identity of the calling process, instead of the identity of your app's +process.

    + +

    To fix this, call {@link android.os.Binder#clearCallingIdentity} , +to reset identity after crossing the IPC boundary, and then restore identity with +{@link android.os.Binder#restoreCallingIdentity restoreCallingIdentity()} when +you've completed the privileged operation: +

    + +
    +long token = Binder.clearCallingIdentity();
+try {
+    performOperationRequiringPermissions();
+} finally {
+    Binder.restoreCallingIdentity(token);
+}
+
    + +

    With a Listener Activity

    + +

    +If your app only cares about data layer events when the user is interacting +with the app and does not need a long-running service to handle every data +change, you can listen for events in an activity by implementing one or more +of the following interfaces: + +

    +

    + +

    To create an activity that listens for data events:

    +
      +
    1. Implement the desired interfaces.
      2. +
    2. In {@link android.app.Activity#onCreate}, create an instance of +GoogleApiClient +to work with the data layer API. +
    3. +In {@link android.app.Activity#onStart onStart()}, call connect() to connect the client to Google Play services. +
      4. +
    4. When the connection to Google Play services is established, the system calls +onConnected(). This is where you call +DataApi.addListener(), + MessageApi.addListener(), + or NodeApi.addListener() + to notify Google Play services that your activity is interested in listening for data layer events. +
      5. +
    5. In {@link android.app.Activity#onStop onStop()}, unregister any listeners with +DataApi.removeListener(), +MessageApi.removeListener(), +or NodeApi.removeListener(). +
      6. +
    6. Implement onDataChanged(), + onMessageReceived(), + onPeerConnected(), and + onPeerDisconnected(), depending on the interfaces that you implemented. +
      7. +
    + +

    Here's an example that implements +DataApi.DataListener:

    + +
    +public class MainActivity extends Activity implements
+        DataApi.DataListener, ConnectionCallbacks, OnConnectionFailedListener {
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+
+        setContentView(R.layout.main);
+        mGoogleApiClient = new GoogleApiClient.Builder(this)
+                .addApi(Wearable.API)
+                .addConnectionCallbacks(this)
+                .addOnConnectionFailedListener(this)
+                .build();
+    }
+
+    @Override
+    protected void onStart() {
+        super.onStart();
+        if (!mResolvingError) {
+            mGoogleApiClient.connect();
+        }
+    }
+
+   @Override
+    public void onConnected(Bundle connectionHint) {
+        if (Log.isLoggable(TAG, Log.DEBUG)) {
+            Log.d(TAG, "Connected to Google Api Service");
+        }
+        Wearable.DataApi.addListener(mGoogleApiClient, this);
+    }
+
+    @Override
+    protected void onStop() {
+        if (null != mGoogleApiClient && mGoogleApiClient.isConnected()) {
+            Wearable.NodeApi.removeListener(mGoogleApiClient, this);
+            mGoogleApiClient.disconnect();
+        }
+        super.onStop();
+    }
+
+    @Override
+    public void onDataChanged(DataEventBuffer dataEvents) {
+        for (DataEvent event : dataEvents) {
+            if (event.getType() == DataEvent.TYPE_DELETED) {
+                Log.d(TAG, "DataItem deleted: " + event.getDataItem().getUri());
+            } else if (event.getType() == DataEvent.TYPE_CHANGED) {
+                 Log.d(TAG, "DataItem changed: " + event.getDataItem().getUri());
+            }
+        }
+    }
+
    \ No newline at end of file diff --git a/docs/html/training/wearables/data-layer/index.jd b/docs/html/training/wearables/data-layer/index.jd new file mode 100644 index 0000000000000..3e06df1ec84bc --- /dev/null +++ b/docs/html/training/wearables/data-layer/index.jd @@ -0,0 +1,87 @@ +page.title=Sending and Syncing Data +@jd:body + +
    +
    + + +

    Dependencies and prerequisites

    +
      +
    • Android 4.3 (API Level 18) or higher on the handset device
      • +
    • The latest version of Google Play services
      • +
    • An Android Wear device or Wear AVD
      • +
    +
    +
    + +

    +The Wearable Data Layer API, which is part of Google Play services, provides a communication channel +for your handheld and wearable apps. The API consists of a set of data objects that the system can +send and synchronize over the wire and listeners that notify your apps of important events with +the data layer:

    + +
    +
    Data Items
    +
    A DataItem + provides data storage with automatic syncing between the handheld and + wearable.
    + +
    Messages
    +
    The MessageApi class + can send messages designed for "fire-and-forget" commands, such as controlling a handheld's + media player from the wearable or starting an intent on the wearable from the handheld. + The system always delivers the message when the handheld and wearable are connected and delivers + an error when the devices are disconnected. Messages are great for one-way requests or for a + request/response communication model.
    + +
    Asset
    +
    Asset objects are for + sending binary blobs of data, such as images. You attach assets to data items and the system + automatically takes care of the transfer for you, conserving Bluetooth bandwidth by caching large assets + to avoid re-transmission.
    + +
    WearableListenerService (for services)
    +

    Extending WearableListenerService + lets you listen for important data layer events in a service. The system manages the lifecycle of + the WearableListenerService, + binding to the service when it needs to send data items or messages and unbinding the service when no work is needed.

    +
    + +
    DataListener (for foreground activities)
    +
    + Implementing DataListener + in an activity lets you listen for important data layer events when an activity + is in the foreground. Using this instead of the + WearableListenerService + lets you listen for changes only when the user is actively using your app. +
    +
    + +

    Warning: +Because these APIs are designed for communication between handhelds and wearables, +these are the only APIs you should use to set up communication between these +devices. For instance, don't try to open low-level sockets to create a communication +channel. +

    + +

    Lessons

    +
    +
    Accessing the Wearable Data Layer
    +
    This lesson shows you how to create a client to access the Data Layer APIs.
    + +
    Syncing Data Items
    +
    Data items are objects that are stored in a replicated data store that is automatically + synced from handhelds to wearables.
    + +
    Transferring Assets
    +
    Assets are binary blobs of data that you typically use to transfer images or media.
    + +
    Sending and Receiving Messages
    +
    Messages are designed for fire-and-forget messages that you can send back and forth + between the wearable and handheld.
    + +
    Handling Data Layer Events
    +
    Be notified of changes and events to the data layer.
    +
    + +
    \ No newline at end of file diff --git a/docs/html/training/wearables/data-layer/messages.jd b/docs/html/training/wearables/data-layer/messages.jd new file mode 100644 index 0000000000000..a9dec75756acc --- /dev/null +++ b/docs/html/training/wearables/data-layer/messages.jd @@ -0,0 +1,99 @@ +page.title=Sending and Receiving Messages + +@jd:body + +
    +
    + +

    This lesson teaches you to

    +
      +
    1. Send a Message
      2. +
    2. Receive a Message
      3. +
    +
    +
    + +

    You send messages using the +MessageApi +and attach the following items to the message:

    + + +

    +Unlike data items, there is no syncing between the handheld and wearable apps. +Messages are a one-way communication mechanism that's meant for +"fire-and-forget" tasks, such as sending a message to the wearable +to start an activity. You can also use messages in request/response model +where one side of the connection sends a message, does some work, +sends back a response message.

    + +

    Send a Message

    + +

    The following example shows how to send a message that indicates to the other +side of the connect to start an activity. +This call is made synchronously, which blocks until the message +is received or when the request times out: +

    + +

    Note: Read more about asynchronous and synchronous calls +to Google Play services and when to use each in +Communicate with Google Play Services. +

    + +
    +Node node; // the connected device to send the message to
+GoogleApiClient mGoogleApiClient;
+public static final START_ACTIVITY_PATH = "/start/MainActivity";
+...
+
+    SendMessageResult result = Wearable.MessageApi.sendMessage(
+            mGoogleApiClient, node, START_ACTIVITY_PATH, null).await();
+    if (!result.getStatus().isSuccess()) {
+        Log.e(TAG, "ERROR: failed to send Message: " + result.getStatus());
+    }
+
    + +

    +Here's a simple way to get a list of connected nodes that you can potentially +send messages to:

    + +
    +private Collection<String> getNodes() {
+    HashSet <String>results= new HashSet<String>();
+    NodeApi.GetConnectedNodesResult nodes =
+            Wearable.NodeApi.getConnectedNodes(mGoogleApiClient).await();
+    for (Node node : nodes.getNodes()) {
+        results.add(node.getId());
+    }
+    return results;
+}
+
    + +

    Receiving a Message

    + +

    + +To be notified of received messages, you implement a listener for message events. +This example shows how you might do this by checking the START_ACTIVITY_PATH +that the previous example used to send the message. If this condition is true, +a specific activity is started. +

    + +
    +@Override
+public void onMessageReceived(MessageEvent messageEvent) {
+    if (messageEvent.getPath().equals(START_ACTIVITY_PATH)) {
+        Intent startIntent = new Intent(this, MainActivity.class);
+        startIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+        startActivity(startIntent);
+    }
+}
+
    + +

    +This is just a snippet that requires more implementation details. Learn about +how to implement a full listener service or activity in +Listening for Data Layer Events. +

    \ No newline at end of file diff --git a/docs/html/training/wearables/notifications/creating.jd b/docs/html/training/wearables/notifications/creating.jd new file mode 100644 index 0000000000000..174cd82cd977a --- /dev/null +++ b/docs/html/training/wearables/notifications/creating.jd @@ -0,0 +1,295 @@ +page.title=Creating a Notification + +@jd:body + + + +

    To build handheld notifications that are also sent to wearables, use +{@link android.support.v4.app.NotificationCompat.Builder}. When you build +notifications with this class, the system takes care of displaying +notifications properly, whether they appear on a handheld or wearable. +

    + +

    Note: +Notifications using {@link android.widget.RemoteViews} are stripped of custom +layouts and the wearable only displays the text and icons. However, you can create +create custom notifications +that use custom card layouts by creating a wearable app that runs on the wearable device.

    + + +

    Import the necessary classes

    +

    Before you begin, import the necessary classes from the support library:

    + +
    +import android.support.v4.app.NotificationCompat;
+import android.support.v4.app.NotificationManagerCompat;
+import android.support.v4.app.NotificationCompat.WearableExtender;
+
    + +

    Create Notifications with the Notification Builder

    + +

    The v4 +support library allows you to create notifications using the latest notification features +such as action buttons and large icons, while remaining compatible with Android 1.6 (API level +4) and higher.

    + +

    To create a notification with the support library, you create an instance of +{@link android.support.v4.app.NotificationCompat.Builder} and issue the notification by +passing it to {@link android.support.v4.app.NotificationManagerCompat#notify notify()}. For example: +

    + +
    +int notificationId = 001;
+// Build intent for notification content
+Intent viewIntent = new Intent(this, ViewEventActivity.class);
+viewIntent.putExtra(EXTRA_EVENT_ID, eventId);
+PendingIntent viewPendingIntent =
+        PendingIntent.getActivity(this, 0, viewIntent, 0);
+
+NotificationCompat.Builder notificationBuilder =
+        new NotificationCompat.Builder(this)
+        .setSmallIcon(R.drawable.ic_event)
+        .setContentTitle(eventTitle)
+        .setContentText(eventLocation)
+        .setContentIntent(viewPendingIntent);
+
+// Get an instance of the NotificationManager service
+NotificationManagerCompat notificationManager =
+        NotificationManagerCompat.from(this);
+
+// Build the notification and issues it with notification manager.
+notificationManager.notify(notificationId, notificationBuilder.build());
+
    + +

    When this notification appears on a handheld device, the user can invoke the +{@link android.app.PendingIntent} +specified by the {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent +setContentIntent()} method by touching the notification. When this +notification appears on an Android wearable, the user can swipe the notification to the left to +reveal the Open action, which invokes the intent on the handheld device.

    + + + + +

    Add Action Buttons

    + +

    In addition to the primary content action defined by +{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent +setContentIntent()}, you can add other actions by passing a {@link android.app.PendingIntent} to +the {@link android.support.v4.app.NotificationCompat.Builder#addAction addAction()} method.

    + +

    For example, the following code shows the same type of notification from above, but adds an +action to view the event location on a map.

    + +
    +// Build an intent for an action to view a map
+Intent mapIntent = new Intent(Intent.ACTION_VIEW);
+Uri geoUri = Uri.parse("geo:0,0?q=" + Uri.encode(location));
+mapIntent.setData(geoUri);
+PendingIntent mapPendingIntent =
+        PendingIntent.getActivity(this, 0, mapIntent, 0);
+
+NotificationCompat.Builder notificationBuilder =
+        new NotificationCompat.Builder(this)
+        .setSmallIcon(R.drawable.ic_event)
+        .setContentTitle(eventTitle)
+        .setContentText(eventLocation)
+        .setContentIntent(viewPendingIntent)
+        .addAction(R.drawable.ic_map,
+                getString(R.string.map), mapPendingIntent);
+
    + +

    On a handheld, the action appears as an +additional button attached to the notification. On a wearable, the action appears as +a large button when the user swipes the notification to the left. When the user taps the action, +the associated intent is invoked on the handheld.

    + +

    Tip: If your notifications include a "Reply" action + (such as for a messaging app), you can enhance the behavior by enabling + voice input replies directly from the Android wearable. For more information, read + Receiving Remote Input from + a Notification. +

    + +

    Specify Wearable-only Actions

    + +

    +If you want the actions available on the wearable to be different from those on the handheld, +then use {@link android.support.v4.app.NotificationCompat.WearableExtender#addAction WearableExtender.addAction()}. +Once you add an action with this method, the wearable does not display any other actions added with +{@link android.support.v4.app.NotificationCompat.Builder#addAction NotificationCompat.Builder.addAction()}. +That is, only the actions added with {@link android.support.v4.app.NotificationCompat.WearableExtender#addAction WearableExtender.addAction()} appear on the wearable and they do not appear on the handheld. +

    + +
    +// Create an intent for the reply action
+Intent actionIntent = new Intent(this, ActionActivity.class);
+PendingIntent actionPendingIntent =
+        PendingIntent.getActivity(this, 0, actionIntent,
+                PendingIntent.FLAG_UPDATE_CURRENT);
+
+// Create the action
+NotificationCompat.Action action =
+        new NotificationCompat.Action.Builder(R.drawable.ic_action,
+                getString(R.string.label, actionPendingIntent))
+                .build();
+
+// Build the notification and add the action via WearableExtender
+Notification notification =
+        new NotificationCompat.Builder(mContext)
+                .setSmallIcon(R.drawable.ic_message)
+                .setContentTitle(getString(R.string.title))
+                .setContentText(getString(R.string.content))
+                .extend(new WearableExtender().addAction(action))
+                .build();
+
    +

    Add a Big View

    + + + +

    You can insert extended text content +to your notification by adding one of the "big view" styles to your notification. On a +handheld device, users can see the big view content by expanding the notification. On +a wearable device, the big view content is visible by default.

    + +

    To add the extended content to your notification, call {@link +android.support.v4.app.NotificationCompat.Builder#setStyle setStyle()} on the {@link +android.support.v4.app.NotificationCompat.Builder} object, passing it an instance of either +{@link android.support.v4.app.NotificationCompat.BigTextStyle BigTextStyle} or +{@link android.support.v4.app.NotificationCompat.InboxStyle InboxStyle}.

    + +

    For example, the following code adds an instance of +{@link android.support.v4.app.NotificationCompat.BigTextStyle} to the event notification, +in order to include the complete event description (which includes more text than can fit +into the space provided for {@link android.support.v4.app.NotificationCompat.Builder#setContentText +setContentText()}).

    + +
    +// Specify the 'big view' content to display the long
+// event description that may not fit the normal content text.
+BigTextStyle bigStyle = new NotificationCompat.BigTextStyle();
+bigStyle.bigText(eventDescription);
+
+NotificationCompat.Builder notificationBuilder =
+        new NotificationCompat.Builder(this)
+        .setSmallIcon(R.drawable.ic_event)
+        .setLargeIcon(BitmapFractory.decodeResource(
+                getResources(), R.drawable.notif_background))
+        .setContentTitle(eventTitle)
+        .setContentText(eventLocation)
+        .setContentIntent(viewPendingIntent)
+        .addAction(R.drawable.ic_map,
+                getString(R.string.map), mapPendingIntent)
+        .setStyle(bigStyle);
+
    + +

    Notice that you can add a large background image to any notification using the +{@link android.support.v4.app.NotificationCompat.Builder#setLargeIcon setLargeIcon()} +method. For more information about designing notifications with large images, see the +Design Principles of Android +Wear.

    + +

    Add Wearable Features For a Notification

    + +

    If you ever need to add wearable-specific options to a notification, such as specifying additional +pages of content or letting users dictate a text response with voice input, you can use the +{@link android.support.v4.app.NotificationCompat.WearableExtender} class to +specify the options. To use this API:

    + +
      +
    1. Create an instance of a {@link android.support.v4.app.NotificationCompat.WearableExtender WearableExtender}, + setting the wearable-specific options for the notication.
      2. +
    2. Create an instance of + {@link android.support.v4.app.NotificationCompat.Builder}, setting the + desired properties for your notification as described earlier in this lesson.
      3. +
    3. Call {@link android.support.v4.app.NotificationCompat.Builder#extend extend()} on + the notification and pass in the + {@link android.support.v4.app.NotificationCompat.WearableExtender WearableExtender}. This applies + the wearable options to the notification.
      4. +
    4. Call {@link android.support.v4.app.NotificationCompat.Builder#build} to build the notification.
      5. +
    + +

    +For example, the following code calls the +{@link android.support.v4.app.NotificationCompat.WearableExtender#setHintHideIcon setHintHideIcon()} +method to remove the app icon from the notification card. +

    + +
    +// Create a WearableExtender to add functionality for wearables
+NotificationCompat.WearableExtender wearableExtender =
+        new NotificationCompat.WearableExtender()
+        .setHintHideIcon(true);
+
+// Create a NotificationCompat.Builder to build a standard notification
+// then extend it with the WearableExtender
+Notification notif = new NotificationCompat.Builder(mContext)
+        .setContentTitle("New mail from " + sender)
+        .setContentText(subject)
+        .setSmallIcon(R.drawable.new_mail);
+        .extend(wearableExtender)
+        .build();
+
    + +

    The + {@link android.support.v4.app.NotificationCompat.WearableExtender#setHintHideIcon setHintHideIcon()} + method is just one example of new notification features available with + {@link android.support.v4.app.NotificationCompat.WearableExtender}. +

    + +

    If you ever need to read wearable-specifc options at a later time, use the corresponding get +method for the option. This example calls the +{@link android.support.v4.app.NotificationCompat.WearableExtender#getHintHideIcon()} method to +get whether or not this notification hides the icon: +

    +NotificationCompat.WearableExtender wearableExtender =
+        new NotificationCompat.WearableExtender(notif);
+boolean hintHideIcon = wearableExtender.getHintHideIcon();
+
    + +

    Deliver the Notification

    +

    When you want to deliver your notifications, always use the + {@link android.support.v4.app.NotificationManagerCompat} API instead of + {@link android.app.NotificationManager}:

    + +
    +// Get an instance of the NotificationManager service
+NotificationManagerCompat notificationManager =
+        NotificationManagerCompat.from(mContext);
+
+// Issue the notification with notification manager.
+notificationManager.notify(notificationId, notif);
+
    + +

    If you use the framework's {@link android.app.NotificationManager}, some +features from {@link android.support.v4.app.NotificationCompat.WearableExtender} +do not work, so make sure to use {@link android.support.v4.app.NotificationCompat}. +

    + +
    +NotificationCompat.WearableExtender wearableExtender =
+        new NotificationCompat.WearableExtender(notif);
+boolean hintHideIcon = wearableExtender.getHintHideIcon();
+
    + +

    The {@link android.support.v4.app.NotificationCompat.WearableExtender} APIs allow you to add +additional pages to notifications, stack notifications, and more. Continue to the following lessons +to learn about these features. +

    \ No newline at end of file diff --git a/docs/html/training/wearables/notifications/index.jd b/docs/html/training/wearables/notifications/index.jd new file mode 100644 index 0000000000000..b9ed6fb9b9262 --- /dev/null +++ b/docs/html/training/wearables/notifications/index.jd @@ -0,0 +1,51 @@ +page.title=Adding Wearable Features to Notifications +@jd:body + +
    +
    + +

    Dependencies and prerequisites

    + +

    You should also read

    +     +
    +
    + +

    When an Android handheld (phone or tablet) and Android wearable are connected, the handheld +automatically shares notifications with the wearable. On the wearable, each +notification appears as a new card in the context stream.

    + +

    However, to give users the best experience, you should add wearable-specific functionality to the +notifications you already create. The following lessons show you how to +create notifications that are catered for handhelds and wearables at the same time. +

    + + + +

    Figure 1. The same notification displayed on a handheld and wearable.

    + +

    Lessons

    +
    +
    Creating a notification
    +
    Learn how to create notifications with wearable features with the Android support library.
    +
    Receiving Remote Input +from a Notification
    +
    Learn how to add an action to a wearable notification that receives voice input from users and delivers + the transcribed message to your handset app.
    +
    Adding Pages to a Notification
    +
    Learn how to add additional pages of information that are visible when the user +swipes to the left.
    +
    Stacking Notifications
    +
    Learn how to place all similar notifications from your app in a stack, allowing users to view + each notification individually without adding multiple cards to the card stream.
    +
    + + \ No newline at end of file diff --git a/docs/html/training/wearables/notifications/pages.jd b/docs/html/training/wearables/notifications/pages.jd new file mode 100644 index 0000000000000..102677421814d --- /dev/null +++ b/docs/html/training/wearables/notifications/pages.jd @@ -0,0 +1,71 @@ +page.title=Adding Pages to a Notification + +@jd:body + +
    +
    + +

    This lesson teaches you to

    +
      +
    1. Add Pages to a Notification
      2. +
    +
    +
    + +

    When you'd like to provide more information without requiring users +to open your app on their handheld device, you can +add one or more pages to the notification on the wearable. The additional pages +appear immediately to the right of the main notification card. +

    + + + + +

    To create a notification with multiple pages:

    +
      +
    1. Create the main notification (the first page) with + {@link android.support.v4.app.NotificationCompat.Builder}, + in the way you'd like the notification to appear on a handset.
      2. +
    2. Create the additional pages for the wearable with + {@link android.support.v4.app.NotificationCompat.Builder}.
      3. +
    3. Apply the pages to the main notification with the + {@link android.support.v4.app.NotificationCompat.WearableExtender#addPage addPage()} + method or add multiple pages in a {@link java.util.Collection} with the + {@link android.support.v4.app.NotificationCompat.WearableExtender#addPage addPages()} method. +
      4. +
    + +

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

    + +
    +// Create builder for the main notification
+NotificationCompat.Builder notificationBuilder =
+        new NotificationCompat.Builder(this)
+        .setSmallIcon(R.drawable.new_message)
+        .setContentTitle("Page 1")
+        .setContentText("Short message")
+        .setContentIntent(viewPendingIntent);
+
+// Create a big text style for the second page
+BigTextStyle secondPageStyle = new NotificationCompat.BigTextStyle();
+secondPageStyle.setBigContentTitle("Page 2")
+               .bigText("A lot of text...");
+
+// Create second page notification
+Notification secondPageNotification =
+        new NotificationCompat.Builder(this)
+        .setStyle(secondPageStyle)
+        .build();
+
+// Add second page with wearable extender and extend the main notification
+Notification twoPageNotification =
+        new WearableExtender()
+                .addPage(secondPageNotification)
+                .extend(notificationBuilder)
+                .build();
+
+// Issue the notification
+    notificationManager =
+            NotificationManagerCompat.from(this);
+    notificationManager.notify(notificationId, twoPageNotification);
+
    \ No newline at end of file diff --git a/docs/html/wear/notifications/stacks.jd b/docs/html/training/wearables/notifications/stacks.jd similarity index 54% rename from docs/html/wear/notifications/stacks.jd rename to docs/html/training/wearables/notifications/stacks.jd index 3c3dc09c266bd..e71e74c098e34 100644 --- a/docs/html/wear/notifications/stacks.jd +++ b/docs/html/training/wearables/notifications/stacks.jd @@ -2,9 +2,21 @@ page.title=Stacking Notifications @jd:body - - +
    +
    +

    This lesson teaches you to

    +
      +
    1. Add Each Notification to a Group
      2. +
    2. Add a Summary Notification
      3. +
    + +
    +
    + +

    When creating notifications for a handheld device, you should always aggregate similar notifications into a single summary notification. For example, if your app creates notifications for received messages, you should not show more than one notification @@ -16,36 +28,25 @@ are not able to read details from each message on the wearable (they must open y handheld to view more information). So for the wearable device, you should group all the notifications together in a stack. The stack of notifications appears as a single card, which users can expand to view the details from each notification separately. The new - -setGroup() method makes this possible while allowing you to still provide -only one summary notification on the handheld device.

    +{@link android.support.v4.app.NotificationCompat.Builder#setGroup setGroup()} method makes this +possible while allowing you to still provide only one summary notification on the handheld device.

    -

    For details about designing notification stacks, see the -Design Principles of Android -Wear.

    +

    Add Each Notification to a Group

    - -

    Add Each Notification to a Group

    - -

    To create a stack, call -setGroup() for each notification you want in the stack and specify a -group key. Then call notify() to send it to the wearable.

    +

    To create a stack, call {@link android.support.v4.app.NotificationCompat.Builder#setGroup setGroup()} +for each notification you want in the stack and specify a +group key. Then call {@link android.support.v4.app.NotificationManagerCompat#notify notify()} +to send it to the wearable.

     final static String GROUP_KEY_EMAILS = "group_key_emails";
 
-// Build the notification
-NotificationCompat.Builder builder = new NotificationCompat.Builder(mContext)
+// Build the notification, setting the group appropriately
+Notification notif = new NotificationCompat.Builder(mContext)
          .setContentTitle("New mail from " + sender1)
          .setContentText(subject1)
          .setSmallIcon(R.drawable.new_mail);
-
-// Set the group with WearableNotificationOptions.Builder and apply to the notification
-Notification notif1 = new WearableNotificationOptions.Builder()
          .setGroup(GROUP_KEY_EMAILS)
-         .build()
-         .applyTo(builder)
          .build();
 
 // Issue the notification
@@ -56,31 +57,24 @@ notificationManager.notify(notificationId1, notif);
 
 
    Later on, when you create another notification, specify
 the same group key. When you call
-notify(),
+{@link android.support.v4.app.NotificationManagerCompat#notify notify()},
 this notification appears in the same stack as the previous notification,
 instead of as a new card:
    
 
 
    -builder = new NotificationCompat.Builder(mContext)
+Notification notif2 = new NotificationCompat.Builder(mContext)
          .setContentTitle("New mail from " + sender2)
          .setContentText(subject2)
          .setSmallIcon(R.drawable.new_mail);
-
-// Use the same group as the previous notification
-Notification notif2 = new WearableNotificationOptions.Builder()
          .setGroup(GROUP_KEY_EMAILS)
-         .build()
-         .applyTo(builder)
          .build();
 
-notificationManager.notify(notificationId2, notif);
+notificationManager.notify(notificationId2, notif2);
 
    
 
 
    By default, notifications appear in the order in which you added them, with the most recent
-  notification visible at the top.  You can define a specific position in the group
-  by passing an order position as the second parameter for 
-setGroup().
    
+  notification visible at the top.  You can order notifications in another fashion by calling
+  {@link android.support.v4.app.NotificationCompat.Builder#setSortKey setSortKey()}.
    
 
 
 
    Add a Summary Notification
    
@@ -89,8 +83,8 @@ href="{@docRoot}reference/android/support/wearable/notifications/WearableNotific
 
 
    It's important that you still provide a summary notification that appears on handheld devices.
 So in addition to adding each unique notification to the same stack group, also add a summary
-notification, but set its order position to be GROUP_ORDER_SUMMARY.
    
+notification and call {@link android.support.v4.app.NotificationCompat.Builder#setGroupSummary setGroupSummary()}
+on the summary notification.
    
 
 
    This notification does not appear in your stack of notifications on the wearable, but
 appears as the only notification on the handheld device.
    
@@ -100,7 +94,7 @@ Bitmap largeIcon = BitmapFactory.decodeResource(getResources(),
         R.drawable.ic_large_icon);
 
 // Create an InboxStyle notification
-builder = new NotificationCompat.Builder(this)
+Notification summaryNotification = new NotificationCompat.Builder(mContext)
         .setContentTitle("2 new messages")
         .setSmallIcon(R.drawable.ic_small_icon)
         .setLargeIcon(largeIcon)
@@ -108,13 +102,9 @@ builder = new NotificationCompat.Builder(this)
                 .addLine("Alex Faaborg   Check this out")
                 .addLine("Jeff Chang   Launch Party")
                 .setBigContentTitle("2 new messages")
-                .setSummaryText("johndoe@gmail.com"));
-
-// Specify the notification to be the group summary
-Notification summaryNotification = new WearableNotificationOptions.Builder()
-        .setGroupSummary(GROUP_KEY_EMAILS)
-        .build()
-        .applyTo(builder)
+                .setSummaryText("johndoe@gmail.com"))
+        .setGroup(GROUP_KEY_EMAILS)
+        .setGroupSummary(true)
         .build();
 
 notificationManager.notify(notificationId3, summaryNotification);
@@ -134,5 +124,31 @@ with HTML markup and
 Styling
 with Spannables.
 
    
-
-
\ No newline at end of file
+
+
    Summary notifications can also affect notifications on wearables without being displayed on them.
+When creating a summary notification, you can use the
+{@link android.support.v4.app.NotificationCompat.WearableExtender} class and call
+{@link android.support.v4.app.NotificationCompat.WearableExtender#setBackground setBackground()} or
+{@link android.support.v4.app.NotificationCompat.WearableExtender#addAction addAction()} to set
+a background image or an action that applies to the entire stack on the wearable. For instance,
+to set the background for an entire stack of notifications:
+
    
+
+
    +Bitmap background = BitmapFactory.decodeResource(getResources(),
+        R.drawable.ic_background);
+
+NotificationCompat.WearableExtender wearableExtender =
+        new NotificationCompat.WearableExtender()
+        .setBackground(background);
+
+// Create an InboxStyle notification
+Notification summaryNotificationWithBackground =
+        new NotificationCompat.Builder(mContext)
+        .setContentTitle("2 new messages")
+        ...
+        .extend(wearableExtender)
+        .setGroup(GROUP_KEY_EMAILS)
+        .setGroupSummary(true)
+        .build();
+
    
\ No newline at end of file
diff --git a/docs/html/training/wearables/notifications/voice-input.jd b/docs/html/training/wearables/notifications/voice-input.jd
new file mode 100644
index 0000000000000..976bd8656952c
--- /dev/null
+++ b/docs/html/training/wearables/notifications/voice-input.jd
@@ -0,0 +1,175 @@
+page.title=Receiving Voice Input in a Notification
+
+@jd:body
+
+
+
+
    If you have handheld notifications that include an action to input text,
+such as reply to an email, it should normally launch an activity
+on the handheld device to input the text. However, when your notification appears on a wearable,
+there is no keyboard input, so you can let users dictate a reply or provide pre-defined text messages
+using {@link android.support.v4.app.RemoteInput}.
+
    
+
+
    When users reply with voice or select one of the available
+messages, the system attaches the text response to the {@link android.content.Intent} you specified
+for the notification action and sends that intent to your handheld app.
    
+
+
+
+
+
    Note: The Android emulator does not support voice input. When
+using the emulator for a wearable device, enable Hardware keyboard present in the AVD settings
+so you can type replies instead.
    
+
+
    Define the Voice Input
    
+
+
    To create an action that supports voice input, create an instance of 
+  {@link android.support.v4.app.RemoteInput.Builder} that you can add to your notification action.
+  This class's constructor accepts a string that the system uses as
+  the key for the voice input, which you'll later use to retrieve the text of the
+  input in your handheld app.
    
+
+
    For example, here's how to create a
+{@link android.support.v4.app.RemoteInput} object that provides a custom
+label for the voice input prompt:
    
+
+
    +// Key for the string that's delivered in the action's intent
+private static final String EXTRA_VOICE_REPLY = "extra_voice_reply";
+
+String replyLabel = getResources().getString(R.string.reply_label);
+
+RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
+        .setLabel(replyLabel)
+        .build();
+
    
+
+
+
    Add Pre-defined Text Responses
    
+
+
+
+
    In addition to allowing voice input, you can
+    provide up to five text responses that the user can select for quick replies. Call
+ {@link android.support.v4.app.RemoteInput.Builder#setChoices setChoices()} and pass it a string array.
    
+
+
    For example, you can define some responses in a resource array:
    
+
+
    res/values/strings.xml
+
    +<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string-array name="reply_choices">
+        <item>Yes</item>
+        <item>No</item>
+        <item>Maybe</item>
+    </string-array>
+</resources>
+
    
+
+
    Then, inflate the string array and add it to the
+ {@link android.support.v4.app.RemoteInput}:
    
+
+
    +public static final EXTRA_VOICE_REPLY = "extra_voice_reply";
+...
+String replyLabel = getResources().getString(R.string.reply_label);
+String[] replyChoices = getResources().getStringArray(R.array.reply_choices);
+
+RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
+        .setLabel(replyLabel)
+        .setChoices(replyChoices)
+        .build();
+
    
+
+
    Add the Voice Input as a Notification Action
    
+
+
    
+To set the voice input, attach your
+{@link android.support.v4.app.RemoteInput} object to an action using
+{@link android.support.v4.app.NotificationCompat.Action.Builder#addRemoteInput addRemoteInput()}.
+You can then apply the action to the notification. For example:
+
    
+
+
    +// Create an intent for the reply action
+Intent replyIntent = new Intent(this, ReplyActivity.class);
+PendingIntent replyPendingIntent =
+        PendingIntent.getActivity(this, 0, replyIntent,
+                PendingIntent.FLAG_UPDATE_CURRENT);
+
+// Create the reply action and add the remote input
+NotificationCompat.Action action =
+        new NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
+                getString(R.string.label, replyPendingIntent))
+                .addRemoteInput(remoteInput)
+                .build();
+
+// Build the notification and add the action via WearableExtender
+Notification notification =
+        new NotificationCompat.Builder(mContext)
+                .setSmallIcon(R.drawable.ic_message)
+                .setContentTitle(getString(R.string.title))
+                .setContentText(getString(R.string.content))
+                .extend(new WearableExtender().addAction(action))
+                .build();
+
+// Issue the notification
+NotificationManagerCompat notificationManager =
+        NotificationManagerCompat.from(mContext);
+notificationManager.notify(notificationId, notification);
+
    
+
    
+When you issue this notification, users can swipe to the left to see the "Reply" action button.
+
    
+
+
    Receiving the Voice Input as a String
    
+
    
+To receive the user's transcribed message in the activity you declared in the reply action's intent,
+call {@link android.support.v4.app.RemoteInput#getResultsFromIntent getResultsFromIntent()},
+passing in the "Reply" action's intent. This method returns a {@link android.os.Bundle} that
+contains the text response. You can then query the {@link android.os.Bundle} to obtain the response.
+
+
    Note: Do not use {@link android.content.Intent#getExtras Intent.getExtras()}
+to obtain the voice result, because the voice input is stored as
+{@link android.content.ClipData}. The {@link android.support.v4.app.RemoteInput#getResultsFromIntent
+getResultsFromIntent()} method provides a convenient way to receive a character sequence without
+having to process the {@link android.content.ClipData} yourself.
+
    
+
+
    
+The following code shows a method that accepts an intent and returns the voice response,
+which is referenced by the EXTRA_VOICE_REPLY key that is used in the previous examples:
+
    
+
+
    +/**
+ * 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 CharSequence getMessageText(Intent intent) {
+    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
+        if (remoteInput != null) {
+            return remoteInput.getCharSequence(EXTRA_VOICE_REPLY);
+        }
+    }
+    return null;
+}
+
    
\ No newline at end of file
diff --git a/docs/html/wear/notifications/creating.jd b/docs/html/wear/notifications/creating.jd
deleted file mode 100644
index a5d7da711bae2..0000000000000
--- a/docs/html/wear/notifications/creating.jd
+++ /dev/null
@@ -1,305 +0,0 @@
-page.title=Creating Notifications for Android Wear
-
-@jd:body
-
-
-
    When an Android device such as a phone or tablet is connected to an Android wearable,
-all notifications are shared between the devices by default. On the Android wearable, each
-notification appears as a new card in the context stream.
    
-
-
-
-
-
    So without any effort, your app notifications are available to users on Android Wear.
-However, you can enhance the user experience in several ways. For instance,
-if users may respond to a notification by entering text, such as to reply to
-a message, you can add the ability for users to reply by voice directly from the
-wearable.
    
-
-
    To help you provide the best user experience
-for your notifications on Android Wear, this guide shows you how to
-build notifications using standard templates in
-the {@link android.support.v4.app.NotificationCompat.Builder} APIs, plus how to begin
-extending your notification's capabilities for the wearable user experience.
    
-
-
    Note:
-Notifications using {@link android.widget.RemoteViews} are stripped of custom
-layouts and the system uses only the text and icons in the
-{@link android.app.Notification} object to
-display the notification in a card. However, custom card layouts will be supported by
-the official Android Wear SDK that is coming later.
    
-
-
-
-
-
-
    Import the Necessary Classes
    
-
-
    To begin development, you must first complete the instructions in the Get Started with the Developer Preview document.
-As mentioned in that document, your app must include
-both the v4 support
-library and the Developer Preview support library. So to get started,
-you should include the following imports in your project code:
    
-
-
    -import android.support.wearable.notifications.*;
-import android.support.wearable.app.NotificationManagerCompat;
-import android.support.v4.app.NotificationCompat;
-
    
-
-
    Caution:
-The APIs in the current Android Wear Developer Preview are intended for development and testing purposes only, not for production apps. Google may change this Developer Preview significantly prior to the official release of the Android Wear SDK. You may not publicly distribute or ship any application using this Developer Preview, as this Developer Preview will no longer be supported after the official SDK is released (which will cause applications based only on the Developer Preview to break).
    
-
-
-
-
    Create Notifications with the Notification Builder
    
-
-
    The v4
-support library allows you to create notifications using the latest notification features
-such as action buttons and large icons, while remaining compatible with Android 1.6 (API level
-4) and higher.
    
-
-
-
    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
-
-NotificationManagerCompat API:
    
-
-
-
    -int notificationId = 001;
-// Build intent for notification content
-Intent viewIntent = new Intent(this, ViewEventActivity.class);
-viewIntent.putExtra(EXTRA_EVENT_ID, eventId);
-PendingIntent viewPendingIntent =
-        PendingIntent.getActivity(this, 0, viewIntent, 0);
-
-NotificationCompat.Builder notificationBuilder =
-        new NotificationCompat.Builder(this)
-        .setSmallIcon(R.drawable.ic_event)
-        .setContentTitle(eventTitle)
-        .setContentText(eventLocation)
-        .setContentIntent(viewPendingIntent);
-
-// Get an instance of the NotificationManager service
-NotificationManagerCompat notificationManager =
-        NotificationManagerCompat.from(this);
-
-// Build the notification and issues it with notification manager.
-notificationManager.notify(notificationId, notificationBuilder.build());
-
    
-
-
    When this notification appears on a handheld device, the user can invoke the
-{@link android.app.PendingIntent}
-specified by the {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent
-setContentIntent()} method by touching the notification. When this
-notification appears on an Android wearable, the user can swipe the notification to the left to
-reveal the Open action, which invokes the intent on the handheld device.
    
-
-
-
-
-
-
-
-
-
    Add Action Buttons
    
-
-
    In addition to the primary content action defined by
-{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent
-setContentIntent()}, you can add other actions by passing a {@link android.app.PendingIntent} to
-the {@link android.support.v4.app.NotificationCompat.Builder#addAction
-addAction()} method.
    
-
-
    For example, the following code shows the same type of notification from above, but adds an
-action to view the event location on a map.
    
-
-
    -// Build an intent for an action to view a map
-Intent mapIntent = new Intent(Intent.ACTION_VIEW);
-Uri geoUri = Uri.parse("geo:0,0?q=" + Uri.encode(location));
-mapIntent.setData(geoUri);
-PendingIntent mapPendingIntent =
-        PendingIntent.getActivity(this, 0, mapIntent, 0);
-
-NotificationCompat.Builder notificationBuilder =
-        new NotificationCompat.Builder(this)
-        .setSmallIcon(R.drawable.ic_event)
-        .setContentTitle(eventTitle)
-        .setContentText(eventLocation)
-        .setContentIntent(viewPendingIntent)
-        .addAction(R.drawable.ic_map,
-                getString(R.string.map), mapPendingIntent);
-
    
-
-
    On a handheld device, the action appears as an
-additional button attached to the notification. On an Android wearable, the action appears as
-a large button when the user swipes the notification to the left. When the user taps the action,
-the associated {@link android.content.Intent} is invoked on the handheld device.
    
-
-
    Tip: If your notifications includes a "Reply" action
-  (such as for a messaging app), you can enhance the behavior by enabling
-  voice input replies directly from the Android wearable. For more information, read
-  Receiving Voice Input from a Notification.
-
    
-
-
    For details about designing action buttons (including the icon specifications), see the
-Design Principles of Android
-Wear.
    
-
-
-
    Add a Big View
    
-
-
-
-
    You can insert extended text content
-to your notification by adding one of the "big view" styles to your notification. On a
-handheld device, users can see the big view content by expanding the notification,
-while on Android Wear, the big view content is visible by default.
    
-
-
    To add the extended content to your notification, call {@link
-android.support.v4.app.NotificationCompat.Builder#setStyle setStyle()} on the {@link
-android.support.v4.app.NotificationCompat.Builder} object, passing it an instance of either
-{@link android.support.v4.app.NotificationCompat.BigTextStyle BigTextStyle} or
-{@link android.support.v4.app.NotificationCompat.InboxStyle InboxStyle}.
    
-
-
    For example, the following code adds an instance of
-{@link android.support.v4.app.NotificationCompat.BigTextStyle} to the event notification,
-in order to include the complete event description (which includes more text than can fit
-into the space provided for {@link android.support.v4.app.NotificationCompat.Builder#setContentText
-setContentText()}).
    
-
-
-
    -// Specify the 'big view' content to display the long
-// event description that may not fit the normal content text.
-BigTextStyle bigStyle = new NotificationCompat.BigTextStyle();
-bigStyle.bigText(eventDescription);
-
-NotificationCompat.Builder notificationBuilder =
-        new NotificationCompat.Builder(this)
-        .setSmallIcon(R.drawable.ic_event)
-        .setLargeIcon(BitmapFractory.decodeResource(
-                getResources(), R.drawable.notif_background))
-        .setContentTitle(eventTitle)
-        .setContentText(eventLocation)
-        .setContentIntent(viewPendingIntent)
-        .addAction(R.drawable.ic_map,
-                getString(R.string.map), mapPendingIntent)
-        .setStyle(bigStyle);
-
    
-
-
    Notice that you can add a large background image to any notification using the
-{@link android.support.v4.app.NotificationCompat.Builder#setLargeIcon setLargeIcon()}
-method. For more information about designing notifications with large images, see the
-Design Principles of Android
-Wear.
    
-
-
-
-
    Add New Features for Wearables
    
-
-
    The Android Wear preview support library provides new APIs that
-  allow you to enhance the user experience for notifications on a wearable device. For example,
-  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.
    
-
-
    To use these new APIs:
    
-
-
      
-  
    1. Create an instance of
-{@link android.support.v4.app.NotificationCompat.Builder}, setting the
-desired properties for your notification.
      2. 
-  
    2. Create a
-   WearableNotificationOptions.Builder, setting the wearable-specific options for the notication.
      3. 
-  
    3. Call WearableNotificationOptions.Builder.applyTo()
-  , passing in the {@link android.support.v4.app.NotificationCompat.Builder}. This applies
-  the wearable options to the notification.
      4. 
-
    
-
-
    
-For example, the following code calls the
- 
-  setHintHideIcon() method to remove the app icon from the notification card.
-
    
-
-
    -// Create a NotificationCompat.Builder for standard notification features
- NotificationCompat.Builder builder = new NotificationCompat.Builder(mContext)
-         .setContentTitle("New mail from " + sender)
-         .setContentText(subject)
-         .setSmallIcon(R.drawable.new_mail);
-// Create a WearablesNotificationOptions.Builder to add functionality for wearables
- Notification notif = new WearableNotificationOptions.Builder()
-         .setHintHideIcon(true)
-         .build()
-         .applyTo(builder); //apply wearable options to to the original notification
-         .build()
-
    
-
-
    The
-  
-  setHintHideIcon() method is just one example of new notification features available with the
-  WearableNotificationOptions.Builder class.
-
    
-
-
-
    When you want to deliver your notifications, always use the
-  
-  NotificationManagerCompat API instead of
-  {@link android.app.NotificationManager}:
    
-
-
    -// Get an instance of the NotificationManager service
-NotificationManagerCompat notificationManager =
-        NotificationManagerCompat.from(this);
-
-// Issue the notification with notification manager.
-notificationManager.notify(notificationId, notif);
-
    
-
-
-
    If you use the framework's {@link android.app.NotificationManager}, some
-features from WearableNotificationOptions.Builder
-do not work.
    
-
-
-
    To continue enhancing your notifications for wearables using
-  WearableNotificationOptions.Builder and other APIs in the
-  preview support library, see the following developer guides:
    
-
-  
    
-    
    Receiving Voice Input
-from a Notification
    
-      
    Add an action that receives voice input from the user and delivers the
-transcribed message to your app.
    
-    
    Adding Pages to a Notification
    
-      
    Add additional pages of information that are visible when the user
-swipes to the left.
    
-    
    Stacking Notifications
    
-      
    Place all similar notifications from your app in a stack, allowing each to be
-viewed individually without adding multiple cards to the card stream.
    
-  
    
-
-
-
    
-
-
    
-  
    You might also want to read:
    
-  
    
-    
    Notifying the User
    
-    
    Learn more about how to create notifications.
    
-    
    Intents and Intent Filters
    
-    
    Learn everything you need to know about the {@link android.content.Intent}
-APIs, used by notificaton actions.
    
-  
    
-
    
-
    
-
-
-
-
diff --git a/docs/html/wear/notifications/pages.jd b/docs/html/wear/notifications/pages.jd
deleted file mode 100644
index 7d18b3f7e4203..0000000000000
--- a/docs/html/wear/notifications/pages.jd
+++ /dev/null
@@ -1,65 +0,0 @@
-page.title=Adding Pages to a Notification
-
-@jd:body
-
-
-
-
-
-
    When you'd like to provide more information without requiring users
-to open your app on their handheld device, you can
-add one or more pages to the notification on Android Wear. The additional pages
-appear immediately to the right of the main notification card.
-For information about when to use and how to design
-multiple pages, see the
-Design Principles of Android
-Wear.
    
-
-
    To create a notification with multiple pages:
    
-
      
-    
    1. Create the main notification (the first page) the way you'd like the notification to appear on a phone
-    or tablet.
      2. 
-    
    2. Add pages one at a time with the
-
-addPage() method, or add multiple pages in a {@link java.util.Collection} with the
-
-addPages() method.
      3. 
-    
    3. Apply the pages to the main notification with the
-    applyTo() method.
      4. 
-
    
-
-
-
    For example, here's some code that adds a second page to a notification:
    
-
-
    -// Create builder for the main notification
-NotificationCompat.Builder notificationBuilder =
-        new NotificationCompat.Builder(this)
-        .setSmallIcon(R.drawable.new_message)
-        .setContentTitle("Page 1")
-        .setContentText("Short message")
-        .setContentIntent(viewPendingIntent);
-
-// Create a big text style for the second page
-BigTextStyle secondPageStyle = new NotificationCompat.BigTextStyle();
-secondPageStyle.setBigContentTitle("Page 2")
-               .bigText("A lot of text...");
-
-// Create second page notification
-Notification secondPageNotification =
-        new NotificationCompat.Builder(this)
-        .setStyle(secondPageStyle)
-        .build();
-
-// Add second page with wearable options and apply to main notification
-Notification twoPageNotification =
-        new WearableNotificationsOptions.Builder()
-        .addPage(secondPageNotification)
-        .build()
-        .applyTo(notificationBuilder)
-        .build();
-
    
-
-
-
diff --git a/docs/html/wear/notifications/remote-input.jd b/docs/html/wear/notifications/remote-input.jd
deleted file mode 100644
index 4db8274d63346..0000000000000
--- a/docs/html/wear/notifications/remote-input.jd
+++ /dev/null
@@ -1,241 +0,0 @@
-page.title=Receiving Voice Input from a Notification
-
-@jd:body
-
-
-
-
-
-
    If your notification includes an action to respond with text,
-    such as to reply to an email, it should normally launch an activity
-    on the handheld device. However, when your notification appears on an Android wearable, you can
-    allow users to dictate a reply with voice input. You can also provide pre-defined text
-    messages for the user to select.
    
-
-
    When the user replies with voice or selects one of the available
-messages, the system sends the message to your app on the connected handheld device.
-The message is attached as an extra in the {@link android.content.Intent} you specified
-to be used for the notification action.
    
-
-
    Note: When developing with the Android emulator,
-you must type text replies into the voice input field, so be sure you have enabled
-Hardware keyboard present in the AVD settings.
    
-
-
-
    Define the Remote Input
    
-
-
    To create an action that supports voice input, first create an instance of
-  
-RemoteInput using the
-  RemoteInput.Builder APIs.
-    The
-  RemoteInput.Builder constructor takes a string that the system
-    will use as a key for the {@link android.content.Intent} extra that carries the reply message
-    to your app on the handheld.
    
-
-
    For example, here's how to create a new
-  
-RemoteInput object that provides a custom
-    label for the voice input prompt:
    
-
-
    -// Key for the string that's delivered in the action's intent
-private static final String EXTRA_VOICE_REPLY = "extra_voice_reply";
-
-String replyLabel = getResources().getString(R.string.reply_label);
-
-RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
-        .setLabel(replyLabel)
-        .build();
-
    
-
-
-
    Add Pre-defined Text Responses
    
-
-
-
-
    In addition to allowing voice input, you can
-    provide up to five text responses that the user can select for quick replies. Call
-  setChoices() and pass it a string array.
    
-
-
    For example, you may define some responses in a resource array:
    
-
-
    res/values/strings.xml
-
    -<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <string-array name="reply_choices">
-        <item>Yes</item>
-        <item>No</item>
-        <item>Maybe</item>
-    </string-array>
-</resources>
-
    
-
-
    Then, inflate the string array and add it to the
-  RemoteInput:
    
-
-
    -String replyLabel = getResources().getString(R.string.reply_label);
-String[] replyChoices = getResources().getStringArray(R.array.reply_choices);
-
-RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
-        .setLabel(replyLabel)
-        .setChoices(replyChoices)
-        .build();
-
    
-
-
-
-
-
    Receive Voice Input for the Primary Action
    
-
-
    If "Reply" is your notification's primary action (defined by the {@link
-android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}
-method), then you should attach the
-  RemoteInput to the main action using
-  
-addRemoteInputForContentIntent(). For example:
    
-
-
    -// Create intent for reply action
-Intent replyIntent = new Intent(this, ReplyActivity.class);
-PendingIntent replyPendingIntent =
-        PendingIntent.getActivity(this, 0, replyIntent, 0);
-
-// Build the notification
-NotificationCompat.Builder replyNotificationBuilder =
-        new NotificationCompat.Builder(this)
-        .setSmallIcon(R.drawable.ic_new_message)
-        .setContentTitle("Message from Travis")
-        .setContentText("I love key lime pie!")
-        .setContentIntent(replyPendingIntent);
-
-// Create the remote input
-RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
-        .setLabel(replyLabel)
-        .build();
-
-// Add remote input to wearable options and apply to notification
-Notification replyNotification =
-        new WearableNotificationOptions.Builder()
-        .addRemoteInputForContentIntent(remoteInput)
-        .build()
-        .applyTo(replyNotificationBuilder)
-        .build();
-
    
-
-
    By using
-  
-addRemoteInputForContentIntent() to add the
-  RemoteInput object to the notification's primary 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.
    
-
-
-
-
    Receive Voice Input for a Secondary Action
    
-
-
    If the "Reply" action is not your notification's primary action and you want to enable
-voice input for a secondary action, add the
-  RemoteInput to a new action button defined by an
-  
-Action object.
    
-
-
    You should instantiate the
-  
-WearableAction with the
-  WearableAction.Builder()
-constructor, which takes an icon and text label for the action button, plus the
-{@link android.app.PendingIntent}
-the system should use to invoke your app when the user selects the action. For example:
    
-
-
    -// Create the pending intent to fire when the user selects the action
-Intent replyIntent = new Intent(this, ReplyActivity.class);
-PendingIntent pendingReplyIntent =
-        PendingIntent.getActivity(this, 0, replyIntent, 0);
-
-// Create the remote input
-RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
-        .setLabel(replyLabel)
-        .build();
-
-// Create the notification action
-WearableAction replyAction = new WearableAction.Builder(R.drawable.ic_message,
-        "Reply", pendingIntent)
-        .addRemoteInput(remoteInput)
-        .build();
-
    
-
-
-
    After you add the
-  RemoteInput to the
-  
-Wearablection, set the
-  
-WearableAction on the
-  WearableNotifications.Builder using
-  addAction().
-For example:
    
-
-
    -// Create basic notification builder
-NotificationCompat.Builder replyNotificationBuilder =
-        new NotificationCompat.Builder(this)
-                .setContentTitle("New message");
-
-// Create the notification action and add remote input
-WearableAction replyAction = new WearableAction.Builder(R.drawable.ic_message,
-        "Reply", pendingIntent)
-        .addRemoteInput(remoteInput)
-        .build();
-
-// Create wearable notification and add action
-Notification replyNotification =
-        new WearableNotificationOptions.Builder()
-                .addAction(replyAction)
-                .build()
-                .applyTo(replyNotificationBuilder)
-                .build();
-
    
-
-
-
    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).
-    Once the user completes a response, the system invokes
-    the {@link android.content.Intent} attached to the action and adds the
-EXTRA_VOICE_REPLY extra (the string
-    you passed to the
-  RemoteInput.Builder constructor)
-  with the user's message as the string value.
    
-
-
    Obtaining the Voice Input as a String
    
-
    To obtain the user's voice input, call
-getResultsFromIntent(),
-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.
-
    
-
    
-The following code shows a method that accepts an intent and returns the voice input string,
-which is referenced by the EXTRA_VOICE_REPLY key that is used in the previous examples:
-
    
-
    -/**
- * 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;
-}
-
    
-
-
-