WatchFaceControlClient

Artifact: androidx.wear.watchface:watchface-client

View Source

Added in 1.0.0

Deprecated in 1.3.0-alpha07

---

Kotlin |Java

interface WatchFaceControlClient : AutoCloseable

Known direct subclasses

ListenableWatchFaceControlClient

ListenableWatchFaceControlClient

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

---

This interface is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

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

use Watch Face Format instead

Summary

Nested types
class WatchFaceControlClient.ServiceNotBoundException : Exception This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.
class WatchFaceControlClient.ServiceStartFailureException : Exception This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Public companion functions
suspend WatchFaceControlClient	createWatchFaceControlClient(     context: Context,     watchFacePackageName: String ) This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.
suspend WatchFaceControlClient	createWatchFaceRuntimeControlClient(     context: Context,     runtimePackageName: String,     resourceOnlyWatchFacePackageName: String ) This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Public functions
HeadlessWatchFaceClient?	createHeadlessWatchFaceClient(     watchFaceName: ComponentName,     deviceConfig: DeviceConfig,     surfaceWidth: @Px Int,     surfaceHeight: @Px Int ) This function is deprecated. Creating a headless client without a watchface ID is deprecated
open HeadlessWatchFaceClient?	createHeadlessWatchFaceClient(     id: String,     watchFaceName: ComponentName,     deviceConfig: DeviceConfig,     surfaceWidth: @Px Int,     surfaceHeight: @Px Int ) This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.
Map<Int, DefaultComplicationDataSourcePolicyAndType>	getDefaultComplicationDataSourcePoliciesAndType(     watchFaceName: ComponentName ) This function is deprecated. Use the WatchFaceMetadataClient instead.
EditorServiceClient	getEditorServiceClient() This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.
InteractiveWatchFaceClient?	getInteractiveWatchFaceClientInstance(instanceId: String) This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.
suspend InteractiveWatchFaceClient	getOrCreateInteractiveWatchFaceClient(     id: String,     deviceConfig: DeviceConfig,     watchUiState: WatchUiState,     userStyle: UserStyleData?,     slotIdToComplicationData: Map<Int, ComplicationData>? ) This function is deprecated. Use an overload that specifies Consumer<String>
open suspend InteractiveWatchFaceClient	getOrCreateInteractiveWatchFaceClient(     instanceId: String,     deviceConfig: DeviceConfig,     watchUiState: WatchUiState,     userStyle: UserStyleData?,     slotIdToComplicationData: Map<Int, ComplicationData>?,     previewImageUpdateRequestedExecutor: Executor,     previewImageUpdateRequestedListener: Consumer<String> ) This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.
open Boolean	hasComplicationDataCache() This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Inherited functions
From java.lang.AutoCloseable Unit close() This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Public companion functions

createWatchFaceControlClient

suspend fun createWatchFaceControlClient(
    context: Context,
    watchFacePackageName: String
): WatchFaceControlClient

This function is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

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

Parameters
context: Context	Calling application's Context.
watchFacePackageName: String	The name of the package containing the watch face control service to bind to.

Returns
WatchFaceControlClient	The WatchFaceControlClient if there is one.

Throws
androidx.wear.watchface.client.WatchFaceControlClient.ServiceNotBoundException	if the watch face control service can not be bound or a ServiceStartFailureException if the watch face dies during startup.

createWatchFaceRuntimeControlClient

suspend fun createWatchFaceRuntimeControlClient(
    context: Context,
    runtimePackageName: String,
    resourceOnlyWatchFacePackageName: String
): WatchFaceControlClient

This function is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Similar createWatchFaceControlClient this constructs a WatchFaceControlClient which attempts to connect to the watch face runtime in the android package runtimePackageName.

A watch face runtime is a special type of watch face, which renders a watch face described by resources in another package resourceOnlyWatchFacePackageName.

