ComplicationSlot

Artifact: androidx.wear.watchface:watchface

View Source

Added in 1.0.0

---

Kotlin |Java

public final 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
public final class ComplicationSlot.Builder Builder for constructing ComplicationSlots.

Public methods
final @NonNull Rect	computeBounds(@NonNull Rect screen, boolean applyMargins) Computes the bounds of the complication by converting the unitSquareBounds of the current complication type to pixels based on the screen's dimensions.
static final @NonNull ComplicationSlot.Builder	createBackgroundComplicationSlotBuilder(     int id,     @NonNull CanvasComplicationFactory canvasComplicationFactory,     @NonNull List<@NonNull ComplicationType> supportedTypes,     @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy ) Constructs a Builder for a complication with bound type ComplicationSlotBoundsType.BACKGROUND whose bounds cover the entire screen.
static final @NonNull ComplicationSlot.Builder	createEdgeComplicationSlotBuilder(     int id,     @NonNull CanvasComplicationFactory canvasComplicationFactory,     @NonNull List<@NonNull ComplicationType> supportedTypes,     @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy,     @NonNull ComplicationSlotBounds bounds,     @NonNull ComplicationTapFilter complicationTapFilter ) Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.EDGE.
static final @NonNull ComplicationSlot.Builder	@ComplicationExperimental createEdgeComplicationSlotBuilder(     int id,     @NonNull CanvasComplicationFactory canvasComplicationFactory,     @NonNull List<@NonNull ComplicationType> supportedTypes,     @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy,     @NonNull ComplicationSlotBounds bounds,     @NonNull BoundingArc boundingArc,     @NonNull ComplicationTapFilter complicationTapFilter ) Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.EDGE, whose contents are contained within boundingArc.
static final @NonNull ComplicationSlot.Builder	createRoundRectComplicationSlotBuilder(     int id,     @NonNull CanvasComplicationFactory canvasComplicationFactory,     @NonNull List<@NonNull ComplicationType> supportedTypes,     @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy,     @NonNull ComplicationSlotBounds bounds ) Constructs a Builder for a complication with bounds type ComplicationSlotBoundsType.ROUND_RECT.
boolean	equals(Object other)
final int	@UiThread getAccessibilityTraversalIndex() This is used to determine the order in which accessibility labels for the watch face are read to the user.
final int	getBoundsType() The ComplicationSlotBoundsTypeIntDef of the complication slot.
final @NonNull CanvasComplicationFactory	getCanvasComplicationFactory() The CanvasComplicationFactory used to generate a CanvasComplication for rendering the complication.
final @NonNull StateFlow<@NonNull ComplicationData>	getComplicationData() The androidx.wear.watchface.complications.data.ComplicationData associated with the ComplicationSlot.
final @NonNull ComplicationSlotBounds	@UiThread getComplicationSlotBounds() The complication's ComplicationSlotBounds which are converted to pixels during rendering.
final @NonNull Bundle	getConfigExtras() Extras to be merged into the Intent sent when invoking the complication data source chooser activity.
final @NonNull DefaultComplicationDataSourcePolicy	@UiThread getDefaultDataSourcePolicy() The DefaultComplicationDataSourcePolicy which defines the default complicationSlots providers selected when the user hasn't yet made a choice.
final @NonNull ComplicationType	@UiThread getDefaultDataSourceType() The default ComplicationType to use alongside defaultDataSourcePolicy.
final int	getId() The Watch Face's ID for the complication slot.
final Integer	@UiThread getNameResourceId() The optional ID of string resource (or null if absent) to identify the complication slot on screen in an editor.
final @NonNull CanvasComplication	getRenderer() The CanvasComplication used to render the complication.
final Integer	@UiThread getScreenReaderNameResourceId() 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.
final @NonNull List<@NonNull ComplicationType>	getSupportedTypes()
final @NonNull ComplicationTapFilter	getTapFilter() The ComplicationTapFilter used to determine whether or not a tap hit the complication slot.
int	hashCode()
final boolean	isActiveAt(@NonNull Instant instant) Whether or not the complication should be considered active and should be rendered at the specified time.
final boolean	@UiThread isEnabled() Whether or not the complication should be drawn and accept taps.
final boolean	isFixedComplicationDataSource() Whether or not the complication data source is fixed (i.e. can't be changed by the user).
final boolean	isInitiallyEnabled() At creation a complication slot is either enabled or disabled.
final void	@UiThread render(     @NonNull Canvas canvas,     @NonNull ZonedDateTime zonedDateTime,     @NonNull RenderParameters renderParameters ) Watch faces should use this method to render a complication.
final void	@UiThread renderHighlightLayer(     @NonNull Canvas canvas,     @NonNull ZonedDateTime zonedDateTime,     @NonNull RenderParameters renderParameters ) Watch faces should use this method to render non-fixed complicationSlots for any highlight layer pass.
final void	setConfigExtras(@NonNull Bundle configExtras) Extras to be merged into the Intent sent when invoking the complication data source chooser activity.

Public methods

computeBounds

Added in 1.2.0

public final @NonNull Rect computeBounds(@NonNull Rect screen, boolean applyMargins)

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

Parameters
@NonNull Rect screen	A Rect describing the dimensions of the screen.
boolean applyMargins	Whether or not the margins should be applied to the computed Rect.

createBackgroundComplicationSlotBuilder

public static final @NonNull ComplicationSlot.Builder createBackgroundComplicationSlotBuilder(
    int id,
    @NonNull CanvasComplicationFactory canvasComplicationFactory,
    @NonNull List<@NonNull ComplicationType> supportedTypes,
    @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy
)

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
int id	The watch face's ID for this complication. Can be any integer but should be unique within the watch face.
@NonNull CanvasComplicationFactory canvasComplicationFactory	The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.
@NonNull List<@NonNull ComplicationType> supportedTypes	The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.
@NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy	The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.

createEdgeComplicationSlotBuilder

public static final @NonNull ComplicationSlot.Builder createEdgeComplicationSlotBuilder(
    int id,
    @NonNull CanvasComplicationFactory canvasComplicationFactory,
    @NonNull List<@NonNull ComplicationType> supportedTypes,
    @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy,
    @NonNull ComplicationSlotBounds bounds,
    @NonNull ComplicationTapFilter complicationTapFilter
)

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
int id	The watch face's ID for this complication. Can be any integer but should be unique within the watch face.
@NonNull CanvasComplicationFactory canvasComplicationFactory	The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.
@NonNull List<@NonNull ComplicationType> supportedTypes	The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.
@NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy	The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.
@NonNull ComplicationSlotBounds bounds	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.
@NonNull ComplicationTapFilter complicationTapFilter	The ComplicationTapFilter used to determine whether or not a tap hit the complication.

createEdgeComplicationSlotBuilder

@ComplicationExperimental
public static final @NonNull ComplicationSlot.Builder createEdgeComplicationSlotBuilder(
    int id,
    @NonNull CanvasComplicationFactory canvasComplicationFactory,
    @NonNull List<@NonNull ComplicationType> supportedTypes,
    @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy,
    @NonNull ComplicationSlotBounds bounds,
    @NonNull BoundingArc boundingArc,
    @NonNull ComplicationTapFilter complicationTapFilter
)

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

Parameters
int id	The watch face's ID for this complication. Can be any integer but should be unique within the watch face.
@NonNull CanvasComplicationFactory canvasComplicationFactory	The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.
@NonNull List<@NonNull ComplicationType> supportedTypes	The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.
@NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy	The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.
@NonNull ComplicationSlotBounds bounds	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.
@NonNull BoundingArc boundingArc	The BoundingArc defining the geometry of the edge complication.
@NonNull ComplicationTapFilter complicationTapFilter	The ComplicationTapFilter used to determine whether or not a tap hit the complication. The default ComplicationTapFilter uses boundingArc to perform hit testing.

createRoundRectComplicationSlotBuilder

public static final @NonNull ComplicationSlot.Builder createRoundRectComplicationSlotBuilder(
    int id,
    @NonNull CanvasComplicationFactory canvasComplicationFactory,
    @NonNull List<@NonNull ComplicationType> supportedTypes,
    @NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy,
    @NonNull ComplicationSlotBounds bounds
)

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
int id	The watch face's ID for this complication. Can be any integer but should be unique within the watch face.
@NonNull CanvasComplicationFactory canvasComplicationFactory	The CanvasComplicationFactory to supply the CanvasComplication to use for rendering. Note renderers should not be shared between complicationSlots.
@NonNull List<@NonNull ComplicationType> supportedTypes	The types of complication supported by this ComplicationSlot. Used during complication, this list should be non-empty.
@NonNull DefaultComplicationDataSourcePolicy defaultDataSourcePolicy	The DefaultComplicationDataSourcePolicy used to select the initial complication data source when the watch is first installed.
@NonNull ComplicationSlotBounds bounds	The complication's ComplicationSlotBounds.

equals

public boolean equals(Object other)

getAccessibilityTraversalIndex

Added in 1.0.0

@UiThread
public final int getAccessibilityTraversalIndex()

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.

getBoundsType

Added in 1.0.0

public final int getBoundsType()

The ComplicationSlotBoundsTypeIntDef of the complication slot.

getCanvasComplicationFactory

Added in 1.0.0

public final @NonNull CanvasComplicationFactory getCanvasComplicationFactory()

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

getComplicationData

Added in 1.0.0

public final @NonNull StateFlow<@NonNull ComplicationData> getComplicationData()

The androidx.wear.watchface.complications.data.ComplicationData associated with the ComplicationSlot. This defaults to NoDataComplicationData.

getComplicationSlotBounds

Added in 1.0.0

@UiThread
public final @NonNull ComplicationSlotBounds getComplicationSlotBounds()

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.

getConfigExtras

Added in 1.0.0

public final @NonNull Bundle getConfigExtras()

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

getDefaultDataSourcePolicy

Added in 1.0.0

@UiThread
public final @NonNull DefaultComplicationDataSourcePolicy getDefaultDataSourcePolicy()

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

getDefaultDataSourceType

Added in 1.0.0

Deprecated in 1.1.0

@UiThread
public final @NonNull ComplicationType getDefaultDataSourceType()

The default ComplicationType to use alongside defaultDataSourcePolicy.

getId

Added in 1.0.0

public final int getId()

The Watch Face's ID for the complication slot.

getNameResourceId

Added in 1.1.0

@UiThread
public final Integer getNameResourceId()

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.

getRenderer

Added in 1.0.0

public final @NonNull CanvasComplication getRenderer()

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

getScreenReaderNameResourceId

Added in 1.1.0

@UiThread
public final Integer getScreenReaderNameResourceId()

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'.

getSupportedTypes

Added in 1.0.0

public final @NonNull List<@NonNull ComplicationType> getSupportedTypes()

getTapFilter

Added in 1.0.0

public final @NonNull ComplicationTapFilter getTapFilter()

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

hashCode

public int hashCode()

isActiveAt

Added in 1.0.0

public final boolean isActiveAt(@NonNull Instant instant)

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

isEnabled

Added in 1.0.0

@UiThread
public final boolean isEnabled()

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

isFixedComplicationDataSource

Added in 1.2.0

public final boolean isFixedComplicationDataSource()

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.

isInitiallyEnabled

Added in 1.2.0

public final boolean isInitiallyEnabled()

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.

render

Added in 1.0.0

@UiThread
public final void render(
    @NonNull Canvas canvas,
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull RenderParameters renderParameters
)

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

Parameters
@NonNull Canvas canvas	The Canvas to render into
@NonNull ZonedDateTime zonedDateTime	The ZonedDateTime to render with
@NonNull RenderParameters renderParameters	The current RenderParameters

renderHighlightLayer

Added in 1.0.0

@UiThread
public final void renderHighlightLayer(
    @NonNull Canvas canvas,
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull RenderParameters renderParameters
)

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

Parameters
@NonNull Canvas canvas	The Canvas to render into
@NonNull ZonedDateTime zonedDateTime	The ZonedDateTime to render with
@NonNull RenderParameters renderParameters	The current RenderParameters

setConfigExtras

Added in 1.1.0

public final void setConfigExtras(@NonNull Bundle configExtras)

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