diff options
Diffstat (limited to 'docs/TUI-GUIDELINES.md')
| -rw-r--r-- | docs/TUI-GUIDELINES.md | 23 |
1 files changed, 21 insertions, 2 deletions
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. |