WatchFaceControlClient

public interface WatchFaceControlClient extends AutoCloseable

Known direct subclasses
ListenableWatchFaceControlClient

ListenableFuture-based compatibility wrapper around WatchFaceControlClient's suspending methods.


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

Summary

Nested types

Exception thrown by createWatchFaceControlClient if the remote service can't be bound.

Exception thrown by WatchFaceControlClient methods if the service dies during start up.

Public methods

abstract HeadlessWatchFaceClient
createHeadlessWatchFaceClient(
    @NonNull ComponentName watchFaceName,
    @NonNull DeviceConfig deviceConfig,
    @Px int surfaceWidth,
    @Px int surfaceHeight
)

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

default HeadlessWatchFaceClient
createHeadlessWatchFaceClient(
    @NonNull String id,
    @NonNull ComponentName watchFaceName,
    @NonNull DeviceConfig deviceConfig,
    @Px int surfaceWidth,
    @Px int surfaceHeight
)

Creates a HeadlessWatchFaceClient with the specified DeviceConfig.

default static final @NonNull WatchFaceControlClient
createWatchFaceControlClient(
    @NonNull Context context,
    @NonNull String watchFacePackageName
)

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

default static final @NonNull WatchFaceControlClient
createWatchFaceRuntimeControlClient(
    @NonNull Context context,
    @NonNull String runtimePackageName,
    @NonNull String resourceOnlyWatchFacePackageName
)

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

abstract @NonNull Map<@NonNull Integer, @NonNull DefaultComplicationDataSourcePolicyAndType>

This method is deprecated. Use the WatchFaceMetadataClient instead.

abstract @NonNull EditorServiceClient
abstract InteractiveWatchFaceClient

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

