Write documentation for UserInterface

examples/ggez/main.rs

@@ -144,9 +144,9 @@ impl event::EventHandler for Game {
                 &mut Renderer::new(context, self.spritesheet.clone());
 
             let mut ui = iced::UserInterface::build(
-                content.into(),
+                content,
-                renderer,
                 self.cache.take().unwrap(),
+                renderer,
             );
 
             let messages = ui.update(self.events.drain(..));

src/element.rs

@@ -4,10 +4,14 @@ use crate::{Event, Hasher, Layout, MouseCursor, Node, Point, Widget};
 
 /// A generic [`Widget`].
 ///
-/// If you have a widget, you should be able to use `widget.into()` to turn it
+/// It is useful to build composable user interfaces that do not leak
-/// into an [`Element`].
+/// implementation details in their __view logic__.
 ///
-/// [`Widget`]: trait.Widget.html
+/// If you have a [built-in widget], you should be able to use `Into<Element>`
+/// to turn it into an [`Element`].
+///
+/// [built-in widget]: widget/index.html#built-in-widgets
+/// [`Widget`]: widget/trait.Widget.html
 /// [`Element`]: struct.Element.html
 pub struct Element<'a, Message, Renderer> {
     pub(crate) widget: Box<dyn Widget<Message, Renderer> + 'a>,

src/layout.rs

@@ -5,7 +5,7 @@ use crate::{Point, Rectangle, Vector};
 /// The computed bounds of a [`Node`] and its children.
 ///
 /// This type is provided by the GUI runtime to [`Widget::on_event`] and
-/// [`Widget::draw`], describing the layout of the produced [`Node`] by
+/// [`Widget::draw`], describing the layout of the [`Node`] produced by
 /// [`Widget::node`].
 ///
 /// [`Node`]: struct.Node.html

src/user_interface.rs

@@ -3,7 +3,14 @@ use crate::{input::mouse, Column, Element, Event, Layout, MouseCursor, Point};
 use std::hash::Hasher;
 use stretch::result;
 
-/// A set of interactive graphical elements with a specific layout.
+/// A set of interactive graphical elements with a specific [`Layout`].
+///
+/// Use this to build, update, and draw your GUI!
+///
+/// Iced tries to avoid dictating how to write your event loop. You are in
+/// charge of integrating Iced in your system in any way you want.
+///
+/// [`Layout`]: struct.Layout.html
 pub struct UserInterface<'a, Message, Renderer> {
     hash: u64,
     root: Element<'a, Message, Renderer>,
@@ -12,11 +19,72 @@ pub struct UserInterface<'a, Message, Renderer> {
 }
 
 impl<'a, Message, Renderer> UserInterface<'a, Message, Renderer> {
-    pub fn build(
+    /// Builds a user interface for an [`Element`].
-        root: Element<'a, Message, Renderer>,
+    ///
-        renderer: &Renderer,
+    /// It is able to avoid expensive computations when using a [`Cache`]
+    /// obtained from a previous instance of a [`UserInterface`].
+    ///
+    /// [`Element`]: struct.Element.html
+    /// [`Cache`]: struct.Cache.html
+    /// [`UserInterface`]: struct.UserInterface.html
+    ///
+    /// # Example
+    /// Imagine we want to build a [`UserInterface`] for
+    /// [the counter example that we previously wrote](index.html#usage). Here
+    /// is how we could build our GUI application indefinitely:
+    ///
+    /// ```no_run
+    /// use iced::{UserInterface, Cache};
+    /// use iced_wgpu::Renderer;
+    ///
+    /// # mod iced_wgpu {
+    /// #     pub struct Renderer;
+    /// #
+    /// #     impl Renderer {
+    /// #         pub fn new() -> Self { Renderer }
+    /// #     }
+    /// # }
+    /// #
+    /// # use iced::Column;
+    /// #
+    /// # pub struct Counter;
+    /// #
+    /// # impl Counter {
+    /// #     pub fn new() -> Self { Counter }
+    /// #     pub fn view(&self) -> Column<(), Renderer> {
+    /// #         Column::new()
+    /// #     }
+    /// # }
+    /// // Initialization
+    /// let mut counter = Counter::new();
+    /// let mut cache = Cache::new();
+    /// let mut renderer = Renderer::new();
+    ///
+    /// // Application loop
+    /// loop {
+    ///     // Process system events here...
+    ///
+    ///     // Build the user interface
+    ///     let user_interface = UserInterface::build(
+    ///         counter.view(),
+    ///         cache,
+    ///         &renderer,
+    ///     );
+    ///
+    ///     // Update and draw the user interface here...
+    ///     // ...
+    ///
+    ///     // Obtain the cache for the next iteration
+    ///     cache = user_interface.into_cache();
+    /// }
+    /// ```
+    pub fn build<E: Into<Element<'a, Message, Renderer>>>(
+        root: E,
         cache: Cache,
+        renderer: &Renderer,
     ) -> Self {
+        let root = root.into();
+
         let hasher = &mut crate::Hasher::default();
         root.hash(hasher);
 
@@ -36,6 +104,68 @@ impl<'a, Message, Renderer> UserInterface<'a, Message, Renderer> {
         }
     }
 
+    /// Updates the [`UserInterface`] by processing each provided [`Event`].
+    ///
+    /// It returns __messages__ that may have been produced as a result of user
+    /// interactions. You should feed these to your __update logic__.
+    ///
+    /// [`UserInterface`]: struct.UserInterface.html
+    /// [`Event`]: enum.Event.html
+    ///
+    /// # Example
+    /// Let's allow our [counter](index.html#usage) to change state by completing
+    /// [the previous example](#example):
+    ///
+    /// ```no_run
+    /// use iced::{UserInterface, Cache};
+    /// use iced_wgpu::Renderer;
+    ///
+    /// # mod iced_wgpu {
+    /// #     pub struct Renderer;
+    /// #
+    /// #     impl Renderer {
+    /// #         pub fn new() -> Self { Renderer }
+    /// #     }
+    /// # }
+    /// #
+    /// # use iced::Column;
+    /// #
+    /// # pub struct Counter;
+    /// #
+    /// # impl Counter {
+    /// #     pub fn new() -> Self { Counter }
+    /// #     pub fn view(&self) -> Column<(), Renderer> {
+    /// #         Column::new()
+    /// #     }
+    /// #     pub fn update(&mut self, message: ()) {}
+    /// # }
+    /// let mut counter = Counter::new();
+    /// let mut cache = Cache::new();
+    /// let mut renderer = Renderer::new();
+    ///
+    /// // Initialize our event storage
+    /// let mut events = Vec::new();
+    ///
+    /// loop {
+    ///     // Process system events...
+    ///
+    ///     let mut user_interface = UserInterface::build(
+    ///         counter.view(),
+    ///         cache,
+    ///         &renderer,
+    ///     );
+    ///
+    ///     // Update the user interface
+    ///     let messages = user_interface.update(events.drain(..));
+    ///
+    ///     cache = user_interface.into_cache();
+    ///
+    ///     // Process the produced messages
+    ///     for message in messages {
+    ///         counter.update(message);
+    ///     }
+    /// }
+    /// ```
     pub fn update(
         &mut self,
         events: impl Iterator<Item = Event>,
@@ -61,6 +191,71 @@ impl<'a, Message, Renderer> UserInterface<'a, Message, Renderer> {
         messages
     }
 
+    /// Draws the [`UserInterface`] with the provided [`Renderer`].
+    ///
+    /// It returns the current state of the [`MouseCursor`]. You should update
+    /// the icon of the mouse cursor accordingly in your system.
+    ///
+    /// [`UserInterface`]: struct.UserInterface.html
+    /// [`Renderer`]: trait.Renderer.html
+    /// [`MouseCursor`]: enum.MouseCursor.html
+    ///
+    /// # Example
+    /// We can finally draw our [counter](index.html#usage) by
+    /// [completing the last example](#example-1):
+    ///
+    /// ```no_run
+    /// use iced::{UserInterface, Cache};
+    /// use iced_wgpu::Renderer;
+    ///
+    /// # mod iced_wgpu {
+    /// #     pub struct Renderer;
+    /// #
+    /// #     impl Renderer {
+    /// #         pub fn new() -> Self { Renderer }
+    /// #     }
+    /// # }
+    /// #
+    /// # use iced::Column;
+    /// #
+    /// # pub struct Counter;
+    /// #
+    /// # impl Counter {
+    /// #     pub fn new() -> Self { Counter }
+    /// #     pub fn view(&self) -> Column<(), Renderer> {
+    /// #         Column::new()
+    /// #     }
+    /// #     pub fn update(&mut self, message: ()) {}
+    /// # }
+    /// let mut counter = Counter::new();
+    /// let mut cache = Cache::new();
+    /// let mut renderer = Renderer::new();
+    /// let mut events = Vec::new();
+    ///
+    /// loop {
+    ///     // Process system events...
+    ///
+    ///     let mut user_interface = UserInterface::build(
+    ///         counter.view(),
+    ///         cache,
+    ///         &renderer,
+    ///     );
+    ///
+    ///     let messages = user_interface.update(events.drain(..));
+    ///
+    ///     // Draw the user interface
+    ///     let mouse_cursor = user_interface.draw(&mut renderer);
+    ///
+    ///     cache = user_interface.into_cache();
+    ///
+    ///     for message in messages {
+    ///         counter.update(message);
+    ///     }
+    ///
+    ///     // Update mouse cursor icon...
+    ///     // Flush rendering operations...
+    /// }
+    /// ```
     pub fn draw(&self, renderer: &mut Renderer) -> MouseCursor {
         let cursor = self.root.widget.draw(
             renderer,
@@ -71,6 +266,11 @@ impl<'a, Message, Renderer> UserInterface<'a, Message, Renderer> {
         cursor
     }
 
+    /// Extract the [`Cache`] of the [`UserInterface`], consuming it in the
+    /// process.
+    ///
+    /// [`Cache`]: struct.Cache.html
+    /// [`UserInterface`]: struct.UserInterface.html
     pub fn into_cache(self) -> Cache {
         Cache {
             hash: self.hash,

src/widget.rs

@@ -44,10 +44,6 @@ use crate::{Event, Hasher, Layout, MouseCursor, Node, Point};
 /// If you want to build your own widgets, you will need to implement this
 /// trait.
 ///
-/// Additionally, remember to also provide [`Into<Element>`] so your users can
-/// easily turn your [`Widget`] into a generic [`Element`].
-///
-/// [`Into<Element>`]: ../struct.Element.html
 /// [`Widget`]: trait.Widget.html
 /// [`Element`]: ../struct.Element.html
 pub trait Widget<Message, Renderer>: std::fmt::Debug {