Struct ScrollMetrics 

pub struct ScrollMetrics { /* private fields */ }

Precomputed values for proportional scrollbars.

All positions are tracked in subcell units (1/8 of a terminal cell). Use this type to compute thumb length, travel, and hit testing without rendering anything. The inputs are:

• content_len and viewport_len in logical units (zero treated as 1)
• track_cells in terminal cells

Implementations

impl ScrollMetrics

pub fn from_lengths( lengths: ScrollLengths, offset: usize, track_cells: u16, ) -> Self

Build metrics using a crate::ScrollLengths helper.

pub fn new(lengths: ScrollLengths, offset: usize, track_cells: u16) -> Self

Build metrics for the given content and viewport lengths.

The track_cells parameter is the number of terminal cells available for the track (height for vertical scrollbars, width for horizontal). The lengths are logical units. When content_len is smaller than viewport_len, the thumb fills the track to indicate no scrolling. Zero lengths are treated as 1.

Examples found in repository

examples/scrollbar.rs (lines 194-201)

fn build_metrics(track_cells: usize, desired_thumb_cells: usize) -> ScrollMetrics {
    let track_len = track_cells.saturating_mul(SUBCELL);
    let viewport_len = track_len.max(1);
    let desired_thumb_len = desired_thumb_cells.saturating_mul(SUBCELL).max(1);
    let content_len =
        ((track_len as u128) * (viewport_len as u128) / (desired_thumb_len as u128)) as usize;
    let content_len = content_len.max(viewport_len.saturating_add(1));
    ScrollMetrics::new(
        ScrollLengths {
            content_len,
            viewport_len,
        },
        0,
        track_cells as u16,
    )
}

examples/scrollbar_mouse.rs (lines 328-335)

    fn metrics_for_layout(&self, content: Rect) -> (ScrollMetrics, ScrollMetrics) {
        // Use subcell units so wheel/drag updates line up with the fractional renderer.
        let h_cells = content.width.max(1) as usize;
        let v_cells = content.height.max(1) as usize;
        let h_content = h_cells.saturating_mul(SUBCELL).max(1);
        let v_content = v_cells.saturating_mul(SUBCELL).max(1);
        let h_viewport = h_content.saturating_sub(100).max(1);
        let v_viewport = v_content.saturating_sub(100).max(1);
        (
            ScrollMetrics::new(
                ScrollLengths {
                    content_len: h_content,
                    viewport_len: h_viewport,
                },
                self.horizontal_offset,
                content.width,
            ),
            ScrollMetrics::new(
                ScrollLengths {
                    content_len: v_content,
                    viewport_len: v_viewport,
                },
                self.vertical_offset,
                content.height,
            ),
        )
    }

pub const fn content_len(&self) -> usize

Returns the current content length in logical units.

Examples found in repository

examples/scrollbar.rs (line 141)

fn render_horizontal_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::horizontal([
            Constraint::Length(2),
            Constraint::Fill(1),
        ]));
        if bar_area.width == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.width as usize, 6);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

/// Draws vertical scrollbars that sweep every 1/8th thumb position, left to right.
fn render_vertical_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::vertical([
            Constraint::Length(1),
            Constraint::Fill(1),
        ]));
        if bar_area.height == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.height as usize, 3);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

examples/scrollbar_mouse.rs (line 193)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

    /// Handles crossterm mouse events using the scrollbar helpers.
    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

    /// Applies a scroll command to the current axis offset.
    fn apply_command(&mut self, command: ScrollCommand, is_horizontal: bool) {
        let ScrollCommand::SetOffset(offset) = command;
        if is_horizontal {
            self.horizontal_offset = offset;
        } else {
            self.vertical_offset = offset;
        }
    }

    /// Builds a horizontal scrollbar from the current metrics.
    fn horizontal_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
    }

    /// Builds a vertical scrollbar from the current metrics.
    fn vertical_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
    }

pub const fn viewport_len(&self) -> usize

Returns the current viewport length in logical units.

Examples found in repository

examples/scrollbar.rs (line 142)

fn render_horizontal_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::horizontal([
            Constraint::Length(2),
            Constraint::Fill(1),
        ]));
        if bar_area.width == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.width as usize, 6);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

/// Draws vertical scrollbars that sweep every 1/8th thumb position, left to right.
fn render_vertical_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::vertical([
            Constraint::Length(1),
            Constraint::Fill(1),
        ]));
        if bar_area.height == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.height as usize, 3);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

