iced_core/
overlay.rs

1//! Display interactive elements on top of other widgets.
2mod element;
3mod group;
4
5pub use element::Element;
6pub use group::Group;
7
8use crate::layout;
9use crate::mouse;
10use crate::renderer;
11use crate::widget;
12use crate::widget::Tree;
13use crate::{Clipboard, Event, Layout, Rectangle, Shell, Size, Vector};
14
15/// An interactive component that can be displayed on top of other widgets.
16pub trait Overlay<Message, Theme, Renderer>
17where
18    Renderer: crate::Renderer,
19{
20    /// Returns the layout [`Node`] of the [`Overlay`].
21    ///
22    /// This [`Node`] is used by the runtime to compute the [`Layout`] of the
23    /// user interface.
24    ///
25    /// [`Node`]: layout::Node
26    fn layout(&mut self, renderer: &Renderer, bounds: Size) -> layout::Node;
27
28    /// Draws the [`Overlay`] using the associated `Renderer`.
29    fn draw(
30        &self,
31        renderer: &mut Renderer,
32        theme: &Theme,
33        style: &renderer::Style,
34        layout: Layout<'_>,
35        cursor: mouse::Cursor,
36    );
37
38    /// Applies a [`widget::Operation`] to the [`Overlay`].
39    fn operate(
40        &mut self,
41        _layout: Layout<'_>,
42        _renderer: &Renderer,
43        _operation: &mut dyn widget::Operation,
44    ) {
45    }
46
47    /// Processes a runtime [`Event`].
48    ///
49    /// It receives:
50    ///   * an [`Event`] describing user interaction
51    ///   * the computed [`Layout`] of the [`Overlay`]
52    ///   * the current cursor position
53    ///   * a mutable `Message` list, allowing the [`Overlay`] to produce
54    ///     new messages based on user interaction.
55    ///   * the `Renderer`
56    ///   * a [`Clipboard`], if available
57    ///
58    /// By default, it does nothing.
59    fn update(
60        &mut self,
61        _event: &Event,
62        _layout: Layout<'_>,
63        _cursor: mouse::Cursor,
64        _renderer: &Renderer,
65        _clipboard: &mut dyn Clipboard,
66        _shell: &mut Shell<'_, Message>,
67    ) {
68    }
69
70    /// Returns the current [`mouse::Interaction`] of the [`Overlay`].
71    ///
72    /// By default, it returns [`mouse::Interaction::None`].
73    fn mouse_interaction(
74        &self,
75        _layout: Layout<'_>,
76        _cursor: mouse::Cursor,
77        _renderer: &Renderer,
78    ) -> mouse::Interaction {
79        mouse::Interaction::None
80    }
81
82    /// Returns the nested overlay of the [`Overlay`], if there is any.
83    fn overlay<'a>(
84        &'a mut self,
85        _layout: Layout<'a>,
86        _renderer: &Renderer,
87    ) -> Option<Element<'a, Message, Theme, Renderer>> {
88        None
89    }
90
91    /// The index of the overlay.
92    ///
93    /// Overlays with a higher index will be rendered on top of overlays with
94    /// a lower index.
95    ///
96    /// By default, it returns `1.0`.
97    fn index(&self) -> f32 {
98        1.0
99    }
100}
101
102/// Returns a [`Group`] of overlay [`Element`] children.
103///
104/// This method will generally only be used by advanced users that are
105/// implementing the [`Widget`](crate::Widget) trait.
106pub fn from_children<'a, Message, Theme, Renderer>(
107    children: &'a mut [crate::Element<'_, Message, Theme, Renderer>],
108    tree: &'a mut Tree,
109    layout: Layout<'a>,
110    renderer: &Renderer,
111    viewport: &Rectangle,
112    translation: Vector,
113) -> Option<Element<'a, Message, Theme, Renderer>>
114where
115    Renderer: crate::Renderer,
116{
117    let children = children
118        .iter_mut()
119        .zip(&mut tree.children)
120        .zip(layout.children())
121        .filter_map(|((child, state), layout)| {
122            child.as_widget_mut().overlay(
123                state,
124                layout,
125                renderer,
126                viewport,
127                translation,
128            )
129        })
130        .collect::<Vec<_>>();
131
132    (!children.is_empty()).then(|| Group::with_children(children).overlay())
133}
iced_core/overlay.rs

iced_core/
overlay.rs
