API reference — widgets

All widgets live in core.term.widget. Most are re-exported from core.term.widget.* and also from core.term.app.*. This page is a dense reference; for guided explanations see the widget catalogue.

Protocols

public type Widget is protocol {
    fn render(&self, area: Rect, buf: &mut Buffer);
};

public type StatefulWidget is protocol {
    type State;
    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self.State);
};

public type Styled is protocol {
    fn style(self, style: Style) -> Self;
};

Block

Block.new() -> Block
    .title(text: Text) -> Self
    .title_alignment(a: Alignment) -> Self
    .borders(b: Borders) -> Self
    .border_type(t: BorderType) -> Self
    .border_style(s: Style) -> Self
    .style(s: Style) -> Self
    .padding(top: Int, right: Int, bottom: Int, left: Int) -> Self
    .inner(area: Rect) -> Rect

Paragraph

Paragraph.new() -> Paragraph
    .text(lines: List<Line>) -> Self
    .wrap(w: Wrap) -> Self           // NoWrap | WordWrap | CharWrap
    .alignment(a: Alignment) -> Self
    .block(b: Block) -> Self
    .scroll(offset: (Int, Int)) -> Self   // (x, y), not a single Int

SelectableList

SelectableList.new(items: &List<Text>) -> Self
    .block(b: Block) -> Self
    .highlight_style(s: Style) -> Self
    .highlight_symbol(sym: &Text) -> Self
    .render(area, f.buffer, &mut ListState)

// From core/term/widget/list.vr. `selected` is a FIELD, not a method,
// and the movers are `next` / `previous`, each taking the total item
// count because the state does not hold the list.
type ListState is { selected: Maybe<Int>, offset: Int };

ListState.new() -> ListState
ListState.with_selected(idx: Int) -> ListState
    fn next(&mut self, total: Int)
    fn previous(&mut self, total: Int)
    fn unselect(&mut self)

Table

The column widths are a CONSTRUCTOR argument — there is no .widths(…) builder — and the row type is TableRow, whose new takes the cell TEXTS. TableCell is the styled-cell type.

Table.new(rows: List<TableRow>, widths: List<LayoutConstraint>) -> Self
    .header(row: TableRow) -> Self
    .footer(row: TableRow) -> Self
    .block(b: Block) -> Self
    .style(s: Style) -> Self
    .highlight_style(s: Style) -> Self
    .highlight_symbol(sym: Text) -> Self
    .highlight_spacing(sp: HighlightSpacing) -> Self
    .column_spacing(n: Int) -> Self

TableRow.new(cells: List<Text>) -> TableRow
    .styled(cells: List<Text>, style: Style) -> TableRow   // constructor
    .height(h: Int) -> Self
    .style(s: Style) -> Self
    .bottom_margin(m: Int) -> Self

TableCell.raw(text: Text) / .styled(text: Text, style: Style)
         / .from_line(line: Line)

TextInput

TextInput.new() -> TextInput
    .block(b: Block) -> Self
    .placeholder(t: Text) -> Self
    .placeholder_style(s: Style) -> Self
    .cursor_style(s: Style) -> Self
    .selection_style(s: Style) -> Self
    .mask(ch: Char) -> Self           // for passwords

TextInputState.new() -> TextInputState
    .with_value(t: Text) -> Self
    .history_cap(n: Int) -> Self

    // selection
    fn has_selection(&self) -> Bool
    fn selection_range(&self) -> (Int, Int)
    fn selected_text(&self) -> Text
    fn select_all(&mut self)
    fn clear_selection(&mut self)

    // history
    fn undo(&mut self) -> Bool
    fn redo(&mut self) -> Bool

    // mutation
    fn insert_char(&mut self, ch: Char)
    fn insert_text(&mut self, t: &Text)
    fn delete_backward(&mut self)
    fn delete_forward(&mut self)
    fn delete_word_backward(&mut self)
    fn delete_word_forward(&mut self)
    fn kill_to_end(&mut self) -> Text
    fn kill_to_start(&mut self) -> Text
    fn delete_selection(&mut self) -> Text
    fn clear(&mut self)

    // movement (extend_selection: bool)
    fn move_left(&mut self, extend: Bool)
    fn move_right(&mut self, extend: Bool)
    fn move_word_left(&mut self, extend: Bool)
    fn move_word_right(&mut self, extend: Bool)
    fn move_home(&mut self, extend: Bool)
    fn move_end(&mut self, extend: Bool)

    // clipboard
    fn copy(&self) -> Text
    fn cut(&mut self) -> Text
    fn paste(&mut self, t: &Text)

    // default dispatcher with Emacs keybindings
    fn handle_key(&mut self, ke: KeyEvent) -> Bool

Default keybindings (via handle_key):