examples/scrollbar_mouse.rs (line 194)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

    /// Handles crossterm mouse events using the scrollbar helpers.
    fn handle_mouse_event(&mut self, event: event::MouseEvent) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        let horizontal = self.horizontal_scrollbar(h_metrics);
        let vertical = self.vertical_scrollbar(v_metrics);

        if let Some(command) = horizontal.handle_mouse_event(
            layout.horizontal_bar,
            event,
            &mut self.horizontal_interaction,
        ) {
            self.apply_command(command, true);
        }
        if let Some(command) =
            vertical.handle_mouse_event(layout.vertical_bar, event, &mut self.vertical_interaction)
        {
            self.apply_command(command, false);
        }
    }

    /// Applies a scroll command to the current axis offset.
    fn apply_command(&mut self, command: ScrollCommand, is_horizontal: bool) {
        let ScrollCommand::SetOffset(offset) = command;
        if is_horizontal {
            self.horizontal_offset = offset;
        } else {
            self.vertical_offset = offset;
        }
    }

    /// Builds a horizontal scrollbar from the current metrics.
    fn horizontal_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
    }

    /// Builds a vertical scrollbar from the current metrics.
    fn vertical_scrollbar(&self, metrics: ScrollMetrics) -> ScrollBar {
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
    }

pub const fn offset(&self) -> usize

Returns the current content offset in logical units.

pub const fn track_cells(&self) -> usize

Returns the track length in terminal cells.

pub const fn track_len(&self) -> usize

Returns the track length in subcells.

pub const fn thumb_len(&self) -> usize

Returns the thumb length in subcells.

pub const fn thumb_start(&self) -> usize

Returns the thumb start position in subcells.

pub const fn max_offset(&self) -> usize

Returns the maximum scrollable offset in subcells.

Examples found in repository

