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

Write documentation for UserInterface

Browse source
This commit is contained in:
Héctor Ramón Jiménez 2019-08-29 00:58:42 +02:00
parent 51050fc45c
commit 268a5f0017
5 changed files with 214 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

208
src/user_interface.rs
View file

@ -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(
root: Element<'a, Message, Renderer>,
renderer: &Renderer,
/// Builds a user interface for an [`Element`].
///
/// 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,