Guide API
Skip to main content

Module list_viewer

Module list_viewer 

Source
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§

ListRoles
The six Roles that draw maps its color matrix through.
ListViewerState
The shared state of every list-viewer. A concrete list widget embeds one and exposes it via ListViewer::lv/ListViewer::lv_mut.

Enums§

FindMode
Find-and-highlight mode for a list. Opt-in; the default FindMode::Off keeps 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 the search_pos -1↔0 transition; file/dir subclasses test shift_state() & KB_SHIFT.

Traits§

ListViewer
The abstract list-viewer base, as a trait of overridable methods.
SortedSearch
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 range items in num_cols columns. Reused verbatim by concrete list widgets; calls back into get_text / is_selected.
focus_item
Set focused = item, push the new value to the vertical bar, and adjust top_item so the focused item is visible.
focus_item_num
Clamp item into 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 None if no focused cell is visible. Computed &self-only so a concrete widget can surface it via View::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_changed for concrete ListViewer implementors.
set_range
Set the list length, resetting focused if 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 SortedSearch widget (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-Context constructor cannot reach the bars — the same constraint the scroller hit).