me/iced
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Write documentation for the new overlay API

Browse source
This commit is contained in:
Héctor Ramón Jiménez 2020-07-10 02:39:12 +02:00
parent dc0e423142
commit 2118a726f8
16 changed files with 205 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

43
native/src/overlay.rs
View file

@ -1,3 +1,4 @@
//! Display interactive elements on top of other widgets.
mod element;
pub mod menu;
@ -7,10 +8,19 @@ pub use menu::Menu;
use crate::{layout, Clipboard, Event, Hasher, Layout, Point, Size};
/// An interactive component that can be displayed on top of other widgets.
pub trait Overlay<Message, Renderer>
where
Renderer: crate::Renderer,
{
/// Returns the layout [`Node`] of the [`Overlay`].
///
/// This [`Node`] is used by the runtime to compute the [`Layout`] of the
/// user interface.
///
/// [`Node`]: ../layout/struct.Node.html
/// [`Widget`]: trait.Overlay.html
/// [`Layout`]: ../layout/struct.Layout.html
fn layout(
&self,
renderer: &Renderer,
@ -18,6 +28,9 @@ where
position: Point,
) -> layout::Node;
/// Draws the [`Overlay`] using the associated `Renderer`.
///
/// [`Overlay`]: trait.Overlay.html
fn draw(
&self,
renderer: &mut Renderer,
@ -26,8 +39,38 @@ where
cursor_position: Point,
) -> Renderer::Output;
/// Computes the _layout_ hash of the [`Overlay`].
///
/// The produced hash is used by the runtime to decide if the [`Layout`]
/// needs to be recomputed between frames. Therefore, to ensure maximum
/// efficiency, the hash should only be affected by the properties of the
/// [`Overlay`] that can affect layouting.
///
/// For example, the [`Text`] widget does not hash its color property, as
/// its value cannot affect the overall [`Layout`] of the user interface.
///
/// [`Overlay`]: trait.Overlay.html
/// [`Layout`]: ../layout/struct.Layout.html
/// [`Text`]: text/struct.Text.html
fn hash_layout(&self, state: &mut Hasher, position: Point);
/// Processes a runtime [`Event`].
///
/// It receives:
/// * an [`Event`] describing user interaction
/// * the computed [`Layout`] of the [`Overlay`]
/// * the current cursor position
/// * a mutable `Message` list, allowing the [`Overlay`] to produce
/// new messages based on user interaction.
/// * the `Renderer`
/// * a [`Clipboard`], if available
///
/// By default, it does nothing.
///
/// [`Event`]: ../enum.Event.html
/// [`Overlay`]: trait.Widget.html
/// [`Layout`]: ../layout/struct.Layout.html
/// [`Clipboard`]: ../trait.Clipboard.html
fn on_event(
&mut self,
_event: Event,