zui_widgets/
lib.rs

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

zui_widgets/
lib.rs
