tui_widget_list/
lib.rs

1//!<div align="center">
2//!
3//! # tui-widget-list: A versatile widget list for Ratatui
4//!
5//! [![Crate Badge]](https://crates.io/crates/tui-widget-list) [![Continuous Integration](https://github.com/preiter93/tui-widget-list/actions/workflows/ci.yml/badge.svg)](https://github.com/preiter93/tui-widget-list/actions/workflows/ci.yml) [![Deps Status](https://deps.rs/repo/github/preiter93/tui-widget-list/status.svg)](https://deps.rs/repo/github/preiter93/tui-widget-list) [![License Badge]](./LICENSE)
6//!
7//! </div>
8//!
9//! This crate provides a stateful widget `ListView` implementation for `Ratatui`.
10//! The associated `ListState`, offers functionalities such as navigating to the next and previous items.
11//! The list view support both horizontal and vertical scrolling.
12//!
13//!![](https://raw.githubusercontent.com/preiter93/tui-widget-list/main/examples/tapes/variants.gif?v=1)
14//!
15//! ## Configuration
16//! The `ListView` can be customized with the following options:
17//! - `ListView::scroll_axis`: Vertical or horizontal scrolling.
18//! - `ListView::scroll_direction`: Forward or backward layout direction.
19//! - `ListView::scroll_padding`: Padding preserved around the selected item while scrolling.
20//! - `ListView::infinite_scrolling`: Wrap around when scrolling past the first or last element.
21//! - `ListView::style`: Base style of the list.
22//! - `ListView::block`: Optional outer block.
23//! - `ListView::scrollbar`: Optional scrollbar.
24//!
25//! ## Example
26//!```
27//! use ratatui::prelude::*;
28//! use tui_widget_list::{ListBuilder, ListState, ListView};
29//!
30//! let builder = ListBuilder::new(|context| {
31//!     let mut item = Line::from(format!("Item {}", context.index));
32//!     if context.is_selected {
33//!         item = item.style(Style::default().bg(Color::Rgb(255, 153, 0)));
34//!     }
35//!     (item, 1)
36//! });
37//!
38//! let mut state = ListState::default();
39//! let list = ListView::new(builder, 20);
40//!```
41//!
42//! ## Mouse handling
43//!
44//! You can handle mouse clicks using `ListState` via `hit_test`:
45//!```ignore
46//! use tui_widget_list::hit_test::Hit;
47//!
48//! match event::read()? {
49//!     Event::Mouse(MouseEvent {
50//!         kind: MouseEventKind::Down(MouseButton::Left),
51//!         column,
52//!         row,
53//!         ..
54//!     }) => match state.hit_test(column, row) {
55//!         Some(Hit::Item(index)) => state.select(Some(index)),
56//!         Some(Hit::Area) | None => {}
57//!     },
58//!     Event::Mouse(MouseEvent {
59//!         kind: MouseEventKind::ScrollUp,
60//!         ..
61//!     }) => {
62//!         state.previous();
63//!     }
64//!     Event::Mouse(MouseEvent {
65//!         kind: MouseEventKind::ScrollDown,
66//!         ..
67//!     }) => {
68//!         state.next();
69//!     }
70//!     _ => {}
71//! }
72//!```
73//!
74//! ## Documentation
75//! For more examples see [tui-widget-list](https://github.com/preiter93/tui-widget-list/tree/main/examples). For documentation see [docs.rs](https://docs.rs/tui-widget-list/).
76//!
77//! [Crate Badge]: https://img.shields.io/crates/v/tui-widget-list?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
78//! [License Badge]: https://img.shields.io/crates/l/tui-widget-list?style=flat-square&color=1370D3
79pub mod hit_test;
80pub(crate) mod state;
81pub(crate) mod utils;
82pub(crate) mod view;
83
84pub use state::ListState;
85pub use view::{ListBuildContext, ListBuilder, ListView, ScrollAxis, ScrollDirection};
tui_widget_list/lib.rs

tui_widget_list/
lib.rs
