Guide API
Skip to main content

tvision_rs/widgets/
tab_bar.rs

1//! `TabBar`, a single-row tab selector (documented on the type).
2
3use crate::capture::TrackMask;
4use crate::command::Command;
5use crate::data::FieldValue;
6use crate::event::{Event, Key, hot_key};
7use crate::theme::Role;
8use crate::view::{Context, DrawCtx, Point, Rect, View, ViewState};
9
10/// A horizontal single-row tab selector: corner-cap active tab (`┌Label┐`),
11/// ←/→/hotkey/click selection.
12///
13/// The bar is **cluster-shaped**: it follows the `TCluster`/`TRadioButtons`
14/// contract (single selection, `~X~` hotkeys, `find_sel` hit-test,
15/// press-on-release, `value`/`set_value` transfer), the way the C++ color
16/// dialog's `TMonoSelector : public TCluster` was a custom selector built on the
17/// cluster. On a change it broadcasts [`Command::TAB_BAR_CHANGED`] carrying its
18/// own [`ViewId`](crate::view::ViewId) as `source`, so a sibling
19/// [`PageStack`](crate::widgets::PageStack) can react (mirrors `ScrollBar`).
20///
21/// # Turbo Vision heritage
22/// **tvision-rs extension**: no Turbo Vision counterpart. The selection mechanics mirror
23/// `TCluster`.
24pub struct TabBar {
25    /// View state (geometry, flags) — the composition target.
26    pub state: ViewState,
27    /// Tab labels, each optionally carrying a `~X~` hotkey marker.
28    tabs: Vec<String>,
29    /// Selected/active tab (cursor ≡ selection for a tab strip), clamped.
30    value: usize,
31    /// Absolute origin of bar-local (0,0), cached each `draw` for the track capture.
32    abs_origin: Point,
33    /// Whether a press-on-release mouse track is in flight.
34    tracking: bool,
35    /// The tab the mouse went down on (pressed only if MouseUp lands on the same one).
36    pressed: Option<usize>,
37}
38
39impl TabBar {
40    /// Construct at `bounds` with `labels` (each may carry `~X~`). Focusable; starts on tab 0.
41    pub fn new(bounds: Rect, labels: &[&str]) -> Self {
42        let mut state = ViewState::new(bounds);
43        state.options.selectable = true;
44        TabBar {
45            state,
46            tabs: labels.iter().map(|s| s.to_string()).collect(),
47            value: 0,
48            abs_origin: bounds.a,
49            tracking: false,
50            pressed: None,
51        }
52    }
53
54    /// The selected tab index.
55    pub fn selected(&self) -> usize {
56        self.value
57    }
58
59    /// Display width of `label` with the `~` hotkey markers stripped (they are not
60    /// printed columns). Mirrors [`cluster.rs::cstrlen`](crate::widgets::Cluster) so
61    /// wide/CJK labels measure correctly.
62    fn label_len(label: &str) -> i32 {
63        crate::text::width(&label.replace('~', "")) as i32
64    }
65
66    /// `(start_x, width)` per tab; the active tab is +2 wide (its caps); 1-cell gaps.
67    fn tab_layout(&self) -> Vec<(i32, i32)> {
68        let mut out = Vec::with_capacity(self.tabs.len());
69        let mut x = 0i32;
70        for (i, label) in self.tabs.iter().enumerate() {
71            let w = Self::label_len(label) + if i == self.value { 2 } else { 0 };
72            out.push((x, w));
73            x += w + 1;
74        }
75        out
76    }
77
78    /// Natural width to fit all tabs (labels + caps for the one active + gaps). Stable.
79    pub fn natural_width(&self) -> i32 {
80        let n = self.tabs.len() as i32;
81        if n == 0 {
82            return 0;
83        }
84        self.tabs.iter().map(|l| Self::label_len(l)).sum::<i32>() + 2 + (n - 1)
85    }
86
87    /// The tab under view-local point `p`, or `None`.
88    fn find_sel(&self, p: Point) -> Option<usize> {
89        if p.y != 0 {
90            return None;
91        }
92        for (i, (start, w)) in self.tab_layout().iter().enumerate() {
93            if p.x >= *start && p.x < start + w {
94                return Some(i);
95            }
96        }
97        None
98    }
99
100    /// Select `item` (clamped); broadcast `TAB_BAR_CHANGED` (source = self) only on change.
101    fn press(&mut self, item: usize, ctx: &mut Context) {
102        let item = item.min(self.tabs.len().saturating_sub(1));
103        if item != self.value {
104            self.value = item;
105            ctx.broadcast(Command::TAB_BAR_CHANGED, self.state.id());
106        }
107    }
108}
109
110impl View for TabBar {
111    fn state(&self) -> &ViewState {
112        &self.state
113    }
114
115    fn state_mut(&mut self) -> &mut ViewState {
116        &mut self.state
117    }
118
119    /// Selected index as the typed transfer currency (getData successor).
120    fn value(&self) -> Option<FieldValue> {
121        Some(FieldValue::Int(self.value as i32))
122    }
123
124    /// Load the selected index (clamped). The trait setter takes NO ctx
125    /// (there is a separate `set_value_ctx`) — match that signature.
126    fn set_value(&mut self, v: FieldValue) {
127        if let FieldValue::Int(i) = v {
128            self.value = (i.max(0) as usize).min(self.tabs.len().saturating_sub(1));
129        }
130    }
131
132    fn as_any_mut(&mut self) -> Option<&mut dyn core::any::Any> {
133        Some(self)
134    }
135
136    fn draw(&mut self, ctx: &mut DrawCtx) {
137        self.abs_origin = ctx.origin();
138        let g = *ctx.glyphs();
139        let (norm, norm_hi) = (
140            ctx.style(Role::LabelNormal),
141            ctx.style(Role::LabelNormalShortcut),
142        );
143        let (act, act_hi) = (
144            ctx.style(Role::LabelLight),
145            ctx.style(Role::LabelLightShortcut),
146        );
147        let layout = self.tab_layout();
148        for (i, (start, _w)) in layout.iter().enumerate() {
149            let label = &self.tabs[i];
150            if i == self.value {
151                ctx.put_char(*start, 0, g.frame_tl, act);
152                let lw = ctx.put_cstr(start + 1, 0, label, act, act_hi);
153                ctx.put_char(start + 1 + lw, 0, g.frame_tr, act);
154            } else {
155                ctx.put_cstr(*start, 0, label, norm, norm_hi);
156            }
157        }
158    }
159
160    fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context) {
161        let n = self.tabs.len();
162        if n == 0 {
163            return;
164        }
165        match *ev {
166            Event::KeyDown(ke) => match ke.key {
167                Key::Left => {
168                    self.press((self.value + n - 1) % n, ctx);
169                    ev.clear();
170                }
171                Key::Right => {
172                    self.press((self.value + 1) % n, ctx);
173                    ev.clear();
174                }
175                Key::Char(c) => {
176                    let up = c.to_ascii_uppercase();
177                    // hot_key returns the char already uppercased
178                    if let Some(i) = self.tabs.iter().position(|l| hot_key(l) == Some(up)) {
179                        self.press(i, ctx);
180                        ev.clear();
181                    }
182                }
183                _ => {}
184            },
185            // Press-on-release (mirrors cluster.rs): arm a track on down, commit on up.
186            Event::MouseDown(me) => {
187                if let Some(i) = self.find_sel(me.position) {
188                    self.pressed = Some(i);
189                    if let Some(id) = self.state.id() {
190                        self.tracking = true;
191                        ctx.start_mouse_track(
192                            id,
193                            self.abs_origin,
194                            TrackMask {
195                                mouse_move: true,
196                                ..Default::default()
197                            },
198                        );
199                    } else {
200                        // Degenerate fallback (no ViewId): single-shot press on down.
201                        self.press(i, ctx);
202                    }
203                    ev.clear();
204                }
205            }
206            Event::MouseUp(me) if self.tracking => {
207                self.tracking = false;
208                // pressed.take() clears self.pressed regardless of the release position.
209                let pressed = self.pressed.take();
210                if let (Some(p), Some(i)) = (pressed, self.find_sel(me.position))
211                    && p == i
212                {
213                    self.press(i, ctx);
214                }
215                ev.clear();
216            }
217            // Consume routed moves while tracking (mirrors cluster.rs's no-op
218            // MouseMove arm — the C++ only toggled cursor visibility, no TUI equivalent).
219            Event::MouseMove(_) if self.tracking => {
220                ev.clear();
221            }
222            _ => {}
223        }
224    }
225}
226
227// ---------------------------------------------------------------------------
228// Tests
229// ---------------------------------------------------------------------------
230
231#[cfg(test)]
232mod tests {
233    use super::*;
234    use crate::backend::{HeadlessBackend, Renderer};
235    use crate::event::{
236        KeyEvent, KeyModifiers, MouseButtons, MouseEvent, MouseEventFlags, MouseWheel,
237    };
238    use crate::screen::Buffer;
239    use crate::theme::Theme;
240    use crate::view::{Deferred, Group};
241    use std::collections::VecDeque;
242
243    // -- Helper to build a Context with local backing storage ----------------
244
245    fn drive(tb: &mut TabBar, ev: &mut Event, out: &mut VecDeque<Event>) {
246        let mut timers = crate::timer::TimerQueue::new();
247        let mut deferred: Vec<Deferred> = vec![];
248        let mut ctx = Context::new(out, &mut timers, 0, &mut deferred);
249        tb.handle_event(ev, &mut ctx);
250    }
251
252    fn key(k: Key) -> Event {
253        Event::KeyDown(KeyEvent::new(k, KeyModifiers::default()))
254    }
255
256    fn mouse(kind: fn(MouseEvent) -> Event, x: i32) -> Event {
257        kind(MouseEvent {
258            position: Point::new(x, 0),
259            buttons: MouseButtons {
260                left: true,
261                ..Default::default()
262            },
263            flags: MouseEventFlags::default(),
264            wheel: MouseWheel::None,
265            modifiers: KeyModifiers::default(),
266        })
267    }
268
269    // -----------------------------------------------------------------------
270    // Task 5 unit tests
271    // -----------------------------------------------------------------------
272
273    #[test]
274    fn natural_width_sums_labels_caps_gaps() {
275        // "AB"(2) + "CDE"(3) + 2(caps) + 1(gap) = 8
276        assert_eq!(
277            TabBar::new(Rect::new(0, 0, 20, 1), &["AB", "CDE"]).natural_width(),
278            8
279        );
280        // "~P~resets" → visible chars = "resets" + "P" = 7 chars, + 2 caps = 9
281        assert_eq!(
282            TabBar::new(Rect::new(0, 0, 20, 1), &["~P~resets"]).natural_width(),
283            9
284        );
285    }
286
287    #[test]
288    fn value_protocol_reports_and_sets_clamped() {
289        let mut tb = TabBar::new(Rect::new(0, 0, 20, 1), &["A", "B", "C"]);
290        assert_eq!(View::value(&tb), Some(FieldValue::Int(0)));
291        View::set_value(&mut tb, FieldValue::Int(5)); // clamped to 2 (len-1)
292        assert_eq!(tb.selected(), 2);
293    }
294
295    #[test]
296    fn find_sel_locates_tab_under_point() {
297        // Active tab 0 ("A"): width = 1 + 2 = 3 → [0..3)  gap@3
298        // Tab 1 ("B"): width = 1           → [4..5)  gap@5
299        // Tab 2 ("C"): width = 1           → [6..7)
300        let tb = TabBar::new(Rect::new(0, 0, 20, 1), &["A", "B", "C"]);
301        assert_eq!(tb.find_sel(Point::new(1, 0)), Some(0));
302        assert_eq!(tb.find_sel(Point::new(4, 0)), Some(1));
303        assert_eq!(tb.find_sel(Point::new(6, 0)), Some(2));
304        assert_eq!(tb.find_sel(Point::new(3, 0)), None, "the gap");
305        assert_eq!(tb.find_sel(Point::new(1, 1)), None, "wrong row");
306    }
307
308    // -----------------------------------------------------------------------
309    // Task 7 event tests
310    // -----------------------------------------------------------------------
311
312    #[test]
313    fn right_left_arrows_cycle_with_wrap() {
314        let mut tb = TabBar::new(Rect::new(0, 0, 30, 1), &["A", "B", "C"]);
315        let mut out = VecDeque::new();
316        let mut e = key(Key::Right);
317        drive(&mut tb, &mut e, &mut out);
318        assert_eq!(tb.selected(), 1);
319        tb.value = 2;
320        let mut e = key(Key::Right);
321        drive(&mut tb, &mut e, &mut out);
322        assert_eq!(tb.selected(), 0, "wrap");
323        let mut e = key(Key::Left);
324        drive(&mut tb, &mut e, &mut out);
325        assert_eq!(tb.selected(), 2, "wrap back");
326    }
327
328    #[test]
329    fn hotkey_selects() {
330        let mut tb = TabBar::new(Rect::new(0, 0, 30, 1), &["~P~resets", "~R~GB", "~X~term"]);
331        let mut out = VecDeque::new();
332        let mut e = key(Key::Char('x'));
333        drive(&mut tb, &mut e, &mut out);
334        assert_eq!(tb.selected(), 2);
335        assert!(e.is_nothing());
336    }
337
338    #[test]
339    fn mouse_presses_on_release_over_same_tab() {
340        let mut tb = TabBar::new(Rect::new(0, 0, 30, 1), &["A", "B", "C"]);
341        tb.state.id = Some(crate::view::ViewId::next());
342        let mut out = VecDeque::new();
343        // Tab 2 ("C"): active is tab 0 (w=3), gap@3, tab1 [4..5), gap@5, tab2 [6..7)
344        let mut down = mouse(Event::MouseDown, 6);
345        drive(&mut tb, &mut down, &mut out);
346        assert_eq!(tb.selected(), 0, "no commit on down");
347        let mut up = mouse(Event::MouseUp, 6);
348        drive(&mut tb, &mut up, &mut out);
349        assert_eq!(tb.selected(), 2, "commit on release over same tab");
350    }
351
352    #[test]
353    fn mouse_release_on_different_tab_does_not_commit() {
354        let mut tb = TabBar::new(Rect::new(0, 0, 30, 1), &["A", "B", "C"]);
355        tb.state.id = Some(crate::view::ViewId::next());
356        let mut out = VecDeque::new();
357        // down on tab 2 (x=6)
358        let mut down = mouse(Event::MouseDown, 6);
359        drive(&mut tb, &mut down, &mut out);
360        // up on tab 0 (x=1) — different tab
361        let mut up = mouse(Event::MouseUp, 1);
362        drive(&mut tb, &mut up, &mut out);
363        assert_eq!(tb.selected(), 0, "no commit when release lands elsewhere");
364    }
365
366    #[test]
367    fn change_broadcasts_with_source_id() {
368        let tb = TabBar::new(Rect::new(0, 0, 30, 1), &["A", "B", "C"]);
369        let mut group = Group::new(Rect::new(0, 0, 30, 1));
370        let id = group.insert(Box::new(tb));
371        let mut out = VecDeque::new();
372        {
373            let mut timers = crate::timer::TimerQueue::new();
374            let mut deferred: Vec<Deferred> = vec![];
375            let mut ctx = Context::new(&mut out, &mut timers, 0, &mut deferred);
376            let mut e = key(Key::Right);
377            group.find_mut(id).unwrap().handle_event(&mut e, &mut ctx);
378        }
379        assert!(out.iter().any(|e| matches!(e,
380            Event::Broadcast { command, source } if *command == Command::TAB_BAR_CHANGED && *source == Some(id)
381        )));
382    }
383
384    // -----------------------------------------------------------------------
385    // Task 6 snapshot tests
386    // -----------------------------------------------------------------------
387
388    fn render(active: usize) -> String {
389        let theme = Theme::classic_blue();
390        let mut tb = TabBar::new(Rect::new(0, 0, 30, 1), &["~P~resets", "~R~GB", "~H~ue/Sat"]);
391        tb.value = active;
392        let (backend, screen) = HeadlessBackend::new(30, 1);
393        let mut r = Renderer::new(Box::new(backend));
394        r.render(|buf: &mut Buffer| {
395            let b = Rect::new(0, 0, 30, 1);
396            tb.draw(&mut DrawCtx::new(buf, &theme, b, b.a));
397        });
398        screen.snapshot()
399    }
400
401    #[test]
402    fn snapshot_tabbar_first_active() {
403        insta::assert_snapshot!(render(0));
404    }
405
406    #[test]
407    fn snapshot_tabbar_middle_active() {
408        insta::assert_snapshot!(render(1));
409    }
410}