Guide API
Skip to main content

ListViewer

Trait ListViewer 

Source
pub trait ListViewer: View {
    // Required methods
    fn lv(&self) -> &ListViewerState;
    fn lv_mut(&mut self) -> &mut ListViewerState;

    // Provided methods
    fn get_text(&self, _item: i32) -> String { ... }
    fn list_roles(&self) -> ListRoles { ... }
    fn is_selected(&self, item: i32) -> bool { ... }
    fn item_role(&self, _item: i32) -> Option<Role> { ... }
    fn select_item(&mut self, _item: i32, ctx: &mut Context<'_>) { ... }
    fn on_focus_changed(&mut self, _ctx: &mut Context<'_>) { ... }
    fn find_query(&self) -> Option<&str> { ... }
    fn set_find_query(&mut self, query: &str, ctx: &mut Context<'_>) { ... }
    fn clear_find(&mut self, ctx: &mut Context<'_>) { ... }
    fn on_query_changed(&mut self, _ctx: &mut Context<'_>) { ... }
}
Expand description

The abstract list-viewer base, as a trait of overridable methods.

Concrete list widgets implement lv/lv_mut (the data accessors) and override get_text/ is_selected/select_item as needed; the shared draw/event/nav logic (the free functions in this module) is generic over L: ListViewer and calls back into these.

Wiring caveat (no compile-time enforcement): a concrete list widget MUST delegate ALL of these View methods to this module’s free functions: draw, handle_event, set_state, View::cursor_request → focused_cursor, View::apply_scroll_sync → apply_scroll, and View::as_any_mut (the cross-view broker downcasts through it). In particular, forgetting to override apply_scroll_sync is silent — its base default is a no-op, so the widget compiles but loses all scrollbar read-sync with no error. (See FakeList in this module’s tests for the full delegation template.)

§Turbo Vision heritage

The trait half of TListViewer (tlstview.cpp): the overridable hooks (item text / selection / commit / palette), with the data members in ListViewerState and the shared logic in this module’s free functions.

Required Methods§

Source

fn lv(&self) -> &ListViewerState

Borrow the embedded ListViewerState.

Source

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

Mutably borrow the embedded ListViewerState.

Provided Methods§

Source

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

The text for item. The default returns empty; concrete list widgets (e.g. a list box) override it.

Source

fn list_roles(&self) -> ListRoles

The six color roles draw uses for this list’s color matrix.

Override to recolor the whole list. Return a ListRoles struct with different Role values for any of the six slots; the base implementation returns ListRoles::LIST_VIEWER. A history viewer, for example, overrides this to use its own lighter palette.

Source

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

Whether item should be drawn in the selected color.

The default returns item == focused (single-selection behavior). Override in a multi-select widget to mark additional items as selected.

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

The default broadcasts Command::LIST_ITEM_SELECTED with this view’s ViewId as source, so an owner dialog can catch it with Event::Broadcast { command: Command::LIST_ITEM_SELECTED, source } and filter on source to distinguish which list fired. Override to perform a direct action instead (e.g. close a dialog or load a file).

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.

No-op when find mode is FindMode::Off or the query is unchanged; otherwise replaces the query, fires Command::LIST_FIND_CHANGED (source = this list) and runs Self::on_query_changed — the same change tail keystroke find runs. Passing "" is exactly Self::clear_find reached through the same door, so a host need not special-case the empty field.

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

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

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§