examples/scrollbar_mouse.rs (line 189)

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();
        if area.width < 2 || area.height < 2 {
            return;
        }

        let title = "tui-scrollbar - mouse scroll demo";
        let block = Block::new()
            .borders(Borders::TOP)
            .border_style(Style::new().fg(TITLE_FG).bg(TITLE_BG))
            .style(Style::new().fg(BLOCK_FG).bg(BLOCK_BG))
            .title(
                Line::from(title)
                    .centered()
                    .fg(TITLE_FG)
                    .bg(TITLE_BG)
                    .bold(),
            );
        frame.render_widget(&block, area);

        let content_area = Rect {
            y: area.y.saturating_add(1),
            height: area.height.saturating_sub(1),
            ..area
        };
        let help = "Arrows: move | Wheel: scroll | Drag: thumb | q/Esc: quit";
        let help_area = Rect {
            x: content_area.x.saturating_add(1),
            y: content_area.y,
            width: content_area.width.saturating_sub(1),
            height: 1,
        };
        if help_area.width > 0 {
            frame.render_widget(
                Paragraph::new(help).style(Style::new().fg(TITLE_FG)),
                help_area,
            );
        }
        let content_area = Rect {
            y: content_area.y.saturating_add(1),
            height: content_area.height.saturating_sub(1),
            ..content_area
        };

        // Split out the bottom row and right column for the scrollbars.
        let [content_row, bar_row] = content_area.layout(&Layout::vertical([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [content, vertical_bar] = content_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));
        let [horizontal_bar, _corner] = bar_row.layout(&Layout::horizontal([
            Constraint::Fill(1),
            Constraint::Length(1),
        ]));

        self.layout = Some(LayoutState {
            content,
            vertical_bar,
            horizontal_bar,
        });

        // Keep offsets valid when the terminal is resized.
        let (h_metrics, v_metrics) = self.metrics_for_layout(content);
        self.horizontal_offset = self.horizontal_offset.min(h_metrics.max_offset());
        self.vertical_offset = self.vertical_offset.min(v_metrics.max_offset());

        let horizontal_lengths = ScrollLengths {
            content_len: h_metrics.content_len(),
            viewport_len: h_metrics.viewport_len(),
        };
        let track_style = Style::new().bg(SCROLLBAR_TRACK_BG);
        let thumb_style = Style::new().fg(SCROLLBAR_THUMB_FG).bg(SCROLLBAR_THUMB_BG);
        let arrow_style = Style::new().fg(SCROLLBAR_ARROW_FG).bg(SCROLLBAR_TRACK_BG);
        let horizontal = ScrollBar::horizontal(horizontal_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.horizontal_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);
        let vertical_lengths = ScrollLengths {
            content_len: v_metrics.content_len(),
            viewport_len: v_metrics.viewport_len(),
        };
        let vertical = ScrollBar::vertical(vertical_lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(self.vertical_offset)
            .scroll_step(SUBCELL)
            .track_style(track_style)
            .thumb_style(thumb_style)
            .arrow_style(arrow_style);

        frame.render_widget(&horizontal, horizontal_bar);
        frame.render_widget(&vertical, vertical_bar);
    }

    /// Handles keyboard and mouse events, updating offsets as needed.
    fn handle_events(&mut self) -> Result<()> {
        match event::read()? {
            Event::Key(key) => {
                if key.is_press() {
                    self.handle_key_event(key.code);
                }
            }
            Event::Mouse(event) => {
                self.handle_mouse_event(event);
            }
            _ => {}
        }
        Ok(())
    }

    /// Handles keyboard input, updating offsets or exiting as needed.
    fn handle_key_event(&mut self, code: KeyCode) {
        match code {
            KeyCode::Char('q') | KeyCode::Esc => self.state = AppState::Quit,
            KeyCode::Up | KeyCode::Char('k') => self.handle_key_scroll(0, -(KEY_STEP as isize)),
            KeyCode::Down | KeyCode::Char('j') => self.handle_key_scroll(0, KEY_STEP as isize),
            KeyCode::Left | KeyCode::Char('h') => self.handle_key_scroll(-(KEY_STEP as isize), 0),
            KeyCode::Right | KeyCode::Char('l') => self.handle_key_scroll(KEY_STEP as isize, 0),
            _ => {}
        }
    }

    /// Applies a keyboard delta to the scrollbar offsets.
    fn handle_key_scroll(&mut self, dx: isize, dy: isize) {
        let Some(layout) = self.layout else {
            return;
        };
        let (h_metrics, v_metrics) = self.metrics_for_layout(layout.content);
        self.horizontal_offset =
            Self::apply_delta(self.horizontal_offset, dx, h_metrics.max_offset());
        self.vertical_offset = Self::apply_delta(self.vertical_offset, dy, v_metrics.max_offset());
    }

pub const fn thumb_travel(&self) -> usize

Returns the maximum thumb travel in subcells.

Examples found in repository

examples/scrollbar.rs (line 206)

fn step_entry(metrics: &ScrollMetrics, index: usize) -> (usize, usize) {
    let max_start = metrics.thumb_travel();
    let local = index % 17;
    if index < 17 {
        (local, local.min(max_start))
    } else {
        let base = max_start.saturating_sub(16);
        (local, base.saturating_add(local).min(max_start))
    }
}

pub const fn thumb_range(&self) -> Range<usize>

Returns the thumb range in subcell coordinates.

pub const fn hit_test(&self, position: usize) -> HitTest

Returns whether a subcell position hits the thumb or the track.

pub fn thumb_start_for_offset(&self, offset: usize) -> usize

Converts an offset (in subcells) to a thumb start position (in subcells).

Larger offsets move the thumb toward the end of the track, clamped to the maximum travel.

pub fn offset_for_thumb_start(&self, thumb_start: usize) -> usize

Converts a thumb start position (in subcells) to an offset (in subcells).

Thumb positions beyond the end of travel are clamped to the maximum offset.

Examples found in repository

examples/scrollbar.rs (line 139)

fn render_horizontal_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::horizontal([
            Constraint::Length(2),
            Constraint::Fill(1),
        ]));
        if bar_area.width == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.width as usize, 6);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::horizontal(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

/// Draws vertical scrollbars that sweep every 1/8th thumb position, left to right.
fn render_vertical_steps(frame: &mut ratatui::Frame, cells: Vec<Rect>) {
    for (index, area) in cells.iter().enumerate() {
        let [label_area, bar_area] = area.layout(&Layout::vertical([
            Constraint::Length(1),
            Constraint::Fill(1),
        ]));
        if bar_area.height == 0 {
            continue;
        }
        let metrics = build_metrics(bar_area.height as usize, 3);
        let (label, thumb_start) = step_entry(&metrics, index);
        let label = (label % 8).to_string();
        let offset = metrics.offset_for_thumb_start(thumb_start);
        let lengths = ScrollLengths {
            content_len: metrics.content_len(),
            viewport_len: metrics.viewport_len(),
        };
        let scrollbar = ScrollBar::vertical(lengths)
            .arrows(ScrollBarArrows::Both)
            .offset(offset);
        render_label(frame, label_area, &label);
        frame.render_widget(&scrollbar, bar_area);
    }
}

pub fn cell_fill(&self, cell_index: usize) -> CellFill

Returns how much of a cell is filled by the thumb.

The cell_index is in terminal cells, not subcells. Use this to select the correct glyph for the track or thumb.

Trait Implementations

impl Clone for ScrollMetrics

fn clone(&self) -> ScrollMetrics

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for ScrollMetrics

impl Debug for ScrollMetrics

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

Formats the value using the given formatter.

impl Eq for ScrollMetrics

impl PartialEq for ScrollMetrics

fn eq(&self, other: &ScrollMetrics) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for ScrollMetrics