ComplicationSlot


class ComplicationSlot


Represents the slot an individual complication on the screen may go in. The number of ComplicationSlots is fixed (see ComplicationSlotsManager) but ComplicationSlots can be enabled or disabled via UserStyleSetting.ComplicationSlotsUserStyleSetting.

Taps on the watch are tested first against each ComplicationSlot's ComplicationSlotBounds.perComplicationTypeBounds for the relevant ComplicationType. Its assumed that ComplicationSlotBounds.perComplicationTypeBounds don't overlap. If no intersection was found then taps are checked against ComplicationSlotBounds.perComplicationTypeBounds expanded by ComplicationSlotBounds.perComplicationTypeMargins. Expanded bounds can overlap so the ComplicationSlot with the lowest id that intersects the coordinates, if any, is selected.

Summary

Nested types

Builder for constructing ComplicationSlots.

Public companion functions

ComplicationSlot.Builder
createBackgroundComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy
)

Constructs a Builder for a complication with bound type ComplicationSlotBoundsType.BACKGROUND whose bounds cover the entire screen.

ComplicationSlot.Builder
createEdgeComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy,
    bounds: ComplicationSlotBounds,
    complicationTapFilter: ComplicationTapFilter
)

Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.EDGE.

ComplicationSlot.Builder
@ComplicationExperimental
createEdgeComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy,
    bounds: ComplicationSlotBounds,
    boundingArc: BoundingArc,
    complicationTapFilter: ComplicationTapFilter
)

Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.EDGE, whose contents are contained within boundingArc.

ComplicationSlot.Builder
createRoundRectComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy,
    bounds: ComplicationSlotBounds
)

Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.ROUND_RECT.

Public functions

Rect
computeBounds(screen: Rect, applyMargins: Boolean)

Computes the bounds of the complication by converting the unitSquareBounds of the current complication type to pixels based on the screen's dimensions.

open operator Boolean
equals(other: Any?)
open Int
Boolean
isActiveAt(instant: Instant)

Whether or not the complication should be considered active and should be rendered at the specified time.

Unit
@UiThread
render(
    canvas: Canvas,
    zonedDateTime: ZonedDateTime,
    renderParameters: RenderParameters
)

Watch faces should use this method to render a complication.

Unit
@UiThread
renderHighlightLayer(
    canvas: Canvas,
    zonedDateTime: ZonedDateTime,
    renderParameters: RenderParameters
)

Watch faces should use this method to render non-fixed complicationSlots for any highlight layer pass.

Public properties

Int

This is used to determine the order in which accessibility labels for the watch face are read to the user.

Int

The ComplicationSlotBoundsTypeIntDef of the complication slot.

CanvasComplicationFactory

The CanvasComplicationFactory used to generate a CanvasComplication for rendering the complication.

StateFlow<ComplicationData>

The androidx.wear.watchface.complications.data.ComplicationData associated with the ComplicationSlot.

ComplicationSlotBounds

The complication's ComplicationSlotBounds which are converted to pixels during rendering.

Bundle

Extras to be merged into the Intent sent when invoking the complication data source chooser activity.

DefaultComplicationDataSourcePolicy

The DefaultComplicationDataSourcePolicy which defines the default complicationSlots providers selected when the user hasn't yet made a choice.

ComplicationType

This property is deprecated. Use DefaultComplicationDataSourcePolicy.systemDataSourceFallbackDefaultType instead

Boolean

Whether or not the complication should be drawn and accept taps.

Boolean

Whether or not the complication data source is fixed (i.e. can't be changed by the user).

Int

The Watch Face's ID for the complication slot.

Boolean

At creation a complication slot is either enabled or disabled.

Int?

The optional ID of string resource (or null if absent) to identify the complication slot on screen in an editor.

CanvasComplication

The CanvasComplication used to render the complication.

Int?

The optional ID of a string resource (or null if absent) for use by a watch face editor to identify the complication slot in a screen reader.

List<ComplicationType>
ComplicationTapFilter

The ComplicationTapFilter used to determine whether or not a tap hit the complication slot.

Public companion functions

createBackgroundComplicationSlotBuilder

fun createBackgroundComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy
): ComplicationSlot.Builder

Constructs a Builder for a complication with bound type ComplicationSlotBoundsType.BACKGROUND whose bounds cover the entire screen. A background complication is for watch faces that wish to have a full screen user selectable backdrop. This sort of complication isn't clickable and at most one may be present in the list of complicationSlots.

