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

Semicircle dial, the needle overshoots each new reading.

A semicircle dial in half-block pixels, a band filled up to the reading,
and a needle that springs to each new value, overshoots, and settles. As
upstream draws it, it plays readings of its own; give it a `value` and it
shows yours, for a dashboard or a terminal UI.

## 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 new
`value` swings the needle from wherever it is, at its speed, overshooting
and settling on the reading.

  * `value` - the reading, in `min`..`max` units; the readout shows it as
    given (rounded). Default `nil`: upstream's own readings, a new one
    every few seconds.
  * `label` - the line under the readout. Default `"load"`.
  * `unit` - after the readout: `%` and `°` close up to it, anything else
    takes a space. Default `"%"`.
  * `min`, `max` - the scale's ends; numbers stand at each fifth of the
    way between them. Defaults 0 and 100.
  * `cols`, `rows` - the frame's size, 43 to 200 by 15 to 100; upstream's
    55 by 18 by default. The dial is drawn as large as fits, centred, its
    ticks, band and needle the same distance inside the rim as ever: to
    fill a pane in a terminal UI or a cell of a grid.

## 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:

  * `dial` - the rim, grey.
  * `axis` - the ticks at every tenth, grey; `axis.minor`, the dots
    between.
  * `scale` - the numbers, grey.
  * `bar` - the band filled up to the needle, blue; `track`, the rest of
    it, grey.
  * `needle` - the needle, yellow; `needle.hub`, the pivot it turns on.
  * `value`, `unit` - the readout.
  * `label` - the line under it.

Where the needle crosses a tick without showing on it, the cell is the
needle's or the tick's as the needle's angle, as far as the picture
tells it, says; in the few frames it cannot tell, the cell is in no part.

## Keys and clicks

It takes none: it shows a reading, and `Ascii.handle_event/2` ignores
every event. A Phoenix player given `interactive` and `notify` still tells
your LiveView where it was clicked, and on which part
(`Ascii.part_at/4`), the needle, say, or the readout.

## Screen readers

`Ascii.describe/1` reads the reading, as the readout shows it: "load:
72%". Playing its own readings, it gives the piece's name and note.

## Example

```elixir
gauge = Ascii.new!("gauge", options: %{label: "cpu", value: 35}, parts: true)
gauge = Ascii.put_options!(gauge, value: 80)
{frame, _gauge} = Ascii.frame(gauge, 2.0)
frame.text =~ "80%"
#=> true

Ascii.describe(gauge)
#=> "cpu: 80%"
```

```heex
<Ascii.Phoenix.live_player id="cpu" piece="gauge" options={%{label: "cpu", value: @cpu}} parts />
```

Ported from `src/pieces/gauge.ts` in bas3line/ascii (MIT).

---

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