public class SurfaceDynamicText

  1. Object
  2. SurfaceNode
  3. SurfaceDynamicText

A date-driven text node the operating system animates natively – the headline feature for timers, delivery ETAs and elapsed-time displays: a countdown keeps ticking every second on the widget or Dynamic Island even though the app process is not running.

// counts down to the ETA the OS-native way, no app wakeups needed
new SurfaceDynamicText(SurfaceDynamicText.STYLE_TIMER_DOWN, "eta")
        .setFontSize(22).setFontWeight(SurfaceFontWeight.BOLD)

The target date is either fixed at build time or referenced from the state map by key (the state value is the epoch time in milliseconds as a Long), so a live-activity update can move the ETA without republishing the layout.

Rendering: iOS uses Text(date, style:), Android uses Chronometer / TextClock. On Android the STYLE_DATE and STYLE_RELATIVE styles are approximated – they render as static text computed when the widget last refreshed.

Fields

public static final int STYLE_TIMER_DOWN = 0Counts down to the target date, e.g. 04:59.
public static final int STYLE_TIMER_UP = 1Counts up since the target date, e.g. 12:07.
public static final int STYLE_TIME = 2The target date’s clock time, e.g. 9:41 AM.
public static final int STYLE_DATE = 3The target date’s calendar date, e.g. June 3.
public static final int STYLE_RELATIVE = 4The distance to the target date in words, e.g. in 5 min.

Constructors

public SurfaceDynamicText(int style, Date date)Creates a dynamic text node with a fixed target date.
public SurfaceDynamicText(int style, String dateStateKey)Creates a dynamic text node whose target date comes from the state map.

Methods

public SurfaceDynamicText setFontSize(int fontSize)Sets the font size.
public SurfaceDynamicText setFontWeight(SurfaceFontWeight fontWeight)Sets the font weight.
public SurfaceDynamicText setColor(SurfaceColor color)Sets the text color.
public int getStyle()Returns the STYLE_... constant of this node.
public Date getDate()Returns the fixed target date, or null when the date comes from the state map.
public String getDateKey()Returns the state-map key of the target date, or null when the date is fixed.
public int getFontSize()Returns the font size in dips, 0 for the platform default.
public SurfaceFontWeight getFontWeight()Returns the font weight, or null for the platform default.
public SurfaceColor getColor()Returns the text color, or null for the platform default.
public SurfaceDynamicText setPadding(int all)Sets the same padding on all four sides.
public SurfaceDynamicText setPadding(int top, int right, int bottom, int left)Sets the padding of each side individually.
public SurfaceDynamicText setBackground(SurfaceColor background)Sets the background color of this node.
public SurfaceDynamicText setCornerRadius(int radius)Sets the corner radius applied to the node’s background.
public SurfaceDynamicText setAlignment(SurfaceAlignment alignment)Sets this node’s alignment within its parent.
public SurfaceDynamicText setWeight(int weight)Sets the flexible-space weight of this node within a row or column.
public SurfaceDynamicText setSize(int widthDips, int heightDips)Sets a fixed size for this node.
public SurfaceDynamicText setAction(String actionId)Assigns a tap action to this node.
public SurfaceDynamicText setAction(String actionId, Map<String, Object> params)Assigns a tap action with parameters to this node.

Inherited methods

From SurfaceNode

getPaddingTop, getPaddingRight, getPaddingBottom, getPaddingLeft, getBackground, getCornerRadius, getAlignment, getWeight, getWidthDips, getHeightDips, getActionId, getActionParams

From Object

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

Field details

STYLE_TIMER_DOWN

public static final int STYLE_TIMER_DOWN = 0
Counts down to the target date, e.g. 04:59. Rendered by Text(date, style: .timer) on iOS and a countdown Chronometer on Android.

STYLE_TIMER_UP

public static final int STYLE_TIMER_UP = 1
Counts up since the target date, e.g. 12:07.

STYLE_TIME

public static final int STYLE_TIME = 2
The target date’s clock time, e.g. 9:41 AM.

STYLE_DATE

public static final int STYLE_DATE = 3
The target date’s calendar date, e.g. June 3. Approximated as static text on Android.

STYLE_RELATIVE