Currently Wear OS only supports the runtime for the Android Watch Face Format (see https://developer.android.com/training/wearables/wff for more details).

Parameters
context: Context	Calling application's Context.
runtimePackageName: String	The name of the package containing the watch face runtime's control service to bind to.
resourceOnlyWatchFacePackageName: String	The name of the package from which to load the resource only watch face. This is exposed to the runtime via WatchFaceService.resourceOnlyWatchFacePackageName. Note only one watch face definition per resource only watch face package is supported.

Returns
WatchFaceControlClient	The WatchFaceControlClient if there is one.

Throws
androidx.wear.watchface.client.WatchFaceControlClient.ServiceNotBoundException	if the watch face control service can not be bound or a ServiceStartFailureException if the watch face dies during startup.

Public functions

createHeadlessWatchFaceClient

Added in 1.0.0

Deprecated in 1.1.0

fun createHeadlessWatchFaceClient(
    watchFaceName: ComponentName,
    deviceConfig: DeviceConfig,
    surfaceWidth: @Px Int,
    surfaceHeight: @Px Int
): HeadlessWatchFaceClient?

This function is deprecated.
Creating a headless client without a watchface ID is deprecated

Creates a HeadlessWatchFaceClient with the specified DeviceConfig. Screenshots made with HeadlessWatchFaceClient.renderWatchFaceToBitmap 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: @Px Int	The width of screen shots taken by the HeadlessWatchFaceClient
surfaceHeight: @Px Int	The height of screen shots taken by the HeadlessWatchFaceClient

Returns
HeadlessWatchFaceClient?	The HeadlessWatchFaceClient or null if watchFaceName is unrecognized.

createHeadlessWatchFaceClient

Added in 1.1.0

Deprecated in 1.3.0-alpha07

open fun createHeadlessWatchFaceClient(
    id: String,
    watchFaceName: ComponentName,
    deviceConfig: DeviceConfig,
    surfaceWidth: @Px Int,
    surfaceHeight: @Px Int
): HeadlessWatchFaceClient?

This function is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

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

When finished call HeadlessWatchFaceClient.close to release resources.

Parameters
id: String	The ID for the requested HeadlessWatchFaceClient, will be exposed to the watch face via androidx.wear.watchface.WatchState.watchFaceInstanceId.
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: @Px Int	The width of screen shots taken by the HeadlessWatchFaceClient
surfaceHeight: @Px Int	The height of screen shots taken by the HeadlessWatchFaceClient

Returns
HeadlessWatchFaceClient?	The HeadlessWatchFaceClient or null if watchFaceName is unrecognized.

getDefaultComplicationDataSourcePoliciesAndType

Added in 1.0.0

Deprecated in 1.1.0

fun getDefaultComplicationDataSourcePoliciesAndType(
    watchFaceName: ComponentName
): Map<Int, DefaultComplicationDataSourcePolicyAndType>

This function is deprecated.
Use the WatchFaceMetadataClient instead.

Returns a map of androidx.wear.watchface.ComplicationSlot id to the DefaultComplicationDataSourcePolicyAndType for each androidx.wear.watchface.ComplicationSlot in the watchface corresponding to watchFaceName. Where possible a fast path is used that doesn't need to fully construct the corresponding watch face.

Parameters
watchFaceName: ComponentName	The ComponentName of the watch face to obtain the map of DefaultComplicationDataSourcePolicyAndTypes for. It must be in the same APK the WatchFaceControlClient is connected to. NB a single apk can contain multiple watch faces.

getEditorServiceClient

Added in 1.0.0

Deprecated in 1.3.0-alpha07

fun getEditorServiceClient(): EditorServiceClient

This function is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

getInteractiveWatchFaceClientInstance

Added in 1.0.0

Deprecated in 1.3.0-alpha07

fun getInteractiveWatchFaceClientInstance(instanceId: String): InteractiveWatchFaceClient?

This function is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

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

When finished call InteractiveWatchFaceClient.close to release resources.

Parameters
instanceId: String	The name of the interactive watch face instance to retrieve

Returns
InteractiveWatchFaceClient?	The InteractiveWatchFaceClient or null if instanceId is unrecognized, or ServiceNotBoundException if the WatchFaceControlService is not bound.

getOrCreateInteractiveWatchFaceClient

suspend fun getOrCreateInteractiveWatchFaceClient(
    id: String,
    deviceConfig: DeviceConfig,
    watchUiState: WatchUiState,
    userStyle: UserStyleData?,
    slotIdToComplicationData: Map<Int, ComplicationData>?
): InteractiveWatchFaceClient

This function is deprecated.
Use an overload that specifies Consumer<String>

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

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

Parameters
id: String	The ID for the requested InteractiveWatchFaceClient, will be exposed to the watch face via androidx.wear.watchface.WatchState.watchFaceInstanceId.
deviceConfig: DeviceConfig	The DeviceConfig for the wearable.
watchUiState: WatchUiState	The initial WatchUiState for the wearable.
userStyle: UserStyleData?	Optional UserStyleData to apply to the instance (whether or not it's created). If null then the pre-existing user style is preserved (if the instance is created this will be the androidx.wear.watchface.style.UserStyleSchema's default).
slotIdToComplicationData: Map<Int, ComplicationData>?	The initial androidx.wear.watchface.ComplicationSlot data, or null if unavailable.

Returns
InteractiveWatchFaceClient	The InteractiveWatchFaceClient, this should be closed when finished.

Throws
androidx.wear.watchface.client.WatchFaceControlClient.ServiceStartFailureException	if the watchface dies during startup.

getOrCreateInteractiveWatchFaceClient

open suspend fun getOrCreateInteractiveWatchFaceClient(
    instanceId: String,
    deviceConfig: DeviceConfig,
    watchUiState: WatchUiState,
    userStyle: UserStyleData?,
    slotIdToComplicationData: Map<Int, ComplicationData>?,
    previewImageUpdateRequestedExecutor: Executor,
    previewImageUpdateRequestedListener: Consumer<String>
): InteractiveWatchFaceClient

This function is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

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

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

Parameters
instanceId: String	The ID for the requested InteractiveWatchFaceClient, will be exposed to the watch face via androidx.wear.watchface.WatchState.watchFaceInstanceId.
deviceConfig: DeviceConfig	The DeviceConfig for the wearable.
watchUiState: WatchUiState	The initial WatchUiState for the wearable.
userStyle: UserStyleData?	Optional UserStyleData to apply to the instance (whether or not it's created). If null then the pre-existing user style is preserved (if the instance is created this will be the androidx.wear.watchface.style.UserStyleSchema's default).
slotIdToComplicationData: Map<Int, ComplicationData>?	The initial androidx.wear.watchface.ComplicationSlot data, or null if unavailable.
previewImageUpdateRequestedExecutor: Executor	The Executor on which to run previewImageUpdateRequestedListener if the watch face calls Renderer.sendPreviewImageNeedsUpdateRequest.
previewImageUpdateRequestedListener: Consumer<String>	The Consumer fires when the watch face calls Renderer.sendPreviewImageNeedsUpdateRequest, indicating that it now looks visually different. The string passed to the Consumer is the ID of the watch face (see instanceId passed into getOrCreateInteractiveWatchFaceClient) requesting the update. This will usually match the current watch face but it could also be from a previous watch face if InteractiveWatchFaceClient.updateWatchFaceInstance is called shortly after Renderer.sendPreviewImageNeedsUpdateRequest. The Consumer should Schedule creation of a headless instance to render a new preview image for the instanceId. This is likely an expensive operation and should be rate limited.

Returns
InteractiveWatchFaceClient	The InteractiveWatchFaceClient, this should be closed when finished.

Throws
androidx.wear.watchface.client.WatchFaceControlClient.ServiceStartFailureException	if the watchface dies during startup.

hasComplicationDataCache

Added in 1.1.0

Deprecated in 1.3.0-alpha07

open fun hasComplicationDataCache(): Boolean

This function is deprecated.
AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Whether or not the watch face has a ComplicationData cache. Based on this the system may wish to adopt a different strategy for sending complication data. E.g. sending initial blank complications before fetching the real ones is not necessary.