From 2118a726f8b6134820e1ca5b7b802fa1344e453a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Ram=C3=B3n=20Jim=C3=A9nez?= Date: Fri, 10 Jul 2020 02:39:12 +0200 Subject: [PATCH] Write documentation for the new `overlay` API --- glow/src/lib.rs | 2 +- glow/src/widget/combo_box.rs | 1 + graphics/src/lib.rs | 2 +- graphics/src/overlay.rs | 1 + graphics/src/overlay/menu.rs | 1 + graphics/src/widget/combo_box.rs | 1 + native/src/element.rs | 5 ++- native/src/lib.rs | 4 +-- native/src/overlay.rs | 43 +++++++++++++++++++++++ native/src/overlay/element.rs | 56 +++++++++++++++++++++-------- native/src/overlay/menu.rs | 60 +++++++++++++++++++++++++++++++- native/src/renderer.rs | 2 ++ native/src/widget.rs | 3 ++ native/src/widget/combo_box.rs | 48 ++++++++++++++++++++++--- wgpu/src/lib.rs | 2 +- wgpu/src/widget/combo_box.rs | 1 + 16 files changed, 205 insertions(+), 27 deletions(-) diff --git a/glow/src/lib.rs b/glow/src/lib.rs index bdd854e3..a6c8a75a 100644 --- a/glow/src/lib.rs +++ b/glow/src/lib.rs @@ -2,7 +2,7 @@ //! //! [`glow`]: https://github.com/grovesNL/glow //! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native -//#![deny(missing_docs)] +#![deny(missing_docs)] #![deny(missing_debug_implementations)] #![deny(unused_results)] #![forbid(rust_2018_idioms)] diff --git a/glow/src/widget/combo_box.rs b/glow/src/widget/combo_box.rs index bfface29..20feeaca 100644 --- a/glow/src/widget/combo_box.rs +++ b/glow/src/widget/combo_box.rs @@ -1,3 +1,4 @@ +//! Display a dropdown list of selectable values. pub use iced_native::combo_box::State; pub use iced_graphics::combo_box::{Style, StyleSheet}; diff --git a/graphics/src/lib.rs b/graphics/src/lib.rs index 0c427634..d03f3b48 100644 --- a/graphics/src/lib.rs +++ b/graphics/src/lib.rs @@ -2,7 +2,7 @@ //! for [`iced`]. //! //! [`iced`]: https://github.com/hecrj/iced -//#![deny(missing_docs)] +#![deny(missing_docs)] #![deny(missing_debug_implementations)] #![deny(unused_results)] #![deny(unsafe_code)] diff --git a/graphics/src/overlay.rs b/graphics/src/overlay.rs index b9a0e3e0..bc0ed744 100644 --- a/graphics/src/overlay.rs +++ b/graphics/src/overlay.rs @@ -1 +1,2 @@ +//! Display interactive elements on top of other widgets. pub mod menu; diff --git a/graphics/src/overlay/menu.rs b/graphics/src/overlay/menu.rs index 89a9cd03..a952f065 100644 --- a/graphics/src/overlay/menu.rs +++ b/graphics/src/overlay/menu.rs @@ -1,3 +1,4 @@ +//! Build and show dropdown menus. use crate::backend::{self, Backend}; use crate::{Primitive, Renderer}; use iced_native::{ diff --git a/graphics/src/widget/combo_box.rs b/graphics/src/widget/combo_box.rs index e7ed4e04..f200c2b7 100644 --- a/graphics/src/widget/combo_box.rs +++ b/graphics/src/widget/combo_box.rs @@ -1,3 +1,4 @@ +//! Display a dropdown list of selectable values. use crate::backend::{self, Backend}; use crate::{Primitive, Renderer}; use iced_native::{ diff --git a/native/src/element.rs b/native/src/element.rs index db95919a..a1320f18 100644 --- a/native/src/element.rs +++ b/native/src/element.rs @@ -24,7 +24,7 @@ impl<'a, Message, Renderer> Element<'a, Message, Renderer> where Renderer: crate::Renderer, { - /// Create a new [`Element`] containing the given [`Widget`]. + /// Creates a new [`Element`] containing the given [`Widget`]. /// /// [`Element`]: struct.Element.html /// [`Widget`]: widget/trait.Widget.html @@ -273,6 +273,9 @@ where self.widget.hash_layout(state); } + /// Returns the overlay of the [`Element`], if there is any. + /// + /// [`Element`]: struct.Element.html pub fn overlay<'b>( &'b mut self, layout: Layout<'_>, diff --git a/native/src/lib.rs b/native/src/lib.rs index ea328592..067e3c0a 100644 --- a/native/src/lib.rs +++ b/native/src/lib.rs @@ -30,8 +30,8 @@ //! [`Widget`]: widget/trait.Widget.html //! [`UserInterface`]: struct.UserInterface.html //! [renderer]: renderer/index.html -//#![deny(missing_docs)] -//#![deny(missing_debug_implementations)] +#![deny(missing_docs)] +#![deny(missing_debug_implementations)] #![deny(unused_results)] #![forbid(unsafe_code)] #![forbid(rust_2018_idioms)] diff --git a/native/src/overlay.rs b/native/src/overlay.rs index b6cbbec3..7c3bec32 100644 --- a/native/src/overlay.rs +++ b/native/src/overlay.rs @@ -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 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, diff --git a/native/src/overlay/element.rs b/native/src/overlay/element.rs index a159e3c1..3d532126 100644 --- a/native/src/overlay/element.rs +++ b/native/src/overlay/element.rs @@ -3,6 +3,9 @@ pub use crate::Overlay; use crate::{layout, Clipboard, Event, Hasher, Layout, Point, Size, Vector}; use std::rc::Rc; +/// A generic [`Overlay`]. +/// +/// [`Overlay`]: trait.Overlay.html #[allow(missing_debug_implementations)] pub struct Element<'a, Message, Renderer> { position: Point, @@ -13,6 +16,10 @@ impl<'a, Message, Renderer> Element<'a, Message, Renderer> where Renderer: crate::Renderer, { + /// Creates a new [`Element`] containing the given [`Overlay`]. + /// + /// [`Element`]: struct.Element.html + /// [`Overlay`]: trait.Overlay.html pub fn new( position: Point, overlay: Box + 'a>, @@ -20,11 +27,17 @@ where Self { position, overlay } } + /// Translates the [`Element`]. + /// + /// [`Element`]: struct.Element.html pub fn translate(mut self, translation: Vector) -> Self { self.position = self.position + translation; self } + /// Applies a transformation to the produced message of the [`Element`]. + /// + /// [`Element`]: struct.Element.html pub fn map(self, f: Rc B>) -> Element<'a, B, Renderer> where Message: 'a, @@ -37,25 +50,16 @@ where } } + /// Computes the layout of the [`Element`] in the given bounds. + /// + /// [`Element`]: struct.Element.html pub fn layout(&self, renderer: &Renderer, bounds: Size) -> layout::Node { self.overlay.layout(renderer, bounds, self.position) } - pub fn draw( - &self, - renderer: &mut Renderer, - defaults: &Renderer::Defaults, - layout: Layout<'_>, - cursor_position: Point, - ) -> Renderer::Output { - self.overlay - .draw(renderer, defaults, layout, cursor_position) - } - - pub fn hash_layout(&self, state: &mut Hasher) { - self.overlay.hash_layout(state, self.position); - } - + /// Processes a runtime [`Event`]. + /// + /// [`Event`]: enum.Event.html pub fn on_event( &mut self, event: Event, @@ -74,6 +78,28 @@ where clipboard, ) } + + /// Draws the [`Element`] and its children using the given [`Layout`]. + /// + /// [`Element`]: struct.Element.html + /// [`Layout`]: layout/struct.Layout.html + pub fn draw( + &self, + renderer: &mut Renderer, + defaults: &Renderer::Defaults, + layout: Layout<'_>, + cursor_position: Point, + ) -> Renderer::Output { + self.overlay + .draw(renderer, defaults, layout, cursor_position) + } + + /// Computes the _layout_ hash of the [`Element`]. + /// + /// [`Element`]: struct.Element.html + pub fn hash_layout(&self, state: &mut Hasher) { + self.overlay.hash_layout(state, self.position); + } } struct Map<'a, A, B, Renderer> { diff --git a/native/src/overlay/menu.rs b/native/src/overlay/menu.rs index 8c5daae1..0d4bc63c 100644 --- a/native/src/overlay/menu.rs +++ b/native/src/overlay/menu.rs @@ -1,9 +1,12 @@ +//! Build and show dropdown menus. use crate::{ container, layout, mouse, overlay, scrollable, text, Clipboard, Container, Element, Event, Hasher, Layout, Length, Point, Rectangle, Scrollable, Size, Vector, Widget, }; +/// A list of selectable options. +#[allow(missing_debug_implementations)] pub struct Menu<'a, T, Message, Renderer: self::Renderer> { state: &'a mut State, options: &'a [T], @@ -21,6 +24,11 @@ where Message: 'a, Renderer: self::Renderer + 'a, { + /// Creates a new [`Menu`] with the given [`State`], a list of options, and + /// the message to produced when an option is selected. + /// + /// [`Menu`]: struct.Menu.html + /// [`State`]: struct.State.html pub fn new( state: &'a mut State, options: &'a [T], @@ -38,26 +46,41 @@ where } } + /// Sets the width of the [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html pub fn width(mut self, width: u16) -> Self { self.width = width; self } + /// Sets the padding of the [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html pub fn padding(mut self, padding: u16) -> Self { self.padding = padding; self } + /// Sets the text size of the [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html pub fn text_size(mut self, text_size: u16) -> Self { self.text_size = Some(text_size); self } + /// Sets the font of the [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html pub fn font(mut self, font: Renderer::Font) -> Self { self.font = font; self } + /// Sets the style of the [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html pub fn style( mut self, style: impl Into<::Style>, @@ -66,6 +89,14 @@ where self } + /// Turns the [`Menu`] into an overlay [`Element`] at the given target + /// position. + /// + /// The `target_height` will be used to display the menu either on top + /// of the target or under it, depending on the screen position and the + /// dimensions of the [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html pub fn overlay( self, position: Point, @@ -78,7 +109,10 @@ where } } -#[derive(Default)] +/// The local state of a [`Menu`]. +/// +/// [`Menu`]: struct.Menu.html +#[derive(Debug, Clone, Default)] pub struct State { scrollable: scrollable::State, hovered_option: Option, @@ -86,10 +120,16 @@ pub struct State { } impl State { + /// Returns whether the [`Menu`] is currently open or not. + /// + /// [`Menu`]: struct.Menu.html pub fn is_open(&self) -> bool { self.is_open } + /// Opens the [`Menu`] with the given option hovered by default. + /// + /// [`Menu`]: struct.Menu.html pub fn open(&mut self, hovered_option: Option) { self.is_open = true; self.hovered_option = hovered_option; @@ -367,11 +407,26 @@ where } } +/// The renderer of a [`Menu`]. +/// +/// Your [renderer] will need to implement this trait before being +/// able to use a [`Menu`] in your user interface. +/// +/// [`Menu`]: struct.Menu.html +/// [renderer]: ../../renderer/index.html pub trait Renderer: scrollable::Renderer + container::Renderer + text::Renderer { + /// The [`Menu`] style supported by this renderer. + /// + /// [`Menu`]: struct.Menu.html type Style: Default + Clone; + /// Decorates a the list of options of a [`Menu`]. + /// + /// This method can be used to draw a background for the [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html fn decorate( &mut self, bounds: Rectangle, @@ -380,6 +435,9 @@ pub trait Renderer: primitive: Self::Output, ) -> Self::Output; + /// Draws the list of options of a [`Menu`]. + /// + /// [`Menu`]: struct.Menu.html fn draw( &mut self, bounds: Rectangle, diff --git a/native/src/renderer.rs b/native/src/renderer.rs index 29a091a4..d986141f 100644 --- a/native/src/renderer.rs +++ b/native/src/renderer.rs @@ -57,6 +57,8 @@ pub trait Renderer: Sized { element.layout(self, limits) } + /// Overlays the `overlay` output with the given bounds on top of the `base` + /// output. fn overlay( &mut self, base: Self::Output, diff --git a/native/src/widget.rs b/native/src/widget.rs index a7f279ed..931b4739 100644 --- a/native/src/widget.rs +++ b/native/src/widget.rs @@ -179,6 +179,9 @@ where ) { } + /// Returns the overlay of the [`Element`], if there is any. + /// + /// [`Element`]: struct.Element.html fn overlay( &mut self, _layout: Layout<'_>, diff --git a/native/src/widget/combo_box.rs b/native/src/widget/combo_box.rs index a9f0e6ed..fefaf8ff 100644 --- a/native/src/widget/combo_box.rs +++ b/native/src/widget/combo_box.rs @@ -1,3 +1,4 @@ +//! Display a dropdown list of selectable values. use crate::{ layout, mouse, overlay, overlay::menu::{self, Menu}, @@ -6,6 +7,8 @@ use crate::{ }; use std::borrow::Cow; +/// A widget for selecting a single value from a list of options. +#[allow(missing_debug_implementations)] pub struct ComboBox<'a, T, Message, Renderer: self::Renderer> where [T]: ToOwned>, @@ -22,7 +25,10 @@ where is_open: bool, } -#[derive(Default)] +/// The local state of a [`ComboBox`]. +/// +/// [`ComboBox`]: struct.ComboBox.html +#[derive(Debug, Clone, Default)] pub struct State { menu: menu::State, } @@ -33,6 +39,12 @@ where T: ToString, [T]: ToOwned>, { + /// Creates a new [`ComboBox`] with the given [`State`], a list of options, + /// the current selected value, and the message to produce when an option is + /// selected. + /// + /// [`ComboBox`]: struct.ComboBox.html + /// [`State`]: struct.State.html pub fn new( state: &'a mut State, options: impl Into>, @@ -57,7 +69,7 @@ where /// Sets the width of the [`ComboBox`]. /// - /// [`ComboBox`]: struct.Button.html + /// [`ComboBox`]: struct.ComboBox.html pub fn width(mut self, width: Length) -> Self { self.width = width; self @@ -65,17 +77,23 @@ where /// Sets the padding of the [`ComboBox`]. /// - /// [`ComboBox`]: struct.Button.html + /// [`ComboBox`]: struct.ComboBox.html pub fn padding(mut self, padding: u16) -> Self { self.padding = padding; self } + /// Sets the text size of the [`ComboBox`]. + /// + /// [`ComboBox`]: struct.ComboBox.html pub fn text_size(mut self, size: u16) -> Self { self.text_size = Some(size); self } + /// Sets the font of the [`ComboBox`]. + /// + /// [`ComboBox`]: struct.ComboBox.html pub fn font(mut self, font: Renderer::Font) -> Self { self.font = font; self @@ -247,15 +265,35 @@ where } } +/// The renderer of a [`ComboBox`]. +/// +/// Your [renderer] will need to implement this trait before being +/// able to use a [`ComboBox`] in your user interface. +/// +/// [`ComboBox`]: struct.ComboBox.html +/// [renderer]: ../../renderer/index.html pub trait Renderer: text::Renderer + menu::Renderer { - type Style: Default; - + /// The default padding of a [`ComboBox`]. + /// + /// [`ComboBox`]: struct.ComboBox.html const DEFAULT_PADDING: u16; + /// The [`ComboBox`] style supported by this renderer. + /// + /// [`ComboBox`]: struct.ComboBox.html + type Style: Default; + + /// Returns the style of the [`Menu`] of the [`ComboBox`]. + /// + /// [`Menu`]: ../../overlay/menu/struct.Menu.html + /// [`ComboBox`]: struct.ComboBox.html fn menu_style( style: &::Style, ) -> ::Style; + /// Draws a [`ComboBox`]. + /// + /// [`ComboBox`]: struct.ComboBox.html fn draw( &mut self, bounds: Rectangle, diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index 0186b007..e51a225c 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -20,7 +20,7 @@ //! [`wgpu`]: https://github.com/gfx-rs/wgpu-rs //! [WebGPU API]: https://gpuweb.github.io/gpuweb/ //! [`wgpu_glyph`]: https://github.com/hecrj/wgpu_glyph -//#![deny(missing_docs)] +#![deny(missing_docs)] #![deny(missing_debug_implementations)] #![deny(unused_results)] #![forbid(unsafe_code)] diff --git a/wgpu/src/widget/combo_box.rs b/wgpu/src/widget/combo_box.rs index bfface29..20feeaca 100644 --- a/wgpu/src/widget/combo_box.rs +++ b/wgpu/src/widget/combo_box.rs @@ -1,3 +1,4 @@ +//! Display a dropdown list of selectable values. pub use iced_native::combo_box::State; pub use iced_graphics::combo_box::{Style, StyleSheet};