From 8907ab90a1e2999fd486c0b913692a11a921902d Mon Sep 17 00:00:00 2001 From: Florian Dehau Date: Tue, 26 Dec 2017 12:03:25 +0100 Subject: [PATCH] [doc] Move "Get started" from README to src/lib.rs --- README.md | 88 +----------------------------- src/lib.rs | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index e81c543..5933965 100644 --- a/README.md +++ b/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) { - - 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 diff --git a/src/lib.rs b/src/lib.rs index ea3c818..21ac1b5 100644 --- a/src/lib.rs +++ b/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. +//! +//! ![](https://raw.githubusercontent.com/fdehau/tui-rs/master/docs/demo.gif) +//! +//! # 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, io::Error> { +//! let backend = RawBackend::new()?; +//! Terminal::new(backend) +//! } +//! +//! fn draw(t: &mut Terminal) -> 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, io::Error> { +//! let backend = RawBackend::new()?; +//! Terminal::new(backend) +//! } +//! +//! fn draw(t: &mut Terminal) -> 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;