# ComplicationData

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

*** ** * ** ***


```
public sealed class ComplicationData
```

<br />

Known direct subclasses [EmptyComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/EmptyComplicationData), [GoalProgressComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/GoalProgressComplicationData), [LongTextComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/LongTextComplicationData), [MonochromaticImageComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/MonochromaticImageComplicationData), [NoDataComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/NoDataComplicationData), [NoPermissionComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/NoPermissionComplicationData), [NotConfiguredComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/NotConfiguredComplicationData), [PhotoImageComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/PhotoImageComplicationData), [RangedValueComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/RangedValueComplicationData), [ShortTextComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/ShortTextComplicationData), [SmallImageComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/SmallImageComplicationData), [WeightedElementsComplicationData](https://developer.android.com/reference/androidx/wear/watchface/complications/data/WeightedElementsComplicationData)

|---|---|
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/EmptyComplicationData` | Type sent when the user has specified that an active complication should have no complication data source, i.e. when the user has chosen "Empty" in the complication data source chooser. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/GoalProgressComplicationData` | Type used for complications which shows the user's progress towards a goal, E.g. you've done 2400 out of your daily target of 10000 steps. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/LongTextComplicationData` | Type used for complications where the primary piece of data is a piece of text. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/MonochromaticImageComplicationData` | Type used for complications which consist only of a `https://developer.android.com/reference/androidx/wear/watchface/complications/data/MonochromaticImage`. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/NoDataComplicationData` | Type that can be sent by any complication data source, regardless of the configured type, when the complication data source has no data to be displayed. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/NoPermissionComplicationData` | Type sent by the system when the watch face does not have permission to receive complication data. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/NotConfiguredComplicationData` | Type sent when a complication does not have a complication data source configured. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/PhotoImageComplicationData` | Type used for complications which consist only of an image that is expected to fill a large part of the watch face, large enough to be shown as either a background or as part of a high resolution complication. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/RangedValueComplicationData` | Type used for complications including a numerical value within a range, such as a percentage. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ShortTextComplicationData` | Type used for complications where the primary piece of data is a short piece of text (expected to be no more than seven characters in length). |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/SmallImageComplicationData` | Type used for complications which consist only of a `https://developer.android.com/reference/androidx/wear/watchface/complications/data/SmallImage`. |
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/WeightedElementsComplicationData` | Type used for complications which want to display the breakdown of something (e.g. nutrition data) perhaps as a pie chart, or as a stacked bar chart etc. |

*** ** * ** ***

Base type for all different types of `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData` types.

Please note to aid unit testing of `https://developer.android.com/reference/androidx/wear/watchface/complications/datasource/ComplicationDataSourceService`, `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#equals(kotlin.Any)`, `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#hashCode()` and `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/to-string.html` have been overridden for all the types of ComplicationData, however due to the embedded `https://developer.android.com/reference/android/graphics/drawable/Icon.html` class we have to fall back to reference equality and hashing below API 28 and also for the `https://developer.android.com/reference/android/graphics/drawable/Icon.html`s that don't use either a resource or a uri (these should be rare but they can exist).

## Evaluation

Some dynamic fields may be evaluated by the platform, and refresh more often than the `https://developer.android.com/reference/androidx/wear/watchface/complications/datasource/ComplicationDataSourceService` provides them. There are interesting use cases that the user of these dynamic fields must consider:

- The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData` can be "invalidated" when the dynamic field cannot be evaluated, e.g. when a data source is not available.

When this happens, the `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#dynamicValueInvalidationFallback()` field is used instead of this `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData`, provided as a `https://developer.android.com/reference/androidx/wear/watchface/complications/data/NoDataComplicationData#placeholder()`.

- If an incompatible platform doesn't recognize the dynamic field, the dynamic field's fallback companion field will be used instead. An example field is `https://developer.android.com/reference/androidx/wear/watchface/complications/data/DynamicComplicationText#fallbackValue()`.

Although the dynamic field APIs are annotated with `https://developer.android.com/reference/androidx/annotation/RequiresApi`, this does not ensure the platform will support the dynamic field at that API level. However, the platform *definitely doesn't* support the dynamic field below that API level.

## Summary

| ### Protected constructors |
|---|
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#ComplicationData(androidx.wear.watchface.complications.data.ComplicationType,android.app.PendingIntent,android.support.wearable.complications.ComplicationData,com.google.wear.services.complications.ComplicationData,androidx.wear.watchface.complications.data.TimeRange,android.content.ComponentName,kotlin.Int,kotlin.Int,androidx.wear.watchface.complications.data.ComplicationData,android.os.PersistableBundle)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationType type, https://developer.android.com/reference/android/app/PendingIntent.html tapAction, https://developer.android.com/reference/android/support/wearable/complications/ComplicationData.html cachedWireComplicationData, https://developer.android.com/reference/com/google/wear/services/complications/ComplicationData.html cachedWearSdkComplicationData, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchface/complications/data/TimeRange validTimeRange, https://developer.android.com/reference/android/content/ComponentName.html dataSource, int persistencePolicy, int displayPolicy, https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData dynamicValueInvalidationFallback, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/os/PersistableBundle.html extras )` |

| ### Public methods |
|---|---|
| `boolean` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#equals(kotlin.Any)(https://developer.android.com/reference/java/lang/Object.html other)` |
| `final https://developer.android.com/reference/android/content/ComponentName.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getDataSource()()` The `https://developer.android.com/reference/android/content/ComponentName.html` of the `https://developer.android.com/reference/androidx/wear/watchface/complications/datasource/ComplicationDataSourceService` that provided the ComplicationData. |
| `final int` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getDisplayPolicy()()` The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationDisplayPolicies` for this complication. |
| `final https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getDynamicValueInvalidationFallback()()` Used in case any dynamic value has been invalidated. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/os/PersistableBundle.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getExtras()()` A copy of any extras set by a complication provider with the privileged permission `com.google.wear.permission.SET_COMPLICATION_EXTRAS` or `https://developer.android.com/reference/android/os/PersistableBundle.html#EMPTY`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/time/Instant.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getNextChangeInstant(java.time.Instant)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/time/Instant.html afterInstant)` Returns the next `https://developer.android.com/reference/java/time/Instant.html` after `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getNextChangeInstant(java.time.Instant)` at which any field of the complication may change. |
| `final int` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getPersistencePolicy()()` The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationPersistencePolicies` for this complication. |
| `final https://developer.android.com/reference/android/app/PendingIntent.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getTapAction()()` The `https://developer.android.com/reference/android/app/PendingIntent.html` to send when the complication is tapped on. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationType` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getType()()` The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationType` of this complication data. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/watchface/complications/data/TimeRange` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getValidTimeRange()()` The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/TimeRange` within which the complication should be displayed. |
| `boolean` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#hasPlaceholderFields()()` Returns `true` if any of the fields of this ComplicationData are placeholders. |
| `int` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#hashCode()()` |
| `final boolean` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#isTapActionLostDueToSerialization()()` `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#tapAction()` which is a `https://developer.android.com/reference/android/app/PendingIntent.html` unfortunately can't be serialized. |
| `final void` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#setTapActionLostDueToSerialization(kotlin.Boolean)(boolean value)` `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#tapAction()` which is a `https://developer.android.com/reference/android/app/PendingIntent.html` unfortunately can't be serialized. |

## Protected constructors

### ComplicationData

```
protected ComplicationData(
    @NonNull ComplicationType type,
    PendingIntent tapAction,
    ComplicationData cachedWireComplicationData,
    ComplicationData cachedWearSdkComplicationData,
    @NonNull TimeRange validTimeRange,
    ComponentName dataSource,
    int persistencePolicy,
    int displayPolicy,
    ComplicationData dynamicValueInvalidationFallback,
    @NonNull PersistableBundle extras
)
```

## Public methods

### equals

```
public boolean equals(Object other)
```

### getDataSource

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

```
public final ComponentName getDataSource()
```

The `https://developer.android.com/reference/android/content/ComponentName.html` of the `https://developer.android.com/reference/androidx/wear/watchface/complications/datasource/ComplicationDataSourceService` that provided the ComplicationData. This may be `null` when run on old systems.

### getDisplayPolicy

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

```
public final int getDisplayPolicy()
```

The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationDisplayPolicies` for this complication. This requires the watchface to be built with a compatible library to work.

### getDynamicValueInvalidationFallback

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

```
public final ComplicationData getDynamicValueInvalidationFallback()
```

Used in case any dynamic value has been invalidated.

IMPORTANT: This is only used when the system supports dynamic values. See each dynamic field's fallback companion field for the situation where the system does not support dynamic values at all.

### getExtras

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

```
public final @NonNull PersistableBundle getExtras()
```

A copy of any extras set by a complication provider with the privileged permission `com.google.wear.permission.SET_COMPLICATION_EXTRAS` or `https://developer.android.com/reference/android/os/PersistableBundle.html#EMPTY`. Extras set by a provider without permission will be stripped. It is assumed that an OEM wrote both the complication provider and the watch face, using fields they defined.

### getNextChangeInstant

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

```
public @NonNull Instant getNextChangeInstant(@NonNull Instant afterInstant)
```

Returns the next `https://developer.android.com/reference/java/time/Instant.html` after `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#getNextChangeInstant(java.time.Instant)` at which any field of the complication may change. If there's no scheduled changes then `https://developer.android.com/reference/java/time/Instant.html#MAX` will be returned.

See `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationText#getNextChangeTime(java.time.Instant)`

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/time/Instant.html afterInstant` | The reference `https://developer.android.com/reference/java/time/Instant.html`, after which changes will be reported. |

### getPersistencePolicy

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

```
public final int getPersistencePolicy()
```

The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationPersistencePolicies` for this complication. This requires the watchface to be built with a compatible library to work.

### getTapAction

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

```
public final PendingIntent getTapAction()
```

The `https://developer.android.com/reference/android/app/PendingIntent.html` to send when the complication is tapped on.

### getType

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

```
public final @NonNull ComplicationType getType()
```

The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationType` of this complication data.

### getValidTimeRange

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

```
public final @NonNull TimeRange getValidTimeRange()
```

The `https://developer.android.com/reference/androidx/wear/watchface/complications/data/TimeRange` within which the complication should be displayed. Whether the complication is active and should be displayed at the given time should be checked with `https://developer.android.com/reference/androidx/wear/watchface/complications/data/TimeRange#contains(java.time.Instant)`.

### hasPlaceholderFields

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

```
public boolean hasPlaceholderFields()
```

Returns `true` if any of the fields of this ComplicationData are placeholders. I.e. if any fields are equal to: `https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationText#PLACEHOLDER()`, `https://developer.android.com/reference/androidx/wear/watchface/complications/data/SmallImage#PLACEHOLDER()`, `https://developer.android.com/reference/androidx/wear/watchface/complications/data/MonochromaticImage#PLACEHOLDER()`, `https://developer.android.com/reference/androidx/wear/watchface/complications/data/PhotoImageComplicationData#PLACEHOLDER()`, or `https://developer.android.com/reference/androidx/wear/watchface/complications/data/RangedValueComplicationData#PLACEHOLDER()`.

### hashCode

```
public int hashCode()
```

### isTapActionLostDueToSerialization

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

```
public final boolean isTapActionLostDueToSerialization()
```

`https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#tapAction()` which is a `https://developer.android.com/reference/android/app/PendingIntent.html` unfortunately can't be serialized. This property is 'true' if tapAction has been lost due to serialization (typically because it has been cached locally). When 'true' the watch face should render the complication differently (e.g. as semi-transparent or grayed out) to signal to the user it can't be tapped. The system will subsequently deliver an updated complication, with a tapAction where applicable.

### setTapActionLostDueToSerialization

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

```
public final void setTapActionLostDueToSerialization(boolean value)
```

`https://developer.android.com/reference/androidx/wear/watchface/complications/data/ComplicationData#tapAction()` which is a `https://developer.android.com/reference/android/app/PendingIntent.html` unfortunately can't be serialized. This property is 'true' if tapAction has been lost due to serialization (typically because it has been cached locally). When 'true' the watch face should render the complication differently (e.g. as semi-transparent or grayed out) to signal to the user it can't be tapped. The system will subsequently deliver an updated complication, with a tapAction where applicable.