1 page.title=Creating Interactive Watch Faces 2 3 @jd:body 4 5 <div id="tb-wrapper"> 6 <div id="tb"> 7 <h2>This lesson teaches you to</h2> 8 <ol> 9 <li><a href="#Construct">Construct an Interactive Watch Face</a></li> 10 <li><a href="#Handle">Handle Gestures</a></li> 11 </ol> 12 <h2>You should also read</h2> 13 <ul> 14 <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li> 15 </ul> 16 <h2>Related Samples</h2> 17 <ul> 18 <li><a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a></li> 19 </ul> 20 </div> 21 </div> 22 23 <p>Your watch's display is more than just a pretty face: Users can interact with it. 24 For example, a user might tap the watch face to learn what song is currently playing, or 25 to see the day's agenda. Android Wear allows Android Wear watch faces to accept 26 the single-tap gesture at a given location on the watch face, as long as there's not another 27 UI element that also responds to that gesture. 28 29 <p>This lesson teaches you how to implement an interactive watch face by first constructing the 30 watch face style, and then implementing gesture handling.</p> 31 32 <p class="note"><strong>Note:</strong> Before beginning development work on your interactive watch 33 face, you should be sure to read the <a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for 34 Android Wear</a> design guide. 35 36 <h2 id="Construct">Handling Tap Events</h2> 37 38 <p>When constructing an interactive watch-face style, the first thing the app must do is tell the 39 system that the watch face receives <a href="{@docRoot}design/wear/watchfaces.html#ag">tap events</a>. 40 The following example shows how to do this: 41 42 <pre> 43 setWatchFaceStyle(new WatchFaceStyle.Builder(mService) 44 .setAcceptsTapEvents(true) 45 // other style customizations 46 .build()); 47 </pre> 48 49 <p>When the system detects a tap on the watch face, it triggers the 50 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onTapCommand(int, int, int, long)"> 51 {@code WatchFaceService.Engine.onTapCommand()}</a> method. Override this method in your 52 implementation of 53 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html"> 54 {@code WatchFaceService.Engine}</a>to initiate the action you wish to perform, such 55 as showing a detailed step count or changing the theme of the watch face. The code snippet 56 in <a href="#Handle">Handle Gestures</a> shows an example of such an 57 implementation.</p> 58 59 <h2 id="Handle">Handle Gestures</h2> 60 61 <p> To provide a consistent user experience, the system 62 reserves gestures such as drag and long-press for system UI elements. 63 Therefore, the system does not send raw touch events to the watch face. Instead, the system forwards specific commands to the 64 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onTapCommand(int, int, int, long)"> 65 onTapCommand()</a> method. 66 67 <p>The system sends the first command, 68 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TOUCH"> 69 {@code TAP_TYPE_TOUCH}</a>, when the user initially touches the 70 screen. This event lets you provide visual feedback to the user on touch. Your app should not 71 launch a UI when this event triggers. Launching a UI prevents drag events from opening the app 72 launcher, settings shade, and notifications stream.</p> 73 74 <p>Before sending the next command, the system judges whether the contact is a single tap, which is 75 <a href="{@docRoot}design/wear/watchfaces.html#ag">the only gesture allowed</a>. If the user 76 immediately lifts their finger, the system determines that a single tap took place, and forwards 77 a 78 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TAP"</a> 79 {@code TAP_TYPE_TAP}</a> event. If the user does not immediately lift their finger, the system 80 forwards a 81 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TOUCH_CANCEL"</a> 82 {@code TAP_TYPE_TOUCH_CANCEL}</a> event. Once the user has triggered a 83 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TOUCH_CANCEL"</a> 84 {@code TAP_TYPE_TOUCH_CANCEL}</a> event, they cannot trigger a 85 <a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.html#TAP_TYPE_TAP"</a> 86 {@code TAP_TYPE_TAP}</a> event until they 87 make a new contact with the screen.</p> 88 89 <p>The following example shows you how to implement tap events on a watch face:</p> 90 91 92 <pre> 93 @Override 94 public void onTapCommand( 95 @TapType int tapType, int x, int y, long eventTime) { 96 switch (tapType) { 97 case WatchFaceService.TAP_TYPE_TAP: 98 hideTapHighlight(); 99 if (withinTapRegion(x, y)) { 100 // Implement the tap action 101 // (e.g. show detailed step count) 102 onWatchFaceTap(); 103 } 104 break; 105 106 case WatchFaceService.TAP_TYPE_TOUCH: 107 if (withinTapRegion(x, y)) { 108 // Provide visual feedback of touch event 109 startTapHighlight(x, y, eventTime); 110 } 111 break; 112 113 case WatchFaceService.TAP_TYPE_TOUCH_CANCEL: 114 hideTapHighlight(); 115 break; 116 117 default: 118 super.onTapCommand(tapType, x, y, eventTime); 119 break; 120 } 121 } 122 </pre> 123 124 <p>In this example, the app determines what kind of event has taken place, 125 and responds accordingly. If the event is initial contact by the user's finger, 126 the app displays visual feedback. If the event is an immediate lifting 127 of the finger after contact, it performs the action on which the 128 user tapped. If the event is prolonged contact by the finger, the app 129 does nothing.</p> 130 131 132 133 134
