Skip to main content

gpui_base/
styled.rs

1use gpui::{
2    App, BoxShadow, Corners, DefiniteLength, Div, Edges, FocusHandle, Hsla, Pixels, Role, Styled,
3    Window, div, hsla, point,
4};
5
6#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
7pub enum RoleOverride {
8    #[default]
9    Implicit,
10    Presentational,
11    Role(Role),
12}
13
14impl RoleOverride {
15    pub fn resolve(self, default: impl FnOnce() -> Role) -> Option<Role> {
16        match self {
17            Self::Implicit => Some(default()),
18            Self::Presentational => None,
19            Self::Role(role) => Some(role),
20        }
21    }
22}
23impl From<Role> for RoleOverride {
24    fn from(role: Role) -> Self {
25        Self::Role(role)
26    }
27}
28impl From<Option<Role>> for RoleOverride {
29    fn from(role: Option<Role>) -> Self {
30        role.map_or(Self::Presentational, Self::Role)
31    }
32}
33
34/// A row that centers its children on the cross axis.
35///
36/// See [`StyledExt::h_flex`] for the cross-axis rule, which is not symmetric
37/// with [`v_flex`].
38pub fn h_flex() -> Div {
39    div().h_flex()
40}
41
42/// A column whose children stretch across the cross axis.
43///
44/// See [`StyledExt::v_flex`] for the cross-axis rule, which is not symmetric
45/// with [`h_flex`].
46pub fn v_flex() -> Div {
47    div().v_flex()
48}
49
50pub fn box_shadow(
51    x: impl Into<Pixels>,
52    y: impl Into<Pixels>,
53    blur: impl Into<Pixels>,
54    spread: impl Into<Pixels>,
55    color: Hsla,
56) -> BoxShadow {
57    BoxShadow {
58        offset: point(x.into(), y.into()),
59        blur_radius: blur.into(),
60        spread_radius: spread.into(),
61        inset: false,
62        color: color.into(),
63    }
64}
65
66macro_rules! font_weight {
67    ($method:ident, $weight:ident) => {
68        fn $method(self) -> Self {
69            self.font_weight(gpui::FontWeight::$weight)
70        }
71    };
72}
73
74#[cfg_attr(
75    any(feature = "inspector", debug_assertions),
76    gpui_macros::derive_inspector_reflection
77)]
78pub trait StyledExt: Styled + Sized {
79    /// Lays children out in a row, centered on the cross axis.
80    ///
81    /// The centering is the desktop default for a row of controls — an icon
82    /// beside its label lines up without either side asking for it — but it is
83    /// **not** the mirror image of [`Self::v_flex`], which leaves the cross axis
84    /// stretching. A column placed in a row therefore does not take the row's
85    /// height: it takes its content's height and is centered inside the row.
86    /// When its content is taller than the row, it overflows equally above and
87    /// below, so the column's header is pushed off the top edge and clipped.
88    ///
89    /// Give a full-height column `h_full()` (or the row `items_start()` /
90    /// `items_stretch()`) whenever the child owns a header, a footer, or a
91    /// scroll region that has to resolve against the row's height.
92    ///
93    /// ```
94    /// use gpui_base::StyledExt as _;
95    /// use gpui::{ParentElement as _, Styled as _, div};
96    ///
97    /// // A sidebar beside a detail pane, both spanning the full height.
98    /// div().h_flex().size_full().child(div().w_64().h_full());
99    /// ```
100    fn h_flex(self) -> Self {
101        self.flex().flex_row().items_center()
102    }
103
104    /// Lays children out in a column, stretching them across the cross axis.
105    ///
106    /// Unlike [`Self::h_flex`] this installs no cross-axis alignment, so a child
107    /// without a width fills the column. See `h_flex` for the asymmetry.
108    fn v_flex(self) -> Self {
109        self.flex().flex_col()
110    }
111
112    fn paddings<L>(self, paddings: impl Into<Edges<L>>) -> Self
113    where
114        L: Into<DefiniteLength> + Clone + Default + std::fmt::Debug + PartialEq,
115    {
116        let paddings = paddings.into();
117        self.pt(paddings.top.into())
118            .pb(paddings.bottom.into())
119            .pl(paddings.left.into())
120            .pr(paddings.right.into())
121    }
122
123    fn margins<L>(self, margins: impl Into<Edges<L>>) -> Self
124    where
125        L: Into<DefiniteLength> + Clone + Default + std::fmt::Debug + PartialEq,
126    {
127        let margins = margins.into();
128        self.mt(margins.top.into())
129            .mb(margins.bottom.into())
130            .ml(margins.left.into())
131            .mr(margins.right.into())
132    }
133
134    fn debug_red(self) -> Self {
135        if cfg!(debug_assertions) {
136            self.border_1().border_color(hsl(0., 72.2, 50.6))
137        } else {
138            self
139        }
140    }
141
142    fn debug_blue(self) -> Self {
143        if cfg!(debug_assertions) {
144            self.border_1().border_color(hsl(217.2, 91.2, 59.8))
145        } else {
146            self
147        }
148    }
149
150    fn debug_yellow(self) -> Self {
151        if cfg!(debug_assertions) {
152            self.border_1().border_color(hsl(47.9, 95.8, 53.1))
153        } else {
154            self
155        }
156    }
157
158    fn debug_green(self) -> Self {
159        if cfg!(debug_assertions) {
160            self.border_1().border_color(hsl(142.1, 70.6, 45.3))
161        } else {
162            self
163        }
164    }
165
166    fn debug_pink(self) -> Self {
167        if cfg!(debug_assertions) {
168            self.border_1().border_color(hsl(330.4, 81.2, 60.4))
169        } else {
170            self
171        }
172    }
173
174    fn debug_focused(self, focus_handle: &FocusHandle, window: &Window, cx: &App) -> Self {
175        if cfg!(debug_assertions) && focus_handle.contains_focused(window, cx) {
176            self.debug_blue()
177        } else {
178            self
179        }
180    }
181
182    font_weight!(font_thin, THIN);
183    font_weight!(font_extralight, EXTRA_LIGHT);
184    font_weight!(font_light, LIGHT);
185    font_weight!(font_normal, NORMAL);
186    font_weight!(font_medium, MEDIUM);
187    font_weight!(font_semibold, SEMIBOLD);
188    font_weight!(font_bold, BOLD);
189    font_weight!(font_extrabold, EXTRA_BOLD);
190    font_weight!(font_black, BLACK);
191
192    fn corner_radii(self, radius: Corners<Pixels>) -> Self {
193        self.rounded_tl(radius.top_left)
194            .rounded_tr(radius.top_right)
195            .rounded_bl(radius.bottom_left)
196            .rounded_br(radius.bottom_right)
197    }
198}
199
200impl<E: Styled> StyledExt for E {}
201
202#[cfg(any(feature = "inspector", debug_assertions))]
203pub fn styled_ext_reflection_methods<T: Styled + 'static>()
204-> Vec<gpui::inspector_reflection::FunctionReflection<T>> {
205    styled_ext_reflection::methods::<T>()
206}
207
208fn hsl(hue: f32, saturation: f32, lightness: f32) -> Hsla {
209    hsla(hue / 360., saturation / 100., lightness / 100., 1.)
210}
211
212#[cfg(test)]
213mod tests {
214    use super::*;
215    use gpui::{
216        Context, InteractiveElement as _, IntoElement, ParentElement as _, Render, TestAppContext,
217        px,
218    };
219
220    fn column(selector: &'static str, height: f32) -> Div {
221        div()
222            .w(px(20.))
223            .h(px(height))
224            .flex_shrink_0()
225            .debug_selector(move || selector.to_string())
226    }
227
228    struct CrossAxisTest;
229
230    impl Render for CrossAxisTest {
231        fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
232            div()
233                .w(px(200.))
234                .h(px(100.))
235                .child(
236                    h_flex()
237                        .size_full()
238                        .child(column("row-child", 40.))
239                        .child(column("row-overflowing-child", 140.))
240                        .child(
241                            div()
242                                .w(px(20.))
243                                .debug_selector(|| "row-stretch".to_string()),
244                        ),
245                )
246                .child(
247                    v_flex().size_full().child(
248                        div()
249                            .h(px(20.))
250                            .debug_selector(|| "col-stretch".to_string()),
251                    ),
252                )
253        }
254    }
255
256    /// `h_flex` centers on the cross axis while `v_flex` leaves the default
257    /// stretch. The asymmetry is deliberate but easy to trip over, so lock it.
258    #[gpui::test]
259    fn h_flex_centers_and_v_flex_stretches_on_the_cross_axis(cx: &mut TestAppContext) {
260        let (_, cx) = cx.add_window_view(|_, _| CrossAxisTest);
261        cx.run_until_parked();
262        cx.update(|window, cx| {
263            _ = window.draw(cx);
264        });
265
266        // A shorter child of a 100px row sits at (100 - 40) / 2, not at the top,
267        // and a height-less child keeps its content height instead of filling.
268        let child = cx.debug_bounds("row-child").unwrap();
269        assert_eq!(child.top(), px(30.));
270        assert_eq!(cx.debug_bounds("row-stretch").unwrap().size.height, px(0.));
271
272        // And a child taller than the row is centered too, so its top — a
273        // column's header, in a real layout — is pushed off the top edge.
274        let overflowing = cx.debug_bounds("row-overflowing-child").unwrap();
275        assert_eq!(overflowing.top(), px(-20.));
276
277        // A width-less child of a column does fill the cross axis.
278        assert_eq!(cx.debug_bounds("col-stretch").unwrap().size.width, px(200.));
279    }
280}