Class WidgetTimeline

java.lang.Object
com.codename1.surfaces.WidgetTimeline
public class WidgetTimeline extends Object

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.

  • Field Details

    • RELOAD_AT_END

      public static final int RELOAD_AT_END
      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.
      See Also:

    • RELOAD_NEVER

      public static final int RELOAD_NEVER
      Keep showing the last entry until the app publishes again.
      See Also:

  • 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: 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: the size family the layout applies to
      • root: 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: the moment the entry becomes current
      • state: 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: 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: 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.