Tui Scrollview

https://docs.rs/tui-scrollview/latest/tui_scrollview/
Admin
Tui Scrollview is a Ratatui widget that enables smooth, scrollable views for terminal user...
Tokens:3,991
Snippets:44
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Implement a Scrollable Widget

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/index.html

This example demonstrates how to create a custom StatefulWidget that uses ScrollView to render scrollable content. It includes rendering line numbers and a large block of text. Ensure you have the necessary Ratatui and tui-scrollview imports.

```rust
use std::iter;

use ratatui::layout::Size;
use ratatui::prelude::*;
use ratatui::widgets::*;
use tui_scrollview::{ScrollView, ScrollViewState};

struct MyScrollableWidget;

impl StatefulWidget for MyScrollableWidget {
    type State = ScrollViewState;

    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
        // 100 lines of text
        let line_numbers = (1..=100).map(|i| format!("{:>3} ", i)).collect::<String>();
        let content =
            iter::repeat("Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n")
                .take(100)
                .collect::<String>();

        let content_size = Size::new(100, 30);
        let mut scroll_view = ScrollView::new(content_size);

        // the layout doesn't have to be hardcoded like this, this is just an example
        scroll_view.render_widget(Paragraph::new(line_numbers), Rect::new(0, 0, 5, 100));
        scroll_view.render_widget(Paragraph::new(content), Rect::new(5, 0, 95, 100));

        scroll_view.render(buf.area, buf, state);
    }
}

```

--------------------------------

### Create and Render ScrollView

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Demonstrates creating a ScrollView with a specific buffer size, rendering widgets into its buffer, and then rendering the visible portion of the ScrollView into the main buffer. It also shows programmatic scrolling and state management.

```rust
use ratatui::{prelude::*, layout::Size, widgets::*};
use tui_scrollview::{ScrollView, ScrollViewState};

let mut scroll_view = ScrollView::new(Size::new(20, 20));

// render a few widgets into the buffer at various positions
scroll_view.render_widget(Paragraph::new("Hello, world!"), Rect::new(0, 0, 20, 1));
scroll_view.render_widget(Paragraph::new("Hello, world!"), Rect::new(10, 10, 20, 1));
scroll_view.render_widget(Paragraph::new("Hello, world!"), Rect::new(15, 15, 20, 1));

// You can also render widgets into the buffer programmatically
Line::raw("Hello, world!").render(Rect::new(0, 0, 20, 1), scroll_view.buf_mut());

// usually you would store the state of the scroll view in a struct that implements
// StatefulWidget (or in your app state if you're using an `App` struct)
let mut state = ScrollViewState::default();

// you can also scroll the view programmatically
state.scroll_down();

// render the scroll view into the main buffer at the given position within a widget
let scroll_view_area = Rect::new(0, 0, 10, 10);
scroll_view.render(scroll_view_area, buf, &mut state);
// or if you're rendering in a terminal draw closure instead of from within another widget:
frame.render_stateful_widget(scroll_view, frame.size(), state);
```

--------------------------------

### ScrollViewState Methods

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollViewState.html

This section details the public methods available for interacting with ScrollViewState.

