Struct Select 

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

A fuzzy single choice among items. Enter returns the focused item’s value; Escape cancels.

Implementations

impl<T> Select<T>

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

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

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

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

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

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

Rows the preview takes when it is below the list (default 10).

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

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

Start with this filter text.

pub fn repaint_every(self, interval: Duration) -> Self

Render again at least every interval, even with no key pressed: for previews that fill in by themselves, such as a command’s output computed on another thread. An unchanged view still writes nothing.

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

The item returned without a terminal when the policy asks for defaults, and focused first.

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

Actions offered on every item, beside each item’s own (#491): in the action menu, and on their keys.

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

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

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

Make keys do action (see select_keymap) on this select only; no keys unbinds it.

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

Report the mouse (#476): a click focuses a row, a second click picks it, and the border beside a preview drags.

pub fn reload_on( self, key: Key, source: impl FnMut() -> Vec<Item<T>> + Send + 'static, ) -> Self

Reload the items from source when key is pressed (#485), as reload does: the query, the focused item and the marks stay.

pub fn reload_from(self, feed: Receiver<Vec<Item<T>>>) -> Self

Take new items from feed whenever they arrive (#485): a watcher or a command on another thread sends the whole list again, and the select reloads it, keeping the query, the focused item and the marks. The select looks every 100 ms.

pub fn split(self, columns: usize) -> Self

The list’s width beside a preview, in columns: where the border is until it is dragged.

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

The id of the Action that picked the item, from its key or the action menu, if one did.

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

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

The focused item’s index, if any item matches.

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

The list’s width beside a preview, once dragged.

pub fn filter(&self) -> &FilterState

The query and what matches it.

pub fn list(&self) -> &ListState

The cursor, the scroll and the marks.

pub fn divider(&self) -> &Divider

The border beside the preview.

pub fn menu(&self) -> Option<&ActionMenu>

The action menu, while it is open.

pub fn select_keymap(&self) -> &Keymap

The keys, with any rebinding.

pub fn is_multi(&self) -> bool

Whether this is the list of a MultiSelect.

pub fn set_kind(&mut self, kind: TargetKind)

What an action is done to: an item, a row, a node, a file.

pub fn set_values(&mut self, values: Vec<String>)

Each item’s identity for an action (ActionTarget::value), by index; the label where missing.

pub fn set_heading(&mut self, heading: Option<Vec<Segment>>)

A line above the list, under the question: a table’s headings.

pub fn set_prefixes(&mut self, prefixes: Vec<String>, plain: bool)

Text before each label, by index, not searched: a tree’s guides, an emoji. Dimmed, unless plain. Call refilter after.

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

An icon before each label, by index, after its prefix: one line of text (see kit::icon), its styles and metadata kept, so a micro asset’s placeholder cells stay tagged for the painter’s graphics. None leaves an item without one.

pub fn set_hidden(&mut self, hidden: Vec<bool>)

Items left out while nothing is typed, by index: a collapsed node’s children. Call refilter after.

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

A line of extra key hints for the footer.

pub fn set_steady(&mut self, steady: bool)

Always take the full height, however few items there are: for lists that change under the user, such as a directory’s entries.

pub fn reload(&mut self, items: Vec<Item<T>>)

Replace the items and keep the user’s place (#485): the query stays and is matched against the new items, the focused item stays focused if it is still there (matched by label), and so do the marks. Per-item settings (values, prefixes, what is hidden) are cleared, as with replace_items; a view that sets them sets them again.

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

Show status in place of the footer until the next key: what an action just did.

pub fn status(&self) -> Option<&[Segment]>

The status line, if one is showing.

pub fn set_tree(&mut self, parents: Option<Vec<Option<usize>>>)

Filter as a tree (#428; see FilterState::set_tree): matches keep their ancestors, dimmed, and the cursor goes to the best match.

pub fn tick_interval(&self) -> Option<Duration>

How often to tick: the repaint interval, and often enough to take fed items.

pub fn replace_items(&mut self, items: Vec<Item<T>>)

Replace the items, keeping the settings; the query is cleared.

pub fn menu_open(&self) -> bool

Whether the action menu is open.

pub fn query_text(&self) -> &str

What is typed.

pub fn set_answer(&mut self, answer: Option<String>)

Show answer in place of the list (None: cancelled), as a finished select does.

pub fn reopen(&mut self)

Carry on after an Enter that did not finish (a directory opened).

pub fn focus_item(&mut self, index: usize)

Focus item index if it is listed.

pub fn target(&self, index: usize) -> ActionTarget

The target an action on item index is done to.

pub fn actions_for(&self, index: usize) -> Vec<Action>

Every action for item index: its own, then the view’s that apply.

pub fn refilter(&mut self)

Match the items against the query again, after the items, their prefixes or what is hidden changed.

pub fn event( &mut self, event: &Event, context: &Context<'_>, ) -> Option<Flow<Vec<usize>>>

Handle an event as the select does, for a component built round one: Some(Flow::Done) finishes with item indices (the view then collapses to the answer), Some(Flow::Cancel) cancels, Some(Flow::Ignored) means the event was not the select’s, and None carries on.

pub fn list_lines(&self, width: usize) -> Vec<Vec<Segment>>

The list’s rows at width: the matches shown, or “no matches”, kept at a steady height.

pub fn footer(&self, width: usize) -> Vec<Segment>

The footer: counts and key hints.

pub fn visible_keymap(&self) -> Keymap

The keys that apply now: no marking for a single choice, and the action menu’s while it is open.

Trait Implementations

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

type Output = T

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 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 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.