Parameters
id: Int

The watch face's ID for this complication. Can be any integer but should be unique within the watch face.

canvasComplicationFactory: CanvasComplicationFactory

The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.

supportedTypes: List<ComplicationType>

The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.

defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy

The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.

createEdgeComplicationSlotBuilder

fun createEdgeComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy,
    bounds: ComplicationSlotBounds,
    complicationTapFilter: ComplicationTapFilter
): ComplicationSlot.Builder

Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.EDGE.

An edge complication is drawn around the border of the display and has custom hit test logic (see complicationTapFilter). When tapped the associated intent is dispatched. Edge complicationSlots should have a custom renderer with CanvasComplication.drawHighlight overridden.

Note hit detection in an editor for ComplicationSlots created with this method is not supported.

Parameters
id: Int

The watch face's ID for this complication. Can be any integer but should be unique within the watch face.

canvasComplicationFactory: CanvasComplicationFactory

The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.

supportedTypes: List<ComplicationType>

The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.

defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy

The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.

bounds: ComplicationSlotBounds

The complication's ComplicationSlotBounds. Its likely the bounding rect will be much larger than the complication and shouldn't directly be used for hit testing.

complicationTapFilter: ComplicationTapFilter

The ComplicationTapFilter used to determine whether or not a tap hit the complication.

createEdgeComplicationSlotBuilder

@ComplicationExperimental
fun createEdgeComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy,
    bounds: ComplicationSlotBounds,
    boundingArc: BoundingArc,
    complicationTapFilter: ComplicationTapFilter = object : ComplicationTapFilter { override fun hitTest( complicationSlot: ComplicationSlot, screenBounds: Rect, x: Int, y: Int, @Suppress("UNUSED_PARAMETER") includeMargins: Boolean ) = boundingArc.hitTest( complicationSlot.computeBounds(screenBounds), x.toFloat(), y.toFloat() ) }
): ComplicationSlot.Builder

Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.EDGE, whose contents are contained within boundingArc.

Parameters
id: Int

The watch face's ID for this complication. Can be any integer but should be unique within the watch face.

canvasComplicationFactory: CanvasComplicationFactory

The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.

supportedTypes: List<ComplicationType>

The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.

defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy

The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.

bounds: ComplicationSlotBounds

The complication's ComplicationSlotBounds. Its likely the bounding rect will have a much larger area than boundingArc and shouldn't directly be used for hit testing.

boundingArc: BoundingArc

The BoundingArc defining the geometry of the edge complication.

complicationTapFilter: ComplicationTapFilter = object : ComplicationTapFilter { override fun hitTest( complicationSlot: ComplicationSlot, screenBounds: Rect, x: Int, y: Int, @Suppress("UNUSED_PARAMETER") includeMargins: Boolean ) = boundingArc.hitTest( complicationSlot.computeBounds(screenBounds), x.toFloat(), y.toFloat() ) }

The ComplicationTapFilter used to determine whether or not a tap hit the complication. The default ComplicationTapFilter uses boundingArc to perform hit testing.

createRoundRectComplicationSlotBuilder

fun createRoundRectComplicationSlotBuilder(
    id: Int,
    canvasComplicationFactory: CanvasComplicationFactory,
    supportedTypes: List<ComplicationType>,
    defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy,
    bounds: ComplicationSlotBounds
): ComplicationSlot.Builder

Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.ROUND_RECT. This is the most common type of complication. These can be tapped by the user to trigger the associated intent.

Parameters
id: Int

The watch face's ID for this complication. Can be any integer but should be unique within the watch face.

canvasComplicationFactory: CanvasComplicationFactory

The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.

supportedTypes: List<ComplicationType>

The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.

defaultDataSourcePolicy: DefaultComplicationDataSourcePolicy

The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.

bounds: ComplicationSlotBounds

The complication's ComplicationSlotBounds.

Public functions

computeBounds

Added in 1.2.0
fun computeBounds(screen: Rect, applyMargins: Boolean = false): Rect

Computes the bounds of the complication by converting the unitSquareBounds of the current complication type to pixels based on the screen's dimensions.

Parameters
screen: Rect

A Rect describing the dimensions of the screen.

applyMargins: Boolean = false

Whether or not the margins should be applied to the computed Rect.

equals

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

hashCode

open fun hashCode(): Int

isActiveAt

