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.

use Watch Face Format instead

Summary

Nested types

This interface is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

This interface is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Constants

default static final int

This field is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default static final int

This field is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default static final int

This field is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Public methods

abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract @NonNull List<@NonNull ContentDescriptionLabel>

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract @NonNull String

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default @NonNull OverlayStyle

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract @NonNull Instant

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default @NonNull UserStyleFlavors

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract @NonNull UserStyleSchema

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default boolean

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract boolean

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default boolean

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

default void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Inherited methods

From java.lang.AutoCloseable
abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Constants

TAP_TYPE_CANCEL

Added in 1.0.0
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
default static final int TAP_TYPE_DOWN

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

TAP_TYPE_UP

Added in 1.0.0
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
@AnyThread
abstract void addClientDisconnectListener(
    @NonNull InteractiveWatchFaceClient.ClientDisconnectListener listener,
    @NonNull Executor executor
)

Registers a ClientDisconnectListener.

addOnWatchFaceColorsListener

Added in 1.2.0
Deprecated in 1.3.0-alpha06
@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
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
@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
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
abstract @NonNull List<@NonNull ContentDescriptionLabelgetContentDescriptionLabels()

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

getInstanceId

Added in 1.0.0
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
abstract @NonNull Instant getPreviewReferenceInstant()

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

getUserStyleFlavors

Added in 1.3.0-alpha06
Deprecated in 1.3.0-alpha06
@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
Deprecated in 1.3.0-alpha06
abstract @NonNull UserStyleSchema getUserStyleSchema()

The watch face's UserStyleSchema.

isComplicationDisplayPolicySupported

Added in 1.2.0
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
@AnyThread
abstract boolean isConnectionAlive()

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

isRemoteWatchFaceViewHostSupported

Added in 1.2.0
Deprecated in 1.3.0-alpha06
default boolean isRemoteWatchFaceViewHostSupported()

Whether or not the watch face supports RemoteWatchFaceViewHost.

performAmbientTick

Added in 1.0.0
Deprecated in 1.3.0-alpha06
abstract void performAmbientTick()

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

removeClientDisconnectListener

Added in 1.0.0
Deprecated in 1.3.0-alpha06
@AnyThread
abstract void removeClientDisconnectListener(
    @NonNull InteractiveWatchFaceClient.ClientDisconnectListener listener
)

Removes a ClientDisconnectListener previously registered by addClientDisconnectListener.

removeOnWatchFaceColorsListener

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

Stops listening for events registered by addOnWatchFaceColorsListener.

removeOnWatchFaceReadyListener

Added in 1.0.0
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
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
Deprecated in 1.3.0-alpha06
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.