guise/
image.rs

1//! `Image` — a themed wrapper around gpui's `img()` element.
2//!
3//! Shows a picture from a remote URI, an asset path, or a filesystem path,
4//! with guise's sizing/radius vocabulary and an optional fallback slot that
5//! renders while the source is loading or unavailable.
6//!
7//! Note: gpui also exports a *type* named `gpui::Image` — that one is raw
8//! encoded bytes (an `Arc<gpui::Image>` is itself a valid source), not an
9//! element. This component is the element.
10//!
11//! ```ignore
12//! Image::new("https://example.com/cat.png")
13//!     .width(240.0)
14//!     .height(160.0)
15//!     .radius(Size::Md)
16//!     .fit(ObjectFit::Cover)
17//!     .fallback(|| Text::new("no image").dimmed())
18//! ```
19
20use gpui::prelude::*;
21use gpui::{img, px, AnyElement, App, ImageSource, IntoElement, Window};
22
23pub use gpui::ObjectFit;
24
25use crate::devtools::Probed;
26use crate::theme::{theme, Size};
27
28/// An image element.
29///
30/// The source accepts anything gpui's [`ImageSource`] converts from: `&str` /
31/// `String` (an `http(s)://` URI, else an embedded-asset path), a
32/// `Path`/`PathBuf` (local file), or decoded/raw image data.
33#[derive(IntoElement)]
34pub struct Image {
35    source: ImageSource,
36    width: Option<f32>,
37    height: Option<f32>,
38    radius: Option<Size>,
39    circle: bool,
40    fit: ObjectFit,
41    fallback: Option<Box<dyn Fn() -> AnyElement + 'static>>,
42}
43
44impl Image {
45    pub fn new(source: impl Into<ImageSource>) -> Self {
46        Image {
47            source: source.into(),
48            width: None,
49            height: None,
50            radius: None,
51            circle: false,
52            fit: ObjectFit::Cover,
53            fallback: None,
54        }
55    }
56
57    /// Fixed width in px. Give the element a size — an unsized image lays
58    /// out at zero.
59    pub fn width(mut self, width: f32) -> Self {
60        self.width = Some(width);
61        self
62    }
63
64    /// Fixed height in px.
65    pub fn height(mut self, height: f32) -> Self {
66        self.height = Some(height);
67        self
68    }
69
70    /// Corner radius from the theme scale (images are square-cornered by
71    /// default).
72    pub fn radius(mut self, radius: Size) -> Self {
73        self.radius = Some(radius);
74        self
75    }
76
77    /// Clip to a circle (an avatar). Pair with equal `width`/`height`.
78    pub fn circle(mut self) -> Self {
79        self.circle = true;
80        self
81    }
82
83    /// How the picture fills its box (default [`ObjectFit::Cover`]).
84    pub fn fit(mut self, fit: ObjectFit) -> Self {
85        self.fit = fit;
86        self
87    }
88
89    /// Element shown while the source is loading or failed to resolve.
90    pub fn fallback<E: IntoElement>(mut self, fallback: impl Fn() -> E + 'static) -> Self {
91        self.fallback = Some(Box::new(move || fallback().into_any_element()));
92        self
93    }
94}
95
96impl RenderOnce for Image {
97    fn render(self, _window: &mut Window, cx: &mut App) -> impl IntoElement {
98        let t = theme(cx);
99        let mut el = img(self.source).object_fit(self.fit);
100        if let Some(fallback) = self.fallback {
101            el = el.with_fallback(fallback);
102        }
103        if let Some(width) = self.width {
104            el = el.w(px(width));
105        }
106        if let Some(height) = self.height {
107            el = el.h(px(height));
108        }
109        if self.circle {
110            el = el.rounded_full();
111        } else if let Some(radius) = self.radius {
112            el = el.rounded(px(t.radius(radius)));
113        }
114        el.probe("Image")
115    }
116}
guise/image.rs

guise/
image.rs
