Google is committed to advancing racial equity for Black communities. See how.

WatchFaceControlClient

interface WatchFaceControlClient : AutoCloseable
androidx.wear.watchface.client.WatchFaceControlClient

Connects to a watch face's WatchFaceControlService which allows the user to control the watch face.

Summary

Nested classes

Exception thrown by WatchFaceControlClient methods when the remote service is not bound.

Public methods
abstract ListenableFuture<HeadlessWatchFaceClient?>
createHeadlessWatchFaceClient(watchFaceName: ComponentName, deviceConfig: DeviceConfig, surfaceWidth: Int, surfaceHeight: Int)

Creates a HeadlessWatchFaceClient with the specified DeviceConfig.

abstract ListenableFuture<InteractiveWatchFaceSysUiClient?>

Returns the InteractiveWatchFaceSysUiClient for the given instance id, or null if no such instance exists.

abstract ListenableFuture<InteractiveWatchFaceWcsClient>
getOrCreateWallpaperServiceBackedInteractiveWatchFaceWcsClient(id: String, deviceConfig: DeviceConfig, systemState: SystemState, userStyle: Map<String, String>?, idToComplicationData: Map<Int, ComplicationData>?)

Requests either an existing InteractiveWatchFaceWcsClient with the specified id or schedules creation of an InteractiveWatchFaceWcsClient for the next time the WallpaperService creates an engine.

Companion functions
WatchFaceControlClient
createWatchFaceControlClient(context: Context, watchFacePackageName: String)

Constructs a WatchFaceControlClient which attempts to connect to a watch face in the android package watchFacePackageName.

Public methods

createHeadlessWatchFaceClient

abstract fun createHeadlessWatchFaceClient(
    watchFaceName: ComponentName,
    deviceConfig: DeviceConfig,
    surfaceWidth: Int,
    surfaceHeight: Int
): ListenableFuture<HeadlessWatchFaceClient?>

Creates a HeadlessWatchFaceClient with the specified DeviceConfig. Screenshots made with HeadlessWatchFaceClient.takeWatchFaceScreenshot will be surfaceWidth x surfaceHeight in size.

When finished call HeadlessWatchFaceClient.close to release resources.

Parameters
watchFaceName: ComponentName The ComponentName of the watch face to create a headless instance for must be in the same APK the WatchFaceControlClient is connected to. NB a single apk can contain multiple watch faces.
deviceConfig: DeviceConfig The hardware DeviceConfig
surfaceWidth: Int The width of screen shots taken by the HeadlessWatchFaceClient
surfaceHeight: Int The height of screen shots taken by the HeadlessWatchFaceClient
Return
A ListenableFuture for the HeadlessWatchFaceClient or null if watchFaceName is unrecognized, or ServiceNotBoundException if the WatchFaceControlService is not bound.

getInteractiveWatchFaceSysUiClientInstance

abstract fun getInteractiveWatchFaceSysUiClientInstance(instanceId: String): ListenableFuture<InteractiveWatchFaceSysUiClient?>

Returns the InteractiveWatchFaceSysUiClient for the given instance id, or null if no such instance exists.

When finished call InteractiveWatchFaceSysUiClient.close to release resources.

Parameters
instanceId: String The name of the interactive watch face instance to retrieve
Return
A ListenableFuture for the InteractiveWatchFaceSysUiClient or null if instanceId is unrecognized, or ServiceNotBoundException if the WatchFaceControlService is not bound.

getOrCreateWallpaperServiceBackedInteractiveWatchFaceWcsClient

abstract fun getOrCreateWallpaperServiceBackedInteractiveWatchFaceWcsClient(
    id: String,
    deviceConfig: DeviceConfig,
    systemState: SystemState,
    userStyle: Map<String, String>?,
    idToComplicationData: Map<Int, ComplicationData>?
): ListenableFuture<InteractiveWatchFaceWcsClient>

Requests either an existing InteractiveWatchFaceWcsClient with the specified id or schedules creation of an InteractiveWatchFaceWcsClient for the next time the WallpaperService creates an engine.

NOTE that currently only one InteractiveWatchFaceWcsClient per process can exist at a time.

Parameters
id: String The ID for the requested InteractiveWatchFaceWcsClient.
deviceConfig: DeviceConfig The DeviceConfig for the wearable.
systemState: SystemState The initial SystemState for the wearable.
userStyle: Map<String, String>? The initial style map (see UserStyle), or null if the default should be used.
idToComplicationData: Map<Int, ComplicationData>? The initial complication data, or null if unavailable.
Return
a ListenableFuture for a InteractiveWatchFaceWcsClient

Companion functions

createWatchFaceControlClient

@JvmStatic fun createWatchFaceControlClient(
    context: Context,
    watchFacePackageName: String
): WatchFaceControlClient

Constructs a WatchFaceControlClient which attempts to connect to a watch face in the android package watchFacePackageName. If this fails the ListenableFutures returned by WatchFaceControlClient methods will fail with ServiceNotBoundException.