```APIDOC
## ScrollViewState

### `new()`

Create a new scroll view state with an offset of (0, 0).

#### Signature

```rust
pub fn new() -> Self
```

### `with_offset(offset: Position)`

Create a new scroll view state with the given offset.

#### Signature

```rust
pub fn with_offset(offset: Position) -> Self
```

### `set_offset(&mut self, offset: Position)`

Set the offset of the scroll view state.

#### Signature

```rust
pub const fn set_offset(&mut self, offset: Position)
```

### `offset(&self) -> Position`

Get the offset of the scroll view state.

#### Signature

```rust
pub const fn offset(&self) -> Position
```

### `scroll_up(&mut self)`

Move the scroll view state up by one row.

#### Signature

```rust
pub const fn scroll_up(&mut self)
```

### `scroll_down(&mut self)`

Move the scroll view state down by one row.

#### Signature

```rust
pub const fn scroll_down(&mut self)
```

### `scroll_page_down(&mut self)`

Move the scroll view state down by one page.

#### Signature

```rust
pub fn scroll_page_down(&mut self)
```

### `scroll_page_up(&mut self)`

Move the scroll view state up by one page.

#### Signature

```rust
pub fn scroll_page_up(&mut self)
```

### `scroll_left(&mut self)`

Move the scroll view state left by one column.

#### Signature

```rust
pub const fn scroll_left(&mut self)
```

### `scroll_right(&mut self)`

Move the scroll view state right by one column.

#### Signature

```rust
pub const fn scroll_right(&mut self)
```

### `scroll_to_top(&mut self)`

Move the scroll view state to the top of the buffer.

#### Signature

```rust
pub const fn scroll_to_top(&mut self)
```

### `scroll_to_bottom(&mut self)`

Move the scroll view state to the bottom of the buffer.

#### Signature

```rust
pub fn scroll_to_bottom(&mut self)
```
```

--------------------------------

### Render Widget into ScrollView Buffer

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Shows how to render a widget directly into the ScrollView's internal buffer using `buf_mut()`. This is useful for programmatic drawing within the scrollable area.

```rust
let mut scroll_view = ScrollView::new(Size::new(20, 20));
Line::raw("Hello, world!").render(Rect::new(0, 0, 20, 1), scroll_view.buf_mut());
```

--------------------------------

### Add tui-scrollview to Project

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/index.html

Use this command to add the tui-scrollview crate as a dependency to your Rust project.

```bash
cargo add tui-scrollview
```

--------------------------------

### ScrollView::new

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Creates a new ScrollView with a specified buffer size. The buffer coordinates range from (0, 0) to (size.width, size.height).

```APIDOC
## ScrollView::new

### Description
Create a new scroll view with a buffer of the given size
The buffer will be empty, with coordinates ranging from (0, 0) to (size.width, size.height).

### Method
`pub fn new(size: Size) -> Self`
```

--------------------------------

### render_stateful_widget

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Renders a stateful widget into the scroll buffer. This is equivalent to Frame::render_stateful_widget but targets the scroll buffer.

```APIDOC
## pub fn render_stateful_widget<W: StatefulWidget>(
  &mut self,
  widget: W,
  area: Rect,
  state: &mut W::State,
)

### Description
Render a stateful widget into the scroll buffer.
This is the equivalent of `Frame::render_stateful_widget`, but renders the stateful widget into the scroll buffer rather than the main buffer. The stateful widget will be rendered into the area of the buffer specified by the `area` parameter.
This should not be confused with the `render` method, which renders the visible area of the ScrollView into the main buffer.

### Parameters
#### Path Parameters
- **widget** (W: StatefulWidget) - Description: The stateful widget to render.
- **area** (Rect) - Description: The area of the buffer to render the widget into.
- **state** (W::State) - Description: The mutable state of the stateful widget.
```

--------------------------------

### TryInto Trait Implementation

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollViewState.html

Provides a fallible conversion from one type to another, leveraging the TryFrom trait.

```APIDOC
## impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

### Associated Type
#### type Error = <U as TryFrom<T>>::Error

Description:
The type returned in the event of a conversion error.

### Methods
#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Description:
Performs the conversion.
```

--------------------------------

### TryFrom Trait Implementation

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollViewState.html

Enables attempting to convert one type into another, with a defined error type for failures.

```APIDOC
## impl<T, U> TryFrom<U> for T
where U: Into<T>,

### Associated Type
#### type Error = Infallible

Description:
The type returned in the event of a conversion error.

### Methods
#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Description:
Performs the conversion.
```

--------------------------------

