TimeText (Character Displays)

Displays time in a specified format and counts up or down. The starting time is provided as a time since the epoch UTC. There is no conversion during time formatting to show the time in anything other than UTC. If the countdown reaches zero, it simply retains that value. Negative values are not shown.

This component can be used in APL documents displayed on character display devices, such as the Echo Dot with clock. It is not supported for devices with screens such as the Echo Show.

Example

{
  "type": "TimeText",
  "format": "%M:%S", // C99 strftime compatible
  "start": "1552070232", // Epoch time in seconds; defaults to current time
  "direction": "down"
}

Properties

The TimeText component inherits the properties from the Text component and also has the following properties in addition to the standard component properties:

Property Type Default Dynamic Description
direction up, down, none up No Direction to count.
format String "%M:%S" No Format for time display (subset of C99 strftime-compatible formats)
start Integer current time No Starting UTC time in seconds since the epoch

direction

Specifies the direction to count. When the direction value is "none" the time shall remain at the starting value.

format

A format string from a subset of the values supported by the C99 (ISO/IEC 9899:1999 (E)) standard format accepted by strftime. Not all the formats are supported by TimeText component. This is deliberate design choice to avoid having to deal with locale-specific formatting on the device. Instead, we encourage the development of locale-appropriate cloud-based logic for formatting.

Below are supported formats with examples on a one-line character display with left alignment, direction of "none" and a "start" value of 1426325213 (Saturday, March 14, 2015 9:26:53 AM) :

"format" value Short explanation Shows as
%C 0-based century (00-99) 20
%d day of the month (01-31) 14
%D equivalent to "%m/%d/%y" 03/14/15
%e day of the month (1-31) 14
%F equivalent to "%Y-%m-%d" 2015-03-14
%g 2 digits of week-based year 15
%H hour (00-23) 09
%I hour (01-12) 09
%j day of the year (001-366) 073
%m month (01-12) 03
%M minute (00-59) 26
%R equivalent to "%H:%M" 09:26
%S seconds (00-60) 53
%T equivalent to "%H:%M:%S" 09:26:53
%u weekday (1-7) 6
%U Sunday-based week (00-53) 10
%V ISO 8601 week (01-53) 11
%w weekday (0-6) 6
%W Monday-based week (00-53) 10
%y 2-digit year 15
%Y full year 2015

start

The starting epoch time value (in seconds) that will be displayed when the component is first rendered. For example, to show a count down from 5 minutes, set start to 300.

Was this page helpful?

Last updated: May 10, 2024