Guide API
Skip to main content

tvision_rs/dialog/
layout.rs

1//! Named layout metrics for dialogs (documented in the `dialog` module docs).
2//! See `docs/design/dialog-layout.md`.
3
4use crate::view::Point;
5
6/// Standard button: 10 columns × 2 rows (row 2 is the drop shadow).
7///
8/// This is the default minimum face width for
9/// [`button_row`](crate::dialog::Dialog::button_row); the autosize
10/// [`ButtonLayout`](crate::dialog::ButtonLayout)s widen past it when a label needs
11/// the room. Ten columns is what the conventional labels come to anyway — "Cancel"
12/// is 6 columns plus `BUTTON_TEXT_PADDING`.
13pub const STD_BUTTON: Point = Point::new(10, 2);
14/// Cells between adjacent buttons in a button row.
15pub const BUTTON_GAP: i32 = 2;
16/// Content inset from the left frame.
17pub const MARGIN_LEFT: i32 = 3;
18/// Content inset from the right frame.
19pub const MARGIN_RIGHT: i32 = 2;
20/// Content inset from the top frame.
21pub const MARGIN_TOP: i32 = 2;
22/// Button-row top edge = `dialog_height - BUTTON_ROW_FROM_BOTTOM`.
23pub const BUTTON_ROW_FROM_BOTTOM: i32 = 3;
24/// Columns a button face needs beyond its label.
25///
26/// [`Button::draw`](crate::widgets::Button) puts the title at column 2 and the
27/// drop-shadow glyph at `width - 1`, so a label of `n` columns needs a face of
28/// `n + 4` to keep one blank column between the text and the shadow. A narrower
29/// face still renders, but the label butts against the shadow.
30pub(crate) const BUTTON_TEXT_PADDING: i32 = 4;
31
32/// The natural face width for a single label: its display width plus
33/// [`BUTTON_TEXT_PADDING`], before any minimum is applied.
34///
35/// Measured with [`crate::text::cstrlen`], the same `~`-stripping measure
36/// `Button::draw` centers with; measuring differently would size the face against
37/// text the button lays out to a different width.
38pub(crate) fn button_face_width(title: &str) -> i32 {
39    crate::text::cstrlen(title) + BUTTON_TEXT_PADDING
40}
41
42/// How [`Dialog::button_row`](crate::dialog::Dialog::button_row) sizes the faces
43/// in a row. In every case the width is floored at the dialog's configured
44/// minimum (see [`set_button_min_width`](crate::dialog::Dialog::set_button_min_width),
45/// default [`STD_BUTTON`]).
46///
47/// # Turbo Vision heritage
48/// **tvision-rs extension** to `TDialog`.
49#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
50#[non_exhaustive]
51pub enum ButtonLayout {
52    /// Every face exactly the minimum width — the minimum is both floor *and*
53    /// ceiling, so labels never widen a face. The classic Turbo Vision fixed row.
54    /// This is the default.
55    #[default]
56    Classic,
57    /// Every face one shared width: the widest label's natural width, floored at
58    /// the minimum. A uniform row whose long labels still fit.
59    Uniform,
60    /// Each face sized to its own label's natural width, floored at the minimum.
61    /// A ragged row with the tightest horizontal footprint.
62    Ragged,
63}
64
65/// How [`Dialog::button_row`](crate::dialog::Dialog::button_row) places buttons.
66#[derive(Clone, Copy, Debug, PartialEq, Eq)]
67pub enum ButtonRowAlign {
68    /// Centered (message-box convention).
69    Center,
70    /// Right-grouped, ending [`MARGIN_RIGHT`] from the right frame (action dialogs).
71    Right,
72}
73
74#[cfg(test)]
75mod tests {
76    use super::*;
77
78    /// A conventional label's natural face is the classic 10: "Cancel" is 6
79    /// columns, `6 + 4 = 10` — which is why the recovered TV dialogs look right at
80    /// `STD_BUTTON` in the first place.
81    #[test]
82    fn button_face_width_of_a_classic_label_is_std_button() {
83        assert_eq!(button_face_width("~C~ancel"), 10);
84    }
85
86    /// A long label's natural face grows: "Keep editing" is 12 columns → 12 + 4.
87    #[test]
88    fn button_face_width_grows_with_the_label() {
89        assert_eq!(button_face_width("~K~eep editing"), 16);
90    }
91
92    /// The `~` hotkey markers are layout-invisible and must not inflate the face.
93    #[test]
94    fn button_face_width_ignores_hotkey_markers() {
95        assert_eq!(button_face_width("~D~iscard"), button_face_width("Discard"));
96    }
97
98    /// Layout defaults to Classic, so a plain Dialog is byte-for-byte unchanged.
99    #[test]
100    fn button_layout_defaults_to_classic() {
101        assert_eq!(ButtonLayout::default(), ButtonLayout::Classic);
102    }
103
104    #[test]
105    fn metrics_match_recovered_tv() {
106        assert_eq!(STD_BUTTON, Point::new(10, 2));
107        assert_eq!(
108            (
109                BUTTON_GAP,
110                MARGIN_LEFT,
111                MARGIN_RIGHT,
112                MARGIN_TOP,
113                BUTTON_ROW_FROM_BOTTOM
114            ),
115            (2, 3, 2, 2, 3)
116        );
117    }
118}