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 enables watch faces to 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.
Type | Required fields | Optional fields | Notes |
---|---|---|---|
SHORT_TEXT | Short text |
Icon Burn-in protection icon Short title |
Show only one icon or short title if either or both are provided. |
ICON | Icon | Burn-in protection icon | Used when text is not needed. The icon is expected to be single-color, and may be tinted by the watch face. |
RANGED_VALUE |
Value Min value Max value |
Icon Burn-in protection icon Short text Short title |
Optional fields are not guaranteed to be displayed.
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.
|
LONG_TEXT | Long text |
Long title Icon Burn-in protection icon Small image |
Show the long title if it's provided. |
SMALL_IMAGE | Small image |
A small image has one of two styles: photo style or icon
style. Photo style means it should fill the space and can be
cropped; icon style means it should not be cropped and may 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 may 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 should not be displayed.
|
|
LARGE_IMAGE | Large image | 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 should not display an image in ambient mode if burn-in protection or low-bit ambient is enabled. |
The types in the table below are for empty data and may be sent for any complication slot. These types have no fields and do not 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 should not send TYPE_EMPTY
in response to
update requests. Sources should send TYPE_NO_DATA
instead.
Details on the complication types for "empty" data are in the following table:
Complication type | Description |
---|---|
TYPE_NOT_CONFIGURED
|
Sent by the system when a complication is activated but the user has
not selected a source, and no default was set.
Cannot be sent by sources. |
TYPE_EMPTY
|
Sent by the system when a complication is activated and the user has
chosen "empty" instead of a source, or when the watch face has
chosen no source and this complication type as the default.
Cannot be sent by sources. |
TYPE_NO_DATA
|
Sent by the system when a complication (that has a source) is
activated to clear the complication before actual data is received
from the source.
Should be sent by sources if they have no actual data to send. |
For more information, check out the WatchFace sample on GitHub.