ListenableWatchFaceControlClient

open class ListenableWatchFaceControlClient : WatchFaceControlClient

ListenableFuture-based compatibility wrapper around WatchFaceControlClient's suspending methods. This class is open to allow mocking.

Summary

Public companion functions
ListenableFuture<ListenableWatchFaceControlClient>
createWatchFaceControlClient(
    context: Context,
    watchFacePackageName: String
)

Returns a ListenableFuture for a ListenableWatchFaceControlClient which attempts to connect to a watch face in the android package watchFacePackageName.
ListenableFuture<ListenableWatchFaceControlClient>
createWatchFaceRuntimeControlClientAsync(
    context: Context,
    runtimePackageName: String,
    resourceOnlyWatchFacePackageName: String
)

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

Public constructors

Public functions
open Unit
open HeadlessWatchFaceClient?
createHeadlessWatchFaceClient(
    watchFaceName: ComponentName,
    deviceConfig: DeviceConfig,
    surfaceWidth: Int,
    surfaceHeight: Int
)

This function is deprecated. createHeadlessWatchFaceClient without an id is deprecated
open HeadlessWatchFaceClient?
createHeadlessWatchFaceClient(
    id: String,
    watchFaceName: ComponentName,
    deviceConfig: DeviceConfig,
    surfaceWidth: Int,
    surfaceHeight: Int
)

Creates a HeadlessWatchFaceClient with the specified DeviceConfig.
open Map<Int, DefaultComplicationDataSourcePolicyAndType>

This function is deprecated. Use the WatchFaceMetadataClient instead.
open EditorServiceClient
open InteractiveWatchFaceClient?

Returns the InteractiveWatchFaceClient for the given instance id, or null if no such instance exists.
open suspend InteractiveWatchFaceClient
getOrCreateInteractiveWatchFaceClient(
    id: String,
    deviceConfig: DeviceConfig,
    watchUiState: WatchUiState,
    userStyle: UserStyleData?,
    slotIdToComplicationData: Map<Int, ComplicationData>?
)

This function is deprecated. Use an overload that specifies a Consumer<String>
open suspend InteractiveWatchFaceClient
getOrCreateInteractiveWatchFaceClient(
    instanceId: String,
    deviceConfig: DeviceConfig,
    watchUiState: WatchUiState,
    userStyle: UserStyleData?,
    slotIdToComplicationData: Map<Int, ComplicationData>?,
    previewImageUpdateRequestedExecutor: Executor,
    previewImageUpdateRequestedListener: Consumer<String>
)

Requests either an existing InteractiveWatchFaceClient with the specified instanceId or schedules creation of an InteractiveWatchFaceClient for the next time the WallpaperService creates an engine.
open ListenableFuture<InteractiveWatchFaceClient>
listenableGetOrCreateInteractiveWatchFaceClient(
    id: String,
    deviceConfig: DeviceConfig,
    watchUiState: WatchUiState,
    userStyle: UserStyleData?,
    slotIdToComplicationData: Map<Int, ComplicationData>?
)

This function is deprecated. Use an overload that specifies Consumer<String>
open ListenableFuture<InteractiveWatchFaceClient>
listenableGetOrCreateInteractiveWatchFaceClient(
    id: String,
    deviceConfig: DeviceConfig,
    watchUiState: WatchUiState,
    userStyle: UserStyleData?,
    slotIdToComplicationData: Map<Int, ComplicationData>?,
    previewImageUpdateRequestedExecutor: Executor,
    previewImageUpdateRequestedListener: Consumer<String>
)

ListenableFuture wrapper around WatchFaceControlClient.getOrCreateInteractiveWatchFaceClient.

Inherited functions
From androidx.wear.watchface.client.WatchFaceControlClient
open Boolean

Whether or not the watch face has a ComplicationData cache.

Public companion functions

createWatchFaceControlClient

Added in 1.0.0
fun createWatchFaceControlClient(
    context: Context,
    watchFacePackageName: String
): ListenableFuture<ListenableWatchFaceControlClient>

