Expand description
The abstract base for every list widget (ListBox,
history viewers, color/file lists). It lays out range items in num_cols
columns, tracks a focused item and a top_item scroll offset, and drives
two sibling scroll bars that live on the window frame.
§A trait, not a concrete struct
A list box reuses the base draw (it does not override it) and overrides
get_text/is_selected. A concrete-struct-embedded base physically cannot
dispatch from the base’s own draw back into the embedder’s get_text. So
the abstract base is modeled as a trait (the same pattern as
Validator): ListViewer carries the
overridable methods, ListViewerState carries the data members, and the
shared draw/event/nav logic lives as free functions generic over
<L: ListViewer + ?Sized> so a concrete widget’s View impl reuses them
verbatim while they call back into get_text/is_selected/select_item.
ListViewer is intentionally not object-safe (get_text -> String);
that is fine — concrete widgets are stored as Box<dyn View>, and
ListViewer is only ever a generic bound behind a concrete type.
§The cross-view scrollbar read-sync
A list viewer holds only &mut Context during dispatch and so can neither
read nor mutate its window-frame sibling scroll bars. The pump is the
broker: the list stores its bars as Option<ViewId> handles and a cached
indent (the live horizontal-bar value the draw
needs, refreshed by the read-sync). On a
SCROLL_BAR_CHANGED broadcast
naming one of its bars as source, the list requests
Deferred::ScrollSync; the pump
reads both bars’ values and calls back through
View::apply_scroll_sync →
apply_scroll.
§Termination
Unlike a plain scroller, this read-sync writes back: apply_scroll’s
vertical-bar branch runs focus_item_num → focus_item → a vertical-bar
set_value(focused). That would re-broadcast the changed signal and
re-enter the sync — except
ScrollBar::set_params is
change-guarded (re-broadcasts only on an actual value change), so the
write-back of the already-current value is a silent no-op. Steady state
(bar == focused): quiescent. After a clamp: one extra round, then quiescent.
§Mouse press-and-hold
A mouse-down arms the mouse-track capture; the subsequent move/auto/up events route the hold loop, auto-scrolling when the mouse moves out of view (skipping four auto ticks per step).
§Colors
Each list role is a Role: Role::ListNormal /
Role::ListInactive / Role::ListSurface / Role::ListFocused /
Role::ListSelected / Role::ListDivider. A subclass that wanted a
different palette surfaces a different ListRoles sextet from
ListViewer::list_roles.
§Resizing
The scroll-bar step republish on a bounds change is not wired, because nothing
currently resizes a list viewer’s bounds. A future resize consumer must apply
the resize step formula directly — vertical bar set_step(size.y, …) and
horizontal bar set_step(size.x / num_cols, …), both preserving the existing
arrow step — and must NOT reuse update_steps, which reproduces the
constructor formula instead.
§Turbo Vision heritage
Ports TListViewer (tlstview.cpp). The abstract-class inheritance becomes a
trait plus a state struct plus generic free functions (D2), because the base’s
draw must call back into the subclass’s get_text. Owner back-pointers to the
sibling scroll bars become ViewId handles brokered by the event loop (D3),
and the palette becomes Roles.
Structs§
- List
Roles - The six
Roles thatdrawmaps its color matrix through. - List
Viewer State - The shared state of every list-viewer. A concrete list widget embeds one and
exposes it via
ListViewer::lv/ListViewer::lv_mut.
Enums§
- Find
Mode - Find-and-highlight mode for a list. Opt-in; the default
FindMode::Offkeeps the classic type-to-search prefix lookup unchanged.
Constants§
- KB_
SHIFT - The shift mask = left-shift | right-shift =
0x01 | 0x02. The incremental-search state machine captures it at thesearch_pos -1↔0transition; file/dir subclasses testshift_state() & KB_SHIFT.
Traits§
- List
Viewer - The abstract list-viewer base, as a trait of overridable methods.
- Sorted
Search - The type-to-search hooks — the polymorphic parts of the incremental-search
state machine. The shared machine is
sorted_handle_event+sorted_cursor; concrete widgets (a sorted list box, a file list) implement these.
Functions§
- apply_
scroll - The body of the scroll-bar-changed read-sync, called by the pump (the read
broker) after it resolves both bars and reads their
values. - draw
- Render the
rangeitems innum_colscolumns. Reused verbatim by concrete list widgets; calls back intoget_text/is_selected. - focus_
item - Set
focused = item, push the new value to the vertical bar, and adjusttop_itemso the focused item is visible. - focus_
item_ num - Clamp
iteminto the valid range, then focus it (only when the list is non-empty). - focused_
cursor - The view-local cursor position the focused cell sits at, or
Noneif no focused cell is visible. Computed&self-only so a concrete widget can surface it viaView::cursor_request. - handle_
event - Mouse + keyboard nav + the scrollbar broadcast filter. Reused verbatim by concrete list widgets.
- on_
bounds_ changed - The resize-step formula — called from
on_bounds_changedfor concreteListViewerimplementors. - set_
range - Set the list length, resetting
focusedif it now falls past the end, and (re)publish the vertical bar’s range. - set_
state - Update a state flag and propagate scrollbar visibility.
- sorted_
cursor - The cursor advanced past the matched prefix.
- sorted_
handle_ event - The incremental type-to-search state machine. Reusable verbatim by every
SortedSearchwidget (a sorted list box, a file list). - update_
steps - The list-viewer construction step formula — (re)publish each bar’s
page/arrow step. Exposed as a
Context-taking entry the consumer/test calls after insertion (the no-Contextconstructor cannot reach the bars — the same constraint the scroller hit).