tabula rasa

output/README.md

@@ -0,0 +1,76 @@
+# `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.