1page.title=Building a Watch Face Service 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="#CreateProject">Create and Configure Your Project</a></li> 10 <li><a href="#CallbackMethods">Implement the Service Callback Methods</a></li> 11 <li><a href="#RegisterService">Register the Service Implementation</a></li> 12</ol> 13<h2>Related Samples</h2> 14<ul> 15<li><a href="{@docRoot}samples/WatchFace/index.html"> 16WatchFace</a></li> 17</ul> 18<h2>You should also read</h2> 19<ul> 20 <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li> 21</ul> 22</div> 23</div> 24 25<p>Watch faces in Android Wear are implemented as <a 26href="{@docRoot}guide/components/services.html">services</a> and packaged inside a <a 27href="{@docRoot}training/wearables/apps/index.html">wearable app</a>. When users install a 28handheld app that contains a wearable app with watch faces, these watch faces become available 29in the <a 30href="https://play.google.com/store/apps/details?id=com.google.android.wearable.app&hl=en">Android 31Wear companion app</a> on the handheld device and in the watch face picker on the wearable. When 32users select one of the available watch faces, the wearable device shows the watch face and 33invokes its service callback methods as required.</p> 34 35<p>This lesson shows you how to configure an Android project to include watch faces and how 36to implement the watch face service.</p> 37 38 39 40<h2 id="CreateProject">Create and Configure Your Project</h2> 41 42<p>To create an Android project for your watch face in Android Studio:</p> 43 44<ol> 45<li>Start Android Studio.</li> 46<li>Create a new project: 47 <ul> 48 <li>If you don't have a project opened, in the <strong>Welcome</strong> screen, click 49 <strong>New Project</strong>.</li> 50 <li>If you have a project opened, from the <strong>File</strong> menu, select <strong>New 51 Project</strong>.</li> 52 </ul> 53</li> 54<li>Provide an application name and click <strong>Next</strong>.</li> 55<li>Select the <strong>Phone and Tablet</strong> form factor.</li> 56<li>Under <strong>Minimum SDK</strong>, choose API 18.</li> 57<li>Select the <strong>Wear</strong> form factor.</li> 58<li>Under <strong>Minimum SDK</strong>, choose API 21 and click <strong>Next</strong>.</li> 59<li>Select <strong>Add No Activity</strong> and click <strong>Next</strong> in the two following 60 screens.</li> 61<li>Click <strong>Finish</strong>.</li> 62<li>Click <strong>View</strong> > <strong>Tool Windows</strong> > <strong>Project</strong> in the 63 IDE window.</li> 64</ol> 65 66<p>Android Studio creates a project with the <code>wear</code> and <code>mobile</code> modules. 67For more information, see <a href="{@docRoot}sdk/installing/create-project.html">Creating a 68Project</a>.</p> 69 70<h3 id="Dependencies">Dependencies</h3> 71 72<p>The 73<a href="{@docRoot}reference/android/support/wearable/watchface/package-summary.html">Wearable Support Library</a> 74provides the necessary classes that you extend to create watch 75face implementations. The Google Play services client libraries (<code>play-services</code> and 76<code>play-services-wearable</code>) are required to sync data items between the companion device 77and the wearable with the <a href="{@docRoot}training/wearables/data-layer/index.html">Wearable 78Data Layer API</a>.</p> 79 80<p>Android Studio automatically adds the required entries in your <code>build.gradle</code> 81files when you create the project in the instructions above.</p> 82 83<h3 id="Reference">Wearable Support Library API Reference</h3> 84 85<p>The reference documentation provides detailed information about the classes you use to 86implement watch faces. Browse the 87<a href="{@docRoot}reference/android/support/wearable/watchface/package-summary.html">API reference 88documentation</a> for the Wearable Support Library.</p> 89 90<h3 id="LibEclipse">Download the Wearable Support Library for Eclipse ADT</h3> 91 92<p>If you are using the ADT plugin for Eclipse, download the 93<a href="{@docRoot}shareables/training/wearable-support-lib.zip">Wearable Support Library</a> and 94include it as a dependency in your project.</p> 95 96<h3 id="Permissions">Declare Permissions</h3> 97 98<p>Watch faces require the <code>PROVIDE_BACKGROUND</code> and <code>WAKE_LOCK</code> permissions. 99Add the following permissions to the manifest files of both the wearable app and the mobile 100app under the <code>manifest</code> element:</p> 101 102<pre> 103<manifest ...> 104 <uses-permission 105 android:name="com.google.android.permission.PROVIDE_BACKGROUND" /> 106 <uses-permission 107 android:name="android.permission.WAKE_LOCK" /> 108 ... 109</manifest> 110</pre> 111 112<p class="caution"><strong>Caution:</strong> The handheld app must include all the permissions 113declared in the wearable app.</p> 114 115 116 117<h2 id="CallbackMethods">Implement the Service and Callback Methods</h2> 118 119<p>Watch faces in Android Wear are implemented as 120<a href="{@docRoot}guide/components/services.html">services</a>. 121When a watch face is active, the system invokes the methods in its service when the time changes 122or when an important event occurs (like switching to ambient mode or receiving a new 123notification). The service implementation then draws the watch face on the screen using the 124updated time and any other relevant data.</p> 125 126<p>To implement a watch face, you extend the 127<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.html"><code>CanvasWatchFaceService</code></a> 128and 129<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a> 130classes, and then you override the callback methods in the 131<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a> 132class. These classes are included in the 133<a href="{@docRoot}reference/android/support/wearable/watchface/package-summary.html">Wearable Support Library</a>. 134</p> 135 136<p>The following snippet outlines the key methods you need to implement:</p> 137 138<pre> 139public class AnalogWatchFaceService extends CanvasWatchFaceService { 140 141 @Override 142 public Engine onCreateEngine() { 143 /* provide your watch face implementation */ 144 return new Engine(); 145 } 146 147 /* implement service callback methods */ 148 private class Engine extends CanvasWatchFaceService.Engine { 149 150 @Override 151 public void onCreate(SurfaceHolder holder) { 152 super.onCreate(holder); 153 /* initialize your watch face */ 154 } 155 156 @Override 157 public void onPropertiesChanged(Bundle properties) { 158 super.onPropertiesChanged(properties); 159 /* get device features (burn-in, low-bit ambient) */ 160 } 161 162 @Override 163 public void onTimeTick() { 164 super.onTimeTick(); 165 /* the time changed */ 166 } 167 168 @Override 169 public void onAmbientModeChanged(boolean inAmbientMode) { 170 super.onAmbientModeChanged(inAmbientMode); 171 /* the wearable switched between modes */ 172 } 173 174 @Override 175 public void onDraw(Canvas canvas, Rect bounds) { 176 /* draw your watch face */ 177 } 178 179 @Override 180 public void onVisibilityChanged(boolean visible) { 181 super.onVisibilityChanged(visible); 182 /* the watch face became visible or invisible */ 183 } 184 } 185} 186</pre> 187 188<p>The 189<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.html"><code>CanvasWatchFaceService</code></a> 190class provides an invalidate mechanism similar to 191the {@link android.view.View#invalidate View.invalidate()} method. You can call the 192<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#invalidate()"><code>invalidate()</code></a> 193method throughout your implementation when 194you want the system to redraw the watch face. You can only use the 195<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#invalidate()"><code>invalidate()</code></a> 196method in the main UI thread. To invalidate the canvas from another thread, call the 197<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#postInvalidate()"><code>postInvalidate()</code></a> 198method.</p> 199 200<p>For more information about implementing the methods in the 201<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a> 202class, see <a 203href="{@docRoot}training/wearables/watch-faces/drawing.html">Drawing Watch Faces</a>.</p> 204 205 206 207<h2 id="RegisterService">Register the Watch Face Service</h2> 208 209<p>After you implement the watch face service, you register the implementation in the manifest 210file of the wearable app. When users install this app, the system uses the information about 211the service to make the watch face available in the <a 212href="https://play.google.com/store/apps/details?id=com.google.android.wearable.app&hl=en">Android 213Wear companion app</a> and in the watch face picker on the wearable device.</p> 214 215</p>The following snippet shows how to register a watch face implementation 216under the <a href="{@docRoot}guide/topics/manifest/application-element.html"> 217<code>application</code></a> element:</p> 218 219<pre> 220<service 221 android:name=".AnalogWatchFaceService" 222 android:label="@string/analog_name" 223 android:allowEmbedded="true" 224 android:taskAffinity="" 225 android:permission="android.permission.BIND_WALLPAPER" > 226 <meta-data 227 android:name="android.service.wallpaper" 228 android:resource="@xml/watch_face" /> 229 <meta-data 230 android:name="com.google.android.wearable.watchface.preview" 231 android:resource="@drawable/preview_analog" /> 232 <meta-data 233 android:name="com.google.android.wearable.watchface.preview_circular" 234 android:resource="@drawable/preview_analog_circular" /> 235 <intent-filter> 236 <action android:name="android.service.wallpaper.WallpaperService" /> 237 <category 238 android:name= 239 "com.google.android.wearable.watchface.category.WATCH_FACE" /> 240 </intent-filter> 241</service> 242</pre> 243 244<p>The <a 245href="https://play.google.com/store/apps/details?id=com.google.android.wearable.app&hl=en">Android 246Wear companion app</a> and the watch face picker on the wearable device use the preview image 247defined by the <code>com.google.android.wearable.watchface.preview</code> metadata entry when 248presenting users with all the watch faces installed on the device. To obtain this drawable, 249run the watch face on your Android Wear device or in an emulator instance and <a 250href="{@docRoot}sdk/installing/studio-debug.html#screenCap">take a screenshot</a>. On Android Wear 251devices with hdpi screens, the preview image is typically 320x320 pixels in size.</p> 252 253<p>Watch faces that look substantially different on round devices can provide both round and 254square preview images. To specify a round preview image, use the 255<code>com.google.android.wearable.watchface.preview_circular</code> metadata entry. If a watch 256face includes both preview images, the companion app and the watch face picker on the wearable 257show the appropriate one, depending on the shape of the watch. If a round preview image is not 258included, the square preview image is used for both square and round devices. For round devices, 259a square preview image is cropped using a circular shape.</p> 260 261<p>The <code>android.service.wallpaper</code> metadata entry specifies the 262<code>watch_face.xml</code> resource file, which contains a <code>wallpaper</code> 263element:</p> 264 265<pre> 266<?xml version="1.0" encoding="UTF-8"?> 267<wallpaper xmlns:android="http://schemas.android.com/apk/res/android" /> 268</pre> 269 270<p>Your wearable app can contain more than one watch face. You must add a service entry to the 271manifest file of the wearable app for each of your watch face implementations.</p> 272