glimmer-tui

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# glimmer-tui

glimmer's **terminal** backend, on the jolt side of the ABI — the namespace
that binds [`libjolttui`](../../crates/jolt-tui) and registers it with
`glimmer.backend`.

It is [glimmer-vidya](../glimmer-vidya) with a different shared object under
it. The reconciler does not know what it is patching, so the same hiccup that
egui paints as a window paints here as cells:

```clojure
(ns myapp
  (:require [glimmer.ratom :refer [atom]]
            [glimmer.core :as ui]
            [glimmer-tui.core]))       ; installs this backend

(defn -main [& _] (ui/run my-app))
```

```bash
cargo build --release -p jolt-tui
LD_LIBRARY_PATH=../../target/release jolt -M:counter
```

## What differs from the window

Only what a terminal actually forces.

* **No pictures, no title, no clipboard, no browser.** `glimmer-vidya.core`'s
  `frame-rgba!`, `set-title!`, `clipboard-image-png!`, `open-url!` and
  `pick-image!` have no answer here and are not defined.
* **Keys instead of a pointer.** `:on-key` is raised on whatever has focus, or
  on the window when nothing does — and it is the one event this backend
  *bubbles*, because the focused widget is rarely what knows the key's meaning.
  `:on-select` and `:on-scroll` join the list; `:on-hover` leaves it.
* **Cells instead of points.** `screen-size` answers columns and rows.
* **A scale for trees written in points.** `:points-per-cell` on `run` divides
  the props that are a distance — margins, padding, spacing, width and height
  requests — on the way across, so an app laid out for a window is legible in a
  terminal without rewriting its numbers. 8 is about right; the default is 1,
  for a tree that was written in cells to begin with.

`after!`, `every!`, `cancel!`, `quit!` and the `dump` family are the same calls
with the same meanings.

## Looking at what was painted

A headless session is a session with the writer taken off the end — same
layout, same painting, same focus ring, no terminal:

```clojure
(tui/after! 100 (fn [] (println (tui/screen-str)) (tui/quit!)))
(ui/run my-app :headless [100 34])
```

`screen-line`, `screen-str` and `screen!` read the grid back; `feed-key!`,
`feed-click!` and `feed-wheel!` drive it. Those are the entry points a real
terminal's input arrives through, so a test types what a person types.