WatchFaceControlClient

interface WatchFaceControlClient

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

WatchFaceControlClient.Companion
WatchFaceControlClient.ServiceNotBoundException

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

WatchFaceControlClient.ServiceStartFailureException

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

Public methods

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

Creates a HeadlessWatchFaceClient with the specified DeviceConfig.

abstract @NonNull Map<@NonNull Integer, @NonNull 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.

abstract @NonNull EditorServiceClient
abstract @Nullable 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,
    @Nullable UserStyleData userStyle,
    @Nullable 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.

Inherited methods

From class AutoCloseable
abstract void

Public methods

createHeadlessWatchFaceClient

@Nullable
public 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.

getDefaultComplicationDataSourcePoliciesAndType

@NonNull
public abstract 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

@NonNull
public abstract EditorServiceClient getEditorServiceClient()

getInteractiveWatchFaceClientInstance

@Nullable
public 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

@NonNull
public abstract InteractiveWatchFaceClient getOrCreateInteractiveWatchFaceClient(
    @NonNull String id,
    @NonNull DeviceConfig deviceConfig,
    @NonNull WatchUiState watchUiState,
    @Nullable UserStyleData userStyle,
    @Nullable 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.

@NonNull DeviceConfig deviceConfig

The DeviceConfig for the wearable.

@NonNull WatchUiState watchUiState

The initial WatchUiState for the wearable.

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

@Nullable Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData

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.