InteractiveWatchFaceClient

public interface InteractiveWatchFaceClient extends 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

default static final int

Indicates that a previous TAP_TYPE_DOWN event has been canceled.

default static final int

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

default static final int

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

Public methods

abstract void

Registers a ClientDisconnectListener.

default void

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.

abstract void

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

default RemoteWatchFaceViewHost
@RequiresApi(value = 30)
createRemoteWatchFaceViewHost(
    @NonNull IBinder hostToken,
    @Px int width,
    @Px int height
)

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

default Integer
getComplicationIdAt(@Px int x, @Px int y)

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

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

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

abstract @NonNull List<@NonNull ContentDescriptionLabel>

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

abstract @NonNull String

Returns the ID of this watch face instance.

default @NonNull OverlayStyle

The watchface's OverlayStyle which may be null.

abstract @NonNull Instant

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

default @NonNull UserStyleFlavors

Returns the watch face's UserStyleFlavors.

abstract @NonNull UserStyleSchema

The watch face's UserStyleSchema.

default boolean

Whether or not the watch face supports ComplicationDisplayPolicy.

abstract boolean

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

default boolean

Whether or not the watch face supports RemoteWatchFaceViewHost.

abstract void

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

abstract void

Removes a ClientDisconnectListener previously registered by addClientDisconnectListener.

default void

Stops listening for events registered by addOnWatchFaceColorsListener.

abstract void

Stops listening for events registered by addOnWatchFaceReadyListener.

abstract @NonNull Bitmap
@RequiresApi(value = 27)
renderWatchFaceToBitmap(
    @NonNull RenderParameters renderParameters,
    @NonNull Instant instant,
    UserStyle userStyle,
    Map<@NonNull Integer, @NonNull ComplicationData> idAndComplicationData
)

Renders the watchface to a shared memory backed Bitmap with the given settings.

abstract void
sendTouchEvent(@Px int xPosition, @Px int yPosition, int tapType)

Sends a tap event to the watch face for processing.

abstract void

Updates the watch faces WatchUiState.