Added in 1.0.0
fun isActiveAt(instant: Instant): Boolean

Whether or not the complication should be considered active and should be rendered at the specified time.

render

Added in 1.0.0
@UiThread
fun render(
    canvas: Canvas,
    zonedDateTime: ZonedDateTime,
    renderParameters: RenderParameters
): Unit

Watch faces should use this method to render a complication. Note the system may call this.

Parameters
canvas: Canvas

The Canvas to render into

zonedDateTime: ZonedDateTime

The ZonedDateTime to render with

renderParameters: RenderParameters

The current RenderParameters

renderHighlightLayer

Added in 1.0.0
@UiThread
fun renderHighlightLayer(
    canvas: Canvas,
    zonedDateTime: ZonedDateTime,
    renderParameters: RenderParameters
): Unit

Watch faces should use this method to render non-fixed complicationSlots for any highlight layer pass. Note the system may call this.

Parameters
canvas: Canvas

The Canvas to render into

zonedDateTime: ZonedDateTime

The ZonedDateTime to render with

renderParameters: RenderParameters

The current RenderParameters

Public properties

accessibilityTraversalIndex

Added in 1.0.0
val accessibilityTraversalIndexInt

This is used to determine the order in which accessibility labels for the watch face are read to the user. Accessibility labels are automatically generated for the time and complicationSlots. See also Renderer.additionalContentDescriptionLabels.

boundsType

Added in 1.0.0
val boundsTypeInt

The ComplicationSlotBoundsTypeIntDef of the complication slot.

canvasComplicationFactory

Added in 1.0.0
val canvasComplicationFactoryCanvasComplicationFactory

The CanvasComplicationFactory used to generate a CanvasComplication for rendering the complication. The factory allows us to decouple ComplicationSlot from potentially expensive asset loading.

complicationSlotBounds

Added in 1.0.0
val complicationSlotBoundsComplicationSlotBounds

The complication's ComplicationSlotBounds which are converted to pixels during rendering.

Note it's not allowed to change the bounds of a background complication because they are assumed to always cover the entire screen.

configExtras

Added in 1.0.0
var configExtrasBundle

Extras to be merged into the Intent sent when invoking the complication data source chooser activity.

defaultDataSourcePolicy

Added in 1.0.0
val defaultDataSourcePolicyDefaultComplicationDataSourcePolicy

The DefaultComplicationDataSourcePolicy which defines the default complicationSlots providers selected when the user hasn't yet made a choice. See also defaultDataSourceType.

defaultDataSourceType

Added in 1.0.0
Deprecated in 1.1.0
val defaultDataSourceTypeComplicationType

The default ComplicationType to use alongside defaultDataSourcePolicy.

enabled

Added in 1.0.0
val enabledBoolean

Whether or not the complication should be drawn and accept taps.

fixedComplicationDataSource

Added in 1.2.0
val fixedComplicationDataSourceBoolean

Whether or not the complication data source is fixed (i.e. can't be changed by the user). This is useful for watch faces built around specific complications.

id

Added in 1.0.0
val idInt

The Watch Face's ID for the complication slot.

initiallyEnabled

Added in 1.2.0
val initiallyEnabledBoolean

At creation a complication slot is either enabled or disabled. This can be overridden by a ComplicationSlotsUserStyleSetting (see ComplicationSlotOverlay.enabled). Editors need to know the initial state of a complication slot to predict the effects of making a style change.

nameResourceId

Added in 1.1.0
val nameResourceIdInt?

The optional ID of string resource (or null if absent) to identify the complication slot on screen in an editor. These strings should be short (perhaps 10 characters max) E.g. complication slots named 'left' and 'right' might be shown by the editor in a list from which the user selects a complication slot for editing.

renderer

Added in 1.0.0
val rendererCanvasComplication

The CanvasComplication used to render the complication. This can't be used until after WatchFaceService.createWatchFace has completed.

screenReaderNameResourceId

Added in 1.1.0
val screenReaderNameResourceIdInt?

The optional ID of a string resource (or null if absent) for use by a watch face editor to identify the complication slot in a screen reader. While similar to nameResourceId this string can be longer and should be more descriptive. E.g. saying 'left complication' rather than just 'left'.

supportedTypes

Added in 1.0.0
val supportedTypesList<ComplicationType>

tapFilter

Added in 1.0.0
val tapFilterComplicationTapFilter

The ComplicationTapFilter used to determine whether or not a tap hit the complication slot.