mirror of
https://github.com/ratatui-org/ratatui
synced 2024-11-26 22:50:47 +00:00
[doc] Move "Get started" from README to src/lib.rs
This commit is contained in:
Florian Dehau
parent
5dd03d91ad
commit
8907ab90a1
2 changed files with 156 additions and 87 deletions
88
README.md
88
README.md
|
|
@ -30,93 +30,7 @@ comes from the terminal emulator than the library itself.
|
|||
Moreover, the library does not provide any input handling nor any event system and
|
||||
you may rely on the previously cited libraries to achieve such features.
|
||||
|
||||
## Get Started
|
||||
|
||||
### Create the terminal interface
|
||||
|
||||
Every application using `tui` should start by instantiating a `Terminal`. It is
|
||||
a light abstraction over available backends that provides basic functionalities
|
||||
such as clearing the screen, hiding the cursor, etc. By default only the `termion`
|
||||
backend is available.
|
||||
|
||||
```rust
|
||||
use tui::Terminal;
|
||||
use tui::backend::TermionBackend;
|
||||
|
||||
fn main() {
|
||||
let backend = TermionBackend::new().unwrap();
|
||||
let mut terminal = Terminal::new(backend);
|
||||
}
|
||||
```
|
||||
|
||||
If for some reason, you might want to use the `rustbox` backend instead, you
|
||||
need the to replace your `tui` dependency specification by:
|
||||
|
||||
```toml
|
||||
[dependencies.tui]
|
||||
version = "0.1.3"
|
||||
default-features = false
|
||||
features = ['rustbox']
|
||||
```
|
||||
|
||||
and then create the terminal in a similar way:
|
||||
|
||||
```rust
|
||||
use tui::Terminal;
|
||||
use tui::backend::RustboxBackend;
|
||||
|
||||
fn main() {
|
||||
let backend = RustboxBackend::new().unwrap();
|
||||
let mut terminal = Terminal::new(backend);
|
||||
}
|
||||
```
|
||||
|
||||
### Layout
|
||||
|
||||
The library comes with a basic yet useful layout management object called
|
||||
`Group`. As you may see below and in the examples, the library makes heavy use
|
||||
of the builder pattern to provide full customization. And the `Group` object is
|
||||
no exception:
|
||||
|
||||
```rust
|
||||
use tui::widgets::{Block, border};
|
||||
use tui::layout::{Group, Rect, Direction};
|
||||
|
||||
fn draw(t: &mut Terminal<TermionBackend>) {
|
||||
|
||||
let size = t.size().unwrap();
|
||||
|
||||
Group::default()
|
||||
/// You first choose a main direction for the group
|
||||
.direction(Direction::Vertical)
|
||||
/// An optional margin
|
||||
.margin(1)
|
||||
/// The preferred sizes (heights in this case)
|
||||
.sizes(&[Size::Fixed(10), Size::Max(20), Size::Min(10)])
|
||||
/// The computed (or cached) layout is then available as the second argument
|
||||
/// of the closure
|
||||
.render(t, &size, |t, chunks| {
|
||||
/// Continue to describe your UI there.
|
||||
Block::default()
|
||||
.title("Block")
|
||||
.borders(border::ALL)
|
||||
.render(t, &chunks[0]);
|
||||
})
|
||||
```
|
||||
|
||||
This let you describe responsive terminal UI by nesting groups. You should note
|
||||
that by default the computed layout tries to fill the available space
|
||||
completely. So if for any reason you might need a blank space somewhere, try to
|
||||
pass an additional size to the group and don't use the corresponding area inside
|
||||
the render method.
|
||||
|
||||
Once you have finished to describe the UI, you just need to call:
|
||||
|
||||
```rust
|
||||
t.draw().unwrap()
|
||||
```
|
||||
|
||||
to actually draw to the terminal.
|
||||
### [Documentation](https://docs.rs/tui)
|
||||
|
||||
### Widgets
|
||||
|
||||
|
|
|
|||
155
src/lib.rs
155
src/lib.rs
|
|
@ -1,3 +1,158 @@
|
|||
//! [tui](https://github.com/fdehau/tui-rs) is a library used to build rich
|
||||
//! terminal users interfaces and dashboards.
|
||||
//!
|
||||
//! 
|
||||
//!
|
||||
//! # Get started
|
||||
//!
|
||||
//! ## Creating a `Terminal`
|
||||
//!
|
||||
//! Every application using `tui` should start by instantiating a `Terminal`. It is
|
||||
//! a light abstraction over available backends that provides basic functionalities
|
||||
//! such as clearing the screen, hiding the cursor, etc. By default only the `termion`
|
||||
//! backend is available.
|
||||
//!
|
||||
//! ```rust,no_run
|
||||
//! extern crate tui;
|
||||
//!
|
||||
//! use tui::Terminal;
|
||||
//! use tui::backend::RawBackend;
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let backend = RawBackend::new().unwrap();
|
||||
//! let mut terminal = Terminal::new(backend).unwrap();
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! If for some reason, you might want to use the `rustbox` backend instead, you
|
||||
//! need the to replace your `tui` dependency specification by:
|
||||
//!
|
||||
//! ```toml
|
||||
//! [dependencies.tui]
|
||||
//! version = "0.1.3"
|
||||
//! default-features = false
|
||||
//! features = ['rustbox']
|
||||
//! ```
|
||||
//!
|
||||
//! and then create the terminal in a similar way:
|
||||
//!
|
||||
//! ```rust,ignore
|
||||
//! extern crate tui;
|
||||
//!
|
||||
//! use tui::Terminal;
|
||||
//! use tui::backend::RustboxBackend;
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let backend = RustboxBackend::new().unwrap();
|
||||
//! let mut terminal = Terminal::new(backend).unwrap();
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Building a User Interface (UI)
|
||||
//!
|
||||
//! Every component of your interface will be implementing the `Widget` trait.
|
||||
//! The library comes with a predefined set of widgets that should met most of
|
||||
//! your use cases. You are also free to implement your owns.
|
||||
//!
|
||||
//! Each widget follows a builder pattern API providing a default configuration
|
||||
//! along with methods to customize them. The widget is then registered using
|
||||
//! its `render` method that take a `Terminal` instance and an area to draw
|
||||
//! to.
|
||||
//!
|
||||
//! The following example renders a block of the size of the terminal:
|
||||
//!
|
||||
//! ```rust,no_run
|
||||
//! extern crate tui;
|
||||
//!
|
||||
//! use std::io;
|
||||
//!
|
||||
//! use tui::Terminal;
|
||||
//! use tui::backend::RawBackend;
|
||||
//! use tui::widgets::{Widget, Block, border};
|
||||
//! use tui::layout::{Group, Size, Direction};
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut terminal = init().expect("Failed initialization");
|
||||
//! draw(&mut terminal).expect("Failed to draw");
|
||||
//! }
|
||||
//!
|
||||
//! fn init() -> Result<Terminal<RawBackend>, io::Error> {
|
||||
//! let backend = RawBackend::new()?;
|
||||
//! Terminal::new(backend)
|
||||
//! }
|
||||
//!
|
||||
//! fn draw(t: &mut Terminal<RawBackend>) -> Result<(), io::Error> {
|
||||
//!
|
||||
//! let size = t.size()?;
|
||||
//!
|
||||
//! Block::default()
|
||||
//! .title("Block")
|
||||
//! .borders(border::ALL)
|
||||
//! .render(t, &size);
|
||||
//!
|
||||
//! t.draw()
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Layout
|
||||
//!
|
||||
//! The library comes with a basic yet useful layout management object called
|
||||
//! `Group`. As you may see below and in the examples, the library makes heavy
|
||||
//! use of the builder pattern to provide full customization. And the `Group`
|
||||
//! object is no exception:
|
||||
//!
|
||||
//! ```rust,no_run
|
||||
//! extern crate tui;
|
||||
//!
|
||||
//! use std::io;
|
||||
//!
|
||||
//! use tui::Terminal;
|
||||
//! use tui::backend::RawBackend;
|
||||
//! use tui::widgets::{Widget, Block, border};
|
||||
//! use tui::layout::{Group, Size, Direction};
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut terminal = init().expect("Failed initialization");
|
||||
//! draw(&mut terminal).expect("Failed to draw");
|
||||
//! }
|
||||
//!
|
||||
//! fn init() -> Result<Terminal<RawBackend>, io::Error> {
|
||||
//! let backend = RawBackend::new()?;
|
||||
//! Terminal::new(backend)
|
||||
//! }
|
||||
//!
|
||||
//! fn draw(t: &mut Terminal<RawBackend>) -> Result<(), io::Error> {
|
||||
//!
|
||||
//! let size = t.size()?;
|
||||
//!
|
||||
//! Group::default()
|
||||
//! .direction(Direction::Vertical)
|
||||
//! .margin(1)
|
||||
//! .sizes(&[Size::Fixed(10), Size::Max(20), Size::Min(10)])
|
||||
//! .render(t, &size, |t, chunks| {
|
||||
//! Block::default()
|
||||
//! .title("Block")
|
||||
//! .borders(border::ALL)
|
||||
//! .render(t, &chunks[0]);
|
||||
//! Block::default()
|
||||
//! .title("Block 2")
|
||||
//! .borders(border::ALL)
|
||||
//! .render(t, &chunks[2]);
|
||||
//! });
|
||||
//!
|
||||
//! t.draw()
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! This let you describe responsive terminal UI by nesting groups. You should note
|
||||
//! that by default the computed layout tries to fill the available space
|
||||
//! completely. So if for any reason you might need a blank space somewhere, try to
|
||||
//! pass an additional size to the group and don't use the corresponding area inside
|
||||
//! the render method.
|
||||
//!
|
||||
//! Once you have finished to describe the UI, you just need to call `draw`
|
||||
//! on `Terminal` to actually flush to the terminal.
|
||||
|
||||
#[macro_use]
|
||||
extern crate bitflags;
|
||||
extern crate cassowary;
|
||||
|
|
|
|||
Loading…
Reference in a new issue