### ScrollView::render_widget

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Renders a given widget into the scroll buffer at the specified area. This is analogous to `Frame::render_widget` but targets the scroll buffer.

```APIDOC
## ScrollView::render_widget

### Description
Render a widget into the scroll buffer
This is the equivalent of `Frame::render_widget`, but renders the widget into the scroll buffer rather than the main buffer. The widget will be rendered into the area of the buffer specified by the `area` parameter.
This should not be confused with the `render` method, which renders the visible area of the ScrollView into the main buffer.

### Method
`pub fn render_widget<W: Widget>(&mut self, widget: W, area: Rect)`
```

--------------------------------

### ScrollView::buf_mut

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Provides mutable access to the buffer, allowing programmatic rendering of widgets into it.

```APIDOC
## ScrollView::buf_mut

### Description
The mutable buffer containing the contents of the scroll view
This can be used to render widgets into the buffer programmatically

### Method
`pub const fn buf_mut(&mut self) -> &mut Buffer`

### Examples
```
let mut scroll_view = ScrollView::new(Size::new(20, 20));
Line::raw("Hello, world!").render(Rect::new(0, 0, 20, 1), scroll_view.buf_mut());
```
```

--------------------------------

### try_into

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Attempts to convert the ScrollView into another type. This method is useful for transforming the ScrollView into a different representation or type that implements the `TryFrom` trait.

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion.

### Method
`try_into`

### Parameters
This method takes `self` by value.

### Return Value
Returns a `Result` which is either the converted type `U` on success, or an error if the conversion fails.
```

--------------------------------

### Set Both Scrollbar Visibilities

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Sets the visibility for both vertical and horizontal scrollbars simultaneously using `ScrollbarVisibility::Automatic`.

```rust
let mut scroll_view =
    ScrollView::new(Size::new(20, 20)).scrollbars_visibility(ScrollbarVisibility::Automatic);
```

--------------------------------

### ScrollView::size

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Returns the content size of the scroll view's buffer.

```APIDOC
## ScrollView::size

### Description
The content size of the scroll view

### Method
`pub const fn size(&self) -> Size`
```

--------------------------------

### ScrollView::buf

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Provides read-only access to the buffer containing the scroll view's contents.

```APIDOC
## ScrollView::buf

### Description
The buffer containing the contents of the scroll view

### Method
`pub const fn buf(&self) -> &Buffer`
```

--------------------------------

### Automatic Scrollbar Visibility

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/enum.ScrollbarVisibility.html

Use this variant to render scrollbars only when they are needed. This is the default behavior for many UI elements.

```rust
ScrollbarVisibility::Automatic
```

--------------------------------

### Set Horizontal Scrollbar Visibility

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Configures the visibility of the horizontal scrollbar for the ScrollView. Use `ScrollbarVisibility::Never` to hide it completely.

```rust
let mut scroll_view = ScrollView::new(Size::new(20, 20))
    .horizontal_scrollbar_visibility(ScrollbarVisibility::Never);
```

--------------------------------

### Default ScrollbarVisibility

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/enum.ScrollbarVisibility.html

Retrieves the default value for ScrollbarVisibility, which is typically Automatic.

```rust
ScrollbarVisibility::default()
```

--------------------------------

### Never Visible Scrollbar

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/enum.ScrollbarVisibility.html

Use this variant to completely hide scrollbars, even if the content is scrollable. This is useful for minimalist UIs or when scrollability is indicated by other means.

```rust
ScrollbarVisibility::Never
```

--------------------------------

### ScrollbarVisibility Enum Definition

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/enum.ScrollbarVisibility.html

Defines the possible states for scrollbar visibility.

```APIDOC
## Enum ScrollbarVisibility

### Description
The visbility of the vertical and horizontal scrollbars.

### Variants

#### Automatic
Render the scrollbar only whenever needed.

#### Always
Always render the scrollbar.

