pub struct ListBox { /* private fields */ }Expand description
A concrete list viewer that owns a Vec<String> as its item source.
A concrete list box over a Vec<String>: the first concrete
ListViewer. It holds the items
and delegates all draw/event/nav logic to the shared list-viewer functions via
the ListViewer trait. Only get_text is
overridden; is_selected and select_item inherit the base behavior
(item == focused, and the base broadcasts that an item was selected).
§Population wiring
The constructor sets fields only (empty items, range 0) — no Context is
available at construction. After insertion into a group:
- Call
new_listto populate the items and publish the vertical-bar range + focus position. - Call
list_viewer::update_stepsto publish the page/arrow step sizes to the bars.
Missing step 1 leaves the list empty; missing step 2 leaves the scrollbar
thumb unsized. Both require a Context, so they cannot run in the constructor.
§The focused item as a value
The list box’s value is its focused item index. Scattering a
value back (focusing an item) is done through
set_value_ctx rather than the plain
set_value, because focusing an item must republish the
scroll-bar position and so needs a Context.
ListBox is the standard list widget: embed it in a dialog or group,
call new_list after insertion to populate and wire
the scroll bar, then read the user’s selection back via
value. It reuses all shared draw/event/navigation logic
from the ListViewer trait; only get_text is
overridden — every other hook (selection highlight, keyboard scroll,
mouse drag) is handled by the trait’s default implementations.
§Turbo Vision heritage
Ports TListBox (tlistbox.cpp). The list-record get/set hooks become the
typed value protocol (D10); mouse press-and-hold, auto-scroll, and resize
handling all live in the shared list-viewer base.
Implementations§
Source§impl ListBox
impl ListBox
Sourcepub fn new(
bounds: Rect,
num_cols: i32,
h: Option<ViewId>,
v: Option<ViewId>,
) -> Self
pub fn new( bounds: Rect, num_cols: i32, h: Option<ViewId>, v: Option<ViewId>, ) -> Self
Create a new, empty list box wired to optional scroll bars.
Pass the ViewId of a ScrollBar for h
and/or v to connect the horizontal and vertical bars; pass None if
no bar is needed. The item list starts empty and the range is 0 —
nothing is drawn until you call new_list after
inserting this widget into its parent group.
§Example
let lb = ListBox::new(bounds, 1, None, Some(vbar_id));
// insert lb into its group, then:
lb.new_list(vec!["Item A".into(), "Item B".into()], ctx);Sourcepub fn with_find(self, mode: FindMode) -> Self
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 source by the query; Highlight
only owns the query + highlight (the host supplies the rows).
Sourcepub fn new_list(&mut self, items: Vec<String>, ctx: &mut Context<'_>)
pub fn new_list(&mut self, items: Vec<String>, ctx: &mut Context<'_>)
Replace the item collection, update the scroll-bar range, and focus item 0.
This is the primary way to populate (or repopulate) a ListBox. Call
it after the widget has been inserted into its parent group so that
the scroll-bar ViewIds are resolvable. After this call, also invoke
list_viewer::update_steps to publish the
page and arrow step sizes to the bars.
On an empty items vec the range is set to 0 and focus stays at 0;
focus_item(0) is skipped. On a non-empty vec focus always resets to
item 0 — to restore a prior selection scatter the index back afterwards
with set_value_ctx.
Sourcepub fn list(&self) -> &[String]
pub fn list(&self) -> &[String]
The current item collection as a read-only slice.
Use this to inspect or copy the items without modifying them. To
replace the collection, call new_list — that
method also republishes the scroll-bar range, which a direct
Vec write would miss. 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 ListBox
impl ListViewer for ListBox
Source§fn get_text(&self, item: i32) -> String
fn get_text(&self, item: i32) -> String
Return the text for item from the owned Vec.
An out-of-bounds index (including an empty list) returns an empty string.
Source§fn lv(&self) -> &ListViewerState
fn lv(&self) -> &ListViewerState
ListViewerState.Source§fn lv_mut(&mut self) -> &mut ListViewerState
fn lv_mut(&mut self) -> &mut ListViewerState
ListViewerState.Source§fn on_query_changed(&mut self, ctx: &mut Context<'_>)
fn on_query_changed(&mut self, ctx: &mut Context<'_>)
handle_event and by Self::set_find_query
(including Self::clear_find).Source§fn list_roles(&self) -> ListRoles
fn list_roles(&self) -> ListRoles
Source§fn is_selected(&self, item: i32) -> bool
fn is_selected(&self, item: i32) -> bool
item should be drawn in the selected color. Read moreSource§fn item_role(&self, _item: i32) -> Option<Role>
fn item_role(&self, _item: i32) -> Option<Role>
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<'_>)
fn select_item(&mut self, _item: i32, ctx: &mut Context<'_>)
item (double-click, Space, or Enter). Read moreSource§fn on_focus_changed(&mut self, _ctx: &mut Context<'_>)
fn on_focus_changed(&mut self, _ctx: &mut Context<'_>)
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>
fn find_query(&self) -> Option<&str>
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<'_>)
fn set_find_query(&mut self, query: &str, ctx: &mut Context<'_>)
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 moreSource§fn clear_find(&mut self, ctx: &mut Context<'_>)
fn clear_find(&mut self, ctx: &mut Context<'_>)
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 View for ListBox
impl View for ListBox
Source§fn on_bounds_changed(&mut self, ctx: &mut Context<'_>)
fn on_bounds_changed(&mut self, ctx: &mut Context<'_>)
Republish the scroll-bar steps after a bounds change.
Source§fn value(&self) -> Option<FieldValue>
fn value(&self) -> Option<FieldValue>
The focused item’s index as a FieldValue::Int.
This is the dialog-gather value: it captures which item the user chose, not the item text. Call this after the user closes the dialog (or at any point) to read the current selection.
The item collection itself is not part of this value — it is
configuration set once via new_list and does not
travel through the gather/scatter cycle.
Source§fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)
fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)
Focus the item at index and republish the vertical scroll bar.
Use this to restore a previously gathered selection (dialog scatter):
pass back the FieldValue::Int that value() returned. The item
list is not replaced — only the focused index changes. If you also
need to repopulate the list, call new_list first,
then scatter the index with this method.
An out-of-range index is clamped to 0..range (so scatter after a
shorter re-population is safe). Non-Int variants are silently
ignored.
Source§fn draw(&mut self, ctx: &mut DrawCtx<'_>)
fn draw(&mut self, ctx: &mut DrawCtx<'_>)
ctx. Must be overridden. Read moreSource§fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)
fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)
Source§fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)
fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)
StateFlag::Focused, emits the focus broadcast
(RECEIVED_FOCUS/RELEASED_FOCUS) via ctx. Read moreSource§fn cursor_request(&self) -> Option<Point>
fn cursor_request(&self) -> Option<Point>
None to
hide it. Base: Some(cursor) iff the view is focused with a visible cursor,
else None. Read moreSource§fn apply_scroll_sync(
&mut self,
h: Option<i32>,
v: Option<i32>,
ctx: &mut Context<'_>,
)
fn apply_scroll_sync( &mut self, h: Option<i32>, v: Option<i32>, ctx: &mut Context<'_>, )
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 moreSource§fn as_any_mut(&mut self) -> Option<&mut dyn Any>
fn as_any_mut(&mut self) -> Option<&mut dyn Any>
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
fn valid(&mut self, _cmd: Command, _ctx: &mut Context<'_>) -> bool
cmd (e.g. a modal end / focus
release). Base is always true. Read moreSource§fn set_modal_answer(&mut self, _cmd: Command)
fn set_modal_answer(&mut self, _cmd: Command)
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)
fn set_value(&mut self, _v: FieldValue)
FieldValue into this control. Read moreSource§fn set_modal_data(&mut self, _data: FieldValue)
fn set_modal_data(&mut self, _data: FieldValue)
Source§fn awaken(&mut self)
fn awaken(&mut self)
Source§fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect
fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect
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)
fn change_bounds(&mut self, bounds: Rect)
bounds to this view and propagate as needed. Read moreSource§fn caret_size(&self) -> u8
fn caret_size(&self) -> u8
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 moreSource§fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>
fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>
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
fn remove_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool
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
fn focus_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool
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 moreSource§fn has_focusable_leaf(&self) -> bool
fn has_focusable_leaf(&self) -> bool
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
fn focus_to_edge(&mut self, backward: bool, ctx: &mut Context<'_>) -> bool
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 moreSource§fn reset_current(&mut self, _ctx: &mut Context<'_>)
fn reset_current(&mut self, _ctx: &mut Context<'_>)
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<'_>)
fn settle_currency(&mut self, _ctx: &mut Context<'_>)
Source§fn set_visible_descendant(
&mut self,
id: ViewId,
visible: bool,
ctx: &mut Context<'_>,
) -> bool
fn set_visible_descendant( &mut self, id: ViewId, visible: bool, ctx: &mut Context<'_>, ) -> bool
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 moreSource§fn number(&self) -> Option<i16>
fn number(&self) -> Option<i16>
None);
Window overrides to return its number when > 0
(0 means unnumbered → None).Source§fn grabs_focus_on_click(&self) -> bool
fn grabs_focus_on_click(&self) -> bool
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
fn select_window_num(&mut self, num: i16, ctx: &mut Context<'_>) -> bool
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)
fn tile(&mut self, _r: Rect)
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)
fn cascade(&mut self, _r: Rect)
Desktop overrides.menu::menu_view::update_menu_commands
implements the re-gray walk. Read moreMenuBar / MenuBox)
override to set their
MenuViewState::current — the write-only
display cache their draw reads to pick the selected colour. Read moreSource§fn get_help_ctx(&self) -> HelpCtx
fn get_help_ctx(&self) -> HelpCtx
HelpCtx::DRAGGING while the view is being dragged, otherwise the
view’s own ViewState::help_ctx. Read moreSource§fn descendant_global_bounds(&self, _id: ViewId, _acc: Point) -> Option<Rect>
fn descendant_global_bounds(&self, _id: ViewId, _acc: Point) -> Option<Rect>
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)
fn set_indicator_value(&mut self, _location: Point, _modified: bool)
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<'_>)
fn apply_page_sync(&mut self, _idx: usize, _ctx: &mut Context<'_>)
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§
impl Freeze for ListBox
impl RefUnwindSafe for ListBox
impl Send for ListBox
impl Sync for ListBox
impl Unpin for ListBox
impl UnsafeUnpin for ListBox
impl UnwindSafe for ListBox
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
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)
fn as_any(&self) -> &(dyn Any + 'static)
&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)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.