InteractiveWatchFaceClient

interface InteractiveWatchFaceClient : AutoCloseable

Controls a stateful remote interactive watch face. Typically this will be used for the current active watch face.

Note clients should call close when finished.

Summary

Nested types

Callback that observes when the client disconnects.

Interface passed to addOnWatchFaceReadyListener which calls OnWatchFaceReadyListener.onWatchFaceReady when the watch face is ready to render.

Constants
const Int

Indicates that a previous TAP_TYPE_DOWN event has been canceled.
const Int

Indicates a "down" touch event on the watch face.
const Int

Indicates that an "up" event on the watch face has occurred that has not been consumed by another activity.

Public functions
Unit

Registers a ClientDisconnectListener.
open Unit

Registers a Consumer which gets called initially with the current Renderer.watchfaceColors if known or null if not, and subsequently whenever the watch face's Renderer.watchfaceColors change.
Unit

Registers a OnWatchFaceReadyListener which gets called when the watch face is ready to render.
open RemoteWatchFaceViewHost?
@RequiresApi(value = 30)
createRemoteWatchFaceViewHost(
    hostToken: IBinder,
    width: @Px Int,
    height: @Px Int
)

Constructs a RemoteWatchFaceViewHost whose RemoteWatchFaceViewHost.surfacePackage can be attached to a SurfaceView owned by the client with SurfaceView.setChildSurfacePackage.
open Int?

Returns the ID of the androidx.wear.watchface.ComplicationSlot at the given coordinates or null if there isn't one.
open UserStyleFlavors

Returns the watch face's UserStyleFlavors.
open Boolean

Whether or not the watch face supports ComplicationDisplayPolicy.
Boolean

Returns true if the connection to the server side is alive.
Unit

Triggers watch face rendering into the surface when in ambient mode.
Unit

Removes a ClientDisconnectListener previously registered by addClientDisconnectListener.
open Unit

Stops listening for events registered by addOnWatchFaceColorsListener.
Unit

Stops listening for events registered by addOnWatchFaceReadyListener.
Bitmap
@RequiresApi(value = 27)
renderWatchFaceToBitmap(
    renderParameters: RenderParameters,
    instant: Instant,
    userStyle: UserStyle?,
    idAndComplicationData: Map<Int, ComplicationData>?
)

Renders the watchface to a shared memory backed Bitmap with the given settings.
Unit
sendTouchEvent(xPosition: @Px Int, yPosition: @Px Int, tapType: Int)

Sends a tap event to the watch face for processing.
Unit

Updates the watch faces WatchUiState.
Unit
updateComplicationData(
    slotIdToComplicationData: Map<Int, ComplicationData>
)

Sends new ComplicationData to the watch face.
Unit
updateWatchFaceInstance(newInstanceId: String, userStyle: UserStyle)

