Guides¶

Eight pages, in the order they build on each other. The first three are the whole model; everything after them is a part of the library you can reach for when you need it.

The model¶

Views — what a View is: a rectangular grid of cells, and the combinators that build one from smaller ones. Start here. Nothing else makes sense until hcat, vcat and zcat do.

State and effects — ui.state, ui.reducer, ui.every, ui.task and ui.spawn. Hook slots are matched by call order, which is the one rule in the library that will bite you if you skip it.

Input — keys, mouse, focus and consumption. Two rules decide who gets an event: focus, and whether a handler returned True.

The parts¶

Widgets — the catalogue. Every signature on this page is compared against the code on every commit, so it cannot drift.

Dialogs and modals — ui.open_modal, awaited rather than mounted, and the dialog helpers built on it.

Using Rich renderables — drawing a Rich table, syntax block or progress bar into a view, for when you already have one.

Painting a region yourself — View.passthrough, for images, another program's output, or anything the cell grid cannot express.

Testing — rendering an app headlessly, feeding it events, and asserting on the screen it drew. This is how the library tests itself, so it is a well-worn path.

Where to go next¶

The architecture page is the same material from underneath: what happens between your function returning a view and the terminal changing. What is stable says which of the names on these pages are safe to build on today.