tui/
lib.rs

1//! [tui](https://github.com/fdehau/tui-rs) is a library used to build rich
2//! terminal users interfaces and dashboards.
3//!
4//! ![](https://raw.githubusercontent.com/fdehau/tui-rs/master/assets/demo.gif)
5//!
6//! # Get started
7//!
8//! ## Adding `tui` as a dependency
9//!
10//! ```toml
11//! [dependencies]
12//! tui = "0.19"
13//! crossterm = "0.25"
14//! ```
15//!
16//! The crate is using the `crossterm` backend by default that works on most platforms. But if for
17//! example you want to use the `termion` backend instead. This can be done by changing your
18//! dependencies specification to the following:
19//!
20//! ```toml
21//! [dependencies]
22//! termion = "1.5"
23//! tui = { version = "0.19", default-features = false, features = ['termion'] }
24//!
25//! ```
26//!
27//! The same logic applies for all other available backends.
28//!
29//! ## Creating a `Terminal`
30//!
31//! Every application using `tui` should start by instantiating a `Terminal`. It is a light
32//! abstraction over available backends that provides basic functionalities such as clearing the
33//! screen, hiding the cursor, etc.
34//!
35//! ```rust,no_run
36//! use std::io;
37//! use tui::{backend::CrosstermBackend, Terminal};
38//!
39//! fn main() -> Result<(), io::Error> {
40//!     let stdout = io::stdout();
41//!     let backend = CrosstermBackend::new(stdout);
42//!     let mut terminal = Terminal::new(backend)?;
43//!     Ok(())
44//! }
45//! ```
46//!
47//! If you had previously chosen `termion` as a backend, the terminal can be created in a similar
48//! way:
49//!
50//! ```rust,ignore
51//! use std::io;
52//! use tui::{backend::TermionBackend, Terminal};
53//! use termion::raw::IntoRawMode;
54//!
55//! fn main() -> Result<(), io::Error> {
56//!     let stdout = io::stdout().into_raw_mode()?;
57//!     let backend = TermionBackend::new(stdout);
58//!     let mut terminal = Terminal::new(backend)?;
59//!     Ok(())
60//! }
61//! ```
62//!
63//! You may also refer to the examples to find out how to create a `Terminal` for each available
64//! backend.
65//!
66//! ## Building a User Interface (UI)
67//!
68//! Every component of your interface will be implementing the `Widget` trait. The library comes
69//! with a predefined set of widgets that should meet most of your use cases. You are also free to
70//! implement your own.
71//!
72//! Each widget follows a builder pattern API providing a default configuration along with methods
73//! to customize them. The widget is then rendered using [`Frame::render_widget`] which takes
74//! your widget instance and an area to draw to.
75//!
76//! The following example renders a block of the size of the terminal:
77//!
78//! ```rust,no_run
79//! use std::{io, thread, time::Duration};
80//! use tui::{
81//!     backend::CrosstermBackend,
82//!     widgets::{Widget, Block, Borders},
83//!     layout::{Layout, Constraint, Direction},
84//!     Terminal
85//! };
86//! use crossterm::{
87//!     event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
88//!     execute,
89//!     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
90//! };
91//!
92//! fn main() -> Result<(), io::Error> {
93//!     // setup terminal
94//!     enable_raw_mode()?;
95//!     let mut stdout = io::stdout();
96//!     execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
97//!     let backend = CrosstermBackend::new(stdout);
98//!     let mut terminal = Terminal::new(backend)?;
99//!
100//!     terminal.draw(|f| {
101//!         let size = f.size();
102//!         let block = Block::default()
103//!             .title("Block")
104//!             .borders(Borders::ALL);
105//!         f.render_widget(block, size);
106//!     })?;
107//!
108//!     thread::sleep(Duration::from_millis(5000));
109//!
110//!     // restore terminal
111//!     disable_raw_mode()?;
112//!     execute!(
113//!         terminal.backend_mut(),
114//!         LeaveAlternateScreen,
115//!         DisableMouseCapture
116//!     )?;
117//!     terminal.show_cursor()?;
118//!
119//!     Ok(())
120//! }
121//! ```
122//!
123//! ## Layout
124//!
125//! The library comes with a basic yet useful layout management object called `Layout`. As you may
126//! see below and in the examples, the library makes heavy use of the builder pattern to provide
127//! full customization. And `Layout` is no exception:
128//!
129//! ```rust,no_run
130//! use tui::{
131//!     backend::Backend,
132//!     layout::{Constraint, Direction, Layout},
133//!     widgets::{Block, Borders},
134//!     Frame,
135//! };
136//! fn ui<B: Backend>(f: &mut Frame<B>) {
137//!    let chunks = Layout::default()
138//!         .direction(Direction::Vertical)
139//!         .margin(1)
140//!         .constraints(
141//!             [
142//!                 Constraint::Percentage(10),
143//!                 Constraint::Percentage(80),
144//!                 Constraint::Percentage(10)
145//!             ].as_ref()
146//!         )
147//!         .split(f.size());
148//!     let block = Block::default()
149//!          .title("Block")
150//!          .borders(Borders::ALL);
151//!     f.render_widget(block, chunks[0]);
152//!     let block = Block::default()
153//!          .title("Block 2")
154//!          .borders(Borders::ALL);
155//!     f.render_widget(block, chunks[1]);
156//! }
157//! ```
158//!
159//! This let you describe responsive terminal UI by nesting layouts. You should note that by
160//! default the computed layout tries to fill the available space completely. So if for any reason
161//! you might need a blank space somewhere, try to pass an additional constraint and don't use the
162//! corresponding area.
163
164pub mod backend;
165pub mod buffer;
166pub mod layout;
167pub mod style;
168pub mod symbols;
169pub mod terminal;
170pub mod text;
171pub mod widgets;
172
173pub use self::terminal::{Frame, Terminal, TerminalOptions, Viewport};
tui/lib.rs

tui/
lib.rs
