tengri/output

tengri_output

free floating layout primitives

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.

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 Contents out of other Contents
• 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.