From 3e2b07158cb812fe864029e635f10c1e1ca84355 Mon Sep 17 00:00:00 2001 From: unspeaker Date: Sat, 23 Aug 2025 12:42:51 +0300 Subject: [PATCH] output: update README --- output/README.md | 87 ++++++-------------------------- output/src/{ops.rs => layout.rs} | 0 output/src/lib.rs | 2 +- output/src/output.rs | 7 +-- tengri/README.md | 11 +++- 5 files changed, 28 insertions(+), 79 deletions(-) rename output/src/{ops.rs => layout.rs} (100%) diff --git a/output/README.md b/output/README.md index dc19511..b827f46 100644 --- a/output/README.md +++ b/output/README.md @@ -1,75 +1,20 @@ -# `tengri_output` +***tengri_output*** is an abstract interface layout framework. -## free floating layout primitives +it expresses the following notions: -this crate exposes several layout operators -which work entirely in unsigned coordinates -and are generic over the trait `Content`. -most importantly, they are not dependent on rendering framework. +* [**space:**](./src/space.rs) `Direction`, `Coordinate`, `Area`, `Size`, `Measure` -|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| +* [**output:**](./src/output.rs) `Output`, `Render`, `Content` + * the layout operators are generic over `Render` and/or `Content` + * the traits `Render` and `Content` are generic over `Output` + * implement `Output` to bring a layout to a new backend: + [see `TuiOut` in `tengri_tui`](../tui/src/tui_engine/tui_output.rs) -**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`, 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. +* [**layout:**](./src/layout.rs) + * conditionals: `When`, `Either` + * iteration: `Map` + * concatenation: `Bsp` + * positioning: `Align`, `Push`, `Pull` + * sizing: `Fill`, `Fixed`, `Expand`, `Shrink`, `Min`, `Max` + * implement custom components (that may be backend-dependent): + [see `tui_content` in `tengri_tui`](../tui/src/tui_content) diff --git a/output/src/ops.rs b/output/src/layout.rs similarity index 100% rename from output/src/ops.rs rename to output/src/layout.rs diff --git a/output/src/lib.rs b/output/src/lib.rs index 334c418..8576d23 100644 --- a/output/src/lib.rs +++ b/output/src/lib.rs @@ -10,7 +10,7 @@ pub(crate) use tengri_core::*; #[cfg(feature = "dsl")] pub(crate) use ::tengri_dsl::*; mod space; pub use self::space::*; -mod ops; pub use self::ops::*; +mod layout; pub use self::layout::*; mod output; pub use self::output::*; #[cfg(test)] mod test; diff --git a/output/src/output.rs b/output/src/output.rs index 77a48b8..324d7a5 100644 --- a/output/src/output.rs +++ b/output/src/output.rs @@ -47,7 +47,7 @@ impl> Render for C { /// Opaque pointer to a renderable living on the heap. /// /// Return this from [Content::content] to use dynamic dispatch. -pub type RenderBox = Box>; +pub type RenderBox = Box>; /// You can render from a box. impl Content for RenderBox { @@ -55,11 +55,8 @@ impl Content for RenderBox { //fn boxed <'b> (self) -> RenderBox<'b, E> where Self: Sized + 'b { self } } -/// Opaque pointer to a renderable. -pub type RenderDyn = dyn Render; - /// You can render from an opaque pointer. -impl Content for &RenderDyn where Self: Sized { +impl Content for &dyn Render where Self: Sized { fn content (&self) -> impl Render + '_ { #[allow(suspicious_double_ref_op)] self.deref() diff --git a/tengri/README.md b/tengri/README.md index 4500aef..9c5e04d 100644 --- a/tengri/README.md +++ b/tengri/README.md @@ -1,3 +1,10 @@ -# tengri +***tengri*** is a metaframework for building interactive applications with rust. (aren't we all?) -an interface metaframework. currently supports ratatui. +tengri is developed as part of [***tek***](https://codeberg.org/unspeaker/tek), +a music program for terminals. + +tengri contains: +* [***dizzle***](./dsl), a framework for defining domain-specific languages. +* [***output***](./output), an abstract UI layout framework. +* [***input***](./input), an abstract UI event framework. +* [***tui***](./tui), an implementation of tengri over [***ratatui***](https://ratatui.rs/).