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/// - [`bezier_tool`], a Paint-like tool for drawing Bézier curves using
29///   [`lyon`].
30/// - [`custom_widget`], a demonstration of how to build a custom widget that
31///   draws a circle.
32/// - [`geometry`], a custom widget showcasing how to draw geometry with the
33///   `Mesh2D` primitive in [`iced_wgpu`].
34///
35/// [examples]: https://github.com/iced-rs/iced/tree/0.13/examples
36/// [`bezier_tool`]: https://github.com/iced-rs/iced/tree/0.13/examples/bezier_tool
37/// [`custom_widget`]: https://github.com/iced-rs/iced/tree/0.13/examples/custom_widget
38/// [`geometry`]: https://github.com/iced-rs/iced/tree/0.13/examples/geometry
39/// [`lyon`]: https://github.com/nical/lyon
40/// [`iced_wgpu`]: https://github.com/iced-rs/iced/tree/0.13/wgpu
41pub trait Widget<Message, Theme, Renderer>
42where
43    Renderer: crate::Renderer,
44{
45    /// Returns the [`Size`] of the [`Widget`] in lengths.
46    fn size(&self) -> Size<Length>;
47
48    /// Returns a [`Size`] hint for laying out the [`Widget`].
49    ///
50    /// This hint may be used by some widget containers to adjust their sizing strategy
51    /// during construction.
52    fn size_hint(&self) -> Size<Length> {
53        self.size()
54    }
55
56    /// Returns the [`layout::Node`] of the [`Widget`].
57    ///
58    /// This [`layout::Node`] is used by the runtime to compute the [`Layout`] of the
59    /// user interface.
60    fn layout(
61        &self,
62        tree: &mut Tree,
63        renderer: &Renderer,
64        limits: &layout::Limits,
65    ) -> layout::Node;
66
67    /// Draws the [`Widget`] using the associated `Renderer`.
68    fn draw(
69        &self,
70        tree: &Tree,
71        renderer: &mut Renderer,
72        theme: &Theme,
73        style: &renderer::Style,
74        layout: Layout<'_>,
75        cursor: mouse::Cursor,
76        viewport: &Rectangle,
77    );
78
79    /// Returns the [`Tag`] of the [`Widget`].
80    ///
81    /// [`Tag`]: tree::Tag
82    fn tag(&self) -> tree::Tag {
83        tree::Tag::stateless()
84    }
85
86    /// Returns the [`State`] of the [`Widget`].
87    ///
88    /// [`State`]: tree::State
89    fn state(&self) -> tree::State {
90        tree::State::None
91    }
92
93    /// Returns the state [`Tree`] of the children of the [`Widget`].
94    fn children(&self) -> Vec<Tree> {
95        Vec::new()
96    }
97
98    /// Reconciles the [`Widget`] with the provided [`Tree`].
99    fn diff(&self, tree: &mut Tree) {
100        tree.children.clear();
101    }
102
103    /// Applies an [`Operation`] to the [`Widget`].
104    fn operate(
105        &self,
106        _state: &mut Tree,
107        _layout: Layout<'_>,
108        _renderer: &Renderer,
109        _operation: &mut dyn Operation,
110    ) {
111    }
112
113    /// Processes a runtime [`Event`].
114    ///
115    /// By default, it does nothing.
116    fn update(
117        &mut self,
118        _state: &mut Tree,
119        _event: &Event,
120        _layout: Layout<'_>,
121        _cursor: mouse::Cursor,
122        _renderer: &Renderer,
123        _clipboard: &mut dyn Clipboard,
124        _shell: &mut Shell<'_, Message>,
125        _viewport: &Rectangle,
126    ) {
127    }
128
129    /// Returns the current [`mouse::Interaction`] of the [`Widget`].
130    ///
131    /// By default, it returns [`mouse::Interaction::Idle`].
132    fn mouse_interaction(
133        &self,
134        _state: &Tree,
135        _layout: Layout<'_>,
136        _cursor: mouse::Cursor,
137        _viewport: &Rectangle,
138        _renderer: &Renderer,
139    ) -> mouse::Interaction {
140        mouse::Interaction::None
141    }
142
143    /// Returns the overlay of the [`Widget`], if there is any.
144    fn overlay<'a>(
145        &'a mut self,
146        _state: &'a mut Tree,
147        _layout: Layout<'a>,
148        _renderer: &Renderer,
149        _viewport: &Rectangle,
150        _translation: Vector,
151    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
152        None
153    }
154}
iced_core/widget.rs

iced_core/
widget.rs