public static final int STYLE_RELATIVE = 4
The distance to the target date in words, e.g. in 5 min. Approximated as static text on Android.

Constructor details

SurfaceDynamicText

public SurfaceDynamicText(int style, Date date)
Creates a dynamic text node with a fixed target date.

Parameters

style int
one of the STYLE_... constants
date Date
the target date

SurfaceDynamicText

public SurfaceDynamicText(int style, String dateStateKey)
Creates a dynamic text node whose target date comes from the state map. The state value is the epoch time in milliseconds as a Long.

Parameters

style int
one of the STYLE_... constants
dateStateKey String
the state-map key holding the epoch millis

Method details

setFontSize

public SurfaceDynamicText setFontSize(int fontSize)
Sets the font size.

Parameters

fontSize int
the size in dips

Returns

this node, for chaining

setFontWeight

public SurfaceDynamicText setFontWeight(SurfaceFontWeight fontWeight)
Sets the font weight.

Parameters

fontWeight SurfaceFontWeight
the weight

Returns

this node, for chaining

setColor

public SurfaceDynamicText setColor(SurfaceColor color)
Sets the text color.

Parameters

color SurfaceColor
the color

Returns

this node, for chaining

getStyle

public int getStyle()
Returns the STYLE_... constant of this node.

getDate

public Date getDate()
Returns the fixed target date, or null when the date comes from the state map.

getDateKey

public String getDateKey()
Returns the state-map key of the target date, or null when the date is fixed.

getFontSize

public int getFontSize()
Returns the font size in dips, 0 for the platform default.

getFontWeight

public SurfaceFontWeight getFontWeight()
Returns the font weight, or null for the platform default.

getColor

public SurfaceColor getColor()
Returns the text color, or null for the platform default.

setPadding

public SurfaceDynamicText setPadding(int all)
Sets the same padding on all four sides.

Parameters

all int
padding in dips

Returns

this node, for chaining

setPadding

public SurfaceDynamicText setPadding(int top, int right, int bottom, int left)
Sets the padding of each side individually.

Parameters

top int
top padding in dips
right int
right padding in dips
bottom int
bottom padding in dips
left int
left padding in dips

Returns

this node, for chaining

setBackground

public SurfaceDynamicText setBackground(SurfaceColor background)
Sets the background color of this node.

Parameters

background SurfaceColor
the background color

Returns

this node, for chaining

setCornerRadius

public SurfaceDynamicText setCornerRadius(int radius)
Sets the corner radius applied to the node’s background. May render square on Android versions below 12.

Parameters

radius int
the corner radius in dips

Returns

this node, for chaining

setAlignment

public SurfaceDynamicText setAlignment(SurfaceAlignment alignment)
Sets this node’s alignment within its parent. In a SurfaceBox all nine positions apply; in rows and columns only the cross-axis component is used.

Parameters

alignment SurfaceAlignment
the alignment

Returns

this node, for chaining

setWeight

public SurfaceDynamicText setWeight(int weight)
Sets the flexible-space weight of this node within a row or column. Nodes with a weight share the leftover space of the parent proportionally; a weight of 0 (the default) sizes the node to its natural size.

Parameters

weight int
the relative weight, 0 for natural sizing

Returns

this node, for chaining

setSize

public SurfaceDynamicText setSize(int widthDips, int heightDips)
Sets a fixed size for this node. A value of 0 (the default) keeps the natural size of the respective axis.

Parameters

widthDips int
fixed width in dips, 0 for natural width
heightDips int
fixed height in dips, 0 for natural height

Returns

this node, for chaining

setAction

public SurfaceDynamicText setAction(String actionId)
Assigns a tap action to this node. Tapping the node opens (or foregrounds) the app and delivers the action id to the handler registered with Surfaces.setActionHandler(...). Note that small iOS home-screen widgets only honor the action of the root node.

Parameters

actionId String
the app-defined action identifier

Returns

this node, for chaining

setAction

public SurfaceDynamicText setAction(String actionId, Map<String, Object> params)
Assigns a tap action with parameters to this node. The parameter map may contain String, Number and Boolean values and is delivered verbatim with the SurfaceActionEvent.

Parameters

actionId String
the app-defined action identifier
params Map<String, Object>
parameters delivered with the action, may be null

Returns

this node, for chaining