Ascii.Pieces.DigitalClock (Ascii v0.3.0)

Copy Markdown View Source

The local time in seven-segment digits, colon blinking.

The local time as big seven-segment digits, HH:MM:SS, with the colon blinking each second and the date set small underneath, as upstream draws it. Give it a timer and it is a countdown or a stopwatch instead, which keeps play time rather than the clock.

Reads the clock from env.now (see Ascii.Kit.Clock), as a clock.

Options

Give them to Ascii.new/2 as options:, and new ones while it plays with Ascii.put_options/2 (or a Phoenix player's options): a timer runs on through a new label or look, and starts again from from when timer or from change.

  • timer - "down" counts down from from to zero, where the digits flash; "up" counts up from from, as a stopwatch, to 99:59:59. Both start with play. Default "", as is any other string: the clock.
  • from - the seconds a timer starts at, 0 to 359,999 (99:59:59). Default 0.
  • label - a line beneath a timer, where the clock has its date. Default "".
  • seconds - the seconds' pair of digits; false shows hours and minutes alone. Default true.
  • hour12 - a 12-hour clock: its first digit dark rather than a zero, and am or pm after the date. Default false.
  • date - the clock's date beneath the digits, as "saturday 14 march 2026"; without it the digits sit a row lower. Default true.

A timer shows hours, minutes and seconds (with seconds: false, hours and minutes), its colons blinking while it runs. The frame is always 70 by 11.

Colours

In one ink, or a gradient, with :ink and :gradient (see Ascii.Ink); part by part with :parts (see Ascii.Parts), parts: true taking the colours suggested here:

  • digit.on - the digits' lit segments; digit.off, the unlit ones, faintly showing like the glass of a real display, grey.
  • colon.on - the colons lit; colon.off, dark as they blink, grey.
  • date - the clock's date beneath the digits; label, a timer's line.
  • ampm - a 12-hour clock's am or pm, cyan.

Keys and clicks

It takes none: it tells the time, and Ascii.handle_event/2 ignores every event; start a timer again with a new from (Ascii.put_options/2). A Phoenix player given interactive and notify still tells your LiveView where it was clicked, and on which part (Ascii.part_at/4).

Screen readers

Ascii.describe/1 tells a timer, with its label, as "tea: countdown from 5:00" or "stopwatch"; not the time left, which changes every second. As a clock, it gives the piece's name and note.

Example

tea = Ascii.new!("digital-clock", options: %{timer: "down", from: 300, label: "tea"}, parts: true)
Ascii.describe(tea)
#=> "tea: countdown from 5:00"

# A minute in, four minutes to go, with its label beneath.
{frame, _tea} = Ascii.frame(tea, 60.0)
frame.text =~ "tea"
#=> true

# The clock, at a given moment.
now = DateTime.new!(~D[2026-03-14], ~T[15:09:26], "Etc/UTC")
clock = Ascii.new!("digital-clock", options: %{hour12: true})
{frame, _clock} = Ascii.frame(clock, 0.0, now: now)
frame.text =~ "saturday 14 march 2026  pm"
#=> true
<Ascii.Phoenix.live_player id="tea" piece="digital-clock" options={%{timer: "down", from: 300, label: "tea"}} parts />

Ported from src/pieces/digital-clock.ts in bas3line/ascii (MIT).