public class SurfaceText

  1. Object
  2. SurfaceNode
  3. SurfaceText

A static text node. The text may embed ${key} placeholders that the platform renderer substitutes from the state map of the current timeline entry or live-activity update, so frequently changing values do not require re-publishing the whole descriptor:

new SurfaceText("${status}").setFontSize(13).setColor(SurfaceColor.SECONDARY_LABEL)

For values the OS should animate on its own clock (countdowns, elapsed time) use SurfaceDynamicText instead.

Constructors

public SurfaceText(String text)Creates a text node.

Methods

public SurfaceText setFontSize(int fontSize)Sets the font size.
public SurfaceText setFontWeight(SurfaceFontWeight fontWeight)Sets the font weight.
public SurfaceText setColor(SurfaceColor color)Sets the text color.
public SurfaceText setMaxLines(int maxLines)Limits the number of rendered lines.
public String getText()Returns the text, potentially containing ${key} placeholders.
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 int getMaxLines()Returns the maximum line count, 0 for unlimited.
public SurfaceText setPadding(int all)Sets the same padding on all four sides.
public SurfaceText setPadding(int top, int right, int bottom, int left)Sets the padding of each side individually.
public SurfaceText setBackground(SurfaceColor background)Sets the background color of this node.
public SurfaceText setCornerRadius(int radius)Sets the corner radius applied to the node’s background.
public SurfaceText setAlignment(SurfaceAlignment alignment)Sets this node’s alignment within its parent.
public SurfaceText setWeight(int weight)Sets the flexible-space weight of this node within a row or column.
public SurfaceText setSize(int widthDips, int heightDips)Sets a fixed size for this node.
public SurfaceText setAction(String actionId)Assigns a tap action to this node.
public SurfaceText 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

Constructor details

SurfaceText

public SurfaceText(String text)
Creates a text node.

Parameters

text String
literal text, optionally embedding ${key} state placeholders

Method details

setFontSize

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

Parameters

fontSize int
the size in dips

Returns

this text node, for chaining

setFontWeight

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

Parameters

fontWeight SurfaceFontWeight
the weight

Returns

this text node, for chaining

setColor

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

Parameters

color SurfaceColor
the color

Returns

this text node, for chaining

setMaxLines

public SurfaceText setMaxLines(int maxLines)
Limits the number of rendered lines.

Parameters

maxLines int
maximum line count, 0 for unlimited

Returns

this text node, for chaining

getText

public String getText()
Returns the text, potentially containing ${key} placeholders.

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.

getMaxLines

public int getMaxLines()
Returns the maximum line count, 0 for unlimited.

setPadding

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

Parameters

all int
padding in dips

Returns

this node, for chaining

setPadding

public SurfaceText 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 SurfaceText setBackground(SurfaceColor background)
Sets the background color of this node.

Parameters

background SurfaceColor
the background color

Returns

this node, for chaining

setCornerRadius

public SurfaceText 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 SurfaceText 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 SurfaceText 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 SurfaceText 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 SurfaceText 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 SurfaceText 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