Wrist Gestures

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:

• In an app for jogging, navigating through vertical screens that show the steps taken, time elapsed, and current pace
• At the airport with luggage, scrolling through flight and gate information
• Scrolling through news articles

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:

• Push wrist down
• Raise wrist up
• Shaking the wrist

Wrist gestures can be used in these ways:

• Using a WearableListView, which has predefined gesture actions
• Using key events directly to define new user actions

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:

• Are recognized when a device is in Active mode
• Are delivered in the same way as all key 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

• Review the KeyEvent and KeyEvent.Callback pages for the delivery of key events to your View and Activity.
• Keep a consistent directional affordance:
  • Use "Flick wrist out" for next, "Flick wrist in" for previous
• Have a touch parallel for a gesture.
• Provide visual feedback.
• Don't use a keycode to implement functionality that would be counter-intuitive to the rest of the system. For example, do not use KEYCODE_NAVIGATE_NEXT to cancel an action or to navigate the left-right axis with flicks.
• Don't intercept the key events on elements that are not part of the user interface, for example the Views that are offscreen or partially covered. This is the same as any other key event.
• Don't reinterpret repeated flick gestures into your own, new gesture. It may conflict with the system's "Shaking the wrist" gesture.
• For a View to receive gesture key events, it must have focus; see View::setFocusable(). Because gestures are treated as key events, they trigger a transition out of "Touch mode" that may do unexpected things. Therefore, since users may alternate between using touch and gestures, the View::setFocusableInTouchmode() method may be necessary. In some cases, it also may be necessary to use setDescendantFocusability(FOCUS_BEFORE_DESCENDANTS) so that when focus changes after a change to or from "Touch mode," your intended View gets the focus.
• Use requestFocus() and clearFocus() carefully:
  • When calling requestFocus(), be sure that the View really should have focus. If the View is offscreen, or is covered by another View, surprises can occur when gestures trigger callbacks.
  • The clearFocus() initiates a focus search to find another suitable View. Depending on the View hierarchy, this search might require non-trivial computation. It can also end up assigning focus to a View you don’t expect to receive focus.
• Key events are delivered first to the View with focus in the View hierarchy. If the focused View does not handle the event (i.e., returns false), the event is not delivered to the parent View, even if it can receive focus and has a KeyListener. Rather, the event is delivered to the current Activity holding the View hierarchy with focus. Thus, it may be necessary to catch all events at the higher level and then pass relevant codes down. Alternatively, you might subclass the Activity and override the dispatchKeyEvent(KeyEvent event) method to ensure that keys are intercepted when necessary, or are handled when not handled at lower layers.