Key	Action
Ctrl+A / Home	Line start
Ctrl+E / End	Line end
Ctrl+B / ←	Grapheme left
Ctrl+F / →	Grapheme right
Alt+B / Ctrl+←	Word left
Alt+F / Ctrl+→	Word right
Ctrl+K	Kill to end
Ctrl+U	Kill to start
Ctrl+W / Ctrl+Backspace	Delete word backward
Alt+D / Ctrl+Delete	Delete word forward
Ctrl+H / Backspace	Delete backward
Ctrl+D / Delete	Delete forward
Ctrl+Z	Undo
Ctrl+Y	Redo
Shift+arrow	Extend selection

TextArea

TextArea.new() -> TextArea
    .block(b: Block) -> Self
    .cursor_style(s: Style) -> Self
    .selection_style(s: Style) -> Self
    .line_numbers(on: Bool) -> Self
    .line_number_style(s: Style) -> Self
    .wrap(w: WrapMode) -> Self        // NoWrap | CharWrap | WordWrap
    .tab_width(n: Int) -> Self

TextAreaState.new() -> TextAreaState
    .from_text(t: &Text) -> Self
    fn to_text(&self) -> Text
    fn has_selection(&self) -> Bool
    fn selection_range(&self) -> (Pos, Pos)
    fn undo(&mut self) -> Bool
    fn redo(&mut self) -> Bool
    fn insert_char(&mut self, ch: Char)
    fn insert_text(&mut self, t: &Text)
    fn insert_newline(&mut self)
    fn delete_backward(&mut self)
    fn delete_forward(&mut self)
    fn move_left / right / up / down / line_start / line_end / document_start / document_end
    fn copy(&self) -> Text
    fn cut(&mut self) -> Text
    fn paste(&mut self, t: &Text)
    fn handle_key(&mut self, ke: KeyEvent) -> Bool

Dropdown<T>

Dropdown.new(items: List<T>, label_fn: fn(&T) -> Text) -> Dropdown<T>
    .placeholder(t: Text) -> Self
    .closed_block(b: Block) -> Self
    .open_block(b: Block) -> Self
    .highlight_style(s: Style) -> Self
    .chevron_style(s: Style) -> Self
    .placeholder_style(s: Style) -> Self
    .search_style(s: Style) -> Self
    .max_visible(n: Int) -> Self
    .searchable(on: Bool) -> Self

DropdownState.new() -> DropdownState
    .with_selected(idx: Int) -> Self
    fn toggle(&mut self)
    fn close(&mut self)
    fn open_it(&mut self)
    fn handle_key<T>(&mut self, d: &Dropdown<T>, ke: KeyEvent) -> Bool

Split

TermSplit.horizontal() -> Split
TermSplit.vertical()   -> Split
    .divider_style(s: Style) -> Self
    .dragging_style(s: Style) -> Self
    .show_divider(on: Bool) -> Self
    .divider_width(n: Int) -> Self
    .min_first(n: Int) -> Self
    .min_second(n: Int) -> Self

    fn layout(&self, area: Rect, state: &SplitState) -> (Rect, Rect, Rect)
    fn render_divider(&self, area: Rect, buf: &mut Buffer, state: &SplitState)

SplitState.ratio(r: Float) -> SplitState
SplitState.fixed(n: Int)   -> SplitState
    fn resize(&mut self, delta, available, min_first, min_second)
    fn set_ratio(&mut self, r: Float)
    fn set_fixed(&mut self, n: Int)
    fn focus_next(&mut self)
    fn handle_resize_key(&mut self, split: &Split, area: Rect, ke: KeyEvent, step: Int) -> Bool
    fn handle_mouse(&mut self, split: &Split, area: Rect, me: MouseEvent) -> Bool

Other widgets

The following are documented inline in the widget catalogue. They implement Widget or StatefulWidget; their constructors vary by widget:

TermGauge.new()                       // then .ratio(f) or .percent(n)
Tabs.new(titles: List<Text>)
Scrollbar.vertical() / .horizontal()  // orientation picks the ctor;
                                      // there is no Scrollbar.new
Canvas.new()                          // .x_bounds(min, max) takes TWO
                                      // Floats; .paint takes a Shape
Sparkline.new(data: List<Float>) / .empty()
BarChart.new(groups: List<BarGroup>) / .empty()
Tree.new(items: List<TreeItem<T>>)
Menu.new(items: List<MenuItem>)
Dialog.new(body: Text)                // the body is a ctor argument
DialogButton.new(label) / .styled(label, style, focused_style)
Spinner.new(frames: SpinnerFrames)    // or the shorthands
Spinner.dots() / .line() / .moon() / .earth() / .arrows() / .blocks()
Notification.info(msg) / .warning(msg) / .error(msg) / .success(msg)
                                      // built from the LEVEL; there is
                                      // no Notification.new