public class WidgetTimeline

Object
WidgetTimeline

The content of a widget kind: a layout descriptor plus a timeline of dated state snapshots. Publishing a timeline lets the widget change over time without waking the app – the OS (or the desktop surface) switches to the entry whose date has most recently passed and interpolates its state map into the layout’s ${key} placeholders:

WidgetTimeline t = new WidgetTimeline()
        .setContent(deliveryLayout)
        .addEntry(now, stateMap("Out for delivery", eta, 0.7f))
        .addEntry(eta, stateMap("Arriving now", eta, 1.0f));
Surfaces.publish("delivery_status", t);

State values may be String, Number, Boolean, or Long epoch millis for the date keys of SurfaceDynamicText / SurfaceProgress. A timeline published without entries gets a single implicit entry effective immediately with an empty state map.

Nested types

class WidgetTimeline.Entry One dated state snapshot within a timeline.

Fields

`public static final int RELOAD_AT_END = 0`	After the last entry passes, ask the platform to request fresh content (the app’s `BackgroundFetch` is the refresh hook).
`public static final int RELOAD_NEVER = 1`	Keep showing the last entry until the app publishes again.

Constructors

public WidgetTimeline()

Methods

`public` `WidgetTimeline setContent(SurfaceNode root)`	Sets the layout used for every size family that has no explicit override.
`public` `WidgetTimeline setContent(WidgetSize size, SurfaceNode root)`	Sets a size-specific layout override.
`public` `WidgetTimeline addEntry(Date date, Map<String, Object> state)`	Appends a dated state snapshot.
`public` `WidgetTimeline setReloadPolicy(int policy)`	Sets what happens after the last entry passes.
`public` `SurfaceNode getContent(WidgetSize size)`	Returns the layout for the given size family: the explicit override when one was set, otherwise the default content.
`public` `SurfaceNode getDefaultContent()`	Returns the layout used for size families without an explicit override, or null.
`public` `List<WidgetTimeline.Entry> getEntries()`	Returns the entries in the order they were added.
`public int getReloadPolicy()`	Returns the reload policy, `RELOAD_AT_END` or `RELOAD_NEVER`.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Field details

RELOAD_AT_END

public static final int RELOAD_AT_END = 0

After the last entry passes, ask the platform to request fresh content (the app’s BackgroundFetch is the refresh hook). Maps to WidgetKit’s .atEnd policy.

RELOAD_NEVER

public static final int RELOAD_NEVER = 1

Keep showing the last entry until the app publishes again.

Constructor details

WidgetTimeline

public WidgetTimeline()

Method details

setContent

public WidgetTimeline setContent(SurfaceNode root)

Sets the layout used for every size family that has no explicit override.

Parameters

root SurfaceNode: the layout root node

Returns

this timeline, for chaining

setContent

public WidgetTimeline setContent(WidgetSize size, SurfaceNode root)

Sets a size-specific layout override.

Parameters

size WidgetSize: the size family the layout applies to
root SurfaceNode: the layout root node

Returns

this timeline, for chaining

addEntry

public WidgetTimeline addEntry(Date date, Map<String, Object> state)

Appends a dated state snapshot. Entries may be added in any order; they are sorted by date when published.

Parameters

date Date: the moment the entry becomes current
state Map<String, Object>: the state map interpolated into the layout, may be null

Returns

this timeline, for chaining

setReloadPolicy

public WidgetTimeline setReloadPolicy(int policy)

Sets what happens after the last entry passes.

Parameters

policy int: RELOAD_AT_END or RELOAD_NEVER

Returns

this timeline, for chaining

getContent

public SurfaceNode getContent(WidgetSize size)

Returns the layout for the given size family: the explicit override when one was set, otherwise the default content.

Parameters

size WidgetSize: the size family

Returns

the layout root, or null when neither an override nor a default was set

getDefaultContent

public SurfaceNode getDefaultContent()

Returns the layout used for size families without an explicit override, or null.

getEntries

public List<WidgetTimeline.Entry> getEntries()

Returns the entries in the order they were added.

getReloadPolicy

public int getReloadPolicy()

Returns the reload policy, RELOAD_AT_END or RELOAD_NEVER.