tui_scrollview/
lib.rs

1//! A [Ratatui] widget to build smooth scrollable views. Part of the [tui-widgets] suite by
2//! [Joshka].
3//!
4//! ![Demo](https://vhs.charm.sh/vhs-6PuT3pdwSTp4aTvKrCBx9F.gif)
5//!
6//! (Note: a github bug stops the example gif above being displayed, but you can view it at:
7//! <https://vhs.charm.sh/vhs-6PuT3pdwSTp4aTvKrCBx9F.gif>)
8//!
9//! [![Crate badge]][Crate]
10//! [![Docs Badge]][Docs]
11//! [![Deps Badge]][Dependency Status]
12//! [![License Badge]][License]
13//! [![Coverage Badge]][Coverage]
14//! [![Discord Badge]][Ratatui Discord]
15//!
16//! [GitHub Repository] · [API Docs] · [Examples] · [Changelog] · [Contributing]
17//!
18//! # Installation
19//!
20//! ```shell
21//! cargo add tui-scrollview
22//! ```
23//!
24//! # Usage
25//!
26//! ```rust
27//! use std::iter;
28//!
29//! use ratatui::layout::Size;
30//! use ratatui::prelude::*;
31//! use ratatui::widgets::*;
32//! use tui_scrollview::{ScrollView, ScrollViewState};
33//!
34//! struct MyScrollableWidget;
35//!
36//! impl StatefulWidget for MyScrollableWidget {
37//!     type State = ScrollViewState;
38//!
39//!     fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
40//!         // 100 lines of text
41//!         let line_numbers = (1..=100).map(|i| format!("{:>3} ", i)).collect::<String>();
42//!         let content =
43//!             iter::repeat("Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n")
44//!                 .take(100)
45//!                 .collect::<String>();
46//!
47//!         let content_size = Size::new(100, 30);
48//!         let mut scroll_view = ScrollView::new(content_size);
49//!
50//!         // the layout doesn't have to be hardcoded like this, this is just an example
51//!         scroll_view.render_widget(Paragraph::new(line_numbers), Rect::new(0, 0, 5, 100));
52//!         scroll_view.render_widget(Paragraph::new(content), Rect::new(5, 0, 95, 100));
53//!
54//!         scroll_view.render(buf.area, buf, state);
55//!     }
56//! }
57//! ```
58//!
59//! Store the `ScrollView` if its content is expensive to rebuild or changes independently from the
60//! frame render. A stored scroll view can be rendered by reference while `ScrollViewState` keeps
61//! the current offset.
62//!
63//! ```rust
64//! use ratatui::prelude::*;
65//! use tui_scrollview::{ScrollView, ScrollViewState};
66//!
67//! struct App {
68//!     scroll_view: ScrollView,
69//!     scroll_view_state: ScrollViewState,
70//! }
71//!
72//! impl App {
73//!     fn draw(&mut self, frame: &mut Frame) {
74//!         frame.render_stateful_widget(
75//!             &self.scroll_view,
76//!             frame.area(),
77//!             &mut self.scroll_view_state,
78//!         );
79//!     }
80//! }
81//! ```
82//!
83//! # Full Example
84//!
85//! A full example can be found in the [examples directory].
86//! [scrollview.rs]
87//!
88//! This example shows a scrollable view with two paragraphs of text, one for the line numbers and
89//! one for the text. On top of this a Gauge widget is rendered to show that this can be used in
90//! combination with any other widget.
91//!
92//! # More widgets
93//!
94//! For the full suite of widgets, see [tui-widgets].
95//!
96//! [Crate]: https://crates.io/crates/tui-scrollview
97//! [Docs]: https://docs.rs/tui-scrollview/
98//! [Dependency Status]: https://deps.rs/repo/github/ratatui/tui-widgets
99//! [Coverage]: https://app.codecov.io/gh/ratatui/tui-widgets
100//! [Ratatui Discord]: https://discord.gg/pMCEU9hNEj
101//! [Crate badge]: https://img.shields.io/crates/v/tui-scrollview?logo=rust&style=flat
102//! [Docs Badge]: https://img.shields.io/docsrs/tui-scrollview?logo=rust&style=flat
103//! [Deps Badge]: https://deps.rs/repo/github/ratatui/tui-widgets/status.svg?style=flat
104//! [License Badge]: https://img.shields.io/crates/l/tui-scrollview?style=flat
105//! [License]: https://github.com/ratatui/tui-widgets/blob/main/LICENSE-MIT
106//! [Coverage Badge]:
107//!     https://img.shields.io/codecov/c/github/ratatui/tui-widgets?logo=codecov&style=flat
108//! [Discord Badge]: https://img.shields.io/discord/1070692720437383208?logo=discord&style=flat
109//!
110//! [GitHub Repository]: https://github.com/ratatui/tui-widgets
111//! [API Docs]: https://docs.rs/tui-scrollview/
112//! [Examples]: https://github.com/ratatui/tui-widgets/tree/main/tui-scrollview/examples
113//! [examples directory]: https://github.com/ratatui/tui-widgets/tree/main/tui-scrollview/examples
114//! [scrollview.rs]:
115//!     https://github.com/ratatui/tui-widgets/tree/main/tui-scrollview/examples/scrollview.rs
116//! [Changelog]: https://github.com/ratatui/tui-widgets/blob/main/tui-scrollview/CHANGELOG.md
117//! [Contributing]: https://github.com/ratatui/tui-widgets/blob/main/CONTRIBUTING.md
118//!
119//! [Ratatui]: https://crates.io/crates/ratatui
120//!
121//! [Joshka]: https://github.com/joshka
122//! [tui-widgets]: https://crates.io/crates/tui-widgets
123
124mod scroll_view;
125mod state;
126
127pub use scroll_view::{ScrollView, ScrollbarVisibility};
128pub use state::ScrollViewState;
tui_scrollview/lib.rs

tui_scrollview/
lib.rs
