tui_splitflap/lib.rs
1//! A [Ratatui] widget for retro split-flap display boards.
2//!
3//! Animated character tiles flip through an ordered character set,
4//! recreating the mechanical departure boards found at airports and train stations.
5//!
6//! # Quick start
7//!
8//! ```rust
9//! use tui_splitflap::{FlapBoardState, FlapMessage};
10//!
11//! let mut state = FlapBoardState::new(1, 20);
12//! state.set_message(&FlapMessage::single("HELLO WORLD"));
13//!
14//! // Advance by elapsed milliseconds each frame; returns true while animating.
15//! let still_animating = state.tick(16);
16//! ```
17//!
18//! Render by passing [`FlapBoard`] (a [`ratatui::widgets::StatefulWidget`]) and `&mut state`
19//! to `frame.render_stateful_widget` in your draw callback.
20//!
21//! # Animation styles
22//!
23//! Configured via [`FlapBoardState::with_flip_style`]:
24//!
25//! | Style | Description |
26//! |-------|-------------|
27//! | [`FlipStyle::Sequential`] | Cycles every intermediate character; duration scales with distance |
28//! | [`FlipStyle::Mechanical`] | Split-block animation; constant duration regardless of distance |
29//! | [`FlipStyle::Combined`] | Mechanical phase, then sequential roll to the target character |
30//!
31//! [Ratatui]: https://ratatui.rs
32
33mod cell;
34mod char_set;
35mod state;
36mod theme;
37
38// `pantry_ingredients!` macro expands to `tui_splitflap::widget::ingredient::ingredients()`,
39// requiring the module to be public when the feature is active.
40#[cfg(feature = "pantry")]
41pub mod widget;
42#[cfg(not(feature = "pantry"))]
43mod widget;
44
45pub use cell::{FlapCell, FlipPhase, FlipStyle};
46pub use char_set::{CharSet, CharSetError};
47pub use state::{FlapBoardState, FlapMessage};
48pub use theme::FlapTheme;
49pub use widget::{CellWidth, FlapBoard};
50
51/// Convenience alias for results that fail with [`CharSetError`].
52pub type Result<T> = std::result::Result<T, CharSetError>;