Add complications to a watch face

A watch face complication displays data from a data source. With the Complications API, watch faces can choose the data sources they want to use to get the underlying data. This lets watch faces display information beyond the time of day without needing code for getting the data.

Use a ComplicationSlotsManager

To add complications to a watch face, use a ComplicationSlotsManager.

The ComplicationSlotsManager defines how many complications a watch face supports and where they are positioned on the screen. To support changing the location or number of complications, the ComplicationSlotsManager also uses the CurrentUserStyleRepository, as shown in the following example:

 override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager {
        val defaultCanvasComplicationFactory =
            CanvasComplicationFactory { watchState, listener ->
                // ...
            }
    
        val leftComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 100,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()
    
        val rightComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 101,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        return ComplicationSlotsManager(
            listOf(leftComplicationSlot, rightComplicationSlot),
            currentUserStyleRepository
        )
 }

Types and fields

The following table describes the types and fields of the ComplicationData object. If a watch face requests a field that is invalid for a complication type, a default value for the field is returned. For example, if a watch face tries to access a LONG_TEXT field in a SHORT_TEXT type, the default value for the LONG_TEXT field, null, is returned. Note optional fields are not guaranteed to be displayed.





Type Required fields Optional fields Notes
SHORT_TEXT Short text Icon
Burn-in protection icon
Short title
Content description

 Shows only one icon or short title if either or both are provided.
MONOCHROMATIC_IMAGE Monochromatic image
 Burn-in protection icon
Content description

 Used when text is not needed. The icon is expected to be single color and might be tinted by the watch face.
RANGED_VALUE Value
Min value
Max value
 Monochromatic image
Burn-in protection icon
Short text
Short title
Color ramp
Dynamic value
Content description

 If you want to draw your own progress bar, you can use the isRangedValueProgressHidden() method to hide the progress bar provided by the ComplicationDrawable class.
GOAL_PROGRESS Value
Target value
 Monochromatic image
Burn-in protection icon
Short text
Short title
Color ramp
Dynamic value
Content description

 GOAL_PROGRESS is intended for things like step count where the Value starts at zero, and it's allowed to go past the Target value.
LONG_TEXT Long text
 Long title
Monochromatic image
Burn-in protection icon
Small image
Content description
 Shows the long title if it's provided.
SMALL_IMAGE Small image
 Content description
 A small image has one of two styles: photo style or icon style. Photo style means it is expected to fill the space and can be cropped. Icon style means it can't be cropped and can be padded. Image variability can result in an unsuitable image for display in ambient mode on devices with burn-in protection or with low-bit ambient mode. When burn-in protection or low-bit ambient mode is enabled, the watch face might use the burn-in protection small image because it is safe. Otherwise, since it is hard for a watch face to determine suitability, an image isn't displayed.
LARGE_IMAGE Large image
 Content description
 This image is expected to be large enough to fill the watch face. Image variability can result in an unsuitable image for display in ambient mode on devices with burn-in protection or with low-bit ambient mode. Since it is hard for a watch face to determine suitability for display, a watch face doesn't display an image in ambient mode if burn-in protection or low-bit ambient is enabled.
WEIGHTED_ELEMENTS Elements list
 Monochromatic image
Burn-in protection icon
Short text
Short title
Content description
 Each Element consists of a color and a weight (greater than zero). The size of the element when rendered should be proportional to its weight. Weights are not required to sum to any particular value. Note watch faces are allowed to recolor WEIGHTED_ELEMENTS.

The following table describes complication types for empty data that can be sent for any complication slot. These types have no fields and don't need to be included in a list of supported types. These types enable watch faces to differentiate among the following three cases:

  • No source was chosen
  • The user has selected "empty" for a slot
  • A source has no data to send

Sources can't send TYPE_EMPTY in response to update requests. Send TYPE_NO_DATA instead.

Complication type Description
TYPE_NOT_CONFIGURED Sent by the system when a complication activates but the user has not selected a source and no default was set.

Can't be sent by sources.

TYPE_EMPTY Sent by the system when a complication activates and the user chooses "empty" instead of a source, or when the watch face chooses no source and this complication type as the default.

Can't be sent by sources.

TYPE_NO_DATA Sent by the system when a complication that has a source activates to clear the complication before actual data is received from the source.

Can be sent by sources if they have no actual data to send.

For more information, check out the WatchFace sample on GitHub.