altui_core/lib.rs
1//! [altui-cure](https://altlinux.space/writers/altui/src/branch/devel/altui-core) is a library used to build rich
2//! terminal users interfaces and dashboards.
3//!
4//! 
5//!
6//! # Get started
7//!
8//! ## Adding `altui-core` as a dependency
9//!
10//! Add `altui-core` to your `Cargo.toml`:
11//!
12//! ```toml
13//! [dependencies]
14//! altui_core = "0.1"
15//! crossterm = "0.29"
16//! ```
17//!
18//! By default, `altui-core` uses the **Crossterm backend**, which works on most
19//! platforms (Linux, macOS, Windows) and requires no additional configuration.
20//!
21//! ### Using a different backend
22//!
23//! If you want to use another backend (for example, `termion`), disable default
24//! features and enable the corresponding backend feature:
25//!
26//! ```toml
27//! [dependencies]
28//! termion = "4"
29//! altui_core = { version = "0.1", default-features = false, features = ["termion"] }
30//! ```
31//!
32//! The same approach applies to all other available backends.
33//!
34//! ---
35//!
36//! ## Creating a terminal (recommended way)
37//!
38//! The easiest and safest way to initialize a terminal is via [`AltuiInit`].
39//! It takes care of:
40//!
41//! - enabling raw mode
42//! - entering the alternate screen
43//! - optional mouse support
44//! - restoring the terminal on panic
45//!
46//! ```rust,ignore
47//! use std::io;
48//! use altui_core::AltuiInit;
49//!
50//! fn main() -> io::Result<()> {
51//! let mut ui = AltuiInit::new(true)? // enable mouse support
52//! .set_panic_hook(); // restore terminal on panic
53//!
54//! ui.run(|terminal| {
55//! terminal.draw(|f| {
56//! let size = f.size();
57//! // draw UI here
58//! }).expect("Fail to draw to the terminal");
59//! Ok(())
60//! })
61//! }
62//! ```
63//!
64//! ### Mouse support
65//!
66//! Mouse input is optional and can be disabled:
67//!
68//! ```rust,no-run
69//! use altui_core::AltuiInit;
70//!
71//! let mut ui = AltuiInit::new(false);
72//! ```
73//!
74//! ---
75//!
76//! ## Manual terminal initialization (advanced)
77//!
78//! If you need full control over terminal initialization, you may construct
79//! a [`Terminal`] and backend manually.
80//!
81//! ```rust
82//! use std::io;
83//! use altui_core::{backend::CrosstermBackend, Terminal};
84//!
85//! fn main() -> io::Result<()> {
86//! let stdout = io::stdout();
87//! let backend = CrosstermBackend::new(stdout);
88//! let mut terminal = Terminal::new(backend)?;
89//! Ok(())
90//! }
91//! ```
92//!
93//! ⚠️ When using this approach, you are responsible for:
94//!
95//! - enabling and disabling raw mode
96//! - entering and leaving the alternate screen
97//! - restoring cursor visibility on exit or panic
98//!
99//! ### See also
100//!
101//! - [`AltuiInit`]
102//! - [`Terminal`]
103//! - [`backend::Backend`]
104//!
105//! ---
106//!
107//! ## Building a User Interface (UI)
108//!
109//! User interfaces in `altui-core` are composed of widgets implementing the
110//! [`Widget`] trait.
111//!
112//! Widgets use a builder-style API and are rendered via
113//! [`Frame::render_widget`].
114//!
115//! ```rust,ignore
116//! use altui_core::{
117//! widgets::{Block, Borders},
118//! };
119//!
120//! terminal.draw(|f| {
121//! let size = f.size();
122//! let mut block = Block::default()
123//! .title("Block")
124//! .borders(Borders::ALL);
125//! f.render_widget(&mut block, size);
126//! })?;
127//! ```
128//!
129//! ---
130//!
131//! ## Layout
132//!
133//! Layout management is handled by [`Layout`], which allows building responsive
134//! terminal UIs by splitting available space into regions.
135//!
136//! The example below creates a **centered block** that occupies **80% of the
137//! terminal width and 80% of the terminal height**. The remaining space is
138//! evenly distributed around the block, keeping it centered both vertically
139//! and horizontally.
140//!
141//! This pattern is useful for dialogs, popups, and other UI elements that should
142//! stay visually centered regardless of terminal size.
143//!
144//! ```rust
145//! use altui_core::{
146//! layout::{Constraint, Layout, Flex},
147//! widgets::{Block, Borders},
148//! };
149//!
150//! fn ui<B: altui_core::backend::Backend>(f: &mut altui_core::Frame<B>) {
151//! let chunks = Layout::vertical([Constraint::Percentage(80)])
152//! .flex(Flex::Center)
153//! .cross_size(Constraint::Percentage(80))
154//! .cross_flex(Flex::Center)
155//! .margin(1)
156//! .split(f.size());
157//!
158//! let mut block = Block::default()
159//! .title("Header")
160//! .borders(Borders::ALL);
161//! f.render_widget(&mut block, chunks[0]);
162//! }
163//! ```
164//!
165//! Layouts can be nested to create complex, adaptive terminal interfaces.
166//! Unused layout regions may be left empty to create spacing.
167
168pub mod backend;
169pub mod buffer;
170#[cfg(feature = "crossterm")]
171mod init;
172pub mod layout;
173pub mod style;
174pub mod symbols;
175pub mod terminal;
176pub mod text;
177pub mod widgets;
178
179#[cfg(feature = "crossterm")]
180pub use self::init::AltuiInit;
181pub use self::terminal::{Frame, Terminal, TerminalOptions, Viewport};