iced_core/
widget.rs

1//! Create custom widgets and operate on them.
2pub mod operation;
3pub mod text;
4pub mod tree;
5
6mod id;
7
8pub use id::Id;
9pub use operation::Operation;
10pub use text::Text;
11pub use tree::Tree;
12
13use crate::layout::{self, Layout};
14use crate::mouse;
15use crate::overlay;
16use crate::renderer;
17use crate::{Clipboard, Event, Length, Rectangle, Shell, Size, Vector};
18
19/// A component that displays information and allows interaction.
20///
21/// If you want to build your own widgets, you will need to implement this
22/// trait.
23///
24/// # Examples
25/// The repository has some [examples] showcasing how to implement a custom
26/// widget:
27///
28/// - [`custom_widget`], a demonstration of how to build a custom widget that
29///   draws a circle.
30/// - [`geometry`], a custom widget showcasing how to draw geometry with the
31///   `Mesh2D` primitive in [`iced_wgpu`].
32///
33/// [examples]: https://github.com/iced-rs/iced/tree/master/examples
34/// [`custom_widget`]: https://github.com/iced-rs/iced/tree/master/examples/custom_widget
35/// [`geometry`]: https://github.com/iced-rs/iced/tree/master/examples/geometry
36/// [`iced_wgpu`]: https://github.com/iced-rs/iced/tree/master/wgpu
37pub trait Widget<Message, Theme, Renderer>
38where
39    Renderer: crate::Renderer,
40{
41    /// Returns the [`Size`] of the [`Widget`] in lengths.
42    fn size(&self) -> Size<Length>;
43
44    /// Returns a [`Size`] hint for laying out the [`Widget`].
45    ///
46    /// This hint may be used by some widget containers to adjust their sizing strategy
47    /// during construction.
48    fn size_hint(&self) -> Size<Length> {
49        self.size()
50    }
51
52    /// Returns the [`layout::Node`] of the [`Widget`].
53    ///
54    /// This [`layout::Node`] is used by the runtime to compute the [`Layout`] of the
55    /// user interface.
56    fn layout(
57        &mut self,
58        tree: &mut Tree,
59        renderer: &Renderer,
60        limits: &layout::Limits,
61    ) -> layout::Node;
62
63    /// Draws the [`Widget`] using the associated `Renderer`.
64    fn draw(
65        &self,
66        tree: &Tree,
67        renderer: &mut Renderer,
68        theme: &Theme,
69        style: &renderer::Style,
70        layout: Layout<'_>,
71        cursor: mouse::Cursor,
72        viewport: &Rectangle,
73    );
74
75    /// Returns the [`Tag`] of the [`Widget`].
76    ///
77    /// [`Tag`]: tree::Tag
78    fn tag(&self) -> tree::Tag {
79        tree::Tag::stateless()
80    }
81
82    /// Returns the [`State`] of the [`Widget`].
83    ///
84    /// [`State`]: tree::State
85    fn state(&self) -> tree::State {
86        tree::State::None
87    }
88
89    /// Returns the state [`Tree`] of the children of the [`Widget`].
90    fn children(&self) -> Vec<Tree> {
91        Vec::new()
92    }
93
94    /// Reconciles the [`Widget`] with the provided [`Tree`].
95    fn diff(&self, tree: &mut Tree) {
96        tree.children.clear();
97    }
98
99    /// Applies an [`Operation`] to the [`Widget`].
100    fn operate(
101        &mut self,
102        _tree: &mut Tree,
103        _layout: Layout<'_>,
104        _renderer: &Renderer,
105        _operation: &mut dyn Operation,
106    ) {
107    }
108
109    /// Processes a runtime [`Event`].
110    ///
111    /// By default, it does nothing.
112    fn update(
113        &mut self,
114        _tree: &mut Tree,
115        _event: &Event,
116        _layout: Layout<'_>,
117        _cursor: mouse::Cursor,
118        _renderer: &Renderer,
119        _clipboard: &mut dyn Clipboard,
120        _shell: &mut Shell<'_, Message>,
121        _viewport: &Rectangle,
122    ) {
123    }
124
125    /// Returns the current [`mouse::Interaction`] of the [`Widget`].
126    ///
127    /// By default, it returns [`mouse::Interaction::None`].
128    fn mouse_interaction(
129        &self,
130        _tree: &Tree,
131        _layout: Layout<'_>,
132        _cursor: mouse::Cursor,
133        _viewport: &Rectangle,
134        _renderer: &Renderer,
135    ) -> mouse::Interaction {
136        mouse::Interaction::None
137    }
138
139    /// Returns the overlay of the [`Widget`], if there is any.
140    fn overlay<'a>(
141        &'a mut self,
142        _tree: &'a mut Tree,
143        _layout: Layout<'a>,
144        _renderer: &Renderer,
145        _viewport: &Rectangle,
146        _translation: Vector,
147    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
148        None
149    }
150}
iced_core/widget.rs

iced_core/
widget.rs
