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 |
|---|
public interface InteractiveWatchFaceClient.ClientDisconnectListenerCallback that observes when the client disconnects. |
public fun interface InteractiveWatchFaceClient.OnWatchFaceReadyListenerInterface passed to |
Constants |
|
|---|---|
default static final int |
Indicates that a previous |
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 |
@AnyThreadRegisters a |
default void |
@WatchFaceClientExperimentalRegisters a |
abstract void |
addOnWatchFaceReadyListener(Registers a |
default RemoteWatchFaceViewHost |
@RequiresApi(value = 30)Constructs a |
default Integer |
getComplicationIdAt(@Px int x, @Px int y)Returns the ID of the |
abstract @NonNull Map<@NonNull Integer, @NonNull ComplicationSlotState> |
Map of |
abstract @NonNull List<@NonNull ContentDescriptionLabel> |
Returns the |
abstract @NonNull String |
Returns the ID of this watch face instance. |
default @NonNull OverlayStyle |
The watchface's |
abstract @NonNull Instant |
The UTC reference preview time for this watch face in milliseconds since the epoch. |
default @NonNull UserStyleFlavors |
@RequiresApi(value = 34)Returns the watch face's |
abstract @NonNull UserStyleSchema |
The watch face's |
default boolean |
Whether or not the watch face supports |
abstract boolean |
Returns true if the connection to the server side is alive. |
default boolean |
Whether or not the watch face supports |
abstract void |
Triggers watch face rendering into the surface when in ambient mode. |
abstract void |
@AnyThreadRemoves a |
default void |
@WatchFaceClientExperimentalStops listening for events registered by |
abstract void |
removeOnWatchFaceReadyListener(Stops listening for events registered by |
abstract @NonNull Bitmap |
@RequiresApi(value = 27)Renders the watchface to a shared memory backed |
abstract void |
sendTouchEvent(@Px int xPosition, @Px int yPosition, int tapType)Sends a tap event to the watch face for processing. |
abstract void |
setWatchUiState(@NonNull WatchUiState watchUiState)Updates the watch faces |
abstract void |
updateComplicationData(Sends new |
abstract void |
updateWatchFaceInstance(Renames this instance to |
abstract void |
updateWatchFaceInstance(Renames this instance to |
Inherited methods |
||
|---|---|---|
|
Constants
TAP_TYPE_CANCEL
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
default static final int TAP_TYPE_DOWN
Indicates a "down" touch event on the watch face.
TAP_TYPE_UP
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
@AnyThread
abstract void addClientDisconnectListener(
@NonNull InteractiveWatchFaceClient.ClientDisconnectListener listener,
@NonNull Executor executor
)
Registers a ClientDisconnectListener.
addOnWatchFaceColorsListener
@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 |
|
@NonNull Consumer<WatchFaceColors> listener |
The |
addOnWatchFaceReadyListener
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 |
@NonNull InteractiveWatchFaceClient.OnWatchFaceReadyListener listener |
The |
createRemoteWatchFaceViewHost
@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 |
getComplicationIdAt
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
abstract @NonNull Map<@NonNull Integer, @NonNull ComplicationSlotState> getComplicationSlotsState()
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
abstract @NonNull List<@NonNull ContentDescriptionLabel> getContentDescriptionLabels()
Returns the ContentDescriptionLabels describing the watch face, for the use by screen readers.
getInstanceId
abstract @NonNull String getInstanceId()
Returns the ID of this watch face instance.
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
abstract @NonNull Instant getPreviewReferenceInstant()
The UTC reference preview time for this watch face in milliseconds since the epoch.
getUserStyleFlavors
@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
abstract @NonNull UserStyleSchema getUserStyleSchema()
The watch face's UserStyleSchema.
isComplicationDisplayPolicySupported
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
@AnyThread
abstract boolean isConnectionAlive()
Returns true if the connection to the server side is alive.
isRemoteWatchFaceViewHostSupported
default boolean isRemoteWatchFaceViewHostSupported()
Whether or not the watch face supports RemoteWatchFaceViewHost.
performAmbientTick
abstract void performAmbientTick()
Triggers watch face rendering into the surface when in ambient mode.
removeClientDisconnectListener
@AnyThread
abstract void removeClientDisconnectListener(
@NonNull InteractiveWatchFaceClient.ClientDisconnectListener listener
)
Removes a ClientDisconnectListener previously registered by addClientDisconnectListener.
removeOnWatchFaceColorsListener
@WatchFaceClientExperimental
default void removeOnWatchFaceColorsListener(
@NonNull Consumer<WatchFaceColors> listener
)
Stops listening for events registered by addOnWatchFaceColorsListener.
removeOnWatchFaceReadyListener
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 |
@NonNull Instant instant |
The |
UserStyle userStyle |
Optional |
Map<@NonNull Integer, @NonNull ComplicationData> idAndComplicationData |
Map of complication ids to |
sendTouchEvent
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 |
setWatchUiState
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.
| Parameters | |
|---|---|
@NonNull Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData |
The |
updateWatchFaceInstance
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
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.