sealed class ComplicationData

Known direct subclasses
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.
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.
LongTextComplicationData

Type used for complications where the primary piece of data is a piece of text.
MonochromaticImageComplicationData

Type used for complications which consist only of a MonochromaticImage.
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.
NoPermissionComplicationData

Type sent by the system when the watch face does not have permission to receive complication data.
NotConfiguredComplicationData

Type sent when a complication does not have a complication data source configured.
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.
RangedValueComplicationData

Type used for complications including a numerical value within a range, such as a percentage.
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).
SmallImageComplicationData

Type used for complications which consist only of a SmallImage.
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 ComplicationData types.

Please note to aid unit testing of androidx.wear.watchface.complications.datasource.ComplicationDataSourceService, equals, hashCode and toString have been overridden for all the types of ComplicationData, however due to the embedded Icon class we have to fall back to reference equality and hashing below API 28 and also for the Icons 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 androidx.wear.watchface.complications.datasource.ComplicationDataSourceService provides them. There are interesting use cases that the user of these dynamic fields must consider:

  • The ComplicationData can be "invalidated" when the dynamic field cannot be evaluated, e.g. when a data source is not available.

When this happens, the dynamicValueInvalidationFallback field is used instead of this ComplicationData, provided as a 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 DynamicComplicationText.fallbackValue.

Although the dynamic field APIs are annotated with 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
ComplicationData(
    type: ComplicationType,
    tapAction: PendingIntent?,
    cachedWireComplicationData: ComplicationData?,
    validTimeRange: TimeRange,
    dataSource: ComponentName?,
    persistencePolicy: Int,
    displayPolicy: Int,
    dynamicValueInvalidationFallback: ComplicationData?
)

Public functions
open operator Boolean
equals(other: Any?)
open Instant

Returns the next Instant after afterInstant at which any field of the complication may change.
open Boolean

Returns true if any of the fields of this ComplicationData are placeholders.
open Int

Public properties
ComponentName?

The ComponentName of the androidx.wear.watchface.complications.datasource.ComplicationDataSourceService that provided the ComplicationData.
Int

The display policy for this complication.
ComplicationData?

Used in case any dynamic value has been invalidated.
Int

The persistence policy for this complication.
PendingIntent?

The PendingIntent to send when the complication is tapped on.
Boolean

tapAction which is a PendingIntent unfortunately can't be serialized.
ComplicationType

The ComplicationType of this complication data.
TimeRange

The TimeRange within which the complication should be displayed.

Protected constructors

ComplicationData

protected ComplicationData(
    type: ComplicationType,
    tapAction: PendingIntent?,
    cachedWireComplicationData: ComplicationData?,
    validTimeRange: TimeRange = TimeRange.ALWAYS,
    dataSource: ComponentName?,
    persistencePolicy: Int,
    displayPolicy: Int,
    dynamicValueInvalidationFallback: ComplicationData?
)

Public functions

equals

open operator fun equals(other: Any?): Boolean

getNextChangeInstant

Added in 1.1.0
open fun getNextChangeInstant(afterInstant: Instant): Instant

Returns the next Instant after afterInstant at which any field of the complication may change. If there's no scheduled changes then Instant.MAX will be returned.

See ComplicationText.getNextChangeTime

Parameters
afterInstant: Instant

The reference Instant, after which changes will be reported.

hasPlaceholderFields

Added in 1.1.0
open fun hasPlaceholderFields(): Boolean

Returns true if any of the fields of this ComplicationData are placeholders. I.e. if any fields are equal to: ComplicationText.PLACEHOLDER, SmallImage.PLACEHOLDER, MonochromaticImage.PLACEHOLDER, PhotoImageComplicationData.PLACEHOLDER, or RangedValueComplicationData.PLACEHOLDER.

hashCode

open fun hashCode(): Int

Public properties

dataSource

Added in 1.1.0
val dataSource: ComponentName?

The ComponentName of the androidx.wear.watchface.complications.datasource.ComplicationDataSourceService that provided the ComplicationData. This may be null when run on old systems.

displayPolicy

Added in 1.2.0
val displayPolicy: Int

The display policy for this complication. This requires the watchface to be built with a compatible library to work.

dynamicValueInvalidationFallback

Added in 1.2.0
val dynamicValueInvalidationFallback: ComplicationData?

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.

persistencePolicy

Added in 1.2.0
val persistencePolicy: Int

The persistence policy for this complication. This requires the watchface to be built with a compatible library to work.

tapAction

Added in 1.0.0
val tapAction: PendingIntent?

The PendingIntent to send when the complication is tapped on.

tapActionLostDueToSerialization

Added in 1.1.0
var tapActionLostDueToSerialization: Boolean

tapAction which is a PendingIntent 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.

type

Added in 1.0.0
val type: ComplicationType

The ComplicationType of this complication data.

validTimeRange

Added in 1.0.0
val validTimeRange: TimeRange

The 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 TimeRange.contains.