Skip to main content

comb/widgets/
scrollbar.rs

1//! A customizable vertical scrollbar with hit-testing and draggable thumb.
2//!
3//! Unlike the legacy one-liner [`scrollbar()`], [`Scrollbar`] carries its own
4//! style (glyphs, colours, width) and drag state so callers can grab the thumb
5//! and pull, or click the track to jump.
6
7use crate::core::buffer::Buffer;
8use crate::core::geom::Rect;
9use crate::core::style::Style;
10use crate::term::event::{MouseButton, MouseKind};
11
12/// Visual appearance of a [`Scrollbar`].
13#[derive(Clone, Copy, Debug)]
14pub struct ScrollbarStyle {
15    /// Track width in columns (usually 1, sometimes 2 for a wider thumb).
16    pub width: u16,
17    pub track: Style,
18    pub thumb: Style,
19    /// While the thumb is being dragged.
20    pub thumb_active: Style,
21    pub track_glyph: char,
22    pub thumb_glyph: char,
23}
24
25impl Default for ScrollbarStyle {
26    fn default() -> Self {
27        ScrollbarStyle {
28            width: 1,
29            track: Style::new(),
30            thumb: Style::new(),
31            thumb_active: Style::new(),
32            track_glyph: '│',
33            thumb_glyph: '█',
34        }
35    }
36}
37
38/// Geometry of the thumb within a track of `track_h` rows.
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40pub struct ScrollMetrics {
41    pub thumb_len: usize,
42    pub thumb_top: usize,
43    pub max_offset: usize,
44}
45
46impl ScrollMetrics {
47    pub fn compute(total: usize, viewport: usize, offset: usize, track_h: usize) -> Self {
48        if track_h == 0 || total <= viewport || viewport == 0 {
49            return ScrollMetrics {
50                thumb_len: track_h,
51                thumb_top: 0,
52                max_offset: 0,
53            };
54        }
55        let thumb_len = ((viewport * track_h) / total).clamp(1, track_h);
56        let max_offset = total - viewport;
57        let span = track_h - thumb_len;
58        let thumb_top = if max_offset == 0 {
59            0
60        } else {
61            (offset.min(max_offset) * span)
62                .checked_div(max_offset)
63                .unwrap_or(0)
64        };
65        ScrollMetrics {
66            thumb_len,
67            thumb_top,
68            max_offset,
69        }
70    }
71
72    pub fn offset_for_thumb_top(&self, thumb_top: usize, track_h: usize) -> usize {
73        let span = track_h.saturating_sub(self.thumb_len);
74        if self.max_offset == 0 || span == 0 {
75            0
76        } else {
77            (thumb_top.min(span) * self.max_offset)
78                .checked_div(span)
79                .unwrap_or(0)
80        }
81    }
82}
83
84/// Stateful scrollbar: style + optional drag anchor (row offset inside the thumb).
85#[derive(Clone, Debug, Default)]
86pub struct Scrollbar {
87    pub style: ScrollbarStyle,
88    drag: Option<isize>,
89}
90
91impl Scrollbar {
92    pub fn new(style: ScrollbarStyle) -> Self {
93        Scrollbar { style, drag: None }
94    }
95
96    pub fn is_dragging(&self) -> bool {
97        self.drag.is_some()
98    }
99
100    pub fn end_drag(&mut self) {
101        self.drag = None;
102    }
103
104    /// The column slice on the right edge of `outer` reserved for this bar.
105    pub fn area(&self, outer: Rect) -> Rect {
106        let w = self.style.width.min(outer.width);
107        Rect::new(outer.right().saturating_sub(w), outer.y, w, outer.height)
108    }
109
110    /// `outer` minus the scrollbar strip (when `needs_bar`).
111    pub fn content_area(&self, outer: Rect, needs_bar: bool) -> Rect {
112        if !needs_bar {
113            return outer;
114        }
115        let w = self.style.width.min(outer.width);
116        Rect::new(
117            outer.x,
118            outer.y,
119            outer.width.saturating_sub(w),
120            outer.height,
121        )
122    }
123
124    pub fn metrics(
125        &self,
126        total: usize,
127        viewport: usize,
128        offset: usize,
129        area: Rect,
130    ) -> ScrollMetrics {
131        ScrollMetrics::compute(total, viewport, offset, area.height as usize)
132    }
133
134    /// Inclusive screen-row range of the thumb, if any.
135    pub fn thumb_rows(
136        &self,
137        area: Rect,
138        total: usize,
139        viewport: usize,
140        offset: usize,
141    ) -> Option<(u16, u16)> {
142        let m = self.metrics(total, viewport, offset, area);
143        if m.max_offset == 0 {
144            return None;
145        }
146        let y0 = area.y + m.thumb_top as u16;
147        let y1 = y0 + m.thumb_len as u16 - 1;
148        Some((y0, y1))
149    }
150
151    pub fn hit(
152        &self,
153        area: Rect,
154        total: usize,
155        viewport: usize,
156        offset: usize,
157        col: u16,
158        row: u16,
159    ) -> ScrollHit {
160        if !area.contains(col, row) || total <= viewport {
161            return ScrollHit::None;
162        }
163        if let Some((y0, y1)) = self.thumb_rows(area, total, viewport, offset) {
164            if row >= y0 && row <= y1 {
165                return ScrollHit::Thumb;
166            }
167        }
168        ScrollHit::Track
169    }
170
171    pub fn render(
172        &self,
173        buf: &mut Buffer,
174        area: Rect,
175        total: usize,
176        viewport: usize,
177        offset: usize,
178    ) {
179        if area.is_empty() {
180            return;
181        }
182        let _h = area.height as usize;
183        let m = self.metrics(total, viewport, offset, area);
184        let st = self.style;
185        let active = self.drag.is_some();
186        let thumb_st = if active { st.thumb_active } else { st.thumb };
187
188        for y in 0..area.height {
189            for dx in 0..area.width {
190                buf.set(area.x + dx, area.y + y, st.track_glyph, st.track);
191            }
192        }
193
194        if m.max_offset == 0 {
195            return;
196        }
197
198        for i in 0..m.thumb_len {
199            let y = area.y + (m.thumb_top + i) as u16;
200            for dx in 0..area.width {
201                buf.set(area.x + dx, y, st.thumb_glyph, thumb_st);
202            }
203        }
204    }
205
206    /// Handle mouse input over the scrollbar `area`. Updates `offset` in place.
207    /// Returns `true` if the event was consumed.
208    #[allow(clippy::too_many_arguments)]
209    pub fn on_mouse(
210        &mut self,
211        area: Rect,
212        total: usize,
213        viewport: usize,
214        offset: &mut usize,
215        kind: MouseKind,
216        col: u16,
217        row: u16,
218    ) -> bool {
219        if total <= viewport || !area.contains(col, row) {
220            if kind == MouseKind::Up {
221                self.end_drag();
222            }
223            return false;
224        }
225
226        let track_h = area.height as usize;
227        let m = self.metrics(total, viewport, *offset, area);
228
229        match kind {
230            MouseKind::Down(MouseButton::Left) => {
231                match self.hit(area, total, viewport, *offset, col, row) {
232                    ScrollHit::Thumb => {
233                        let rel = row as isize - area.y as isize - m.thumb_top as isize;
234                        self.drag = Some(rel);
235                        true
236                    }
237                    ScrollHit::Track => {
238                        let rel = row as isize - area.y as isize;
239                        let thumb_top = (rel - m.thumb_len as isize / 2)
240                            .clamp(0, (track_h - m.thumb_len) as isize)
241                            as usize;
242                        *offset = m.offset_for_thumb_top(thumb_top, track_h);
243                        true
244                    }
245                    ScrollHit::None => false,
246                }
247            }
248            MouseKind::Drag => {
249                if let Some(drag) = self.drag {
250                    let rel = row as isize - area.y as isize - drag;
251                    let thumb_top = rel.clamp(0, (track_h - m.thumb_len) as isize) as usize;
252                    *offset = m.offset_for_thumb_top(thumb_top, track_h);
253                    true
254                } else {
255                    false
256                }
257            }
258            MouseKind::Up => {
259                let was = self.drag.is_some();
260                self.end_drag();
261                was
262            }
263            MouseKind::ScrollUp => {
264                *offset = offset.saturating_sub(3);
265                true
266            }
267            MouseKind::ScrollDown => {
268                *offset = (*offset + 3).min(m.max_offset);
269                true
270            }
271            _ => false,
272        }
273    }
274}
275
276#[derive(Clone, Copy, PartialEq, Eq, Debug)]
277pub enum ScrollHit {
278    None,
279    Track,
280    Thumb,
281}
282
283/// Legacy helper — draws a default-style bar in one column.
284pub fn scrollbar(
285    buf: &mut Buffer,
286    area: Rect,
287    total: usize,
288    offset: usize,
289    viewport: usize,
290    thumb: Style,
291    track: Style,
292) {
293    let bar = Scrollbar::new(ScrollbarStyle {
294        thumb,
295        track,
296        ..ScrollbarStyle::default()
297    });
298    bar.render(buf, area, total, viewport, offset);
299}
300
301#[cfg(test)]
302mod tests {
303    use super::*;
304
305    #[test]
306    fn thumb_top_roundtrip() {
307        let m = ScrollMetrics::compute(100, 10, 45, 20);
308        let top = m.thumb_top;
309        let off = m.offset_for_thumb_top(top, 20);
310        assert_eq!(off, 45);
311    }
312
313    #[test]
314    fn drag_updates_offset() {
315        let area = Rect::new(10, 0, 1, 10);
316        let mut bar = Scrollbar::default();
317        let mut off = 0usize;
318        bar.on_mouse(
319            area,
320            50,
321            10,
322            &mut off,
323            MouseKind::Down(MouseButton::Left),
324            10,
325            5,
326        );
327        assert!(off > 0);
328    }
329}