mirror of
https://github.com/ratatui-org/ratatui
synced 2024-11-23 05:03:13 +00:00
More documentation
This commit is contained in:
parent
fcac19d6c5
commit
652ff12380
12 changed files with 167 additions and 26 deletions
|
@ -8,16 +8,48 @@ use layout::Rect;
|
||||||
use style::Color;
|
use style::Color;
|
||||||
use symbols::bar;
|
use symbols::bar;
|
||||||
|
|
||||||
|
/// Display multiple bars in a single widgets
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// # extern crate tui;
|
||||||
|
/// # use tui::widgets::{Block, border, BarChart};
|
||||||
|
/// # use tui::style::Color;
|
||||||
|
/// # fn main() {
|
||||||
|
/// BarChart::default()
|
||||||
|
/// .block(Block::default().title("BarChart").borders(border::ALL))
|
||||||
|
/// .bar_width(3)
|
||||||
|
/// .bar_gap(1)
|
||||||
|
/// .bar_color(Color::Yellow)
|
||||||
|
/// .value_color(Color::Red)
|
||||||
|
/// .label_color(Color::White)
|
||||||
|
/// .background_color(Color::Black)
|
||||||
|
/// .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)])
|
||||||
|
/// .max(4);
|
||||||
|
/// # }
|
||||||
|
/// ```
|
||||||
pub struct BarChart<'a> {
|
pub struct BarChart<'a> {
|
||||||
|
/// Block to wrap the widget in
|
||||||
block: Option<Block<'a>>,
|
block: Option<Block<'a>>,
|
||||||
max: Option<u64>,
|
/// The width of each bar
|
||||||
bar_width: u16,
|
bar_width: u16,
|
||||||
|
/// The gap between each bar
|
||||||
bar_gap: u16,
|
bar_gap: u16,
|
||||||
|
/// Color of the bars
|
||||||
bar_color: Color,
|
bar_color: Color,
|
||||||
|
/// Color of the values printed at the bottom of each bar
|
||||||
value_color: Color,
|
value_color: Color,
|
||||||
|
/// Color of the labels printed under each bar
|
||||||
label_color: Color,
|
label_color: Color,
|
||||||
|
/// Background color for the widget
|
||||||
background_color: Color,
|
background_color: Color,
|
||||||
|
/// Slice of (label, value) pair to plot on the chart
|
||||||
data: &'a [(&'a str, u64)],
|
data: &'a [(&'a str, u64)],
|
||||||
|
/// Value necessary for a bar to reach the maximum height (if no value is specified,
|
||||||
|
/// the maximum value in the data is taken as reference)
|
||||||
|
max: Option<u64>,
|
||||||
|
/// Values to display on the bar (computed when the data is passed to the widget)
|
||||||
values: Vec<String>,
|
values: Vec<String>,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,7 @@
|
||||||
use super::Shape;
|
use super::Shape;
|
||||||
use style::Color;
|
use style::Color;
|
||||||
|
|
||||||
|
/// Shape to draw a line from (x1, y1) to (x2, y2) with the given color
|
||||||
pub struct Line {
|
pub struct Line {
|
||||||
pub x1: f64,
|
pub x1: f64,
|
||||||
pub y1: f64,
|
pub y1: f64,
|
||||||
|
|
|
@ -18,6 +18,7 @@ impl MapResolution {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Shape to draw a world map with the given resolution and color
|
||||||
pub struct Map {
|
pub struct Map {
|
||||||
pub resolution: MapResolution,
|
pub resolution: MapResolution,
|
||||||
pub color: Color,
|
pub color: Color,
|
||||||
|
|
|
@ -68,11 +68,12 @@ impl Grid {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Holds the state of the Canvas when painting to it.
|
||||||
pub struct Context<'a> {
|
pub struct Context<'a> {
|
||||||
x_bounds: [f64; 2],
|
|
||||||
y_bounds: [f64; 2],
|
|
||||||
width: u16,
|
width: u16,
|
||||||
height: u16,
|
height: u16,
|
||||||
|
x_bounds: [f64; 2],
|
||||||
|
y_bounds: [f64; 2],
|
||||||
grid: Grid,
|
grid: Grid,
|
||||||
dirty: bool,
|
dirty: bool,
|
||||||
layers: Vec<Layer>,
|
layers: Vec<Layer>,
|
||||||
|
@ -80,7 +81,10 @@ pub struct Context<'a> {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl<'a> Context<'a> {
|
impl<'a> Context<'a> {
|
||||||
pub fn draw<'b>(&mut self, shape: &'b Shape<'b>) {
|
/// Draw any object that may implement the Shape trait
|
||||||
|
pub fn draw<'b, S>(&mut self, shape: &'b S)
|
||||||
|
where S: Shape<'b>
|
||||||
|
{
|
||||||
self.dirty = true;
|
self.dirty = true;
|
||||||
let left = self.x_bounds[0];
|
let left = self.x_bounds[0];
|
||||||
let right = self.x_bounds[1];
|
let right = self.x_bounds[1];
|
||||||
|
@ -96,12 +100,14 @@ impl<'a> Context<'a> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Go one layer above in the canvas.
|
||||||
pub fn layer(&mut self) {
|
pub fn layer(&mut self) {
|
||||||
self.layers.push(self.grid.save());
|
self.layers.push(self.grid.save());
|
||||||
self.grid.reset();
|
self.grid.reset();
|
||||||
self.dirty = false;
|
self.dirty = false;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Print a string on the canvas at the given position
|
||||||
pub fn print(&mut self, x: f64, y: f64, text: &'a str, color: Color) {
|
pub fn print(&mut self, x: f64, y: f64, text: &'a str, color: Color) {
|
||||||
self.labels.push(Label {
|
self.labels.push(Label {
|
||||||
x: x,
|
x: x,
|
||||||
|
@ -111,6 +117,7 @@ impl<'a> Context<'a> {
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Push the last layer if necessary
|
||||||
fn finish(&mut self) {
|
fn finish(&mut self) {
|
||||||
if self.dirty {
|
if self.dirty {
|
||||||
self.layer()
|
self.layer()
|
||||||
|
@ -118,7 +125,8 @@ impl<'a> Context<'a> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
///
|
/// The Canvas widget may be used to draw more detailed figures using braille patterns (each
|
||||||
|
/// cell can have a braille character in 8 different positions).
|
||||||
/// # Examples
|
/// # Examples
|
||||||
///
|
///
|
||||||
/// ```
|
/// ```
|
||||||
|
@ -194,6 +202,7 @@ impl<'a, F> Canvas<'a, F>
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Store the closure that will be used to draw to the Canvas
|
||||||
pub fn paint(&mut self, f: F) -> &mut Canvas<'a, F> {
|
pub fn paint(&mut self, f: F) -> &mut Canvas<'a, F> {
|
||||||
self.painter = Some(f);
|
self.painter = Some(f);
|
||||||
self
|
self
|
||||||
|
@ -221,6 +230,8 @@ impl<'a, F> Widget for Canvas<'a, F>
|
||||||
let height = canvas_area.height as usize;
|
let height = canvas_area.height as usize;
|
||||||
|
|
||||||
if let Some(ref painter) = self.painter {
|
if let Some(ref painter) = self.painter {
|
||||||
|
|
||||||
|
// Create a blank context that match the size of the terminal
|
||||||
let mut ctx = Context {
|
let mut ctx = Context {
|
||||||
x_bounds: self.x_bounds,
|
x_bounds: self.x_bounds,
|
||||||
y_bounds: self.y_bounds,
|
y_bounds: self.y_bounds,
|
||||||
|
@ -231,9 +242,11 @@ impl<'a, F> Widget for Canvas<'a, F>
|
||||||
layers: Vec::new(),
|
layers: Vec::new(),
|
||||||
labels: Vec::new(),
|
labels: Vec::new(),
|
||||||
};
|
};
|
||||||
|
// Paint to this context
|
||||||
painter(&mut ctx);
|
painter(&mut ctx);
|
||||||
ctx.finish();
|
ctx.finish();
|
||||||
|
|
||||||
|
// Retreive painted points for each layer
|
||||||
for layer in ctx.layers {
|
for layer in ctx.layers {
|
||||||
for (i, (ch, color)) in layer.string
|
for (i, (ch, color)) in layer.string
|
||||||
.chars()
|
.chars()
|
||||||
|
@ -252,6 +265,8 @@ impl<'a, F> Widget for Canvas<'a, F>
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Finally draw the labels
|
||||||
for label in ctx.labels.iter().filter(|l| {
|
for label in ctx.labels.iter().filter(|l| {
|
||||||
!(l.x < self.x_bounds[0] || l.x > self.x_bounds[1] || l.y < self.y_bounds[0] ||
|
!(l.x < self.x_bounds[0] || l.x > self.x_bounds[1] || l.y < self.y_bounds[0] ||
|
||||||
l.y > self.y_bounds[1])
|
l.y > self.y_bounds[1])
|
||||||
|
|
|
@ -3,6 +3,7 @@ use std::slice;
|
||||||
use super::Shape;
|
use super::Shape;
|
||||||
use style::Color;
|
use style::Color;
|
||||||
|
|
||||||
|
/// A shape to draw a group of points with the given color
|
||||||
pub struct Points<'a> {
|
pub struct Points<'a> {
|
||||||
pub coords: &'a [(f64, f64)],
|
pub coords: &'a [(f64, f64)],
|
||||||
pub color: Color,
|
pub color: Color,
|
||||||
|
|
|
@ -72,7 +72,9 @@ impl<'a> Axis<'a> {
|
||||||
|
|
||||||
/// Marker to use when plotting data points
|
/// Marker to use when plotting data points
|
||||||
pub enum Marker {
|
pub enum Marker {
|
||||||
|
/// One point per cell
|
||||||
Dot,
|
Dot,
|
||||||
|
/// Up to 8 points per cell
|
||||||
Braille,
|
Braille,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -151,6 +153,37 @@ impl Default for ChartLayout {
|
||||||
}
|
}
|
||||||
|
|
||||||
/// A widget to plot one or more dataset in a cartesian coordinate system
|
/// A widget to plot one or more dataset in a cartesian coordinate system
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// # extern crate tui;
|
||||||
|
/// # use tui::widgets::{Block, border, Chart, Axis, Dataset, Marker};
|
||||||
|
/// # use tui::style::Color;
|
||||||
|
/// # fn main() {
|
||||||
|
/// Chart::default()
|
||||||
|
/// .block(Block::default().title("Chart"))
|
||||||
|
/// .x_axis(Axis::default()
|
||||||
|
/// .title("X Axis")
|
||||||
|
/// .color(Color::Gray)
|
||||||
|
/// .bounds([0.0, 10.0])
|
||||||
|
/// .labels(&["0.0", "5.0", "10.0"]))
|
||||||
|
/// .y_axis(Axis::default()
|
||||||
|
/// .title("Y Axis")
|
||||||
|
/// .color(Color::Gray)
|
||||||
|
/// .bounds([0.0, 10.0])
|
||||||
|
/// .labels(&["0.0", "5.0", "10.0"]))
|
||||||
|
/// .datasets(&[Dataset::default()
|
||||||
|
/// .name("data1")
|
||||||
|
/// .marker(Marker::Dot)
|
||||||
|
/// .color(Color::Cyan)
|
||||||
|
/// .data(&[(0.0, 5.0), (1.0, 6.0), (1.5, 6.434)]),
|
||||||
|
/// Dataset::default()
|
||||||
|
/// .name("data2")
|
||||||
|
/// .marker(Marker::Braille)
|
||||||
|
/// .color(Color::Magenta)
|
||||||
|
/// .data(&[(4.0, 5.0), (5.0, 8.0), (7.66, 13.5)])]);
|
||||||
|
/// # }
|
||||||
pub struct Chart<'a> {
|
pub struct Chart<'a> {
|
||||||
/// A block to display around the widget eventually
|
/// A block to display around the widget eventually
|
||||||
block: Option<Block<'a>>,
|
block: Option<Block<'a>>,
|
||||||
|
|
|
@ -13,13 +13,12 @@ use layout::Rect;
|
||||||
/// # extern crate tui;
|
/// # extern crate tui;
|
||||||
/// # use tui::widgets::{Widget, Gauge, Block, border};
|
/// # use tui::widgets::{Widget, Gauge, Block, border};
|
||||||
/// # use tui::style::Color;
|
/// # use tui::style::Color;
|
||||||
///
|
|
||||||
/// # fn main() {
|
/// # fn main() {
|
||||||
/// Gauge::default()
|
/// Gauge::default()
|
||||||
/// .block(Block::default().borders(border::ALL).title("Progress"))
|
/// .block(Block::default().borders(border::ALL).title("Progress"))
|
||||||
/// .color(Color::White)
|
/// .color(Color::White)
|
||||||
/// .background_color(Color::Black)
|
/// .background_color(Color::Black)
|
||||||
/// .percent(20);
|
/// .percent(20);
|
||||||
/// # }
|
/// # }
|
||||||
/// ```
|
/// ```
|
||||||
pub struct Gauge<'a> {
|
pub struct Gauge<'a> {
|
||||||
|
|
|
@ -16,13 +16,13 @@ use style::Color;
|
||||||
/// # use tui::widgets::{Block, border, List};
|
/// # use tui::widgets::{Block, border, List};
|
||||||
/// # use tui::style::Color;
|
/// # use tui::style::Color;
|
||||||
/// # fn main() {
|
/// # fn main() {
|
||||||
/// List::default()
|
/// List::default()
|
||||||
/// .block(Block::default().title("List").borders(border::ALL))
|
/// .block(Block::default().title("List").borders(border::ALL))
|
||||||
/// .items(&["Item 1", "Item 2", "Item 3"])
|
/// .items(&["Item 1", "Item 2", "Item 3"])
|
||||||
/// .select(1)
|
/// .select(1)
|
||||||
/// .color(Color::White)
|
/// .color(Color::White)
|
||||||
/// .highlight_color(Color::Yellow)
|
/// .highlight_color(Color::Yellow)
|
||||||
/// .highlight_symbol(">>");
|
/// .highlight_symbol(">>");
|
||||||
/// # }
|
/// # }
|
||||||
/// ```
|
/// ```
|
||||||
pub struct List<'a> {
|
pub struct List<'a> {
|
||||||
|
|
|
@ -28,11 +28,17 @@ use style::Color;
|
||||||
pub mod border {
|
pub mod border {
|
||||||
bitflags! {
|
bitflags! {
|
||||||
pub flags Flags: u32 {
|
pub flags Flags: u32 {
|
||||||
|
/// Show no border (default)
|
||||||
const NONE = 0b00000001,
|
const NONE = 0b00000001,
|
||||||
|
/// Show the top border
|
||||||
const TOP = 0b00000010,
|
const TOP = 0b00000010,
|
||||||
|
/// Show the right border
|
||||||
const RIGHT = 0b00000100,
|
const RIGHT = 0b00000100,
|
||||||
|
/// Show the bottom border
|
||||||
const BOTTOM = 0b0001000,
|
const BOTTOM = 0b0001000,
|
||||||
|
/// Show the left border
|
||||||
const LEFT = 0b00010000,
|
const LEFT = 0b00010000,
|
||||||
|
/// Show all borders
|
||||||
const ALL = TOP.bits | RIGHT.bits | BOTTOM.bits | LEFT.bits,
|
const ALL = TOP.bits | RIGHT.bits | BOTTOM.bits | LEFT.bits,
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
@ -6,11 +6,34 @@ use widgets::{Widget, Block};
|
||||||
use style::Color;
|
use style::Color;
|
||||||
use symbols::bar;
|
use symbols::bar;
|
||||||
|
|
||||||
|
/// Widget to render a sparkline over one or more lines.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// # extern crate tui;
|
||||||
|
/// # use tui::widgets::{Block, border, Sparkline};
|
||||||
|
/// # use tui::style::Color;
|
||||||
|
/// # fn main() {
|
||||||
|
/// Sparkline::default()
|
||||||
|
/// .block(Block::default().title("Sparkline").borders(border::ALL))
|
||||||
|
/// .data(&[0, 2, 3, 4, 1, 4, 10])
|
||||||
|
/// .max(5)
|
||||||
|
/// .color(Color::Yellow)
|
||||||
|
/// .background_color(Color::Red);
|
||||||
|
/// # }
|
||||||
|
/// ```
|
||||||
pub struct Sparkline<'a> {
|
pub struct Sparkline<'a> {
|
||||||
|
/// A block to wrap the widget in
|
||||||
block: Option<Block<'a>>,
|
block: Option<Block<'a>>,
|
||||||
|
/// Color of the bars
|
||||||
color: Color,
|
color: Color,
|
||||||
|
/// Background color of the widget
|
||||||
background_color: Color,
|
background_color: Color,
|
||||||
|
/// A slice of the data to display
|
||||||
data: &'a [u64],
|
data: &'a [u64],
|
||||||
|
/// The maximum value to take to compute the maximum bar height (if nothing is specified, the
|
||||||
|
/// widget uses the max of the dataset)
|
||||||
max: Option<u64>,
|
max: Option<u64>,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
@ -8,14 +8,44 @@ use widgets::{Widget, Block};
|
||||||
use layout::Rect;
|
use layout::Rect;
|
||||||
use style::Color;
|
use style::Color;
|
||||||
|
|
||||||
|
/// A widget to display data in formatted column
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// # use tui::widgets::{Block, border, Table};
|
||||||
|
/// # use tui::style::Color;
|
||||||
|
/// # fn main() {
|
||||||
|
/// Table::default()
|
||||||
|
/// .block(Block::default().title("Table"))
|
||||||
|
/// .header(&["Col1", "Col2", "Col3"])
|
||||||
|
/// .header_color(Color::Yellow)
|
||||||
|
/// .widths(&[5, 5, 10])
|
||||||
|
/// .column_spacing(1)
|
||||||
|
/// .rows(vec![["Row11", "Row12", "Row13"].as_ref(),
|
||||||
|
/// ["Row21", "Row22", "Row23"].as_ref(),
|
||||||
|
/// ["Row31", "Row32", "Row33"].as_ref()])
|
||||||
|
/// .color(Color::White)
|
||||||
|
/// .background_color(Color::Black);
|
||||||
|
/// # }
|
||||||
|
/// ```
|
||||||
pub struct Table<'a> {
|
pub struct Table<'a> {
|
||||||
|
/// A block to wrap the widget in
|
||||||
block: Option<Block<'a>>,
|
block: Option<Block<'a>>,
|
||||||
|
/// Header row for all columns
|
||||||
header: &'a [&'a str],
|
header: &'a [&'a str],
|
||||||
|
/// Color of the text in the header
|
||||||
header_color: Color,
|
header_color: Color,
|
||||||
|
/// Width of each column (if the total width is greater than the widget width some columns may
|
||||||
|
/// not be displayed)
|
||||||
widths: &'a [u16],
|
widths: &'a [u16],
|
||||||
rows: Vec<Cow<'a, [&'a str]>>,
|
/// Space between each column
|
||||||
color: Color,
|
|
||||||
column_spacing: u16,
|
column_spacing: u16,
|
||||||
|
/// Data to display in each row
|
||||||
|
rows: Vec<Cow<'a, [&'a str]>>,
|
||||||
|
/// Color of the text
|
||||||
|
color: Color,
|
||||||
|
/// Background color for the widget
|
||||||
background_color: Color,
|
background_color: Color,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
@ -15,12 +15,12 @@ use symbols::line;
|
||||||
/// # use tui::widgets::{Block, border, Tabs};
|
/// # use tui::widgets::{Block, border, Tabs};
|
||||||
/// # use tui::style::Color;
|
/// # use tui::style::Color;
|
||||||
/// # fn main() {
|
/// # fn main() {
|
||||||
/// Tabs::default()
|
/// Tabs::default()
|
||||||
/// .block(Block::default().title("Tabs").borders(border::ALL))
|
/// .block(Block::default().title("Tabs").borders(border::ALL))
|
||||||
/// .titles(&["Tab1", "Tab2", "Tab3", "Tab4"])
|
/// .titles(&["Tab1", "Tab2", "Tab3", "Tab4"])
|
||||||
/// .color(Color::White)
|
/// .color(Color::White)
|
||||||
/// .highlight_color(Color::Yellow)
|
/// .highlight_color(Color::Yellow)
|
||||||
/// .background_color(Color::Black);
|
/// .background_color(Color::Black);
|
||||||
/// # }
|
/// # }
|
||||||
/// ```
|
/// ```
|
||||||
pub struct Tabs<'a> {
|
pub struct Tabs<'a> {
|
||||||
|
|
Loading…
Reference in a new issue