Struct List 

pub struct List<'a> { /* private fields */ }

A scrollable, single-column list of plain-text items with a ListState-driven highlighted item: Table’s single-column sibling, sharing its windowing and selection story.

One item renders per line, top-aligned in the area it’s rendered into and clipped to area.width(). state.offset() is the index of the first item drawn: rendering draws whatever window offset names and does not clamp or auto-scroll it, matching Table’s and ListState’s existing “only the caller knows the viewport height” design. Call state.ensure_visible(visible_item_count) before rendering to keep state.selected() on-screen. If selected() is Some and its item falls within the visible window, that item is drawn with an inverted highlight background; if it has scrolled out of view, nothing is highlighted.

item_style and selected_style default to Theme::DARK, as if List::theme had been called; set a different Theme with List::theme/List::theme_on or override a single field with List::item_style/List::selected_style.

As an InteractiveWidget, a single id covers the whole list: a click selects the row under Response::pointer_pos, resolved from this list’s own row geometry (state.offset() plus the pointer’s row within surface.area()) rather than from a separate id per row, and the wheel scrolls it via Response::scroll_delta/ListState::scroll_by.

Selection is style-only by default (a swap to selected_style), the same as before List::highlight_symbol existed. Set it to prefix the selected item with a marker like "> ", the one selection signal that survives set_plain_mode’s style stripping, or that reads clearly on a 16-color backend where selected_style’s background isn’t distinct enough. List::highlight_spacing controls whether that marker column reserves width even when nothing is selected, and List::direction draws the same windowed items from the bottom of the area upward instead of the top downward, for a chat/log-style list that grows upward.

Examples

use retroglyph_core::grid::{Grid, Rect};
use retroglyph_ui::{List, ListState, StatefulWidget, Surface};

let items = ["Alpha", "Bravo", "Charlie"];
let mut state = ListState::new();
state.select(Some(1));

let area = Rect::new(0, 0, 20, 3);
let mut grid = Grid::new(20, 3);
List::new(&items).render(&mut Surface::new(&mut grid, area, 0), &mut state);

Implementations

impl<'a> List<'a>

pub fn new(items: &'a [&'a str]) -> Self

A list of items, styled from Theme::DARK (as if List::theme had been called); set List::theme/List::theme_on for a different Theme or List::item_style/List::selected_style for a one-off override.

pub const fn item_style(self, style: Style) -> Self

Set the style of unselected items.

pub const fn selected_style(self, style: Style) -> Self

Set the style of the selected item, including its background fill.

pub const fn highlight_symbol(self, symbol: &'a str) -> Self

Prefix the selected item with symbol, e.g. "> ". Empty by default (no marker column, the same style-only highlight as before this method existed).

While the marker column is reserved (see List::highlight_spacing), unselected items’ text still starts one column past it, so every item’s text lines up regardless of which row is selected; that reserved column itself is left untouched (not filled) on unselected rows, the same “caller’s backdrop shows through” behavior List::item_style already has for any unset background.

pub const fn highlight_spacing(self, spacing: HighlightSpacing) -> Self

Whether the marker column List::highlight_symbol draws into reserves width even when nothing is selected. Defaults to HighlightSpacing::WhenSelected.

pub const fn direction(self, direction: ListDirection) -> Self

Which end of the area this list’s items render from. Defaults to ListDirection::TopToBottom.

pub fn theme(self, theme: Theme) -> Self

Applies theme’s named roles to this list: item_style becomes theme.fg on theme.panel_bg, and selected_style becomes theme.bg on theme.accent.

item_style sets an explicit background rather than leaving it at Style::new()’s default: an unset background isn’t “transparent” once a real backend draws it (a bare Color::Default cell paints as solid black behind the glyph; see retroglyph-software’s DEFAULT_BG), so this widget assumes it’s drawn on theme.panel_bg, true when composed with a themed super::Panel/super::Modal. Drawing this list directly on the raw screen background instead needs a manual .item_style(...) override afterwards.

Call before any manual List::item_style/List::selected_style override you want to keep.

pub fn theme_on(self, theme: Theme, bg: Color) -> Self

Same as List::theme, but item_style is drawn on bg instead of theme.panel_bg – for a list drawn directly on a backdrop other than a themed super::Panel/ super::Modal’s fill. List::theme is exactly theme_on(theme, theme.panel_bg).

Trait Implementations

impl<'a> Clone for List<'a>

fn clone(&self) -> List<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for List<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Id> InteractiveWidget<Id> for List<'_>

fn sense(&self) -> Sense

A single id covers the whole list: clicking resolves which row via Response::pointer_pos and this list’s own row geometry, rather than each row registering its own id.

type State = ListState

State that outlives one render call, e.g. a selection index or scroll offset. () for widgets that have none.

fn render( &self, surface: &mut Surface<'_>, state: &mut Self::State, response: Response<Id>, )

Draw into surface, styled by response, which the caller already resolved (via Interaction::interact) for surface.area() and sense.

impl Measure for List<'_>

fn height_for(&self, _width: u16) -> u16

One row per item; width is ignored, since items are truncated rather than wrapped.

impl StatefulWidget for List<'_>

type State = ListState

The externally owned state this widget reads and/or updates while rendering.

fn render(&self, surface: &mut Surface<'_>, state: &mut Self::State)

Draw this widget into surface, filling surface.area(), using and/or updating state.

impl<'a> Copy for List<'a>