Guide API
Skip to main content

SortedListBox

Struct SortedListBox 

Source
pub struct SortedListBox { /* private fields */ }
Expand description

A list viewer with incremental type-to-search over a case-insensitively sorted string list. A direct ListViewer impl (like ListBox); the search state machine lives as the sorted_handle_event / sorted_cursor free functions over the SortedSearch sub-trait, which this widget implements.

§Design notes

  • The list is an owned Vec<String>; new_list keeps it CASE-INSENSITIVELY SORTED so the binary search and the case-insensitive prefix-confirm cohere. File/dir subclasses can impose their own ordering.
  • The search key here is the typed prefix itself; a file/dir subclass overrides search to supply its own key derivation and ordering.
  • The shift bits are captured but UNUSED in this base — a file list reads them.

§Turbo Vision heritage

Ports TSortedListBox (stddlg.cpp); the injected sorted collection becomes the owned, case-insensitively sorted Vec<String>.

Implementations§

Source§

impl SortedListBox

Source

pub fn new( bounds: Rect, num_cols: i32, h: Option<ViewId>, v: Option<ViewId>, ) -> Self

Create a new, empty sorted list box wired to optional scroll bars.

Like ListBox::new, but additionally enables the visible cursor and positions it at column 1 — the cursor advances past the matched prefix during type-to-search. The item list starts empty; call new_list after insertion to populate it.

Pass None for h or v when no horizontal or vertical scroll bar is needed.

Source

pub fn with_find(self, mode: FindMode) -> Self

Enable find mode (default FindMode::Off keeps the classic lookup). Filter makes the list narrow its own (already-sorted) source by the query, so the narrowed view stays in sorted order.

Source

