Watch faces in Android Wear are implemented as services and packaged inside a wearable app. When users install a handheld app that contains a wearable app with watch faces, these watch faces become available in the Android Wear companion app on the handheld device and in the watch face picker on the wearable. When users select one of the available watch faces, the wearable device shows the watch face and invokes its service callback methods as required.
This lesson shows you how to configure an Android project to include watch faces and how to implement the watch face service.
To create an Android project for your watch face in Android Studio:
Android Studio creates a project with the wear and mobile modules.
For more information, see Creating a
Project.
The
Wearable Support Library
provides the necessary classes that you extend to create watch
face implementations. The Google Play services client libraries (play-services and
play-services-wearable) are required to sync data items between the companion device
and the wearable with the Wearable
Data Layer API.
Android Studio automatically adds the required entries in your build.gradle
files when you create the project in the instructions above.
The reference documentation provides detailed information about the classes you use to implement watch faces. Browse the API reference documentation for the Wearable Support Library.
If you are using the ADT plugin for Eclipse, download the Wearable Support Library and include it as a dependency in your project.
Watch faces require the PROVIDE_BACKGROUND and WAKE_LOCK permissions.
Add the following permissions to the manifest files of both the wearable app and the mobile
app under the manifest element:
<manifest ...>
<uses-permission
android:name="com.google.android.permission.PROVIDE_BACKGROUND" />
<uses-permission
android:name="android.permission.WAKE_LOCK" />
...
</manifest>
Caution: The handheld app must include all the permissions declared in the wearable app.
Watch faces in Android Wear are implemented as services. When a watch face is active, the system invokes the methods in its service when the time changes or when an important event occurs (like switching to ambient mode or receiving a new notification). The service implementation then draws the watch face on the screen using the updated time and any other relevant data.
To implement a watch face, you extend the
CanvasWatchFaceService
and
CanvasWatchFaceService.Engine
classes, and then you override the callback methods in the
CanvasWatchFaceService.Engine
class. These classes are included in the
Wearable Support Library.
The following snippet outlines the key methods you need to implement:
public class AnalogWatchFaceService extends CanvasWatchFaceService {
@Override
public Engine onCreateEngine() {
/* provide your watch face implementation */
return new Engine();
}
/* implement service callback methods */
private class Engine extends CanvasWatchFaceService.Engine {
@Override
public void onCreate(SurfaceHolder holder) {
super.onCreate(holder);
/* initialize your watch face */
}
@Override
public void onPropertiesChanged(Bundle properties) {
super.onPropertiesChanged(properties);
/* get device features (burn-in, low-bit ambient) */
}
@Override
public void onTimeTick() {
super.onTimeTick();
/* the time changed */
}
@Override
public void onAmbientModeChanged(boolean inAmbientMode) {
super.onAmbientModeChanged(inAmbientMode);
/* the wearable switched between modes */
}
@Override
public void onDraw(Canvas canvas, Rect bounds) {
/* draw your watch face */
}
@Override
public void onVisibilityChanged(boolean visible) {
super.onVisibilityChanged(visible);
/* the watch face became visible or invisible */
}
}
}
The
CanvasWatchFaceService
class provides an invalidate mechanism similar to
the {@link android.view.View#invalidate View.invalidate()} method. You can call the
invalidate()
method throughout your implementation when
you want the system to redraw the watch face. You can only use the
invalidate()
method in the main UI thread. To invalidate the canvas from another thread, call the
postInvalidate()
method.
For more information about implementing the methods in the
CanvasWatchFaceService.Engine
class, see Drawing Watch Faces.
After you implement the watch face service, you register the implementation in the manifest file of the wearable app. When users install this app, the system uses the information about the service to make the watch face available in the Android Wear companion app and in the watch face picker on the wearable device.
The following snippet shows how to register a watch face implementation under theapplication element:
<service
android:name=".AnalogWatchFaceService"
android:label="@string/analog_name"
android:allowEmbedded="true"
android:taskAffinity=""
android:permission="android.permission.BIND_WALLPAPER" >
<meta-data
android:name="android.service.wallpaper"
android:resource="@xml/watch_face" />
<meta-data
android:name="com.google.android.wearable.watchface.preview"
android:resource="@drawable/preview_analog" />
<meta-data
android:name="com.google.android.wearable.watchface.preview_circular"
android:resource="@drawable/preview_analog_circular" />
<intent-filter>
<action android:name="android.service.wallpaper.WallpaperService" />
<category
android:name=
"com.google.android.wearable.watchface.category.WATCH_FACE" />
</intent-filter>
</service>
The Android
Wear companion app and the watch face picker on the wearable device use the preview image
defined by the com.google.android.wearable.watchface.preview metadata entry when
presenting users with all the watch faces installed on the device. To obtain this drawable,
run the watch face on your Android Wear device or in an emulator instance and take a screenshot. On Android Wear
devices with hdpi screens, the preview image is typically 320x320 pixels in size.
Watch faces that look substantially different on round devices can provide both round and
square preview images. To specify a round preview image, use the
com.google.android.wearable.watchface.preview_circular metadata entry. If a watch
face includes both preview images, the companion app and the watch face picker on the wearable
show the appropriate one, depending on the shape of the watch. If a round preview image is not
included, the square preview image is used for both square and round devices. For round devices,
a square preview image is cropped using a circular shape.
The android.service.wallpaper metadata entry specifies the
watch_face.xml resource file, which contains a wallpaper
element:
<?xml version="1.0" encoding="UTF-8"?> <wallpaper xmlns:android="http://schemas.android.com/apk/res/android" />
Your wearable app can contain more than one watch face. You must add a service entry to the manifest file of the wearable app for each of your watch face implementations.