fdehau/tui-rs v0.10.0

on GitHub

Breaking changes

Easier cursor management

A new method has been added to Frame called set_cursor. It lets you specify where the cursor
should be placed after the draw call. Furthermore like any other widgets, if you do not set a cursor
position during a draw call, the cursor is automatically hidden.

For example:

fn draw_input(f: &mut Frame, app: &App) {
  if app.editing {
    let input_width = app.input.width() as u16;
    // The cursor will be placed just after the last character of the input
    f.set_cursor((input_width + 1, 0));
  } else {
    // We are no longer editing, the cursor does not have to be shown, set_cursor is not called and
    // thus automatically hidden.
  }
}

In order to make this possible, the draw closure takes in input &mut Frame instead of mut Frame.

Advanced text styling

It has been reported several times that the text styling capabilities were somewhat limited in many
places of the crate. To solve the issue, this release includes a new set of text primitives that are
now used by a majority of widgets to provide flexible text styling.

Text is replaced by the following types:

• Span: a string with a unique style.
• Spans: a string with multiple styles.
• Text: a multi-lines string with multiple styles.

However, you do not always need this complexity so the crate provides From implementations to
let you use simple strings as a default and switch to the previous primitives when you need
additional styling capabilities.

For example, the title of a Block can be set in the following ways:

// A title with no styling
Block::default().title("My title");
// A yellow title
Block::default().title(Span::styled("My title", Style::default().fg(Color::Yellow)));
// A title where "My" is bold and "title" is a simple string
Block::default().title(vec![
    Span::styled("My", Style::default().add_modifier(Modifier::BOLD)),
    Span::from("title")
]);

• Buffer::set_spans and Buffer::set_span were added.
• Paragraph::new expects an input that can be converted to a Text.
• Block::title_style is deprecated.
• Block::title expects a Spans.
• Tabs expects a list of Spans.
• Gauge custom label is now a Span.
• Axis title and labels are Spans (as a consequence Chart no longer has generic bounds).

Incremental styling

Previously Style was used to represent an exhaustive set of style rules to be applied to an UI
element. It implied that whenever you wanted to change even only one property you had to provide the
complete style. For example, if you had a Block where you wanted to have a green background and
a title in bold, you had to do the following:

let style = Style::default().bg(Color::Green);
Block::default()
  .style(style)
  .title("My title")
  // Here we reused the style otherwise the background color would have been reset
  .title_style(style.modifier(Modifier::BOLD));

In this new release, you may now write this as:

Block::default()
    .style(Style::default().bg(Color::Green))
    // The style is not overidden anymore, we simply add new style rule for the title.
    .title(Span::styled("My title", Style::default().add_modifier(Modifier::BOLD)))

In addition, the crate now provides a method patch to combine two styles into a new set of style
rules:

let style = Style::default().modifer(Modifier::BOLD);
let style = style.patch(Style::default().add_modifier(Modifier::ITALIC));
// style.modifer == Modifier::BOLD | Modifier::ITALIC, the modifier has been enriched not overidden

• Style::modifier has been removed in favor of Style::add_modifier and Style::remove_modifier.
• Buffer::set_style has been added. Buffer::set_background is deprecated.
• BarChart::style no longer set the style of the bars. Use BarChart::bar_style in replacement.
• Gauge::style no longer set the style of the gauge. Use Gauge::gauge_style in replacement.

List with item on multiple lines

The List widget has been refactored once again to support items with variable heights and complex
styling.

• List::new expects an input that can be converted to a Vec<ListItem> where ListItem is a
  wrapper around the item content to provide additional styling capabilities. ListItem contains a
  Text.
• List::items has been removed.

// Before
let items = vec![
  "Item1",
  "Item2",
  "Item3"
];
List::default().items(items.iters());

// After
let items = vec![
  ListItem::new("Item1"),
  ListItem::new("Item2"),
  ListItem::new("Item3"),
];
List::new(items);

See the examples for more advanced usages.

More wrapping options

Paragraph::wrap expects Wrap instead of bool to let users decided whether they want to trim
whitespaces when the text is wrapped.

// before
Paragraph::new(text).wrap(true)
// after
Paragraph::new(text).wrap(Wrap { trim: true }) // to have the same behavior
Paragraph::new(text).wrap(Wrap { trim: false }) // to use the new behavior

Horizontal scrolling in paragraph

You can now scroll horizontally in Paragraph. The argument of Paragraph::scroll has thus be
changed from u16 to (u16, u16).

Features

Serialization of style

You can now serialize and de-serialize Style using the optional serde feature.