TileKt

Added in 1.6.0-alpha05

public final class TileKt

Summary

Public methods
static final @NonNull TileBuilders.Tile
tile(
    @NonNull TimelineBuilders.Timeline timeline,
    long freshnessMillis,
    @RequiresSchemaVersion(major = 1, minor = 200) StateBuilders.State state,
    String resourcesVersion
)

Creates a tile from the defined parameters and layout components defined in the Timeline that can be rendered by a tile renderer.
static final @NonNull TimelineBuilders.TimeInterval

Creates a time interval, typically used to describe the validity period of a TimelineEntry.
static final @NonNull TimelineBuilders.Timeline

Creates a Timeline as a collection of TimelineEntry items.
static final @NonNull TimelineBuilders.TimelineEntry

Creates one piece of renderable content along with the time that it is valid for.

Public methods

tile

public static final @NonNull TileBuilders.Tile tile(
    @NonNull TimelineBuilders.Timeline timeline,
    long freshnessMillis,
    @RequiresSchemaVersion(major = 1, minor = 200) StateBuilders.State state,
    String resourcesVersion
)

Creates a tile from the defined parameters and layout components defined in the Timeline that can be rendered by a tile renderer.

Example of usage to create a tile from the given LayoutElement for 1 entry: tile(timeline = timeline(timelineEntry(tileLayout()))). For more Kotlin friendly support and automatic, more performant resources handling, see Material3TileService.

Parameters
@NonNull TimelineBuilders.Timeline timeline

The Timeline containing the layouts for the tiles to show in the carousel, along with their validity periods.
long freshnessMillis

How many milliseconds of elapsed time (not wall clock time) this tile can be considered to be "fresh". The platform will attempt to refresh your tile at some point in the future after this interval has lapsed. A value of 0 here signifies that auto-refreshes should not be used (i.e. you will manually request updates via TileService.getUpdater. This mechanism should not be used to update your tile more frequently than once a minute, and the system may throttle your updates if you request updates faster than this interval. This interval is also inexact; the system will generally update your tile if it is on-screen, or about to be on-screen, although this is not guaranteed due to system-level optimizations. Negative values will be ignored and considered as 0.
@RequiresSchemaVersion(major = 1, minor = 200) StateBuilders.State state

The State for this tile
String resourcesVersion

The resource version for tile's resources used for caching the resources in system. When using better resources handling via androidx.wear.protolayout.ProtoLayoutScope this can be omitted.

timeInterval

public static final @NonNull TimelineBuilders.TimeInterval timeInterval(@NonNull Duration start, @NonNull Duration end)

Creates a time interval, typically used to describe the validity period of a TimelineEntry.

Parameters
@NonNull Duration start

The starting point of the time interval, since the Unix epoch
@NonNull Duration end

The end point of the time interval, since the Unix epoch

timeline

public static final @NonNull TimelineBuilders.Timeline timeline(@NonNull TimelineBuilders.TimelineEntry... entries)

Creates a Timeline as a collection of TimelineEntry items.

TimelineEntry items can be used to update a tile layout on-screen at known times, without having to explicitly update a layout. This allows for cases where, say, a calendar can be used to show the next event, and automatically switch to showing the next event when one has passed.

The active TimelineEntry is switched, at most, once a minute. In the case where the validity periods of TimelineEntry items overlap, the item with the shortest* validity period will be shown. This allows a layout provider to show a "default" layout, and override it at set points without having to explicitly insert the default layout between the "override" layout.

Parameters
@NonNull TimelineBuilders.TimelineEntry... entries

The list of one or more TimelineEntry. If your tile only has 1 TimelineEntry, cleaner helper method to use instead of this one is Timeline.fromLayoutElement where LayoutElement can be passed in directly.

timelineEntry

public static final @NonNull TimelineBuilders.TimelineEntry timelineEntry(
    @NonNull LayoutElementBuilders.LayoutElement layout,
    TimelineBuilders.TimeInterval validity
)

Creates one piece of renderable content along with the time that it is valid for.

Parameters
@NonNull LayoutElementBuilders.LayoutElement layout

The contents of this timeline entry, root LayoutElement of tile
TimelineBuilders.TimeInterval validity

The validity period for this timeline entry. If not set, this entry doesn't expire.