tui_kit/
mouse.rs

1//! Mouse event helpers.
2//!
3//! ## Enabling mouse support
4//!
5//! In your terminal setup / teardown, enable and disable mouse capture:
6//!
7//! ```rust
8//! use crossterm::{execute, event::{EnableMouseCapture, DisableMouseCapture}};
9//!
10//! // setup
11//! execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
12//!
13//! // teardown
14//! execute!(terminal.backend_mut(), LeaveAlternateScreen, DisableMouseCapture)?;
15//! ```
16//!
17//! ## Hit-testing in the event loop
18//!
19//! ```rust
20//! use crossterm::event::{Event, MouseButton, MouseEventKind};
21//! use tui_kit::mouse_hit;
22//!
23//! if let Event::Mouse(m) = event::read()? {
24//!     if m.kind == MouseEventKind::Down(MouseButton::Left) {
25//!         app.handle_mouse(m.column, m.row);
26//!     }
27//! }
28//! ```
29//!
30//! ## Storing panel areas
31//!
32//! Record each focusable widget's `Rect` during the render pass, then use
33//! [`mouse_hit`] to map a click coordinate back to the focused widget:
34//!
35//! ```rust
36//! // In render:
37//! app.areas[Panel::List as usize] = Some(list_area);
38//!
39//! // In handle_mouse:
40//! for (i, area) in app.areas.iter().enumerate() {
41//!     if let Some(a) = area {
42//!         if mouse_hit(*a, col, row) {
43//!             app.focus = Panel::from(i);
44//!             return;
45//!         }
46//!     }
47//! }
48//! ```
49
50use ratatui::{layout::Position, layout::Rect};
51
52/// Returns `true` if the terminal cell `(col, row)` falls inside `area`.
53///
54/// Use this to map a [`crossterm::event::MouseEvent`] to a widget that was
55/// rendered at a known [`Rect`].
56#[inline]
57pub fn mouse_hit(area: Rect, col: u16, row: u16) -> bool {
58    area.contains(Position { x: col, y: row })
59}
60
61/// Given the **outer** block area (including borders) of a list widget and a
62/// click `row`, returns the item index that was clicked.
63///
64/// Returns `None` if the click lands on a border row or is outside the area.
65/// The returned index accounts for the current scroll `offset` — it is an
66/// absolute index into the items slice, ready to assign to `ListState::selected`.
67///
68/// # Example
69/// ```rust
70/// if let Some(idx) = list_item_at(app.panel_areas[0], app.list_state.offset(), m.row) {
71///     if idx < app.items.len() {
72///         app.list_state.selected = idx;
73///     }
74/// }
75/// ```
76pub fn list_item_at(area: Rect, offset: usize, row: u16) -> Option<usize> {
77    let inner_y = area.y + 1;
78    let inner_height = area.height.saturating_sub(2);
79    if row < inner_y || row >= inner_y + inner_height {
80        return None;
81    }
82    Some(offset + (row - inner_y) as usize)
83}
84
85/// Given the **outer** block area of a scrollable paragraph and a click `row`,
86/// returns the absolute content line number that was clicked (i.e. accounting
87/// for the scroll offset).
88///
89/// Returns `None` if the click is on a border row.
90/// The caller can then match this line number against their tracked link/item
91/// line positions to find which element was clicked.
92///
93/// # Example
94/// ```rust
95/// if let Some(line) = paragraph_line_at(area, app.desc_scroll as usize, m.row) {
96///     if let Some(i) = app.desc_link_lines.iter().position(|&l| l as usize == line) {
97///         app.selected_desc_link = i;
98///     }
99/// }
100/// ```
101pub fn paragraph_line_at(area: Rect, scroll: usize, row: u16) -> Option<usize> {
102    let inner_y = area.y + 1;
103    let inner_height = area.height.saturating_sub(2);
104    if row < inner_y || row >= inner_y + inner_height {
105        return None;
106    }
107    Some(scroll + (row - inner_y) as usize)
108}
tui_kit/mouse.rs

tui_kit/
mouse.rs
