iced_widget/
canvas.rs

1//! Canvases can be leveraged to draw interactive 2D graphics.
2//!
3//! # Example: Drawing a Simple Circle
4//! ```no_run
5//! # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
6//! # pub type State = ();
7//! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
8//! #
9//! use iced::mouse;
10//! use iced::widget::canvas;
11//! use iced::{Color, Rectangle, Renderer, Theme};
12//!
13//! // First, we define the data we need for drawing
14//! #[derive(Debug)]
15//! struct Circle {
16//!     radius: f32,
17//! }
18//!
19//! // Then, we implement the `Program` trait
20//! impl<Message> canvas::Program<Message> for Circle {
21//!     // No internal state
22//!     type State = ();
23//!
24//!     fn draw(
25//!         &self,
26//!         _state: &(),
27//!         renderer: &Renderer,
28//!         _theme: &Theme,
29//!         bounds: Rectangle,
30//!         _cursor: mouse::Cursor
31//!     ) -> Vec<canvas::Geometry> {
32//!         // We prepare a new `Frame`
33//!         let mut frame = canvas::Frame::new(renderer, bounds.size());
34//!
35//!         // We create a `Path` representing a simple circle
36//!         let circle = canvas::Path::circle(frame.center(), self.radius);
37//!
38//!         // And fill it with some color
39//!         frame.fill(&circle, Color::BLACK);
40//!
41//!         // Then, we produce the geometry
42//!         vec![frame.into_geometry()]
43//!     }
44//! }
45//!
46//! // Finally, we simply use our `Circle` to create the `Canvas`!
47//! fn view<'a, Message: 'a>(_state: &'a State) -> Element<'a, Message> {
48//!     canvas(Circle { radius: 50.0 }).into()
49//! }
50//! ```
51mod program;
52
53pub use program::Program;
54
55pub use crate::Action;
56pub use crate::core::event::Event;
57pub use crate::graphics::cache::Group;
58pub use crate::graphics::geometry::{
59    Fill, Gradient, Image, LineCap, LineDash, LineJoin, Path, Stroke, Style, Text, fill, gradient,
60    path, stroke,
61};
62
63use crate::core::event;
64use crate::core::layout::{self, Layout};
65use crate::core::mouse;
66use crate::core::renderer;
67use crate::core::widget::tree::{self, Tree};
68use crate::core::window;
69use crate::core::{Element, Length, Rectangle, Shell, Size, Vector, Widget};
70use crate::graphics::geometry;
71
72use std::marker::PhantomData;
73
74/// A simple cache that stores generated [`Geometry`] to avoid recomputation.
75///
76/// A [`Cache`] will not redraw its geometry unless the dimensions of its layer
77/// change or it is explicitly cleared.
78pub type Cache<Renderer = crate::Renderer> = geometry::Cache<Renderer>;
79
80/// The geometry supported by a renderer.
81pub type Geometry<Renderer = crate::Renderer> = <Renderer as geometry::Renderer>::Geometry;
82
83/// The frame supported by a renderer.
84pub type Frame<Renderer = crate::Renderer> = geometry::Frame<Renderer>;
85
86/// A widget capable of drawing 2D graphics.
87///
88/// # Example: Drawing a Simple Circle
89/// ```no_run
90/// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
91/// # pub type State = ();
92/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
93/// #
94/// use iced::mouse;
95/// use iced::widget::canvas;
96/// use iced::{Color, Rectangle, Renderer, Theme};
97///
98/// // First, we define the data we need for drawing
99/// #[derive(Debug)]
100/// struct Circle {
101///     radius: f32,
102/// }
103///
104/// // Then, we implement the `Program` trait
105/// impl<Message> canvas::Program<Message> for Circle {
106///     // No internal state
107///     type State = ();
108///
109///     fn draw(
110///         &self,
111///         _state: &(),
112///         renderer: &Renderer,
113///         _theme: &Theme,
114///         bounds: Rectangle,
115///         _cursor: mouse::Cursor
116///     ) -> Vec<canvas::Geometry> {
117///         // We prepare a new `Frame`
118///         let mut frame = canvas::Frame::new(renderer, bounds.size());
119///
120///         // We create a `Path` representing a simple circle
121///         let circle = canvas::Path::circle(frame.center(), self.radius);
122///
123///         // And fill it with some color
124///         frame.fill(&circle, Color::BLACK);
125///
126///         // Then, we produce the geometry
127///         vec![frame.into_geometry()]
128///     }
129/// }
130///
131/// // Finally, we simply use our `Circle` to create the `Canvas`!
132/// fn view<'a, Message: 'a>(_state: &'a State) -> Element<'a, Message> {
133///     canvas(Circle { radius: 50.0 }).into()
134/// }
135/// ```
136#[derive(Debug)]
137pub struct Canvas<P, Message, Theme = crate::Theme, Renderer = crate::Renderer>
138where
139    Renderer: geometry::Renderer,
140    P: Program<Message, Theme, Renderer>,
141{
142    width: Length,
143    height: Length,
144    program: P,
145    message_: PhantomData<Message>,
146    theme_: PhantomData<Theme>,
147    renderer_: PhantomData<Renderer>,
148    last_mouse_interaction: Option<mouse::Interaction>,
149}
150
151impl<P, Message, Theme, Renderer> Canvas<P, Message, Theme, Renderer>
152where
153    P: Program<Message, Theme, Renderer>,
154    Renderer: geometry::Renderer,
155{
156    const DEFAULT_SIZE: f32 = 100.0;
157
158    /// Creates a new [`Canvas`].
159    pub fn new(program: P) -> Self {
160        Canvas {
161            width: Length::Fixed(Self::DEFAULT_SIZE),
162            height: Length::Fixed(Self::DEFAULT_SIZE),
163            program,
164            message_: PhantomData,
165            theme_: PhantomData,
166            renderer_: PhantomData,
167            last_mouse_interaction: None,
168        }
169    }
170
171    /// Sets the width of the [`Canvas`].
172    pub fn width(mut self, width: impl Into<Length>) -> Self {
173        self.width = width.into();
174        self
175    }
176
177    /// Sets the height of the [`Canvas`].
178    pub fn height(mut self, height: impl Into<Length>) -> Self {
179        self.height = height.into();
180        self
181    }
182}
183
184impl<P, Message, Theme, Renderer> Widget<Message, Theme, Renderer>
185    for Canvas<P, Message, Theme, Renderer>
186where
187    Renderer: geometry::Renderer,
188    P: Program<Message, Theme, Renderer>,
189{
190    fn tag(&self) -> tree::Tag {
191        struct Tag<T>(T);
192        tree::Tag::of::<Tag<P::State>>()
193    }
194
195    fn state(&self) -> tree::State {
196        tree::State::new(P::State::default())
197    }
198
199    fn size(&self) -> Size<Length> {
200        Size {
201            width: self.width,
202            height: self.height,
203        }
204    }
205
206    fn layout(
207        &mut self,
208        _tree: &mut Tree,
209        _renderer: &Renderer,
210        limits: &layout::Limits,
211    ) -> layout::Node {
212        layout::atomic(limits, self.width, self.height)
213    }
214
215    fn update(
216        &mut self,
217        tree: &mut Tree,
218        event: &Event,
219        layout: Layout<'_>,
220        cursor: mouse::Cursor,
221        renderer: &Renderer,
222        shell: &mut Shell<'_, Message>,
223        viewport: &Rectangle,
224    ) {
225        let bounds = layout.bounds();
226
227        let state = tree.state.downcast_mut::<P::State>();
228        let is_redraw_request =
229            matches!(event, Event::Window(window::Event::RedrawRequested(_now)),);
230
231        if let Some(action) = self.program.update(state, event, bounds, cursor) {
232            let (message, redraw_request, event_status) = action.into_inner();
233
234            shell.request_redraw_at(redraw_request);
235
236            if let Some(message) = message {
237                shell.publish(message);
238            }
239
240            if event_status == event::Status::Captured {
241                shell.capture_event();
242            }
243        }
244
245        if shell.redraw_request() != window::RedrawRequest::NextFrame {
246            let mouse_interaction =
247                self.mouse_interaction(tree, layout, cursor, viewport, renderer);
248
249            if is_redraw_request {
250                self.last_mouse_interaction = Some(mouse_interaction);
251            } else if self
252                .last_mouse_interaction
253                .is_some_and(|last_mouse_interaction| last_mouse_interaction != mouse_interaction)
254            {
255                shell.request_redraw();
256            }
257        }
258    }
259
260    fn mouse_interaction(
261        &self,
262        tree: &Tree,
263        layout: Layout<'_>,
264        cursor: mouse::Cursor,
265        _viewport: &Rectangle,
266        _renderer: &Renderer,
267    ) -> mouse::Interaction {
268        let bounds = layout.bounds();
269        let state = tree.state.downcast_ref::<P::State>();
270
271        self.program.mouse_interaction(state, bounds, cursor)
272    }
273
274    fn draw(
275        &self,
276        tree: &Tree,
277        renderer: &mut Renderer,
278        theme: &Theme,
279        _style: &renderer::Style,
280        layout: Layout<'_>,
281        cursor: mouse::Cursor,
282        _viewport: &Rectangle,
283    ) {
284        let bounds = layout.bounds();
285
286        if bounds.width < 1.0 || bounds.height < 1.0 {
287            return;
288        }
289
290        let state = tree.state.downcast_ref::<P::State>();
291
292        renderer.with_translation(Vector::new(bounds.x, bounds.y), |renderer| {
293            let layers = self.program.draw(state, renderer, theme, bounds, cursor);
294
295            for layer in layers {
296                renderer.draw_geometry(layer);
297            }
298        });
299    }
300}
301
302impl<'a, P, Message, Theme, Renderer> From<Canvas<P, Message, Theme, Renderer>>
303    for Element<'a, Message, Theme, Renderer>
304where
305    Message: 'a,
306    Theme: 'a,
307    Renderer: 'a + geometry::Renderer,
308    P: 'a + Program<Message, Theme, Renderer>,
309{
310    fn from(canvas: Canvas<P, Message, Theme, Renderer>) -> Element<'a, Message, Theme, Renderer> {
311        Element::new(canvas)
312    }
313}
iced_widget/canvas.rs

iced_widget/
canvas.rs
