mirror of
https://codeberg.org/unspeaker/tek.git
synced 2025-12-06 19:56:42 +01:00
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# `tek_output`
|
|
|
|
## free floating layout primitives
|
|
|
|
this crate exposes several layout operators
|
|
which work entirely in unsigned coordinates
|
|
and are generic over `tek_engine::Engine`
|
|
and `tek_engine::Content`. chiefly, they
|
|
are not dependent on rendering framework.
|
|
|
|
|operator|description|
|
|
|-|-|
|
|
|**`When(x, a)`**|render `a` only when `x == true`|
|
|
|**`Either(x, a, b)`**|render `a` when `x == true`, otherwise render `b`|
|
|
|**`Map(get_iterator, callback)`**|transform items in uniform way|
|
|
|**`Bsp`**|concatenative layout|
|
|
|...|...|
|
|
|**`Align`**|pin content along axis|
|
|
|...|...|
|
|
|**`Fill`**|**make content's dimension equal to container's:**|
|
|
|`Fill::x(a)`|use container's width for content|
|
|
|`Fill::y(a)`|use container's height for content|
|
|
|`Fill::xy(a)`|use container's width and height for content|
|
|
|**`Fixed`**|**assign fixed dimension to content:**|
|
|
|`Fixed::x(w, a)`|use width `w` for content|
|
|
|`Fixed::y(w, a)`|use height `w` for content|
|
|
|`Fixed::xy(w, h, a)`|use width `w` and height `h` for content|
|
|
|**`Expand`/`Shrink`**|**change dimension of content:**|
|
|
|`Expand::x(n, a)`/`Shrink::x(n, a)`|increment/decrement width of content area by `n`|
|
|
|`Expand::y(n, a)`/`Shrink::y(n, a)`|increment/decrement height of content area by `m`|
|
|
|`Expand::xy(n, m, a)`/`Shrink::xy(n, m, a)`|increment/decrement width of content area by `n`, height by `m`|
|
|
|**`Min`/`Max`**|**constrain dimension of content:**|
|
|
|`Min::x(w, a)`/`Max::x(w, a)`|enforce minimum/maximum width `w` for content|
|
|
|`Min::y(h, a)`/`Max::y(h, a)`|enforce minimum/maximum height `h` for content|
|
|
|`Min::xy(w, h, a)`/`Max::xy(w, h, a)`|enforce minimum/maximum width `w` and height `h` for content|
|
|
|**`Push`/`Pull`**|**move content along axis:**|
|
|
|`Push::x(n, a)`/`Pull::x(n, a)`|increment/decrement `x` of content area|
|
|
|`Push::y(n, a)`/`Pull::y(n, a)`|increment/decrement `y` of content area|
|
|
|`Push::xy(n, m, a)`/`Pull::xy(n, m, a)`|increment/decrement `x` and `y` of content area|
|
|
|
|
**todo:**
|
|
* sensible `Margin`/`Padding`
|
|
* `Reduce`
|
|
|
|
## example rendering loop
|
|
|
|
the **render thread** continually invokes the
|
|
`Content::render` method of the application
|
|
to redraw the display. it does this efficiently
|
|
by using ratatui's double buffering.
|
|
|
|
thus, for a type to be a valid application for engine `E`,
|
|
it must implement the trait `Content<E>`, which allows
|
|
it to display content to the engine's output.
|
|
|
|
the most important thing about the `Content` trait is that
|
|
it composes:
|
|
* you can implement `Content::content` to build
|
|
`Content`s out of other `Content`s
|
|
* and/or `Content::area` for custom positioning and sizing,
|
|
* and/or `Content::render` for custom rendering
|
|
within the given `Content`'s area.
|
|
|
|
the manner of output is determined by the
|
|
`Engine::Output` type, a mutable pointer to which
|
|
is passed to the render method, e.g. in the case of
|
|
the `Tui` engine: `fn render(&self, output: &mut TuiOut)`
|
|
|
|
you can use `TuiOut::blit` and `TuiOut::place`
|
|
to draw at specified coordinates of the display, and/or
|
|
directly modify the underlying `ratatui::Buffer` at
|
|
`output.buffer`
|
|
|
|
rendering is intended to work with read-only access
|
|
to the application state. if you really need to update
|
|
values during rendering, use interior mutability.
|