public class SurfaceProgress

  1. Object
  2. SurfaceNode
  3. SurfaceProgress

A progress indicator node. The value is a fraction between 0 and 1, supplied either literally, by state-map key, or as a date interval the OS animates natively (iOS only; other platforms freeze the interval’s value as of the last refresh).

Determinate STYLE_CIRCULAR progress falls back to a linear bar on Android app widgets, which only support indeterminate circular spinners.

Fields

public static final int STYLE_LINEAR = 0A horizontal progress bar.
public static final int STYLE_CIRCULAR = 1A circular gauge.

Constructors

public SurfaceProgress(int style)Creates a progress node.

Methods

public SurfaceProgress setValue(float value)Sets a literal progress value.
public SurfaceProgress setValueState(String valueStateKey)Reads the progress value from the state map.
public SurfaceProgress setDateInterval(Date start, Date end)Animates progress across a date interval on the OS clock without app wakeups.
public SurfaceProgress setColor(SurfaceColor color)Sets the indicator color.
public int getStyle()Returns STYLE_LINEAR or STYLE_CIRCULAR.
public float getValue()Returns the literal progress fraction, or -1 when unset.
public String getValueKey()Returns the state-map key of the progress value, or null.
public Date getIntervalStart()Returns the animated interval start, or null.
public Date getIntervalEnd()Returns the animated interval end, or null.
public SurfaceColor getColor()Returns the indicator color, or null for the platform default.
public SurfaceProgress setPadding(int all)Sets the same padding on all four sides.
public SurfaceProgress setPadding(int top, int right, int bottom, int left)Sets the padding of each side individually.
public SurfaceProgress setBackground(SurfaceColor background)Sets the background color of this node.
public SurfaceProgress setCornerRadius(int radius)Sets the corner radius applied to the node’s background.
public SurfaceProgress setAlignment(SurfaceAlignment alignment)Sets this node’s alignment within its parent.
public SurfaceProgress setWeight(int weight)Sets the flexible-space weight of this node within a row or column.
public SurfaceProgress setSize(int widthDips, int heightDips)Sets a fixed size for this node.
public SurfaceProgress setAction(String actionId)Assigns a tap action to this node.
public SurfaceProgress 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_LINEAR

public static final int STYLE_LINEAR = 0
A horizontal progress bar.

STYLE_CIRCULAR

public static final int STYLE_CIRCULAR = 1
A circular gauge. Falls back to linear on Android app widgets.

Constructor details

SurfaceProgress

public SurfaceProgress(int style)
Creates a progress node.

Parameters

style int
STYLE_LINEAR or STYLE_CIRCULAR

Method details

setValue

public SurfaceProgress setValue(float value)
Sets a literal progress value.

Parameters

value float
the progress fraction between 0 and 1

Returns

this progress node, for chaining

setValueState

public SurfaceProgress setValueState(String valueStateKey)
Reads the progress value from the state map. The state value is a Number between 0 and 1.

Parameters

valueStateKey String
the state-map key holding the fraction

Returns

this progress node, for chaining

setDateInterval

public SurfaceProgress setDateInterval(Date start, Date end)
Animates progress across a date interval on the OS clock without app wakeups. Only iOS renders this natively; other platforms display the interval’s fraction as of their last refresh.

Parameters

start Date
interval start
end Date
interval end

Returns

this progress node, for chaining

setColor

public SurfaceProgress setColor(SurfaceColor color)
Sets the indicator color.

Parameters

color SurfaceColor
the color

Returns

this progress node, for chaining

getStyle

public int getStyle()
Returns STYLE_LINEAR or STYLE_CIRCULAR.

getValue

public float getValue()
Returns the literal progress fraction, or -1 when unset.

getValueKey

public String getValueKey()
Returns the state-map key of the progress value, or null.

getIntervalStart

public Date getIntervalStart()
Returns the animated interval start, or null.

getIntervalEnd

public Date getIntervalEnd()
Returns the animated interval end, or null.

getColor

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

setPadding

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

Parameters

all int
padding in dips

Returns

this node, for chaining

setPadding

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

Parameters

background SurfaceColor
the background color

Returns

this node, for chaining

setCornerRadius

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