diff options
Diffstat (limited to 'docs/html/training/wearables/watch-faces/interacting.jd')
| -rw-r--r-- | docs/html/training/wearables/watch-faces/interacting.jd | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/docs/html/training/wearables/watch-faces/interacting.jd b/docs/html/training/wearables/watch-faces/interacting.jd new file mode 100644 index 0000000..4f2486c --- /dev/null +++ b/docs/html/training/wearables/watch-faces/interacting.jd @@ -0,0 +1,133 @@ +page.title=Creating Interactive Watch Faces + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#Construct">Construct an Interactive Watch Face</a></li> + <li><a href="#Handle">Handle Gestures</a></li> +</ol> +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li> +</ul> +<h2>Related Samples</h2> + <ul> + <li><a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a></li> + </ul> +</div> +</div> + +<p>Your watch's display is more than just a pretty face: Users can interact with it. +For example, a user might tap the watch face to learn what song is currently playing, or +to see the day's agenda. Android Wear allows Android Wear watch faces to accept +the single-tap gesture at a given location on the watch face, as long as there's not another +UI element that also responds to that gesture. + +<p>This lesson teaches you how to implement an interactive watch face by first constructing the +watch face style, and then implementing gesture handling.</p> + +<p class="note"><strong>Note:</strong> Before beginning development work on your interactive watch +face, you should be sure to read the <a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for +Android Wear</a> design guide. + +<h2 id="Construct">Handling Tap Events</h2> + +<p>When constructing an interactive watch-face style, the first thing the app must do is tell the +system that the watch face receives <a href="{@docRoot}design/wear/watchfaces.html#ag">tap events</a>. +The following example shows how to do this: + +<pre> +setWatchFaceStyle(new WatchFaceStyle.Builder(mService) + .setAcceptsTapEvents(true) + // other style customizations + .build()); +</pre> + +<p>When the system detects a tap on the watch face, it triggers the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onTapCommand(int, int, int, long)"> +{@code WatchFaceService.Engine.onTapCommand()}</a> method. Override this method in your +implementation of +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html"> +{@code WatchFaceService.Engine}</a>to initiate the action you wish to perform, such +as showing a detailed step count or changing the theme of the watch face. The code snippet +in <a href="#Handle">Handle Gestures</a> shows an example of such an +implementation.</p> + +<h2 id="Handle">Handle Gestures</h2> + +<p> To provide a consistent user experience, the system +reserves gestures such as drag and long-press for system UI elements. +Therefore, the system does not send raw touch events to the watch face. Instead, the system forwards specific commands to the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onTapCommand(int, int, int, long)"> +method. + +<p>The system sends the first command, +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TOUCH"</a> +{@code TAP_TYPE_TOUCH}</a>, when the user initially touches the +screen. This event lets you provide visual feedback to the user on touch. Your app should not +launch a UI when this event triggers. Launching a UI prevents drag events from opening the app +launcher, settings shade, and notifications stream.</p> + +<p>Before sending the next command, the system judges whether the contact is a single tap, which is +<a href="{@docRoot}design/wear/watchfaces.html#ag">the only gesture allowed</a>. If the user +immediately lifts their finger, the system determines that a single tap took place, and forwards +a +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TAP"</a> +{@code TAP_TYPE_TAP}</a> event. If the user does not immediately lift their finger, the system +forwards a +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TOUCH_CANCEL"</a> +{@code TAP_TYPE_TOUCH_CANCEL}</a> event. Once the user has triggered a +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TOUCH_CANCEL"</a> +{@code TAP_TYPE_TOUCH_CANCEL}</a> event, they cannot trigger a +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TAP"</a> +{@code TAP_TYPE_TAP}</a> event until they +make a new contact with the screen.</p> + +<p>The following example shows you how to implement tap events on a watch face:</p> + + +<pre> +@Override +public void onTapCommand( + @TapType int tapType, int x, int y, long eventTime) { + switch (tapType) { + case WatchFaceService.TAP_TYPE_TAP: + hideTapHighlight(); + if (withinTapRegion(x, y)) { + // Implement the tap action + // (e.g. show detailed step count) + onWatchFaceTap(); + } + break; + + case WatchFaceService.TAP_TYPE_TOUCH: + if (withinTapRegion(x, y)) { + // Provide visual feedback of touch event + startTapHighlight(x, y, eventTime); + } + break; + + case WatchFaceService.TAP_TYPE_TOUCH_CANCEL: + hideTapHighlight(); + break; + + default: + super.onTapCommand(tapType, x, y, eventTime); + break; + } +} +</pre> + +<p>In this example, the app determines what kind of event has taken place, +and responds accordingly. If the event is initial contact by the user's finger, +the app displays visual feedback. If the event is an immediate lifting +of the finger after contact, it performs the action on which the +user tapped. If the event is prolonged contact by the finger, the app +does nothing.</p> + + + + |