Returns a ListenableFuture for a ListenableWatchFaceControlClient which attempts to connect to a watch face in the android package watchFacePackageName. Resolves as ServiceNotBoundException if the watch face control service can not be bound.

Note the returned future may resolve immediately on the calling thread or it may resolve asynchronously when the service is connected on a background thread.

Parameters
context: Context

Calling application's Context.
watchFacePackageName: String

Name of the package containing the watch face control service to bind to.
Returns
ListenableFuture<ListenableWatchFaceControlClient>

ListenableFuture<ListenableWatchFaceControlClient> which on success resolves to a ListenableWatchFaceControlClient or throws a ServiceNotBoundException if the watch face control service can not be bound.

createWatchFaceRuntimeControlClientAsync

Added in 1.2.0
fun createWatchFaceRuntimeControlClientAsync(
    context: Context,
    runtimePackageName: String,
    resourceOnlyWatchFacePackageName: String
): ListenableFuture<ListenableWatchFaceControlClient>

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.

Note only one watch face definition per resource only watch face package is supported.

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 the resourceOnlyWatchFacePackageName parameter passed to WatchFaceRuntimeService.createUserStyleSchema, WatchFaceRuntimeService.createComplicationSlotsManager, WatchFaceRuntimeService.createUserStyleFlavors and WatchFaceRuntimeService.createWatchFace).
Returns
ListenableFuture<ListenableWatchFaceControlClient>

ListenableFuture<ListenableWatchFaceControlClient> which on success resolves to a ListenableWatchFaceControlClient or throws a ServiceNotBoundException if the watch face control service can not be bound.

Public constructors

ListenableWatchFaceControlClient

Added in 1.0.0
ListenableWatchFaceControlClient(
    watchFaceControlClient: WatchFaceControlClient
)

Public functions

close

Added in 1.0.0
open fun close(): Unit

createHeadlessWatchFaceClient

Added in 1.0.0
Deprecated in 1.1.0
open fun createHeadlessWatchFaceClient(
    watchFaceName: ComponentName,
    deviceConfig: DeviceConfig,
    surfaceWidth: Int,
    surfaceHeight: Int
): HeadlessWatchFaceClient?

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: Int

The width of screen shots taken by the HeadlessWatchFaceClient
surfaceHeight: 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
open fun createHeadlessWatchFaceClient(
    id: String,
    watchFaceName: ComponentName,
    deviceConfig: DeviceConfig,
    surfaceWidth: Int,
    surfaceHeight: Int
): HeadlessWatchFaceClient?

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: Int

The width of screen shots taken by the HeadlessWatchFaceClient
surfaceHeight: 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
open fun getDefaultComplicationDataSourcePoliciesAndType(
    watchFaceName: ComponentName
): Map<Int, DefaultComplicationDataSourcePolicyAndType>

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
open fun getEditorServiceClient(): EditorServiceClient

getInteractiveWatchFaceClientInstance

Added in 1.0.0
open fun getInteractiveWatchFaceClientInstance(instanceId: String): InteractiveWatchFaceClient?

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

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

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
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

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
ServiceStartFailureException

if the watchface dies during startup.

listenableGetOrCreateInteractiveWatchFaceClient

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

ListenableFuture wrapper around WatchFaceControlClient.getOrCreateInteractiveWatchFaceClient. This is open to allow mocking.

Parameters
id: String

The Id of the interactive instance to get or create.
deviceConfig: DeviceConfig

The DeviceConfig of the interactive instance (only used when creating)
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
ListenableFuture<InteractiveWatchFaceClient>

a ListenableFuture for the InteractiveWatchFaceClient.

listenableGetOrCreateInteractiveWatchFaceClient

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

ListenableFuture wrapper around WatchFaceControlClient.getOrCreateInteractiveWatchFaceClient. This is open to allow mocking.

Parameters
id: String

The Id of the interactive instance to get or create.
deviceConfig: DeviceConfig

The DeviceConfig of the interactive instance (only used when creating)
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 id 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
ListenableFuture<InteractiveWatchFaceClient>

a ListenableFuture for the InteractiveWatchFaceClient.