abstract void
updateComplicationData(
    @NonNull Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

Sends new ComplicationData to the watch face.

abstract void
updateWatchFaceInstance(
    @NonNull String newInstanceId,
    @NonNull 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).

abstract void
updateWatchFaceInstance(
    @NonNull String newInstanceId,
    @NonNull UserStyleData userStyle
)

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

Inherited methods

From java.lang.AutoCloseable
abstract void

Constants

TAP_TYPE_CANCEL

Added in 1.0.0
default static final int TAP_TYPE_CANCEL

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
default static final int TAP_TYPE_DOWN

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

TAP_TYPE_UP

Added in 1.0.0
default static final int TAP_TYPE_UP

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 methods

addClientDisconnectListener

Added in 1.0.0
@AnyThread
abstract void addClientDisconnectListener(
    @NonNull InteractiveWatchFaceClient.ClientDisconnectListener listener,
    @NonNull Executor executor
)

Registers a ClientDisconnectListener.

addOnWatchFaceColorsListener

Added in 1.2.0
@WatchFaceClientExperimental
default void addOnWatchFaceColorsListener(
    @NonNull Executor executor,
    @NonNull Consumer<WatchFaceColors> listener
)

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
@NonNull Executor executor

The Executor on which to run listener.

@NonNull Consumer<WatchFaceColors> listener

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

addOnWatchFaceReadyListener

Added in 1.0.0
abstract void addOnWatchFaceReadyListener(
    @NonNull Executor executor,
    @NonNull InteractiveWatchFaceClient.OnWatchFaceReadyListener listener
)

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
@NonNull Executor executor

The Executor on which to run OnWatchFaceReadyListener.

@NonNull InteractiveWatchFaceClient.OnWatchFaceReadyListener listener

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

createRemoteWatchFaceViewHost

Added in 1.2.0
@RequiresApi(value = 30)
default RemoteWatchFaceViewHost createRemoteWatchFaceViewHost(
    @NonNull IBinder hostToken,
    @Px int width,
    @Px int height
)

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
@NonNull IBinder hostToken

The return value of View.getHostToken()

@Px int width

The width of the view in pixels

@Px int height

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
default Integer getComplicationIdAt(@Px int x, @Px int y)

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.

getComplicationSlotsState

Added in 1.0.0
abstract @NonNull Map<@NonNull Integer, @NonNull ComplicationSlotStategetComplicationSlotsState()

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.

getContentDescriptionLabels

Added in 1.0.0
abstract @NonNull List<@NonNull ContentDescriptionLabelgetContentDescriptionLabels()

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

getInstanceId

Added in 1.0.0
abstract @NonNull String getInstanceId()

Returns the ID of this watch face instance.

getOverlayStyle

Added in 1.1.0
Deprecated in 1.2.0
default @NonNull OverlayStyle getOverlayStyle()

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.

getPreviewReferenceInstant

Added in 1.0.0
abstract @NonNull Instant getPreviewReferenceInstant()

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

getUserStyleFlavors

Added in 1.3.0-alpha01
@RequiresApi(value = 34)
default @NonNull UserStyleFlavors getUserStyleFlavors()

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.

getUserStyleSchema

Added in 1.0.0
abstract @NonNull UserStyleSchema getUserStyleSchema()

The watch face's UserStyleSchema.

isComplicationDisplayPolicySupported

Added in 1.2.0
default boolean isComplicationDisplayPolicySupported()

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
abstract boolean isConnectionAlive()

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

isRemoteWatchFaceViewHostSupported

Added in 1.2.0
default boolean isRemoteWatchFaceViewHostSupported()

Whether or not the watch face supports RemoteWatchFaceViewHost.

performAmbientTick

Added in 1.0.0
abstract void performAmbientTick()

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

removeClientDisconnectListener

Added in 1.0.0
@AnyThread
abstract void removeClientDisconnectListener(
    @NonNull InteractiveWatchFaceClient.ClientDisconnectListener listener
)

Removes a ClientDisconnectListener previously registered by addClientDisconnectListener.

removeOnWatchFaceColorsListener

Added in 1.2.0
@WatchFaceClientExperimental
default void removeOnWatchFaceColorsListener(
    @NonNull Consumer<WatchFaceColors> listener
)

Stops listening for events registered by addOnWatchFaceColorsListener.

removeOnWatchFaceReadyListener

Added in 1.0.0
abstract void removeOnWatchFaceReadyListener(
    @NonNull InteractiveWatchFaceClient.OnWatchFaceReadyListener listener
)

Stops listening for events registered by addOnWatchFaceReadyListener.

renderWatchFaceToBitmap

@RequiresApi(value = 27)
abstract @NonNull Bitmap renderWatchFaceToBitmap(
    @NonNull RenderParameters renderParameters,
    @NonNull Instant instant,
    UserStyle userStyle,
    Map<@NonNull Integer, @NonNull ComplicationData> idAndComplicationData
)

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
@NonNull RenderParameters renderParameters

The RenderParameters to draw with.

@NonNull Instant instant

The Instant render with.

UserStyle userStyle

Optional UserStyle to render with, if null the current style is used.

Map<@NonNull Integer, @NonNull ComplicationData> idAndComplicationData

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

Returns
@NonNull Bitmap

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

sendTouchEvent

Added in 1.0.0
abstract void sendTouchEvent(@Px int xPosition, @Px int yPosition, int tapType)

Sends a tap event to the watch face for processing.

Parameters
@Px int xPosition

The x-coordinate of the tap in pixels

@Px int yPosition

The y-coordinate of the tap in pixels

int tapType

The TapTypeIntDef of the event

setWatchUiState

Added in 1.0.0
abstract void setWatchUiState(@NonNull WatchUiState watchUiState)

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

updateComplicationData

abstract void updateComplicationData(
    @NonNull Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

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.

updateWatchFaceInstance

Added in 1.0.0
abstract void updateWatchFaceInstance(
    @NonNull String newInstanceId,
    @NonNull 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). 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
abstract void updateWatchFaceInstance(
    @NonNull String newInstanceId,
    @NonNull UserStyleData userStyle
)

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.