From 4329ffb98d7eeffe2b3874d2b31cb0857d33d944 Mon Sep 17 00:00:00 2001 From: Anders Betts Date: Sat, 19 Sep 2026 21:58:58 +0200 Subject: tui: shared widget layer (fields, prompts, lists, forms, pager) + tests --- docs/TUI-GUIDELINES.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'docs/TUI-GUIDELINES.md') diff --git a/docs/TUI-GUIDELINES.md b/docs/TUI-GUIDELINES.md index a54fef8..63c492f 100644 --- a/docs/TUI-GUIDELINES.md +++ b/docs/TUI-GUIDELINES.md @@ -104,12 +104,31 @@ written compactly as `^N`, `^A`, `^C`, `^R` to save width. - Selection = reverse video, headers = bold, derived data = dim. - All user-visible TUI text is Swedish; server messages are English. +## Widget layer (`clients/tui.[ch]`) + +Every element a screen needs is a widget here, and the widget layer is the +only place that touches ncurses. Rules: + +- Screens never call ncurses directly (`mvadd*`, `attron`, `getch`…) and + never keep a local one-off input or drawing loop. +- If no widget fits, **extend the widget layer first** (spec in this file + + unit tests in `tests/test_tui.c`) and then use it. There is no "do it + locally once" option. +- Pure logic (line editing, date input, list navigation, prompts parsing) + is separated from drawing so it can be tested without a terminal. +- Widgets return key codes (`-1` back, `-2` refresh, `-4` new, `-6` remove, + `-7` toggle) and write text into the caller's buffer; nothing returns + static storage. +- The application supplies input, frame/hints and quit through + `tui_set_input`/`tui_set_screen`/`tui_set_quit`. + ## Adding a view — checklist 1. Data comes from public protocol commands only. 2. Wrap the screen in `frame()`/`hints()`; return `Esc`/`q` to the parent. -3. Use `menu()` or `select_list()` instead of writing a new loop; pass +3. Use `tui_menu`/`tui_select_list` instead of writing a new loop; pass `allow_new`/`allow_refresh` so the universal keys apply. -4. Forms use the shared editor (`field_edit`) and the row-normalising helpers. +4. Forms use the shared editor (`tui_edit_field`, `tui_prompt_into`, + `tui_date_prompt_into`, `tui_amount_prompt_into`) and the row helpers. 5. Support `F5` if the data can change elsewhere. 6. Update `PROTOCOL.md` §8 and this file if you add a new key or interaction. -- cgit v1.3