Class SurfaceDynamicText

java.lang.Object
com.codename1.surfaces.SurfaceNode
com.codename1.surfaces.SurfaceDynamicText
public class SurfaceDynamicText extends SurfaceNode

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.

  • Field Details

    • STYLE_TIMER_DOWN

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

    • STYLE_TIMER_UP

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

    • STYLE_TIME

      public static final int STYLE_TIME
      The target date's clock time, e.g. 9:41 AM.
      See Also:

    • STYLE_DATE

      public static final int STYLE_DATE
      The target date's calendar date, e.g. June 3. Approximated as static text on Android.
      See Also:

    • STYLE_RELATIVE

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

  • Constructor Details

    • SurfaceDynamicText

      public SurfaceDynamicText(int style, Date date)

      Creates a dynamic text node with a fixed target date.

      Parameters
      • style: one of the STYLE_... constants
      • 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: one of the STYLE_... constants
      • dateStateKey: the state-map key holding the epoch millis

  • Method Details

    • setFontSize

      public SurfaceDynamicText setFontSize(int fontSize)

      Sets the font size.

      Parameters
      • fontSize: the size in dips
      Returns

      this node, for chaining

    • setFontWeight

      public SurfaceDynamicText setFontWeight(SurfaceFontWeight fontWeight)

      Sets the font weight.

      Parameters
      • fontWeight: the weight
      Returns

      this node, for chaining

    • setColor

      public SurfaceDynamicText setColor(SurfaceColor color)

      Sets the text color.

      Parameters
      • color: 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)
      Description copied from class: SurfaceNode

      Sets the same padding on all four sides.

      Parameters
      • all: padding in dips
      Returns

      this node, for chaining

      Overrides:
      setPadding in class SurfaceNode

    • setPadding

      public SurfaceDynamicText setPadding(int top, int right, int bottom, int left)
      Description copied from class: SurfaceNode

      Sets the padding of each side individually.

      Parameters
      • top: top padding in dips
      • right: right padding in dips
      • bottom: bottom padding in dips
      • left: left padding in dips
      Returns

      this node, for chaining

      Overrides:
      setPadding in class SurfaceNode

    • setBackground

      public SurfaceDynamicText setBackground(SurfaceColor background)
      Description copied from class: SurfaceNode

      Sets the background color of this node.

      Parameters
      • color: the background color
      Returns

      this node, for chaining

      Overrides:
      setBackground in class SurfaceNode

    • setCornerRadius

      public SurfaceDynamicText setCornerRadius(int radius)
      Description copied from class: SurfaceNode

      Sets the corner radius applied to the node's background. May render square on Android versions below 12.

      Parameters
      • radius: the corner radius in dips
      Returns

      this node, for chaining

      Overrides:
      setCornerRadius in class SurfaceNode

    • setAlignment

      public SurfaceDynamicText setAlignment(SurfaceAlignment alignment)
      Description copied from class: SurfaceNode

      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: the alignment
      Returns

      this node, for chaining

      Overrides:
      setAlignment in class SurfaceNode

    • setWeight

      public SurfaceDynamicText setWeight(int weight)
      Description copied from class: SurfaceNode

      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: the relative weight, 0 for natural sizing
      Returns

      this node, for chaining

      Overrides:
      setWeight in class SurfaceNode

    • setSize

      public SurfaceDynamicText setSize(int widthDips, int heightDips)
      Description copied from class: SurfaceNode

      Sets a fixed size for this node. A value of 0 (the default) keeps the natural size of the respective axis.

      Parameters
      • widthDips: fixed width in dips, 0 for natural width
      • heightDips: fixed height in dips, 0 for natural height
      Returns

      this node, for chaining

      Overrides:
      setSize in class SurfaceNode

    • setAction

      public SurfaceDynamicText setAction(String actionId)
      Description copied from class: SurfaceNode

      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: the app-defined action identifier
      Returns

      this node, for chaining

      Overrides:
      setAction in class SurfaceNode

    • setAction

      public SurfaceDynamicText setAction(String actionId, Map<String,Object> params)
      Description copied from class: SurfaceNode

      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: the app-defined action identifier
      • params: parameters delivered with the action, may be null
      Returns

      this node, for chaining

      Overrides:
      setAction in class SurfaceNode