Struct TreeSelect 

pub struct TreeSelect<T> { /* private fields */ }

Pick a node of a tree. Nodes are given in order, each with its depth (0 for a root); Right expands the focused node and Left collapses it, or moves to its parent.

Typing searches every node, collapsed or not, and filters as a tree (#428): each match keeps its ancestors, dimmed, so you see where it is, and the cursor goes to the best match. With breadcrumbs on, a line under the question shows the path to the focused node (#464). Ctrl+Y copies that path (the node’s ActionTarget::value) to the terminal’s clipboard.

Implementations

impl<T> TreeSelect<T>

pub fn new<I, V>(prompt: impl Into<String>, nodes: I) -> TreeSelect<T>

where I: IntoIterator<Item = (usize, V)>, V: Into<Item<T>>,

A tree of nodes, in order, each with its depth.

Building it is linear in the number of nodes, and so is what it keeps: each node’s path (the labels joined by /) is worked out when it is asked for, and its guides when its row is drawn.

pub fn breadcrumbs(self, on: bool) -> Self

Show the path to the focused node on a line under the question (#464): root › parent › node, cut from the left when it is too wide.

pub fn crumbs(self, crumbs: Vec<String>) -> Self

Each node’s name in the breadcrumbs, by index, in place of its label: a key rather than key: value, say.

pub fn paths(self, paths: Vec<String>) -> Self

What Ctrl+Y copies and actions see as each node’s value, by index, in place of the labels joined by /: a JSON path, say. Nodes past the end of paths keep the joined labels.

pub fn paths_with( self, path: impl Fn(usize) -> String + Send + Sync + 'static, ) -> Self

Like paths, with each node’s value worked out from its index when it is asked for (the focused node’s, on Ctrl+Y or an action), so a large tree keeps no string per node.

pub fn fold_below(self, depth: usize) -> Self

Collapse every node at depth or deeper that has children, and expand the rest: fold_below(1) shows the roots’ children only.

pub fn rebind(self, action: &str, keys: impl IntoIterator<Item = Key>) -> Self

Make keys do action (see tree_keymap) on this tree only.

pub fn parents(&self) -> &[Option<usize>]

Each node’s parent, by index.

pub fn focused(&self) -> Option<usize>

The focused node’s index.

pub fn path_to(&self, index: usize) -> Vec<&str>

The names on the path to node index, from the root.

pub fn set_status(&mut self, status: Option<String>)

Show status in place of the footer until the next key.

pub fn set_hints(&mut self, hints: Option<String>)

The footer’s extra key hints (default ←→ fold).

pub fn collapsed(self, collapsed: bool) -> Self

Start with every node that has children collapsed (true) or expanded.

pub fn height(self, rows: usize) -> Self

Show at most rows rows at once (default 10).

pub fn preview(self, layout: PreviewLayout) -> Self

pub fn theme(self, theme: Theme) -> Self

pub fn query(self, query: impl Into<String>) -> Self

Start with this filter text.

pub fn default(self, index: usize) -> Self

The row returned without a terminal, and focused first.

pub fn actions(self, actions: Actions) -> Self

Actions offered on every row, beside each row’s own.

pub fn menu_key(self, key: Key) -> Self

The key that opens the action menu (default Ctrl+K).

pub fn with_mouse(self, on: bool) -> Self

Report the mouse: see Select::with_mouse.

pub fn action(&self) -> Option<&str>

The id of the action that picked the row, if one did.

pub fn items(&self) -> &[Item<T>]

pub fn select(&self) -> &Select<T>

The underlying list.

pub fn set_icons(&mut self, icons: Vec<Option<Text>>)

An icon before each row’s label, by item index: see Select::set_icons.

pub fn is_collapsed(&self, index: usize) -> bool

Whether node index is collapsed.

pub fn set_collapsed(&mut self, index: usize, collapsed: bool)

Collapse (true) or expand node index.

Trait Implementations

impl<T: Clone> Component for TreeSelect<T>

type Output = T

fn keymap(&self) -> Keymap

The bindings this component has right now, for a help overlay, a shortcut list or status-bar hints to read (see keymap). A container’s include its focused child’s, before its own. The default declares none.

fn handle(&mut self, event: &Event, context: &Context<'_>) -> Flow<T>

Handle one event. Ctrl+C never arrives here: the event loop ends the component with Outcome::Interrupted.

fn render(&self, context: &Context<'_>) -> View

Render the current state.

fn tick(&self) -> Option<Duration>

How often the component wants Event::Tick, for a spinner or a countdown. None (the default): never.

fn mouse(&self) -> bool

Whether the component wants mouse events (#476): clicks, drags and the wheel. Off by default, since reporting the mouse takes text selection away from the terminal; a component turns it on when its caller opts in, and run then enables mouse reporting for the session.

fn default_value(&self) -> Option<T>

The value to return when the terminal is not interactive and the policy asks for defaults. None: there is none.

fn prompt(&mut self, io: &mut dyn LineIo) -> Result<Option<T>, NotInteractive>

Ask for the value line by line, for when the terminal is not interactive and the policy asks for a prompt. The default says the component has no line-based form.

fn start(&mut self, context: &Context<'_>) -> Flow<Self::Output>

Called once, before the component is first painted, with the terminal’s size: for work that needs it, such as rendering content at the width. Returning Done or Cancel finishes the component without waiting for an event. The default does nothing.

fn focusable(&self) -> bool

Whether the component takes focus in a container: Tab stops on it and keys go to it. The default: yes. A label, or a component that has finished, says no.

fn focus_step(&mut self, forward: bool) -> bool

Move focus to the next (forward) or previous focus stop inside this component, for Tab and Shift+Tab. false when there is none after the current one, so the container moves on to its next child. The default, for a component that is one stop: false.

fn focus_enter(&mut self, forward: bool) -> bool

Take focus from outside: at the first stop inside when forward, at the last otherwise. false when nothing in it can take focus. The default: whether the component is focusable.