# `Ascii.Pieces.DigitalClock`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/pieces/digital_clock.ex#L1)

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

```elixir
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
```

```heex
<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).

---

*Consult [api-reference.md](api-reference.md) for complete listing*