mirror of
https://codeberg.org/unspeaker/tek.git
synced 2025-12-06 11:46:41 +01:00
65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
# `tek_engine`
|
|
|
|
this crate provides the `Engine` trait,
|
|
which defines an application's lifecycle.
|
|
|
|
currently, there is one kind of engine implemented, `Tui`.
|
|
it uses `ratatui` to present an interactive user interface
|
|
in text mode.
|
|
|
|
at launch, the `Tui` engine spawns two threads,
|
|
a **render thread** and an **input thread**. (the
|
|
application may spawn further threads, such as a
|
|
**jack thread**.)
|
|
|
|
all threads communicate using shared ownership,
|
|
`Arc<RwLock>` and `Arc<Atomic>`. the engine and
|
|
application instances are expected to be wrapped
|
|
in `Arc<RwLock>`; internally, those synchronization
|
|
mechanisms may be used liberally.
|
|
|
|
## rendering
|
|
|
|
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 TuiOutput)`
|
|
|
|
you can use `TuiOutput::blit` and `TuiOutput::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.
|
|
|
|
## input handling
|
|
|
|
the **input thread** polls for keyboard events
|
|
and passes them onto the application's `Handle::handle` method.
|
|
|
|
thus, for a type to be a valid application for engine `E`,
|
|
it must implement the trait `Handle<E>`, which allows it
|
|
to respond to user input.
|
|
|
|
this thread has write access to the application state,
|
|
and is responsible for mutating it in response to
|
|
user activity.
|