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::{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 the [`layout::Node`] of the [`Widget`].
45    ///
46    /// This [`layout::Node`] is used by the runtime to compute the [`Layout`] of the
47    /// user interface.
48    fn layout(
49        &mut self,
50        tree: &mut Tree,
51        renderer: &Renderer,
52        limits: &layout::Limits,
53    ) -> layout::Node;
54
55    /// Draws the [`Widget`] using the associated `Renderer`.
56    fn draw(
57        &self,
58        tree: &Tree,
59        renderer: &mut Renderer,
60        theme: &Theme,
61        style: &renderer::Style,
62        layout: Layout<'_>,
63        cursor: mouse::Cursor,
64        viewport: &Rectangle,
65    );
66
67    /// Returns the [`Tag`] of the [`Widget`].
68    ///
69    /// [`Tag`]: tree::Tag
70    fn tag(&self) -> tree::Tag {
71        tree::Tag::stateless()
72    }
73
74    /// Returns the [`State`] of the [`Widget`].
75    ///
76    /// [`State`]: tree::State
77    fn state(&self) -> tree::State {
78        tree::State::None
79    }
80
81    /// Reconciles the [`Widget`] with the provided [`Tree`].
82    fn diff(&mut self, tree: &mut Tree) {
83        tree.children.clear();
84    }
85
86    /// Applies an [`Operation`] to the [`Widget`].
87    fn operate(
88        &mut self,
89        _tree: &mut Tree,
90        _layout: Layout<'_>,
91        _renderer: &Renderer,
92        _operation: &mut dyn Operation,
93    ) {
94    }
95
96    /// Processes a runtime [`Event`].
97    ///
98    /// By default, it does nothing.
99    fn update(
100        &mut self,
101        _tree: &mut Tree,
102        _event: &Event,
103        _layout: Layout<'_>,
104        _cursor: mouse::Cursor,
105        _renderer: &Renderer,
106        _shell: &mut Shell<'_, Message>,
107        _viewport: &Rectangle,
108    ) {
109    }
110
111    /// Returns the current [`mouse::Interaction`] of the [`Widget`].
112    ///
113    /// By default, it returns [`mouse::Interaction::None`].
114    fn mouse_interaction(
115        &self,
116        _tree: &Tree,
117        _layout: Layout<'_>,
118        _cursor: mouse::Cursor,
119        _viewport: &Rectangle,
120        _renderer: &Renderer,
121    ) -> mouse::Interaction {
122        mouse::Interaction::None
123    }
124
125    /// Returns the overlay of the [`Widget`], if there is any.
126    fn overlay<'a>(
127        &'a mut self,
128        _tree: &'a mut Tree,
129        _layout: Layout<'a>,
130        _renderer: &Renderer,
131        _viewport: &Rectangle,
132        _translation: Vector,
133    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
134        None
135    }
136
137    /// Returns whether the [`Widget`] is [`Void`].
138    fn is_void(&self) -> bool {
139        false
140    }
141}
142
143/// A zero-sized [`Widget`] that does nothing and will be filtered out by containers.
144pub struct Void;
145
146impl<Message, Theme, Renderer> Widget<Message, Theme, Renderer> for Void
147where
148    Renderer: crate::Renderer,
149{
150    fn size(&self) -> Size<Length> {
151        Size {
152            width: Length::Shrink,
153            height: Length::Shrink,
154        }
155    }
156
157    fn layout(
158        &mut self,
159        _tree: &mut Tree,
160        _renderer: &Renderer,
161        _limits: &layout::Limits,
162    ) -> layout::Node {
163        layout::Node::new(Size::ZERO)
164    }
165
166    fn draw(
167        &self,
168        _tree: &Tree,
169        _renderer: &mut Renderer,
170        _theme: &Theme,
171        _style: &renderer::Style,
172        _layout: Layout<'_>,
173        _cursor: mouse::Cursor,
174        _viewport: &Rectangle,
175    ) {
176    }
177
178    fn is_void(&self) -> bool {
179        true
180    }
181}
iced_core/widget.rs

iced_core/
widget.rs