#### Never
Never render the scrollbar (hide it).
```

--------------------------------

### Set Vertical Scrollbar Visibility

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Configures the visibility of the vertical scrollbar for the ScrollView. Use `ScrollbarVisibility::Always` to ensure it's always shown.

```rust
let mut scroll_view = ScrollView::new(Size::new(20, 20))
    .vertical_scrollbar_visibility(ScrollbarVisibility::Always);
```

--------------------------------

### Always Visible Scrollbar

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/enum.ScrollbarVisibility.html

Use this variant to ensure scrollbars are always displayed, regardless of whether content exceeds the viewable area.

```rust
ScrollbarVisibility::Always
```

--------------------------------

### ToOwned Trait Implementation

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollViewState.html

Provides methods for creating owned data from borrowed data and updating owned data with borrowed data.

```APIDOC
## impl<T> ToOwned for T
where T: Clone,

### Associated Type
#### type Owned = T

Description:
The resulting type after obtaining ownership.

### Methods
#### fn to_owned(&self) -> T

Description:
Creates owned data from borrowed data, usually by cloning.

#### fn clone_into(&self, target: &mut T)

Description:
Uses borrowed data to replace owned data, usually by cloning.
```

--------------------------------

### ScrollbarVisibility Enum Definition

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/enum.ScrollbarVisibility.html

Defines the possible states for scrollbar visibility: Automatic, Always, or Never.

```rust
pub enum ScrollbarVisibility {
    Automatic,
    Always,
    Never,
}
```

--------------------------------

### ScrollView::area

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Returns the rectangular area of the buffer that is available to be scrolled.

```APIDOC
## ScrollView::area

### Description
The area of the buffer that is available to be scrolled

### Method
`pub const fn area(&self) -> Rect`
```

--------------------------------

### ScrollView::horizontal_scrollbar_visibility

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Sets the visibility of the horizontal scrollbar. This is a fluent setter that consumes self.

```APIDOC
## ScrollView::horizontal_scrollbar_visibility

### Description
Set the visibility of the horizontal scrollbar
See `ScrollbarVisibility` for all the options.
This is a fluent setter method which must be chained or used as it consumes self

### Method
`pub const fn horizontal_scrollbar_visibility( self, visibility: ScrollbarVisibility, ) -> Self`

### Examples
```
let mut scroll_view = ScrollView::new(Size::new(20, 20))
    .horizontal_scrollbar_visibility(ScrollbarVisibility::Never);
```
```

--------------------------------

### ScrollView::vertical_scrollbar_visibility

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Sets the visibility of the vertical scrollbar. This is a fluent setter that consumes self.

```APIDOC
## ScrollView::vertical_scrollbar_visibility

### Description
Set the visibility of the vertical scrollbar
See `ScrollbarVisibility` for all the options.
This is a fluent setter method which must be chained or used as it consumes self

### Method
`pub const fn vertical_scrollbar_visibility( self, visibility: ScrollbarVisibility, ) -> Self`

### Examples
```
let mut scroll_view = ScrollView::new(Size::new(20, 20))
    .vertical_scrollbar_visibility(ScrollbarVisibility::Always);
```
```

--------------------------------

### ScrollView::scrollbars_visibility

Source: https://docs.rs/tui-scrollview/latest/tui_scrollview/struct.ScrollView.html

Sets the visibility for both vertical and horizontal scrollbars. This is a fluent setter that consumes self.

```APIDOC
## ScrollView::scrollbars_visibility

### Description
Set the visibility of both vertical and horizontal scrollbars
See `ScrollbarVisibility` for all the options.
This is a fluent setter method which must be chained or used as it consumes self

### Method
`pub const fn scrollbars_visibility( self, visibility: ScrollbarVisibility, ) -> Self`

### Examples
```
let mut scroll_view =
    ScrollView::new(Size::new(20, 20)).scrollbars_visibility(ScrollbarVisibility::Automatic);
```
```
Tokens:
Raw