Skip to main content

ttui/
lib.rs

1#![warn(missing_docs)]
2#![doc(html_root_url = "https://docs.rs/ttui/2.0.0")]
3
4//! `ttui` — a terminal UI framework built around layered buffers,
5//! `Transition`-driven animation, and dumb (no-internal-state) widgets.
6//!
7//! # Quick start
8//!
9//! An app is one type implementing [`App`](app::App). You own the state;
10//! `ttui` owns the loop, the diffing, and the terminal.
11//!
12//! ```no_run
13//! use crossterm::event::{Event, KeyCode};
14//! use ttui::app::{run, App};
15//! use ttui::buffer::LayerStack;
16//! use ttui::layout::Rect;
17//! use ttui::widgets::text::Text;
18//!
19//! struct Hello {
20//!     quit: bool,
21//! }
22//!
23//! impl App for Hello {
24//!     fn update(&mut self, event: &Event) {
25//!         if let Event::Key(key) = event {
26//!             if key.code == KeyCode::Char('q') {
27//!                 self.quit = true;
28//!             }
29//!         }
30//!     }
31//!
32//!     fn view(&self, area: Rect, buf: &mut LayerStack) {
33//!         Text::new("hello, terminal — press q to quit").render(area, buf);
34//!     }
35//!
36//!     fn should_quit(&self) -> bool {
37//!         self.quit
38//!     }
39//! }
40//!
41//! fn main() -> std::io::Result<()> {
42//!     run(&mut Hello { quit: false })
43//! }
44//! ```
45//!
46//! [`run`](app::run) enables raw mode, installs a panic hook that restores
47//! the terminal, and only redraws cells that actually changed.
48//!
49//! # How it fits together
50//!
51//! ```text
52//! App state ──view()──▶ LayerStack ──composite()──▶ Buffer ──diff()──▶ terminal
53//!     ▲                                                                    │
54//!     └──────────────── update(event) / on_tick(elapsed) ◀─────────────────┘
55//! ```
56//!
57//! - **[`buffer`]** — [`Cell`](buffer::Cell), [`Buffer`](buffer::Buffer) and
58//!   [`LayerStack`](buffer::LayerStack), the render target. Layers composite
59//!   top-to-bottom by alpha, so an effects layer can sit over a UI layer
60//!   without either knowing about the other.
61//! - **[`layout`]** — splits a [`Rect`](layout::Rect) by
62//!   [`Constraint`](layout::Constraint)s. No widget computes its own position.
63//! - **[`widgets`]** — stateless renderers. A widget is handed an area and a
64//!   buffer and draws; it never holds selection or scroll state, so your app
65//!   stays the single source of truth.
66//! - **[`transition`]** — [`Transition`](transition::Transition) tracks
67//!   real elapsed time as `0.0..=1.0` progress, and
68//!   [`Phases`](transition::Phases) subdivides that progress into named
69//!   stages without writing every boundary twice.
70//! - **[`theme`]** — one palette and border set threaded through widgets.
71//!
72//! Beyond the core: [`canvas`] (sub-cell half-block and braille drawing),
73//! [`perspective`] (fixed-forward 3D projection), [`particles`], [`glitch`],
74//! [`effects`], [`camera`], [`input`] (key chords), [`easing`], [`noise`] and
75//! [`audio`].
76//!
77//! # Animation
78//!
79//! Return a [`tick_rate`](app::App::tick_rate) and `ttui` calls
80//! [`on_tick`](app::App::on_tick) with the *real* elapsed time, so animation
81//! stays correct when a frame runs long:
82//!
83//! ```
84//! use std::time::Duration;
85//! use ttui::transition::{Phases, Transition};
86//!
87//! // Three stages across one 900ms transition: 20% fade in, 60% hold,
88//! // 20% fade out. Boundaries are written once, not twice.
89//! const STAGES: Phases<3> = Phases::new([0.2, 0.8, 1.0]);
90//!
91//! let t = Transition::start(Duration::from_millis(900));
92//! let (stage, progress_within) = STAGES.at(t.progress());
93//! assert!(stage < 3);
94//! assert!((0.0..=1.0).contains(&progress_within));
95//! ```
96//!
97//! # Examples
98//!
99//! The repository carries ten runnable example apps and a `showcase` demo
100//! reel. From a checkout:
101//!
102//! ```text
103//! cargo run --bin showcase        # mascot-hosted reel of five vignettes
104//! cargo run --example demo        # nested panes, Tab focus, list + table
105//! cargo run --example falcon      # cockpit: starfield, HUD, glitch effects
106//! ```
107//!
108//! See [`examples/README.md`] for what each one demonstrates.
109//!
110//! [`examples/README.md`]: https://github.com/tatemeyer/ttui/blob/main/examples/README.md
111
112/// Terminal event loop and the `App` trait apps implement.
113pub mod app;
114/// `AudioSink` trait for optional sound-effect playback.
115pub mod audio;
116/// Cell/`Buffer`/`LayerStack` — the framework's core render target.
117pub mod buffer;
118/// Deterministic camera viewport and brightness scaling.
119pub mod camera;
120/// Sub-cell rendering primitive (half-block + braille) — graduated,
121/// committed API; see the module docs for `HalfBlock` vs `Braille`
122/// details.
123pub mod canvas;
124/// Linear/eased interpolation and progress helpers.
125pub mod easing;
126/// Screen-shake and other whole-buffer visual effects.
127pub mod effects;
128/// Decaying noise overlay for glitch/corruption effects.
129pub mod glitch;
130/// Key-binding resolver: single keys and multi-key chords resolving
131/// to an app-defined action type.
132pub mod input;
133/// `Rect`/`Constraint`-based area splitting.
134pub mod layout;
135/// Deterministic seed-driven jitter for scattering and placement.
136pub mod noise;
137/// A simple particle system for bursts and impacts.
138pub mod particles;
139/// Fixed-forward pinhole-camera projection: points, lines, polygons.
140pub mod perspective;
141/// Raw-mode terminal setup/teardown.
142pub mod terminal;
143/// App color palette and border glyph set.
144pub mod theme;
145/// Time-driven progress tracking for animations, and the `Phases`
146/// subdivision of a progress range.
147pub mod transition;
148/// Ready-to-render widgets — see `widgets` module docs.
149pub mod widgets;