Struct SelectState 

pub struct SelectState<V: SelectValue> { /* private fields */ }

The rows, the selection, and the open menu of a Select.

Owned by the view that shows the select, which observes it so a change renders. Edit the rows and the selection through its methods; the menu’s own state (the query, the highlighted row, the scroll position) is the state’s to keep.

The selection is kept as items, not values alone, so the trigger can show a chosen item’s label after a search has replaced the rows.

Implementations

impl<V: SelectValue> SelectState<V>

pub fn new( entries: impl IntoIterator<Item = impl Into<SelectEntry<V>>>, cx: &mut Context<'_, Self>, ) -> Self

A closed, single select over entries with nothing selected.

pub fn multiple( entries: impl IntoIterator<Item = impl Into<SelectEntry<V>>>, cx: &mut Context<'_, Self>, ) -> Self

A closed select over entries in which more than one item can be selected: the menu stays open while items are toggled, and the trigger counts the selection.

pub fn with_search( self, placeholder: impl Into<SharedString>, window: &mut Window, cx: &mut Context<'_, Self>, ) -> Self

Adds a search field at the top of the menu, with placeholder in it while it is empty. Typing narrows the rows to those whose label or keywords the query matches as a fuzzy subsequence, ignoring case.

pub fn with_search_handler( self, placeholder: impl Into<SharedString>, handler: impl Fn(SharedString, &mut Context<'_, Self>) -> Task<Vec<SelectEntry<V>>> + 'static, window: &mut Window, cx: &mut Context<'_, Self>, ) -> Self

Adds a search field whose query the application answers: for each change, and once when the menu opens, handler gets the query and returns a task with the rows to show. The task can do its work on a background thread or over the network; a newer query cancels the task before it. The rows given to the state are the ones shown until the first answer, and a chosen item stays selected when a later answer no longer lists it.

The state keeps no answers: what makes one stale is the application’s to know. A handler that remembers its answers can return Task::ready for a query it has seen, and the menu shows those rows on the next frame.

use gpui_cn::{SelectEntry, SelectItem, SelectState};
use gpui_kit::{AppContext as _, Context, Task, Window};

fn cities(window: &mut Window, cx: &mut Context<SelectState<usize>>) -> SelectState<usize> {
    SelectState::new([SelectItem::new(1, "Zurich")], cx).with_search_handler(
        "Search cities",
        |query, cx| {
            cx.background_spawn(async move {
                // Any search: fuzzy, indexed, or a request.
                vec![SelectEntry::from(SelectItem::new(2, format!("{query} City")))]
            })
        },
        window,
        cx,
    )
}

pub fn with_selected(self, values: impl IntoIterator<Item = V>) -> Self

Seeds the selection. Values that are not items are dropped, and a single select keeps the first.

pub fn with_row_height(self, height: Pixels) -> Self

Gives every item row this height. Without it a row is as tall as its content, a plain row’s height at least, and the list measures rows as they come into view. With it the list knows every row’s height before it is laid out, so a scroll to a far row of a long menu lands exactly; rows drawn by Select::render_item clip to it.

pub fn entries(&self) -> &[SelectEntry<V>]

The rows, in menu order.

pub fn set_entries( &mut self, entries: impl IntoIterator<Item = impl Into<SelectEntry<V>>>, cx: &mut Context<'_, Self>, )

Replaces the rows. With a local search, a selected value that is no longer an item is dropped from the selection; with a handler the rows come and go with the query, so the selection stays.

pub fn selected(&self) -> Vec<V>

The selected values, in the order chosen.

pub fn selected_value(&self) -> Option<&V>

The selected value of a single select.

pub fn selected_items(&self) -> &[SelectItem<V>]

The selected items, in the order chosen.

pub fn is_selected(&self, value: &V) -> bool

Whether value is selected.

pub fn set_selected( &mut self, values: impl IntoIterator<Item = V>, cx: &mut Context<'_, Self>, )

Replaces the selection and reports the change. Values that are not items are dropped, and a single select keeps the first.

pub fn is_multiple(&self) -> bool

Whether more than one item can be selected.

pub fn is_searchable(&self) -> bool

Whether the menu has a search field.

pub fn is_searching(&self) -> bool

Whether a search handler is still answering the query.

pub fn is_open(&self) -> bool

Whether the menu is open.

pub fn query(&self, cx: &App) -> SharedString

The search query, or an empty string without a search field.

pub fn highlighted(&self) -> Option<&SelectItem<V>>

The item the keyboard is on while the menu is open.

pub fn open(&mut self, window: &mut Window, cx: &mut Context<'_, Self>)

Opens the menu, highlights the selected item (or the first), decides which side of the trigger the menu takes, and moves focus into the menu: to the search field, else to the list. A search handler is asked for the rows of the empty query.

pub fn close(&mut self, window: &mut Window, cx: &mut Context<'_, Self>)

Closes the menu, clears the query, cancels a running search, and returns focus to the trigger if the menu had it.

pub fn choose( &mut self, value: &V, window: &mut Window, cx: &mut Context<'_, Self>, )

Chooses value while the menu is open: a single select selects it and closes, a multiple select toggles it and stays open. A disabled item, or a closed menu, ignores it.

pub fn choose_highlighted( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, )

Chooses the highlighted item. While a handler is still answering there is no row to choose: the highlight is on rows the answer will replace.

pub fn move_highlight(&mut self, delta: isize, cx: &mut Context<'_, Self>)

Moves the highlight one selectable row up or down, wrapping at the ends, and scrolls it into view.

pub fn highlight_first(&mut self, cx: &mut Context<'_, Self>)

Highlights the first selectable row.

pub fn highlight_last(&mut self, cx: &mut Context<'_, Self>)

Highlights the last selectable row.

Trait Implementations

impl<V: SelectValue> EventEmitter<SelectEvent<V>> for SelectState<V>

impl<V: SelectValue> Focusable for SelectState<V>

The trigger’s focus handle: focusing the state focuses the trigger.

fn focus_handle(&self, _: &App) -> FocusHandle

Returns the focus handle associated with this view.