iced_widget/
svg.rs

1//! Svg widgets display vector graphics in your application.
2//!
3//! # Example
4//! ```no_run
5//! # mod iced { pub mod widget { pub use iced_widget::*; } }
6//! # pub type State = ();
7//! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
8//! use iced::widget::svg;
9//!
10//! enum Message {
11//!     // ...
12//! }
13//!
14//! fn view(state: &State) -> Element<'_, Message> {
15//!     svg("tiger.svg").into()
16//! }
17//! ```
18use crate::core::layout;
19use crate::core::mouse;
20use crate::core::renderer;
21use crate::core::svg;
22use crate::core::widget;
23use crate::core::widget::Tree;
24use crate::core::widget::operation::accessible::{Accessible, Role};
25use crate::core::window;
26use crate::core::{
27    Color, ContentFit, Element, Event, Layout, Length, Point, Rectangle, Rotation, Shell, Size,
28    Theme, Vector, Widget,
29};
30
31use std::path::PathBuf;
32
33pub use crate::core::svg::Handle;
34
35/// A vector graphics image.
36///
37/// An [`Svg`] image resizes smoothly without losing any quality.
38///
39/// [`Svg`] images can have a considerable rendering cost when resized,
40/// specially when they are complex.
41///
42/// # Example
43/// ```no_run
44/// # mod iced { pub mod widget { pub use iced_widget::*; } }
45/// # pub type State = ();
46/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
47/// use iced::widget::svg;
48///
49/// enum Message {
50///     // ...
51/// }
52///
53/// fn view(state: &State) -> Element<'_, Message> {
54///     svg("tiger.svg").into()
55/// }
56/// ```
57pub struct Svg<'a, Theme = crate::Theme>
58where
59    Theme: Catalog,
60{
61    handle: Handle,
62    width: Length,
63    height: Length,
64    content_fit: ContentFit,
65    class: Theme::Class<'a>,
66    rotation: Rotation,
67    opacity: f32,
68    status: Option<Status>,
69    alt: Option<String>,
70    description: Option<String>,
71}
72
73impl<'a, Theme> Svg<'a, Theme>
74where
75    Theme: Catalog,
76{
77    /// Creates a new [`Svg`] from the given [`Handle`].
78    pub fn new(handle: impl Into<Handle>) -> Self {
79        Svg {
80            handle: handle.into(),
81            width: Length::Fill,
82            height: Length::Shrink,
83            content_fit: ContentFit::Contain,
84            class: Theme::default(),
85            rotation: Rotation::default(),
86            opacity: 1.0,
87            status: None,
88            alt: None,
89            description: None,
90        }
91    }
92
93    /// Creates a new [`Svg`] that will display the contents of the file at the
94    /// provided path.
95    #[must_use]
96    pub fn from_path(path: impl Into<PathBuf>) -> Self {
97        Self::new(Handle::from_path(path))
98    }
99
100    /// Sets the width of the [`Svg`].
101    #[must_use]
102    pub fn width(mut self, width: impl Into<Length>) -> Self {
103        self.width = width.into();
104        self
105    }
106
107    /// Sets the height of the [`Svg`].
108    #[must_use]
109    pub fn height(mut self, height: impl Into<Length>) -> Self {
110        self.height = height.into();
111        self
112    }
113
114    /// Sets the [`ContentFit`] of the [`Svg`].
115    ///
116    /// Defaults to [`ContentFit::Contain`]
117    #[must_use]
118    pub fn content_fit(self, content_fit: ContentFit) -> Self {
119        Self {
120            content_fit,
121            ..self
122        }
123    }
124
125    /// Sets the style of the [`Svg`].
126    #[must_use]
127    pub fn style(mut self, style: impl Fn(&Theme, Status) -> Style + 'a) -> Self
128    where
129        Theme::Class<'a>: From<StyleFn<'a, Theme>>,
130    {
131        self.class = (Box::new(style) as StyleFn<'a, Theme>).into();
132        self
133    }
134
135    /// Sets the style class of the [`Svg`].
136    #[cfg(feature = "advanced")]
137    #[must_use]
138    pub fn class(mut self, class: impl Into<Theme::Class<'a>>) -> Self {
139        self.class = class.into();
140        self
141    }
142
143    /// Applies the given [`Rotation`] to the [`Svg`].
144    pub fn rotation(mut self, rotation: impl Into<Rotation>) -> Self {
145        self.rotation = rotation.into();
146        self
147    }
148
149    /// Sets the opacity of the [`Svg`].
150    ///
151    /// It should be in the [0.0, 1.0] range—`0.0` meaning completely transparent,
152    /// and `1.0` meaning completely opaque.
153    pub fn opacity(mut self, opacity: impl Into<f32>) -> Self {
154        self.opacity = opacity.into();
155        self
156    }
157
158    /// Sets the alt text of the [`Svg`].
159    ///
160    /// This is the accessible name announced by screen readers. It should
161    /// be a short phrase describing the image content.
162    pub fn alt(mut self, text: impl Into<String>) -> Self {
163        self.alt = Some(text.into());
164        self
165    }
166
167    /// Sets an extended description of the [`Svg`].
168    ///
169    /// This supplements the alt text with additional context for
170    /// assistive technology, when the alt text alone is not sufficient.
171    pub fn description(mut self, description: impl Into<String>) -> Self {
172        self.description = Some(description.into());
173        self
174    }
175}
176
177impl<Message, Theme, Renderer> Widget<Message, Theme, Renderer> for Svg<'_, Theme>
178where
179    Renderer: svg::Renderer,
180    Theme: Catalog,
181{
182    fn size(&self) -> Size<Length> {
183        Size {
184            width: self.width,
185            height: self.height,
186        }
187    }
188
189    fn layout(
190        &mut self,
191        _tree: &mut Tree,
192        renderer: &Renderer,
193        limits: &layout::Limits,
194    ) -> layout::Node {
195        // The raw w/h of the underlying image
196        let Size { width, height } = renderer.measure_svg(&self.handle);
197        let image_size = Size::new(width as f32, height as f32);
198
199        // The rotated size of the svg
200        let rotated_size = self.rotation.apply(image_size);
201
202        // The size to be available to the widget prior to `Shrink`ing
203        let raw_size = limits.resolve(self.width, self.height, rotated_size);
204
205        // The uncropped size of the image when fit to the bounds above
206        let full_size = self.content_fit.fit(rotated_size, raw_size);
207
208        // Shrink the widget to fit the resized image, if requested
209        let final_size = Size {
210            width: match self.width {
211                Length::Shrink => f32::min(raw_size.width, full_size.width),
212                _ => raw_size.width,
213            },
214            height: match self.height {
215                Length::Shrink => f32::min(raw_size.height, full_size.height),
216                _ => raw_size.height,
217            },
218        };
219
220        layout::Node::new(final_size)
221    }
222
223    fn update(
224        &mut self,
225        _state: &mut Tree,
226        event: &Event,
227        layout: Layout<'_>,
228        cursor: mouse::Cursor,
229        _renderer: &Renderer,
230        shell: &mut Shell<'_, Message>,
231        _viewport: &Rectangle,
232    ) {
233        let current_status = if cursor.is_over(layout.bounds()) {
234            Status::Hovered
235        } else {
236            Status::Idle
237        };
238
239        if let Event::Window(window::Event::RedrawRequested(_now)) = event {
240            self.status = Some(current_status);
241        } else if self.status.is_some_and(|status| status != current_status) {
242            shell.request_redraw();
243        }
244    }
245
246    fn draw(
247        &self,
248        _state: &Tree,
249        renderer: &mut Renderer,
250        theme: &Theme,
251        _style: &renderer::Style,
252        layout: Layout<'_>,
253        _cursor: mouse::Cursor,
254        _viewport: &Rectangle,
255    ) {
256        let Size { width, height } = renderer.measure_svg(&self.handle);
257        let image_size = Size::new(width as f32, height as f32);
258        let rotated_size = self.rotation.apply(image_size);
259
260        let bounds = layout.bounds();
261        let adjusted_fit = self.content_fit.fit(rotated_size, bounds.size());
262        let scale = Vector::new(
263            adjusted_fit.width / rotated_size.width,
264            adjusted_fit.height / rotated_size.height,
265        );
266
267        let final_size = image_size * scale;
268
269        let position = match self.content_fit {
270            ContentFit::None => Point::new(
271                bounds.x + (rotated_size.width - adjusted_fit.width) / 2.0,
272                bounds.y + (rotated_size.height - adjusted_fit.height) / 2.0,
273            ),
274            _ => Point::new(
275                bounds.center_x() - final_size.width / 2.0,
276                bounds.center_y() - final_size.height / 2.0,
277            ),
278        };
279
280        let drawing_bounds = Rectangle::new(position, final_size);
281
282        let style = theme.style(&self.class, self.status.unwrap_or(Status::Idle));
283
284        renderer.draw_svg(
285            svg::Svg {
286                handle: self.handle.clone(),
287                color: style.color,
288                rotation: self.rotation.radians(),
289                opacity: self.opacity,
290            },
291            drawing_bounds,
292            bounds,
293        );
294    }
295
296    fn operate(
297        &mut self,
298        _tree: &mut Tree,
299        layout: Layout<'_>,
300        _renderer: &Renderer,
301        operation: &mut dyn widget::Operation,
302    ) {
303        operation.accessible(
304            None,
305            layout.bounds(),
306            &Accessible {
307                role: Role::Image,
308                label: self.alt.as_deref(),
309                description: self.description.as_deref(),
310                ..Accessible::default()
311            },
312        );
313    }
314}
315
316impl<'a, Message, Theme, Renderer> From<Svg<'a, Theme>> for Element<'a, Message, Theme, Renderer>
317where
318    Theme: Catalog + 'a,
319    Renderer: svg::Renderer + 'a,
320{
321    fn from(icon: Svg<'a, Theme>) -> Element<'a, Message, Theme, Renderer> {
322        Element::new(icon)
323    }
324}
325
326/// The possible status of an [`Svg`].
327#[derive(Debug, Clone, Copy, PartialEq, Eq)]
328pub enum Status {
329    /// The [`Svg`] is idle.
330    Idle,
331    /// The [`Svg`] is being hovered.
332    Hovered,
333}
334
335/// The appearance of an [`Svg`].
336#[derive(Debug, Clone, Copy, PartialEq, Default)]
337pub struct Style {
338    /// The [`Color`] filter of an [`Svg`].
339    ///
340    /// Useful for coloring a symbolic icon.
341    ///
342    /// `None` keeps the original color.
343    pub color: Option<Color>,
344}
345
346/// The theme catalog of an [`Svg`].
347pub trait Catalog {
348    /// The item class of the [`Catalog`].
349    type Class<'a>;
350
351    /// The default class produced by the [`Catalog`].
352    fn default<'a>() -> Self::Class<'a>;
353
354    /// The [`Style`] of a class with the given status.
355    fn style(&self, class: &Self::Class<'_>, status: Status) -> Style;
356}
357
358impl Catalog for Theme {
359    type Class<'a> = StyleFn<'a, Self>;
360
361    fn default<'a>() -> Self::Class<'a> {
362        Box::new(|_theme, _status| Style::default())
363    }
364
365    fn style(&self, class: &Self::Class<'_>, status: Status) -> Style {
366        class(self, status)
367    }
368}
369
370/// A styling function for an [`Svg`].
371///
372/// This is just a boxed closure: `Fn(&Theme, Status) -> Style`.
373pub type StyleFn<'a, Theme> = Box<dyn Fn(&Theme, Status) -> Style + 'a>;
374
375impl<Theme> From<Style> for StyleFn<'_, Theme> {
376    fn from(style: Style) -> Self {
377        Box::new(move |_theme, _status| style)
378    }
379}
iced_widget/svg.rs

iced_widget/
svg.rs
