More documentation

This commit is contained in:
Florian Dehau 2016-11-04 19:27:19 +01:00
parent fcac19d6c5
commit 652ff12380
12 changed files with 167 additions and 26 deletions

View file

@ -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>,
} }

View file

@ -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,

View file

@ -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,

View file

@ -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])

View file

@ -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,

View file

@ -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>>,

View file

@ -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> {

View file

@ -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> {

View file

@ -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,
} }
} }

View file

@ -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>,
} }

View file

@ -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,
} }

View file

@ -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> {