iced_core/
widget.rs

Help
1//! Create custom widgets and operate on them.
2pub mod operation;
3pub mod text;
4pub mod tree;
5
6pub use crate::id::Id;
7pub use operation::Operation;
8pub use text::Text;
9pub use tree::Tree;
10
11use crate::event::{self, Event};
12use crate::layout::{self, Layout};
13use crate::mouse;
14use crate::overlay;
15use crate::renderer;
16use crate::{Clipboard, Length, Rectangle, Shell, Size, Vector};
17
18/// A component that displays information and allows interaction.
19///
20/// If you want to build your own widgets, you will need to implement this
21/// trait.
22///
23/// # Examples
24/// The repository has some [examples] showcasing how to implement a custom
25/// widget:
26///
27/// - [`bezier_tool`], a Paint-like tool for drawing Bézier curves using
28///   [`lyon`].
29/// - [`custom_widget`], a demonstration of how to build a custom widget that
30///   draws a circle.
31/// - [`geometry`], a custom widget showcasing how to draw geometry with the
32///   `Mesh2D` primitive in [`iced_wgpu`].
33///
34/// [examples]: https://github.com/iced-rs/iced/tree/0.13/examples
35/// [`bezier_tool`]: https://github.com/iced-rs/iced/tree/0.13/examples/bezier_tool
36/// [`custom_widget`]: https://github.com/iced-rs/iced/tree/0.13/examples/custom_widget
37/// [`geometry`]: https://github.com/iced-rs/iced/tree/0.13/examples/geometry
38/// [`lyon`]: https://github.com/nical/lyon
39/// [`iced_wgpu`]: https://github.com/iced-rs/iced/tree/0.13/wgpu
40pub trait Widget<Message, Theme, Renderer>
41where
42    Renderer: crate::Renderer,
43{
44    /// Returns the [`Size`] of the [`Widget`] in lengths.
45    fn size(&self) -> Size<Length>;
46
47    /// Returns a [`Size`] hint for laying out the [`Widget`].
48    ///
49    /// This hint may be used by some widget containers to adjust their sizing strategy
50    /// during construction.
51    fn size_hint(&self) -> Size<Length> {
52        self.size()
53    }
54
55    /// Returns the [`layout::Node`] of the [`Widget`].
56    ///
57    /// This [`layout::Node`] is used by the runtime to compute the [`Layout`] of the
58    /// user interface.
59    fn layout(
60        &self,
61        tree: &mut Tree,
62        renderer: &Renderer,
63        limits: &layout::Limits,
64    ) -> layout::Node;
65
66    /// Draws the [`Widget`] using the associated `Renderer`.
67    fn draw(
68        &self,
69        tree: &Tree,
70        renderer: &mut Renderer,
71        theme: &Theme,
72        style: &renderer::Style,
73        layout: Layout<'_>,
74        cursor: mouse::Cursor,
75        viewport: &Rectangle,
76    );
77
78    /// Returns the [`Tag`] of the [`Widget`].
79    ///
80    /// [`Tag`]: tree::Tag
81    fn tag(&self) -> tree::Tag {
82        tree::Tag::stateless()
83    }
84
85    /// Returns the [`State`] of the [`Widget`].
86    ///
87    /// [`State`]: tree::State
88    fn state(&self) -> tree::State {
89        tree::State::None
90    }
91
92    /// Returns the state [`Tree`] of the children of the [`Widget`].
93    fn children(&self) -> Vec<Tree> {
94        Vec::new()
95    }
96
97    /// Reconciliates the [`Widget`] with the provided [`Tree`].
98    fn diff(&mut self, _tree: &mut Tree) {}
99
100    /// Applies an [`Operation`] to the [`Widget`].
101    fn operate(
102        &self,
103        _state: &mut Tree,
104        _layout: Layout<'_>,
105        _renderer: &Renderer,
106        _operation: &mut dyn Operation,
107    ) {
108    }
109
110    /// Processes a runtime [`Event`].
111    ///
112    /// By default, it does nothing.
113    fn on_event(
114        &mut self,
115        _state: &mut Tree,
116        _event: Event,
117        _layout: Layout<'_>,
118        _cursor: mouse::Cursor,
119        _renderer: &Renderer,
120        _clipboard: &mut dyn Clipboard,
121        _shell: &mut Shell<'_, Message>,
122        _viewport: &Rectangle,
123    ) -> event::Status {
124        event::Status::Ignored
125    }
126
127    /// Returns the current [`mouse::Interaction`] of the [`Widget`].
128    ///
129    /// By default, it returns [`mouse::Interaction::Idle`].
130    fn mouse_interaction(
131        &self,
132        _state: &Tree,
133        _layout: Layout<'_>,
134        _cursor: mouse::Cursor,
135        _viewport: &Rectangle,
136        _renderer: &Renderer,
137    ) -> mouse::Interaction {
138        mouse::Interaction::None
139    }
140
141    /// Returns the overlay of the [`Widget`], if there is any.
142    fn overlay<'a>(
143        &'a mut self,
144        _state: &'a mut Tree,
145        _layout: Layout<'_>,
146        _renderer: &Renderer,
147        _translation: Vector,
148    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
149        None
150    }
151
152    #[cfg(feature = "a11y")]
153    /// get the a11y nodes for the widget and its children
154    fn a11y_nodes(
155        &self,
156        _layout: Layout<'_>,
157        _state: &Tree,
158        _cursor: mouse::Cursor,
159    ) -> iced_accessibility::A11yTree {
160        iced_accessibility::A11yTree::default()
161    }
162
163    /// Returns the id of the widget
164    fn id(&self) -> Option<Id> {
165        None
166    }
167
168    /// Sets the id of the widget
169    /// This may be called while diffing the widget tree
170    fn set_id(&mut self, _id: Id) {}
171
172    /// Adds the drag destination rectangles of the widget.
173    /// Runs after the layout phase for each widget in the tree.
174    fn drag_destinations(
175        &self,
176        _state: &Tree,
177        _layout: Layout<'_>,
178        _renderer: &Renderer,
179        _dnd_rectangles: &mut crate::clipboard::DndDestinationRectangles,
180    ) {
181    }
182}
iced_core/widget.rs

iced_core/
widget.rs
