# WatchFace

Artifact: [androidx.wear.watchface:watchface](https://developer.android.com/jetpack/androidx/releases/wear-watchface) [View Source](https://cs.android.com/search?q=file:androidx/wear/watchface/WatchFace.kt+class:androidx.wear.watchface.WatchFace) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

*** ** * ** ***


```
class WatchFace
```

<br />

*** ** * ** ***

> [!CAUTION]
> **This class is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

The return value of `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFaceService#createWatchFace(android.view.SurfaceHolder,androidx.wear.watchface.WatchState,androidx.wear.watchface.ComplicationSlotsManager,androidx.wear.watchface.style.CurrentUserStyleRepository)` which brings together rendering, styling, complicationSlots and state observers.

use Watch Face Format instead

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.LegacyWatchFaceOverlayStyle` **This class is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `class https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.OverlayStyle` **This class is deprecated.** OverlayStyle will be removed in a future release. |
| `interface https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.TapListener` **This interface is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |

| ### Public companion functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `[isLegacyWatchFaceOverlayStyleSupported](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#isLegacyWatchFaceOverlayStyleSupported())()` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |

| ### Public constructors |
|---|
| `[WatchFace](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#WatchFace(kotlin.Int,androidx.wear.watchface.Renderer))(watchFaceType: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, renderer: https://developer.android.com/reference/kotlin/androidx/wear/watchface/Renderer)` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace` | `[setComplicationDeniedDialogIntent](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setComplicationDeniedDialogIntent(android.content.Intent))( complicationDeniedDialogIntent: https://developer.android.com/reference/android/content/Intent.html? )` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace` | `[setComplicationRationaleDialogIntent](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setComplicationRationaleDialogIntent(android.content.Intent))( complicationRationaleDialogIntent: https://developer.android.com/reference/android/content/Intent.html? )` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace` | `[setLegacyWatchFaceStyle](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setLegacyWatchFaceStyle(androidx.wear.watchface.WatchFace.LegacyWatchFaceOverlayStyle))( legacyWatchFaceStyle: https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.LegacyWatchFaceOverlayStyle )` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace` | `[setOverlayStyle](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setOverlayStyle(androidx.wear.watchface.WatchFace.OverlayStyle))(watchFaceOverlayStyle: https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.OverlayStyle)` **This function is deprecated.** OverlayStyle will be removed in a future release. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace` | `[setOverridePreviewReferenceInstant](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setOverridePreviewReferenceInstant(java.time.Instant))(previewReferenceTimeMillis: https://developer.android.com/reference/java/time/Instant.html)` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace` | `[setTapListener](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setTapListener(androidx.wear.watchface.WatchFace.TapListener))(tapListener: https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.TapListener?)` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace` | `[setUpdateScreenshotOnConfigurationChange](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setUpdateScreenshotOnConfigurationChange(kotlin.Boolean))( updateScreenshotOnConfigurationChange: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` **This function is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.LegacyWatchFaceOverlayStyle` | `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#legacyWatchFaceStyle()` **This property is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.OverlayStyle` | `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#overlayStyle()` **This property is deprecated.** OverlayStyle will be removed in a future release. |
| `https://developer.android.com/reference/java/time/Instant.html?` | `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#overridePreviewReferenceInstant()` **This property is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://developer.android.com/reference/kotlin/androidx/wear/watchface/Renderer` | `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#renderer()` **This property is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#watchFaceType()` **This property is deprecated.** AndroidX watchface libraries are deprecated, use Watch Face Format instead. |

## Public companion functions

### isLegacyWatchFaceOverlayStyleSupported

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
fun [isLegacyWatchFaceOverlayStyleSupported](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#isLegacyWatchFaceOverlayStyleSupported())(): Boolean
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Returns whether `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.LegacyWatchFaceOverlayStyle` is supported on this device.

## Public constructors

### WatchFace

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
[WatchFace](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#WatchFace(kotlin.Int,androidx.wear.watchface.Renderer))(watchFaceType: Int, renderer: Renderer)
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

| Parameters |
|---|---|
| `watchFaceType: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The type of watch face, whether it's digital or analog. Used to determine the default time for editor preview screenshots. Value is one of the following: - `1` - `0` <br /> |
| `renderer: https://developer.android.com/reference/kotlin/androidx/wear/watchface/Renderer` | The `https://developer.android.com/reference/kotlin/androidx/wear/watchface/Renderer` for this WatchFace. |

## Public functions

### setComplicationDeniedDialogIntent

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.1.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
fun [setComplicationDeniedDialogIntent](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setComplicationDeniedDialogIntent(android.content.Intent))(
    complicationDeniedDialogIntent: Intent?
): WatchFace
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Sets the `https://developer.android.com/reference/android/content/Intent.html` 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 `https://developer.android.com/reference/android/provider/Settings.html#ACTION_APPLICATION_DETAILS_SETTINGS` to allow the user to grant permissions if they wish.

This `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setComplicationDeniedDialogIntent(android.content.Intent)` 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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.1.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
fun [setComplicationRationaleDialogIntent](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setComplicationRationaleDialogIntent(android.content.Intent))(
    complicationRationaleDialogIntent: Intent?
): WatchFace
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Sets the `https://developer.android.com/reference/android/content/Intent.html` to launch an activity that explains the rational for the requesting the com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA`permission 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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
fun [setLegacyWatchFaceStyle](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setLegacyWatchFaceStyle(androidx.wear.watchface.WatchFace.LegacyWatchFaceOverlayStyle))(
    legacyWatchFaceStyle: WatchFace.LegacyWatchFaceOverlayStyle
): WatchFace
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Sets the legacy `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.LegacyWatchFaceOverlayStyle` which only affects Wear 2.0 devices.

### setOverlayStyle

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.1.0) Deprecated in [1.2.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.2.0)

```
fun [setOverlayStyle](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setOverlayStyle(androidx.wear.watchface.WatchFace.OverlayStyle))(watchFaceOverlayStyle: WatchFace.OverlayStyle): WatchFace
```

> [!CAUTION]
> **This function is deprecated.**   
> OverlayStyle will be removed in a future release.

Sets the `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.OverlayStyle` which is ignored because this feature is unimplemented on any platform, and will be removed.

### setOverridePreviewReferenceInstant

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
fun [setOverridePreviewReferenceInstant](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setOverridePreviewReferenceInstant(java.time.Instant))(previewReferenceTimeMillis: Instant): WatchFace
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Overrides the reference time for editor preview images.

| Parameters |
|---|---|
| `previewReferenceTimeMillis: https://developer.android.com/reference/java/time/Instant.html` | The UTC preview time in milliseconds since the epoch |

### setTapListener

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
fun [setTapListener](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setTapListener(androidx.wear.watchface.WatchFace.TapListener))(tapListener: WatchFace.TapListener?): WatchFace
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

Sets an optional `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.TapListener` which if not `null` gets called on the ui thread whenever the user taps on the watchface.

### setUpdateScreenshotOnConfigurationChange

Added in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
fun [setUpdateScreenshotOnConfigurationChange](https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setUpdateScreenshotOnConfigurationChange(kotlin.Boolean))(
    updateScreenshotOnConfigurationChange: Boolean
): WatchFace
```

> [!CAUTION]
> **This function is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

If `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace#setUpdateScreenshotOnConfigurationChange(kotlin.Boolean)` is true then whenever `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFaceService#onConfigurationChanged(android.content.res.Configuration)` 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 `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFaceService#onConfigurationChanged(android.content.res.Configuration)` or `https://developer.android.com/reference/kotlin/androidx/wear/watchface/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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
val legacyWatchFaceStyle: WatchFace.LegacyWatchFaceOverlayStyle
```

> [!CAUTION]
> **This property is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

The legacy `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.LegacyWatchFaceOverlayStyle` which only affects Wear 2.0 devices.

### overlayStyle

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.1.0) Deprecated in [1.2.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.2.0)

```
val overlayStyle: WatchFace.OverlayStyle
```

> [!CAUTION]
> **This property is deprecated.**   
> OverlayStyle will be removed in a future release.

The `https://developer.android.com/reference/kotlin/androidx/wear/watchface/WatchFace.OverlayStyle`. This feature is unimplemented on any platform, and will be removed.

### overridePreviewReferenceInstant

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
val overridePreviewReferenceInstant: Instant?
```

> [!CAUTION]
> **This property is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

The `https://developer.android.com/reference/java/time/Instant.html` 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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
val renderer: Renderer
```

> [!CAUTION]
> **This property is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

The `https://developer.android.com/reference/kotlin/androidx/wear/watchface/Renderer` for this WatchFace.

### watchFaceType

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.0.0) Deprecated in [1.3.0-alpha07](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0-alpha07)

```
var watchFaceType: Int
```

> [!CAUTION]
> **This property is deprecated.**   
> AndroidX watchface libraries are deprecated, use Watch Face Format instead. For more info see: https://developer.android.com/training/wearables/wff

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

Value is one of the following:

- `1`
- `0`

<br />