abstract @NonNull InteractiveWatchFaceClient
getOrCreateInteractiveWatchFaceClient(
    @NonNull String id,
    @NonNull DeviceConfig deviceConfig,
    @NonNull WatchUiState watchUiState,
    UserStyleData userStyle,
    Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

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

default @NonNull InteractiveWatchFaceClient
getOrCreateInteractiveWatchFaceClient(
    @NonNull String instanceId,
    @NonNull DeviceConfig deviceConfig,
    @NonNull WatchUiState watchUiState,
    UserStyleData userStyle,
    Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData,
    @NonNull Executor previewImageUpdateRequestedExecutor,
    @NonNull Consumer<@NonNull String> previewImageUpdateRequestedListener
)

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

default boolean

Whether or not the watch face has a ComplicationData cache.

Inherited methods

From java.lang.AutoCloseable
abstract void

Public methods

createHeadlessWatchFaceClient

Added in 1.0.0
Deprecated in 1.1.0
abstract HeadlessWatchFaceClient createHeadlessWatchFaceClient(
    @NonNull ComponentName watchFaceName,
    @NonNull DeviceConfig deviceConfig,
    @Px int surfaceWidth,
    @Px int surfaceHeight
)

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
@NonNull ComponentName watchFaceName

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.

@NonNull DeviceConfig deviceConfig

The hardware DeviceConfig

@Px int surfaceWidth

The width of screen shots taken by the HeadlessWatchFaceClient

@Px int surfaceHeight

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
default HeadlessWatchFaceClient createHeadlessWatchFaceClient(
    @NonNull String id,
    @NonNull ComponentName watchFaceName,
    @NonNull DeviceConfig deviceConfig,
    @Px int surfaceWidth,
    @Px int surfaceHeight
)

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
@NonNull String id

The ID for the requested HeadlessWatchFaceClient, will be exposed to the watch face via androidx.wear.watchface.WatchState.watchFaceInstanceId.

@NonNull ComponentName watchFaceName

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.

@NonNull DeviceConfig deviceConfig

The hardware DeviceConfig

@Px int surfaceWidth

The width of screen shots taken by the HeadlessWatchFaceClient

@Px int surfaceHeight

The height of screen shots taken by the HeadlessWatchFaceClient

Returns
HeadlessWatchFaceClient

The HeadlessWatchFaceClient or null if watchFaceName is unrecognized.

createWatchFaceControlClient

default static final @NonNull WatchFaceControlClient createWatchFaceControlClient(
    @NonNull Context context,
    @NonNull String watchFacePackageName
)

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

Parameters
@NonNull Context context

Calling application's Context.

@NonNull String watchFacePackageName

The name of the package containing the watch face control service to bind to.

Returns
@NonNull 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

default static final @NonNull WatchFaceControlClient createWatchFaceRuntimeControlClient(
    @NonNull Context context,
    @NonNull String runtimePackageName,
    @NonNull String resourceOnlyWatchFacePackageName
)

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
@NonNull Context context

Calling application's Context.

@NonNull String runtimePackageName

The name of the package containing the watch face runtime's control service to bind to.

@NonNull String resourceOnlyWatchFacePackageName

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
@NonNull 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.

getDefaultComplicationDataSourcePoliciesAndType

Added in 1.0.0
Deprecated in 1.1.0
abstract @NonNull Map<@NonNull Integer, @NonNull DefaultComplicationDataSourcePolicyAndTypegetDefaultComplicationDataSourcePoliciesAndType(
    @NonNull ComponentName watchFaceName
)

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
@NonNull ComponentName watchFaceName

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
abstract @NonNull EditorServiceClient getEditorServiceClient()

getInteractiveWatchFaceClientInstance

Added in 1.0.0
abstract InteractiveWatchFaceClient getInteractiveWatchFaceClientInstance(@NonNull String instanceId)

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

When finished call InteractiveWatchFaceClient.close to release resources.

Parameters
@NonNull String instanceId

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

abstract @NonNull InteractiveWatchFaceClient getOrCreateInteractiveWatchFaceClient(
    @NonNull String id,
    @NonNull DeviceConfig deviceConfig,
    @NonNull WatchUiState watchUiState,
    UserStyleData userStyle,
    Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

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
@NonNull String id

The ID for the requested InteractiveWatchFaceClient, will be exposed to the watch face via androidx.wear.watchface.WatchState.watchFaceInstanceId.

@NonNull DeviceConfig deviceConfig

The DeviceConfig for the wearable.

@NonNull WatchUiState watchUiState

The initial WatchUiState for the wearable.

UserStyleData userStyle

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

Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData

The initial androidx.wear.watchface.ComplicationSlot data, or null if unavailable.

Returns
@NonNull InteractiveWatchFaceClient

The InteractiveWatchFaceClient, this should be closed when finished.

getOrCreateInteractiveWatchFaceClient

default @NonNull InteractiveWatchFaceClient getOrCreateInteractiveWatchFaceClient(
    @NonNull String instanceId,
    @NonNull DeviceConfig deviceConfig,
    @NonNull WatchUiState watchUiState,
    UserStyleData userStyle,
    Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData,
    @NonNull Executor previewImageUpdateRequestedExecutor,
    @NonNull Consumer<@NonNull String> previewImageUpdateRequestedListener
)

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
@NonNull String instanceId

The ID for the requested InteractiveWatchFaceClient, will be exposed to the watch face via androidx.wear.watchface.WatchState.watchFaceInstanceId.

@NonNull DeviceConfig deviceConfig

The DeviceConfig for the wearable.

@NonNull WatchUiState watchUiState

The initial WatchUiState for the wearable.

UserStyleData userStyle

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

Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData

The initial androidx.wear.watchface.ComplicationSlot data, or null if unavailable.

@NonNull Executor previewImageUpdateRequestedExecutor

The Executor on which to run previewImageUpdateRequestedListener if the watch face calls Renderer.sendPreviewImageNeedsUpdateRequest.

@NonNull Consumer<@NonNull String> previewImageUpdateRequestedListener

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
@NonNull InteractiveWatchFaceClient

The InteractiveWatchFaceClient, this should be closed when finished.

hasComplicationDataCache

Added in 1.1.0
default boolean hasComplicationDataCache()

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.