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§
Sourcefn lv(&self) -> &ListViewerState
fn lv(&self) -> &ListViewerState
Borrow the embedded ListViewerState.
Sourcefn lv_mut(&mut self) -> &mut ListViewerState
fn lv_mut(&mut self) -> &mut ListViewerState
Mutably borrow the embedded ListViewerState.
Provided Methods§
Sourcefn get_text(&self, _item: i32) -> String
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.
Sourcefn list_roles(&self) -> ListRoles
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.
Sourcefn is_selected(&self, item: i32) -> bool
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.
Sourcefn item_role(&self, _item: i32) -> Option<Role>
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.
Sourcefn select_item(&mut self, _item: i32, ctx: &mut Context<'_>)
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).
Sourcefn on_focus_changed(&mut self, _ctx: &mut Context<'_>)
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.
Sourcefn find_query(&self) -> Option<&str>
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.
Sourcefn set_find_query(&mut self, query: &str, ctx: &mut Context<'_>)
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.
Sourcefn clear_find(&mut self, ctx: &mut Context<'_>)
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.
Sourcefn on_query_changed(&mut self, _ctx: &mut Context<'_>)
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".