WatchFace


class WatchFace


The return value of WatchFaceService.createWatchFace which brings together rendering, styling, complicationSlots and state observers.

Summary

Nested types

Legacy Wear 2.0 watch face styling.

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

Listens for taps on the watchface.

Public companion functions

Boolean

Returns whether LegacyWatchFaceOverlayStyle is supported on this device.

Public constructors

WatchFace(watchFaceType: Int, renderer: Renderer)

Public functions

WatchFace
setComplicationDeniedDialogIntent(
    complicationDeniedDialogIntent: Intent?
)

Sets the Intent to launch an activity which explains the watch face needs permission to display complications.

WatchFace
setComplicationRationaleDialogIntent(
    complicationRationaleDialogIntent: Intent?
)

Sets the Intent to launch an activity that explains the rational for the requesting the com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATApermission prior to requesting it, if [Activity.shouldShowRequestPermissionRationale] returns true`.

WatchFace

Sets the legacy LegacyWatchFaceOverlayStyle which only affects Wear 2.0 devices.

WatchFace
setOverlayStyle(watchFaceOverlayStyle: WatchFace.OverlayStyle)

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

WatchFace
setOverridePreviewReferenceInstant(previewReferenceTimeMillis: Instant)

Overrides the reference time for editor preview images.

WatchFace

Sets an optional TapListener which if not null gets called on the ui thread whenever the user taps on the watchface.

WatchFace
setUpdateScreenshotOnConfigurationChange(
    updateScreenshotOnConfigurationChange: Boolean
)

If updateScreenshotOnConfigurationChange is true then whenever WatchFaceService.onConfigurationChanged gets called while this watch face is active then a request will be made for the system to update the watch's screenshot displayed in the picker.

Public properties

WatchFace.LegacyWatchFaceOverlayStyle

The legacy LegacyWatchFaceOverlayStyle which only affects Wear 2.0 devices.

WatchFace.OverlayStyle

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

Instant?

The Instant to use for preview rendering, or null if not set in which case the system chooses the Instant to use.

Renderer

The Renderer for this WatchFace.

Int

The type of watch face, whether it's digital or analog.

Public companion functions

isLegacyWatchFaceOverlayStyleSupported

Added in 1.0.0
fun isLegacyWatchFaceOverlayStyleSupported(): Boolean

Returns whether LegacyWatchFaceOverlayStyle is supported on this device.

Public constructors

WatchFace

Added in 1.0.0
WatchFace(watchFaceType: Int, renderer: Renderer)
Parameters
watchFaceType: Int

The type of watch face, whether it's digital or analog. Used to determine the default time for editor preview screenshots.

renderer: Renderer

The Renderer for this WatchFace.

Public functions

setComplicationDeniedDialogIntent

Added in 1.1.0
fun setComplicationDeniedDialogIntent(
    complicationDeniedDialogIntent: Intent?
): WatchFace

Sets the Intent to launch an activity which explains the watch face needs permission to display complications. It is recommended the activity have a button which launches an intent with Settings.ACTION_APPLICATION_DETAILS_SETTINGS to allow the user to grant permissions if they wish.

This complicationDeniedDialogIntent is launched when the user tries to configure a complication slot when the com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA permission has been denied. If the intent is not set or is null then no dialog will be displayed.

setComplicationRationaleDialogIntent

Added in 1.1.0
fun setComplicationRationaleDialogIntent(
    complicationRationaleDialogIntent: Intent?
): WatchFace

Sets the Intent to launch an activity that explains the rational for the requesting the com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATApermission prior to requesting it, if [Activity.shouldShowRequestPermissionRationale] returns true`.

If the intent is not set or is null then no dialog will be displayed.

setLegacyWatchFaceStyle

Added in 1.0.0
fun setLegacyWatchFaceStyle(
    legacyWatchFaceStyle: WatchFace.LegacyWatchFaceOverlayStyle
): WatchFace

Sets the legacy LegacyWatchFaceOverlayStyle which only affects Wear 2.0 devices.

setOverlayStyle

Added in 1.1.0
Deprecated in 1.2.0
fun setOverlayStyle(watchFaceOverlayStyle: WatchFace.OverlayStyle): WatchFace

Sets the OverlayStyle which is ignored because this feature is unimplemented on any platform, and will be removed.

setOverridePreviewReferenceInstant

Added in 1.0.0
fun setOverridePreviewReferenceInstant(previewReferenceTimeMillis: Instant): WatchFace

Overrides the reference time for editor preview images.

Parameters
previewReferenceTimeMillis: Instant

The UTC preview time in milliseconds since the epoch

setTapListener

Added in 1.0.0
fun setTapListener(tapListener: WatchFace.TapListener?): WatchFace

Sets an optional TapListener which if not null gets called on the ui thread whenever the user taps on the watchface.

setUpdateScreenshotOnConfigurationChange

Added in 1.3.0-alpha04
fun setUpdateScreenshotOnConfigurationChange(
    updateScreenshotOnConfigurationChange: Boolean
): WatchFace

If updateScreenshotOnConfigurationChange is true then whenever WatchFaceService.onConfigurationChanged gets called while this watch face is active then a request will be made for the system to update the watch's screenshot displayed in the picker.

By default this is off.

Note if WatchFaceService.onConfigurationChanged or Renderer.sendPreviewImageNeedsUpdateRequest get called very frequently then the system may throttle the rate at which screenshots are taken.

Public properties

legacyWatchFaceStyle

Added in 1.0.0
val legacyWatchFaceStyleWatchFace.LegacyWatchFaceOverlayStyle

The legacy LegacyWatchFaceOverlayStyle which only affects Wear 2.0 devices.

overlayStyle

Added in 1.1.0
Deprecated in 1.2.0
val overlayStyleWatchFace.OverlayStyle

The OverlayStyle. This feature is unimplemented on any platform, and will be removed.

overridePreviewReferenceInstant

Added in 1.0.0
val overridePreviewReferenceInstantInstant?

The Instant to use for preview rendering, or null if not set in which case the system chooses the Instant to use.

renderer

Added in 1.0.0
val rendererRenderer

The Renderer for this WatchFace.

watchFaceType

Added in 1.0.0
var watchFaceTypeInt

The type of watch face, whether it's digital or analog. Used to determine the default time for editor preview screenshots.