pub fn new_list(&mut self, items: Vec<String>, ctx: &mut Context<'_>)

Replace the item collection, sort it case-insensitively, and reset the search state.

The items are sorted in-place (ASCII case-fold) so that the binary search used by type-to-search produces correct results. After sorting, the scroll-bar range is republished and focus is reset to item 0. Any active type-to-search state (search_pos) is cleared.

Call this after the widget has been inserted into its parent group (same requirement as ListBox::new_list). Pass items in any order — new_list sorts them for you.

Source

pub fn list(&self) -> &[String]

The current item collection as a read-only, case-insensitively sorted slice.

The slice is always in the order established by the last new_list call (ASCII case-folded lexicographic). Use it to read the items; to replace them call new_list. In FindMode::Filter with an active query, the returned slice is the query-narrowed view, not the full set supplied via new_list; clearing the query restores the full set.

Trait Implementations§

Source§

impl ListViewer for SortedListBox

Source§

fn get_text(&self, item: i32) -> String

Return the text for item from the owned Vec.

Source§

fn lv(&self) -> &ListViewerState

Borrow the embedded ListViewerState.
Source§

fn lv_mut(&mut self) -> &mut ListViewerState

Mutably borrow the embedded ListViewerState.
Source§

fn on_query_changed(&mut self, ctx: &mut Context<'_>)

Hook fired after the find query changes (default: no-op). A self-filtering concrete widget overrides it to re-derive its visible rows from its source. Called by the shared handle_event and by Self::set_find_query (including Self::clear_find).
Source§

fn list_roles(&self) -> ListRoles

The six color roles draw uses for this list’s color matrix. Read more
Source§

fn is_selected(&self, item: i32) -> bool

Whether item should be drawn in the selected color. Read more
Source§

fn item_role(&self, _item: i32) -> Option<Role>

An optional per-item Role for a normal row — one that is neither the focused cursor item nor selected. Only the role’s foreground is used: the row keeps the list’s surface background, so a tinted row still reads as part of the list. None (the default) keeps the plain surface colour. A table uses it to tint a whole row (a dimmed or an error row); the focused and selected colours always win over it.
Source§

fn select_item(&mut self, _item: i32, ctx: &mut Context<'_>)

Called when the user commits to item (double-click, Space, or Enter). Read more
Source§

fn on_focus_changed(&mut self, _ctx: &mut Context<'_>)

A hook that runs after the focus moves. The base focus_item free fn calls this after moving focused (and adjusting top_item), so an override fires on EVERY focus change (keyboard, mouse, scrollbar sync, …). Default: no-op. A file list overrides it to broadcast that the focused file changed.
Source§

fn find_query(&self) -> Option<&str>

The current non-empty find query, or None when find mode is Off or the query is empty. The shared draw reads this to highlight matches; hosts read it to mirror the query elsewhere.
Source§

fn set_find_query(&mut self, query: &str, ctx: &mut Context<'_>)

Set the find query from an external source — e.g. a host InputLine that owns the text and drives an unfocused list’s incremental find (a combobox). The mirror image of typed find, minus the keystrokes: a whole-string setter because a text source always holds the complete string. Read more
Source§

fn clear_find(&mut self, ctx: &mut Context<'_>)

Clear the find query — the host-callable Esc equivalent. Equivalent to set_find_query("", ctx): no-op when find is Off or already empty, else fires Command::LIST_FIND_CHANGED and runs Self::on_query_changed.
Source§

impl SortedSearch for SortedListBox

Source§

fn search(&self, cur: &[char]) -> i32

Map the typed prefix to the best matching item index.

The key IS the typed prefix itself: cur is joined into a string and compared case-insensitively against the sorted items. Returns the first index i in 0..range such that items[i] >= key (case-insensitive insertion point), or range when every item sorts before the prefix.

Subclasses (e.g. a file-list box) can override search to derive a different key or use a different ordering; this base implementation covers the generic string case.

Source§

fn search_pos(&self) -> i32

The index of the last matched char in the focused item’s text; -1 = no active search.
Source§

fn set_search_pos(&mut self, pos: i32)

Source§

fn shift_state(&self) -> u8

The shift bits captured at the search_pos -1↔0 transition. A plain sorted list box never reads it; file/dir subclasses’ search does.
Source§

fn set_shift_state(&mut self, s: u8)

Source§

impl View for SortedListBox

Source§

fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)

The incremental type-to-search state machine, shared verbatim via the sorted_handle_event free function over the SortedSearch sub-trait.

Source§

fn on_bounds_changed(&mut self, ctx: &mut Context<'_>)

Republish the scroll-bar steps after a bounds change.

Source§

fn cursor_request(&self) -> Option<Point>

Cursor advanced past the matched prefix — shared via sorted_cursor.

Source§

fn value(&self) -> Option<FieldValue>

The focused item’s index in the (sorted) item Vec as a FieldValue::Int.

Gather this value after the user closes the dialog to find out which item was selected. Because the list is sorted by new_list, the index refers to the sorted position — use list to map it back to the item text if needed. The item collection itself is not part of this value (same contract as ListBox::value).

Source§

fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)

Focus the item at index and republish the vertical scroll bar.

Scatter a previously gathered FieldValue::Int back here to restore the user’s prior selection. The index refers to the sorted position; an out-of-range value is clamped. Non-Int variants are silently ignored. The item list is not replaced — call new_list first if you need to repopulate.

Source§

fn state(&self) -> &ViewState

Borrow the embedded ViewState (the view’s data members).
Source§

fn state_mut(&mut self) -> &mut ViewState

Mutably borrow the embedded ViewState.
Source§

fn draw(&mut self, ctx: &mut DrawCtx<'_>)

Paint the view through ctx. Must be overridden. Read more
Source§

fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)

Flip a propagating state flag and run its side effects. The base flips the flag and, for StateFlag::Focused, emits the focus broadcast (RECEIVED_FOCUS/RELEASED_FOCUS) via ctx. Read more
Source§

fn apply_scroll_sync( &mut self, h: Option<i32>, v: Option<i32>, ctx: &mut Context<'_>, )

The shared scrollbar read-sync broker hook. Defaulted no-op; scroll-aware widgets override it to apply a freshly-read scrollbar delta to themselves. The pump passes the horizontal/vertical scrollbar values (None if that bar is absent or unresolved), each read via View::value. Overridden by the list viewers (delegate to list_viewer::apply_scroll), Scroller, the outline viewer, and the editor — every sibling-scrollbar read sync routes through this one method instead of a pump downcast. Read more
Source§

fn as_any_mut(&mut self) -> Option<&mut dyn Any>

Downcast hook for the rare parent→child push that needs the concrete type (e.g. a window pushing its zoomed flag to its frame). Base returns None; only views that must be reached concretely override it. (Any requires 'static, which every view is.)
Source§

fn valid(&mut self, _cmd: Command, _ctx: &mut Context<'_>) -> bool

Whether the view is in a valid state for cmd (e.g. a modal end / focus release). Base is always true. Read more
Source§

fn set_modal_answer(&mut self, _cmd: Command)

Stash the user’s choice from an async modal message box this view requested via Context::request_message_box (the answer_to/RouteModalAnswer round-trip). Default: no-op. Overridden by views that drive a Yes/No/Cancel prompt out of valid (e.g. FileEditor caches it for the re-validate).
Source§

fn set_value(&mut self, _v: FieldValue)

Load a typed FieldValue into this control. Read more
Source§

fn set_modal_data(&mut self, _data: FieldValue)

Deliver a finished modal’s typed result record to the view that launched it. Defaulted no-op; a launcher view overrides it to load the record. Two producers call it: Read more
Source§

fn awaken(&mut self)

Post-construction initialization hook. Called once after the view has been inserted into its group and the group’s layout is complete — the earliest point at which a view may safely resolve sibling ids or run initialization that requires a fully-wired tree. Override when a widget needs to do work that cannot happen during construction (e.g. reading a linked control’s current value). Base is a no-op.
Source§

fn size_limits(&self, owner_size: Point) -> (Point, Point)

The (min, max) size this view may take inside an owner of owner_size. Read more
Source§

fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect

The new bounds after the owner resized to owner_size (delta = new - old). Computes the size limits via the overridable size_limits hook — so a widget override (e.g. a window’s minimum) participates — then delegates the grow math to ViewState::calc_bounds (the single source). Returns the bounds; it does not apply them (change_bounds does).
Source§

fn change_bounds(&mut self, bounds: Rect)

Apply bounds to this view and propagate as needed. Read more
Source§

fn caret_size(&self) -> u8

The caret size this view wants while its cursor is shown, as a percentage of the character cell (1..=100). Base: CARET_INSERT (a block) when the cursor_ins state is set, else CARET_NORMAL (the normal caret). The event loop reads it along the same focused chain as cursor_request; Group overrides it to descend into its current child. Read more
Source§

fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>

Resolve id to a descendant of this view (never self — the parent identifies a view by id). A leaf has no descendants, so the base returns None; a Group overrides to search its children and recurse; a Group-embedding view delegates to its inner group. This is the “tree-walk via Context” — the uniform way the event loop / a capture handler acts on a view it holds only by id (move a window’s bounds, flip the dragging flag, …).
Source§

fn remove_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Remove the descendant named by id from whichever group owns it. Returns true if it was found+removed. Distinct from find_mut because removal happens in the owner’s child Vec (a view cannot remove itself — it doesn’t know its owner) and must run the owning group’s reset_current. Base: false (a leaf owns nothing).
Source§

fn focus_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Focus (select) the descendant named by id within whichever group owns it — the tree-op behind a label focusing its linked control. Returns true if id was found in this subtree (selectable or not — finding it stops the walk). Distinct from find_mut because focusing happens in the owning group (a view cannot select itself within itself): the owning Group calls focus_child after applying the selectable gate. Base: false (a leaf owns nothing). Read more
Source§

fn has_focusable_leaf(&self) -> bool

Whether this view’s subtree contains a focusable leaf (visible, enabled, selectable). Base: whether THIS view is itself a focusable leaf; Group overrides to recurse into children; wrapper views delegate. Used by the hierarchical Tab traversal to skip selectable-but-empty subtrees.
Source§

fn focus_to_edge(&mut self, backward: bool, ctx: &mut Context<'_>) -> bool

Focus the first (Tab, backward = false) or last (Shift-Tab, backward = true) focusable leaf in this view’s subtree, establishing the full focus path down to it. Returns true if a focusable leaf was focused. Read more
Source§

fn reset_current(&mut self, _ctx: &mut Context<'_>)

Establish this view’s INTERNAL currency — for a group-bearing view, set its current child to the first visible+selectable child. The insert-time currency cascade cannot run inside the context-less Group::insert, so exec_view calls this on a freshly-inserted modal BEFORE focusing it, so the modal’s first selectable child is current on open (otherwise the modal is keyboard-dead until a nav event — see the seam note in exec_view). Base: no-op (a leaf has no internal currency); Group overrides; Window/Dialog delegate.
Source§

fn settle_currency(&mut self, _ctx: &mut Context<'_>)

Run any pending insert-time reset-current cascades in this subtree. Read more
Source§

fn set_visible_descendant( &mut self, id: ViewId, visible: bool, ctx: &mut Context<'_>, ) -> bool

Tree-op: set the visible flag of the descendant named by id from its OWNING group, running the owning group’s currency tail. Toggling visibility on a selectable view re-picks the owner’s current child, in both directions (show and hide). Returns true if id was found in this subtree. Read more
Source§

fn number(&self) -> Option<i16>

The window number for Alt-N selection. Base views are unnumbered (None); Window overrides to return its number when > 0 (0 means unnumbered → None).
Source§

fn grabs_focus_on_click(&self) -> bool

Whether a mouse-down inside this view should auto-select (focus) it — the per-view opt-out for the group’s mouse-down auto-select (see Group::route_event). Default true (the common case); a Button overrides to return its grab-focus flag. A view returning false is not focused by a click but still receives the click (so it can act, e.g. press, without becoming the current view).
Source§

fn select_window_num(&mut self, num: i16, ctx: &mut Context<'_>) -> bool

Tree-op: ask this subtree to select the window numbered num. Returns whether one matched. Consistent with the find_mut / remove_descendant tree-op family: the live loop holds a subtree only by id (here, the desktop) and asks it to act. Default: no-op (false). Desktop overrides.
Source§

fn tile(&mut self, _r: Rect)

Tree-op: lay this subtree’s tileable windows out in a grid (the tile command). Base: no-op (only Desktop lays out windows). r is the desktop-local layout rect. Mirrors select_window_num: the live loop drives the desktop by id through &mut dyn View.
Source§

fn cascade(&mut self, _r: Rect)

Tree-op: lay this subtree’s tileable windows out cascaded (the cascade command). Base: no-op; Desktop overrides.
Source§

fn update_menu_commands(&mut self, _disabled_cmds: &CommandSet)

The menu command-graying broker hook. Defaulted no-op; menu views override to re-gray their menu tree against the program’s live disabled-command set (denylist — the argument is the set of commands currently disabled; an item grays iff its command is in it). The free fn menu::menu_view::update_menu_commands implements the re-gray walk. Read more
Source§

fn set_menu_current(&mut self, _current: Option<usize>)

The menu-highlight write-back hook. Defaulted no-op; menu views (MenuBar / MenuBox) override to set their MenuViewState::current — the write-only display cache their draw reads to pick the selected colour. Read more
Source§

fn get_help_ctx(&self) -> HelpCtx

The effective help context for status-line switching. Returns HelpCtx::DRAGGING while the view is being dragged, otherwise the view’s own ViewState::help_ctx. Read more
Source§

fn descendant_global_bounds(&self, _id: ViewId, _acc: Point) -> Option<Rect>

Resolve descendant id to its absolute bounds, given acc = this view’s own absolute origin. Base returns None (a leaf owns no descendants); a Group overrides to walk its children accumulating origins, and a Group-embedding view delegates to its inner group. The THistory open path needs its linked input line’s bounds in the root/absolute frame, because exec_view root-inserts the modal and the modal frame hit-tests in absolute coords (the documented ROOT-INSERT + (0,0) caveat). Mirrors find_mut’s recursion but returns geometry, not a borrow.
Source§

fn set_indicator_value(&mut self, _location: Point, _modified: bool)

The editor→indicator status-push broker hook. Defaulted no-op; the editor’s status Indicator overrides it to store the new cursor location + modified flag. Driven by Deferred::IndicatorSetValue: the editor (a leaf) cannot reach its indicator sibling inline, so it requests this and the pump calls the method by id — virtual dispatch, not a downcast.
Source§

fn apply_page_sync(&mut self, _idx: usize, _ctx: &mut Context<'_>)

The tab-bar→page-stack switch broker hook. Defaulted no-op; PageStack overrides it to make page idx active. Driven by Deferred::PageStackSync: the pump reads the bound tab bar’s value and calls this method by id — virtual dispatch, not a downcast.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync> ⓘ

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.