Renames this instance to newInstanceId (must be unique, usually this would be different from the old ID but that's not a requirement).
Unit
updateWatchFaceInstance(newInstanceId: String, userStyle: UserStyleData)

Renames this instance to newInstanceId (must be unique, usually this would be different from the old ID but that's not a requirement).

Public properties
Map<Int, ComplicationSlotState>

Map of androidx.wear.watchface.ComplicationSlot ids to ComplicationSlotState for each ComplicationSlot registered with the watch face's ComplicationSlotsManager.
List<ContentDescriptionLabel>

Returns the ContentDescriptionLabels describing the watch face, for the use by screen readers.
String

Returns the ID of this watch face instance.
open Boolean

Whether or not the watch face supports RemoteWatchFaceViewHost.
open OverlayStyle

This property is deprecated. OverlayStyle will be removed in a future release.
Instant

The UTC reference preview time for this watch face in milliseconds since the epoch.
UserStyleSchema

The watch face's UserStyleSchema.

Inherited functions
From java.lang.AutoCloseable
Unit

Constants

TAP_TYPE_CANCEL

Added in 1.0.0
const val TAP_TYPE_CANCEL: Int

Indicates that a previous TAP_TYPE_DOWN event has been canceled. This generally happens when the watch face is touched but then a move or long press occurs.

TAP_TYPE_DOWN

Added in 1.0.0
const val TAP_TYPE_DOWN: Int

Indicates a "down" touch event on the watch face.

TAP_TYPE_UP

Added in 1.0.0
const val TAP_TYPE_UP: Int

Indicates that an "up" event on the watch face has occurred that has not been consumed by another activity. A TAP_TYPE_DOWN always occur first. This event will not occur if a TAP_TYPE_CANCEL is sent.

Public functions

addClientDisconnectListener

Added in 1.0.0
@AnyThread
fun addClientDisconnectListener(
    listener: InteractiveWatchFaceClient.ClientDisconnectListener,
    executor: Executor
): Unit

Registers a ClientDisconnectListener.

addOnWatchFaceColorsListener

Added in 1.2.0
@WatchFaceClientExperimental
open fun addOnWatchFaceColorsListener(
    executor: Executor,
    listener: Consumer<WatchFaceColors?>
): Unit

Registers a Consumer which gets called initially with the current Renderer.watchfaceColors if known or null if not, and subsequently whenever the watch face's Renderer.watchfaceColors change.

Parameters
executor: Executor

The Executor on which to run listener.
listener: Consumer<WatchFaceColors?>

The Consumer to run whenever the watch face's Renderer.watchfaceColors change.

addOnWatchFaceReadyListener

Added in 1.0.0
fun addOnWatchFaceReadyListener(
    executor: Executor,
    listener: InteractiveWatchFaceClient.OnWatchFaceReadyListener
): Unit

Registers a OnWatchFaceReadyListener which gets called when the watch face is ready to render.

Note in the event of the watch face disconnecting (e.g. due to a crash) the listener will never get called. Use ClientDisconnectListener to observe disconnects.

Parameters
executor: Executor

The Executor on which to run OnWatchFaceReadyListener.
listener: InteractiveWatchFaceClient.OnWatchFaceReadyListener

The OnWatchFaceReadyListener to run when the watchface is ready to render.

createRemoteWatchFaceViewHost

Added in 1.2.0
@RequiresApi(value = 30)
open fun createRemoteWatchFaceViewHost(
    hostToken: IBinder,
    width: @Px Int,
    height: @Px Int
): RemoteWatchFaceViewHost?

Constructs a RemoteWatchFaceViewHost whose RemoteWatchFaceViewHost.surfacePackage can be attached to a SurfaceView owned by the client with SurfaceView.setChildSurfacePackage. The watch face will render into this view upon demand (see RemoteWatchFaceViewHost.renderWatchFace).

This is more efficient than calling renderWatchFaceToBitmap multiple times, although there is some overhead (memory and cpu) to setting up a RemoteWatchFaceViewHost.

Requires the watchface to be compiled with a compatible library, to check if that's the case use isRemoteWatchFaceViewHostSupported.

Parameters
hostToken: IBinder

The return value of View.getHostToken()
width: @Px Int

The width of the view in pixels
height: @Px Int

The height of the view in pixels
Returns
RemoteWatchFaceViewHost?

The RemoteWatchFaceViewHost or null if the client has already been closed or if the watch face is not compatible.

getComplicationIdAt

Added in 1.0.0
open fun getComplicationIdAt(x: @Px Int, y: @Px Int): Int?

Returns the ID of the androidx.wear.watchface.ComplicationSlot at the given coordinates or null if there isn't one.

Note this currently doesn't support Edge complications.

getUserStyleFlavors

Added in 1.3.0-alpha04
@RequiresApi(value = 34)
open fun getUserStyleFlavors(): UserStyleFlavors

Returns the watch face's UserStyleFlavors.

Throws
kotlin.RuntimeException

if the watch face threw an exception while trying to service the request or there was a communication problem with watch face process.

isComplicationDisplayPolicySupported

Added in 1.2.0
open fun isComplicationDisplayPolicySupported(): Boolean

Whether or not the watch face supports ComplicationDisplayPolicy. If it doesn't then the client is responsible for emulating it by observing the state of the keyguard and sending NoData complications when the device becomes locked and subsequently restoring them when it becomes unlocked for affected complications.

isConnectionAlive

Added in 1.0.0
@AnyThread
fun isConnectionAlive(): Boolean

Returns true if the connection to the server side is alive.

performAmbientTick

Added in 1.0.0
fun performAmbientTick(): Unit

Triggers watch face rendering into the surface when in ambient mode.

removeClientDisconnectListener

Added in 1.0.0
@AnyThread
fun removeClientDisconnectListener(
    listener: InteractiveWatchFaceClient.ClientDisconnectListener
): Unit

Removes a ClientDisconnectListener previously registered by addClientDisconnectListener.

removeOnWatchFaceColorsListener

Added in 1.2.0
@WatchFaceClientExperimental
open fun removeOnWatchFaceColorsListener(listener: Consumer<WatchFaceColors?>): Unit

Stops listening for events registered by addOnWatchFaceColorsListener.

removeOnWatchFaceReadyListener

Added in 1.0.0
fun removeOnWatchFaceReadyListener(
    listener: InteractiveWatchFaceClient.OnWatchFaceReadyListener
): Unit

Stops listening for events registered by addOnWatchFaceReadyListener.

renderWatchFaceToBitmap

@RequiresApi(value = 27)
fun renderWatchFaceToBitmap(
    renderParameters: RenderParameters,
    instant: Instant,
    userStyle: UserStyle?,
    idAndComplicationData: Map<Int, ComplicationData>?
): Bitmap

Renders the watchface to a shared memory backed Bitmap with the given settings. Note this will be fairly slow since either software canvas or glReadPixels will be invoked.

Parameters
renderParameters: RenderParameters

The RenderParameters to draw with.
instant: Instant

The Instant render with.
userStyle: UserStyle?

Optional UserStyle to render with, if null the current style is used.
idAndComplicationData: Map<Int, ComplicationData>?

Map of complication ids to ComplicationData to render with, or if null then the existing complication data if any is used.
Returns
Bitmap

A shared memory backed Bitmap containing a screenshot of the watch face with the given settings.

sendTouchEvent

Added in 1.0.0
fun sendTouchEvent(xPosition: @Px Int, yPosition: @Px Int, tapType: Int): Unit

Sends a tap event to the watch face for processing.

Parameters
xPosition: @Px Int

The x-coordinate of the tap in pixels
yPosition: @Px Int

The y-coordinate of the tap in pixels
tapType: Int

The TapTypeIntDef of the event

setWatchUiState

Added in 1.0.0
fun setWatchUiState(watchUiState: WatchUiState): Unit

Updates the watch faces WatchUiState. NB setWatchUiState and updateWatchFaceInstance can be called in any order.

updateComplicationData

fun updateComplicationData(
    slotIdToComplicationData: Map<Int, ComplicationData>
): Unit

Sends new ComplicationData to the watch face. Note this doesn't have to be a full update, it's possible to update just one complication at a time, but doing so may result in a less visually clean transition.

Parameters
slotIdToComplicationData: Map<Int, ComplicationData>

The ComplicationData for each androidx.wear.watchface.ComplicationSlot.

updateWatchFaceInstance

Added in 1.0.0
fun updateWatchFaceInstance(newInstanceId: String, userStyle: UserStyle): Unit

Renames this instance to newInstanceId (must be unique, usually this would be different from the old ID but that's not a requirement). Sets the current UserStyle and clears any complication data. Setting the new UserStyle may have a side effect of enabling or disabling complicationSlots, which will be visible via ComplicationSlotState.isEnabled.

NB setWatchUiState and updateWatchFaceInstance can be called in any order.

updateWatchFaceInstance

Added in 1.0.0
fun updateWatchFaceInstance(newInstanceId: String, userStyle: UserStyleData): Unit

Renames this instance to newInstanceId (must be unique, usually this would be different from the old ID but that's not a requirement). Sets the current UserStyle represented as a [UserStyleData> and clears any complication data. Setting the new UserStyle may have a side effect of enabling or disabling complicationSlots, which will be visible via ComplicationSlotState.isEnabled.

Public properties

complicationSlotsState

Added in 1.0.0
val complicationSlotsState: Map<Int, ComplicationSlotState>

Map of androidx.wear.watchface.ComplicationSlot ids to ComplicationSlotState for each ComplicationSlot registered with the watch face's ComplicationSlotsManager. The ComplicationSlotState is based on the initial state of each androidx.wear.watchface.ComplicationSlot plus any overrides from a ComplicationSlotsUserStyleSetting. As a consequence ComplicationSlotState may update based on style changes.

contentDescriptionLabels

Added in 1.0.0
val contentDescriptionLabels: List<ContentDescriptionLabel>

Returns the ContentDescriptionLabels describing the watch face, for the use by screen readers.

instanceId

Added in 1.0.0
val instanceId: String

Returns the ID of this watch face instance.

isRemoteWatchFaceViewHostSupported

Added in 1.2.0
open val isRemoteWatchFaceViewHostSupported: Boolean

Whether or not the watch face supports RemoteWatchFaceViewHost.

overlayStyle

Added in 1.1.0
Deprecated in 1.2.0
open val overlayStyle: OverlayStyle

The watchface's OverlayStyle which may be null.

Note while this plumbing got built, it was never used by the system ui on any platform and it will be removed.

previewReferenceInstant

Added in 1.0.0
val previewReferenceInstant: Instant

The UTC reference preview time for this watch face in milliseconds since the epoch.

userStyleSchema

Added in 1.0.0
val userStyleSchema: UserStyleSchema

The watch face's UserStyleSchema.