From d10df93b7cb0f1ea91b4d9f97d9ea64a0cc0c73e Mon Sep 17 00:00:00 2001 From: Bert McMeen Date: Fri, 8 Jul 2016 13:12:05 -0700 Subject: [PATCH] Docs: Gestures docs Bug: 22008636 Change-Id: I74626e262e9ddebadd4804047a4a2983d099f059 --- docs/html/wear/preview/_book.yaml | 2 + docs/html/wear/preview/api-overview.jd | 22 +- docs/html/wear/preview/features/gestures.jd | 323 ++++++++++++++++++++ 3 files changed, 345 insertions(+), 2 deletions(-) create mode 100644 docs/html/wear/preview/features/gestures.jd diff --git a/docs/html/wear/preview/_book.yaml b/docs/html/wear/preview/_book.yaml index a4acad04afcc7..3bea2fde22d10 100644 --- a/docs/html/wear/preview/_book.yaml +++ b/docs/html/wear/preview/_book.yaml @@ -18,6 +18,8 @@ toc: path: /wear/preview/features/ui-nav-actions.html - title: Bridging for Notifications path: /wear/preview/features/bridger.html + - title: Wrist Gestures + path: /wear/preview/features/gestures.html - title: Get Started path: /wear/preview/start.html diff --git a/docs/html/wear/preview/api-overview.jd b/docs/html/wear/preview/api-overview.jd index 11331a777d62e..42336244e4e6f 100644 --- a/docs/html/wear/preview/api-overview.jd +++ b/docs/html/wear/preview/api-overview.jd @@ -25,6 +25,7 @@ page.image=images/cards/card-n-apis_2x.png
  • Remote Input
  • Bridging Mode
  • Input Method Framework
    • +
  • Wrist Gestures
    • @@ -79,12 +80,11 @@ The navigation and action drawers provide users with new ways to interact with a watch face using the API.

    -

    For examples of how to use this feature, +

    For information about this API, see Watch Face Complications.

    -

    Navigation and Action drawers

    Wear 2.0 introduces two new widgets, navigation drawer and action drawer. These @@ -233,6 +233,24 @@ This allows users to enter text on Wear using the system default IME or third pa Input Method Framework.

    +

    Wrist Gestures

    + +

    + Wrist gestures can enable quick, one-handed interactions with your app + when use of a touch screen is inconvenient. The following + wrist gestures + are available for use by apps: +

    + + + +

    For more information, see + + Wrist Gestures. +

    Standalone Devices

    diff --git a/docs/html/wear/preview/features/gestures.jd b/docs/html/wear/preview/features/gestures.jd new file mode 100644 index 0000000000000..7806c4e998368 --- /dev/null +++ b/docs/html/wear/preview/features/gestures.jd @@ -0,0 +1,323 @@ +page.title=Wrist Gestures +meta.keywords="wear-preview" +page.tags="wear-preview" +page.image=images/cards/card-n-sdk_2x.png + +@jd:body + +
    + +
    + +

    + Wrist gestures can enable quick, one-handed interactions with your app + when use of a touch screen is inconvenient. For example, a user can scroll + through notifications with one hand while holding a cup of water with the + other. Other examples of using wrist gestures when a touch screen would + be inconvenient include: +

    + + + +

    + To review the wrist gestures on your watch, first confirm gestures are + turned on by selecting Settings > Gestures > Wrist Gestures + On. (Wrist gestures are on by default.) Then complete the + Gestures tutorial on the watch (Settings > Gestures > + Launch Tutorial). +

    + +

    + The following gestures from the Android Wear + Help are unavailable to apps: +

    + + + +

    + Wrist gestures can be used in these ways: +

    + + + +

    + Each wrist gesture is mapped to an int constant from the + KeyEvent + class, as shown in the following table: +

    + + + + + + + + + + + + + + + + + + + +
    + Gesture + + KeyEvent + + Description +
    + Flick wrist out + + + KEYCODE_NAVIGATE_NEXT + + This key code goes to the next item. +
    + Flick wrist in + + + KEYCODE_NAVIGATE_PREVIOUS + + This key code goes to the previous item. +
    + +

    + Using a WearableListView +

    + +

    + A + WearableListView has predefined actions for occurrences of + wrist gestures when the View has the focus. For more information, see + Best Practices. For information about using + WearableListView, see Creating + Lists. +

    + +

    + Even if you use a WearableListView, you may want to use + constants from the KeyEvent + class. The predefined actions can be overridden by subclassing the + WearableListView and re-implementing the + onKeyDown() callback. The behavior can be disabled entirely + by using setEnableGestureNavigation(false). Also see + + Handling Keyboard Actions. +

    + +

    + Using Key Events Directly +

    + +

    + You can use key events outside of a + WearableListView to trigger new actions in response to gesture + events. Importantly, these gesture events: +

    + + + +

    + Specifically, these events are delivered to the top Activity, to the View + with keyboard focus. Just as any other key event, a class that relates to + user interaction (such as a View or an Activity) that implements + + KeyEvent.Callback can listen to key events that relate to + wrist gestures. The Android framework calls the View or Activity that has + the focus with the key events; for gestures, the onKeyDown() + method callback is called when gestures occur. +

    + +

    + As an example, an app may override predefined actions in a View or + Activity (both implementing KeyEvent.Callback) as follows: +

    + + 
    +public final class GesturesActivity extends Activity {
+
+ @Override /* KeyEvent.Callback */
+ public boolean onKeyDown(int keyCode, KeyEvent event) {
+  switch (keyCode) {
+   case KeyEvent.KEYCODE_NAVIGATE_NEXT:
+    // Do something that advances a user View to the next item in an ordered list.
+    return moveToNextItem();
+   case KeyEvent.KEYCODE_NAVIGATE_PREVIOUS:
+    // Do something that advances a user View to the previous item in an ordered list.
+    return moveToPreviousItem();
+  }
+  // If you did not handle it, let it be handled by the next possible element as deemed by the Activity.
+  return super.onKeyDown(keyCode, event);
+ }
+
+ /** Shows the next item in the custom list. */
+ private boolean moveToNextItem() {
+  boolean handled = false;
+  …
+  // Return true if handled successfully, otherwise return false.
+  return handled;
+ }
+
+ /** Shows the previous item in the custom list. */
+ private boolean moveToPreviousItem() {
+  boolean handled = false;
+  …
+  // Return true if handled successfully, otherwise return false.
+  return handled;
+ }
+}
+
    + +

    + Best Practices +

    + +