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        _viewport: &Rectangle,
92        _renderer: &Renderer,
93        _operation: &mut dyn Operation,
94    ) {
95    }
96
97    /// Processes a runtime [`Event`].
98    ///
99    /// By default, it does nothing.
100    fn update(
101        &mut self,
102        _tree: &mut Tree,
103        _event: &Event,
104        _layout: Layout<'_>,
105        _cursor: mouse::Cursor,
106        _renderer: &Renderer,
107        _shell: &mut Shell<'_, Message>,
108        _viewport: &Rectangle,
109    ) {
110    }
111
112    /// Returns the current [`mouse::Interaction`] of the [`Widget`].
113    ///
114    /// By default, it returns [`mouse::Interaction::None`].
115    fn mouse_interaction(
116        &self,
117        _tree: &Tree,
118        _layout: Layout<'_>,
119        _cursor: mouse::Cursor,
120        _viewport: &Rectangle,
121        _renderer: &Renderer,
122    ) -> mouse::Interaction {
123        mouse::Interaction::None
124    }
125
126    /// Returns the overlays of the [`Widget`].
127    fn overlay<'a>(
128        &'a mut self,
129        _tree: &'a mut Tree,
130        _layout: Layout<'a>,
131        _renderer: &Renderer,
132        _viewport: &Rectangle,
133        _translation: Vector,
134    ) -> Vec<overlay::Element<'a, Message, Theme, Renderer>> {
135        Vec::new()
136    }
137
138    /// Returns whether the [`Widget`] is [`Void`].
139    fn is_void(&self) -> bool {
140        false
141    }
142}
143
144/// A zero-sized [`Widget`] that does nothing and will be filtered out by containers.
145pub struct Void;
146
147impl<Message, Theme, Renderer> Widget<Message, Theme, Renderer> for Void
148where
149    Renderer: crate::Renderer,
150{
151    fn size(&self) -> Size<Length> {
152        Size {
153            width: Length::Shrink,
154            height: Length::Shrink,
155        }
156    }
157
158    fn layout(
159        &mut self,
160        _tree: &mut Tree,
161        _renderer: &Renderer,
162        _limits: &layout::Limits,
163    ) -> layout::Node {
164        layout::Node::new(Size::ZERO)
165    }
166
167    fn draw(
168        &self,
169        _tree: &Tree,
170        _renderer: &mut Renderer,
171        _theme: &Theme,
172        _style: &renderer::Style,
173        _layout: Layout<'_>,
174        _cursor: mouse::Cursor,
175        _viewport: &Rectangle,
176    ) {
177    }
178
179    fn is_void(&self) -> bool {
180        true
181    }
182}
iced_core/widget.rs

iced_core/
widget.rs
