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

Improve docs for Sandbox and Application

Browse source
This commit is contained in:
Héctor Ramón Jiménez 2020-04-01 04:35:24 +02:00
parent 4c44517556
commit f5e7e0625e
6 changed files with 123 additions and 108 deletions
Download patch file Download diff file Expand all files Collapse all files

99
src/application.rs
View file

@ -9,75 +9,76 @@ use crate::{window, Command, Element, Executor, Settings, Subscription};
/// - On the web, it will take control of the `<title>` and the `<body>` of the /// - On the web, it will take control of the `<title>` and the `<body>` of the
/// document. /// document.
/// ///
/// An [`Application`](trait.Application.html) can execute asynchronous actions /// An [`Application`] can execute asynchronous actions by returning a
/// by returning a [`Command`](struct.Command.html) in some of its methods. If /// [`Command`](struct.Command.html) in some of its methods. If
/// you do not intend to perform any background work in your program, the /// you do not intend to perform any background work in your program, the
/// [`Sandbox`](trait.Sandbox.html) trait offers a simplified interface. /// [`Sandbox`](trait.Sandbox.html) trait offers a simplified interface.
/// ///
/// # Example /// [`Application`]: trait.Application.html
/// Let's say we want to run the [`Counter` example we implemented ///
/// before](index.html#overview). We just need to fill in the gaps: /// # Examples
/// [The repository has a bunch of examples] that use the [`Application`] trait:
///
/// - [`clock`], an application that uses the [`Canvas`] widget to draw a clock
/// and its hands to display the current time.
/// - [`download_progress`], a basic application that asynchronously downloads
/// a dummy file of 100 MB and tracks the download progress.
/// - [`events`], a log of native events displayed using a conditional
/// [`Subscription`].
/// - [`pokedex`], an application that displays a random Pokédex entry (sprite
/// included!) by using the [PokéAPI].
/// - [`solar_system`], an animated solar system drawn using the [`Canvas`] widget
/// and showcasing how to compose different transforms.
/// - [`stopwatch`], a watch with start/stop and reset buttons showcasing how
/// to listen to time.
/// - [`todos`], a todos tracker inspired by [TodoMVC].
///
/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.1/examples
/// [`clock`]: https://github.com/hecrj/iced/tree/0.1/examples/clock
/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.1/examples/download_progress
/// [`events`]: https://github.com/hecrj/iced/tree/0.1/examples/events
/// [`pokedex`]: https://github.com/hecrj/iced/tree/0.1/examples/pokedex
/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.1/examples/solar_system
/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.1/examples/stopwatch
/// [`todos`]: https://github.com/hecrj/iced/tree/0.1/examples/todos
/// [`Canvas`]: widget/canvas/struct.Canvas.html
/// [PokéAPI]: https://pokeapi.co/
/// [`Subscription`]: type.Subscription.html
/// [TodoMVC]: http://todomvc.com/
///
/// ## A simple "Hello, world!"
///
/// If you just want to get started, here is a simple [`Application`] that
/// says "Hello, world!":
/// ///
/// ```no_run /// ```no_run
/// use iced::{button, executor, Application, Button, Column, Command, Element, Settings, Text}; /// use iced::{executor, Application, Command, Element, Settings, Text};
/// ///
/// pub fn main() { /// pub fn main() {
/// Counter::run(Settings::default()) /// Hello::run(Settings::default())
/// } /// }
/// ///
/// #[derive(Default)] /// struct Hello;
/// struct Counter {
/// value: i32,
/// increment_button: button::State,
/// decrement_button: button::State,
/// }
/// ///
/// #[derive(Debug, Clone, Copy)] /// impl Application for Hello {
/// enum Message {
/// IncrementPressed,
/// DecrementPressed,
/// }
///
/// impl Application for Counter {
/// type Executor = executor::Null; /// type Executor = executor::Null;
/// type Message = Message; /// type Message = ();
/// type Flags = (); /// type Flags = ();
/// ///
/// fn new(_flags: ()) -> (Self, Command<Message>) { /// fn new(_flags: ()) -> (Hello, Command<Self::Message>) {
/// (Self::default(), Command::none()) /// (Hello, Command::none())
/// } /// }
/// ///
/// fn title(&self) -> String { /// fn title(&self) -> String {
/// String::from("A simple counter") /// String::from("A cool application")
/// } /// }
/// ///
/// fn update(&mut self, message: Message) -> Command<Message> { /// fn update(&mut self, _message: Self::Message) -> Command<Self::Message> {
/// match message {
/// Message::IncrementPressed => {
/// self.value += 1;
/// }
/// Message::DecrementPressed => {
/// self.value -= 1;
/// }
/// }
///
/// Command::none() /// Command::none()
/// } /// }
/// ///
/// fn view(&mut self) -> Element<Message> { /// fn view(&mut self) -> Element<Self::Message> {
/// Column::new() /// Text::new("Hello, world!").into()
/// .push(
/// Button::new(&mut self.increment_button, Text::new("Increment"))
/// .on_press(Message::IncrementPressed),
/// )
/// .push(
/// Text::new(self.value.to_string()).size(50),
/// )
/// .push(
/// Button::new(&mut self.decrement_button, Text::new("Decrement"))
/// .on_press(Message::DecrementPressed),
/// )
/// .into()
/// } /// }
/// } /// }
/// ``` /// ```
@ -101,7 +102,7 @@ pub trait Application: Sized {
type Flags; type Flags;
/// Initializes the [`Application`] with the flags provided to /// Initializes the [`Application`] with the flags provided to
/// [`run`] as part of the [`Settings`]: /// [`run`] as part of the [`Settings`].
/// ///
/// Here is where you should return the initial state of your app. /// Here is where you should return the initial state of your app.
/// ///

2
src/executor.rs
View file

@ -1,5 +1,5 @@
//! Choose your preferred executor to power your application. //! Choose your preferred executor to power your application.
pub use crate::common::{executor::Null, Executor}; pub use crate::runtime::{executor::Null, Executor};
pub use platform::Default; pub use platform::Default;

11
src/lib.rs
View file

@ -166,13 +166,14 @@
//! 1. Draw the resulting user interface. //! 1. Draw the resulting user interface.
//! //!
//! # Usage //! # Usage
//! Take a look at the [`Application`] trait, which streamlines all the process //! The [`Application`] and [`Sandbox`] traits should get you started quickly,
//! described above for you! //! streamlining all the process described above!
//! //!
//! [Elm]: https://elm-lang.org/ //! [Elm]: https://elm-lang.org/
//! [The Elm Architecture]: https://guide.elm-lang.org/architecture/ //! [The Elm Architecture]: https://guide.elm-lang.org/architecture/
//! [examples]: https://github.com/hecrj/iced/tree/master/examples //! [examples]: https://github.com/hecrj/iced/tree/master/examples
//! [`Application`]: trait.Application.html //! [`Application`]: trait.Application.html
//! [`Sandbox`]: trait.Sandbox.html
#![deny(missing_docs)] #![deny(missing_docs)]
#![deny(missing_debug_implementations)] #![deny(missing_debug_implementations)]
#![deny(unused_results)] #![deny(unused_results)]
@ -198,12 +199,12 @@ pub use sandbox::Sandbox;
pub use settings::Settings; pub use settings::Settings;
#[cfg(not(target_arch = "wasm32"))] #[cfg(not(target_arch = "wasm32"))]
use iced_winit as common; use iced_winit as runtime;
#[cfg(target_arch = "wasm32")] #[cfg(target_arch = "wasm32")]
use iced_web as common; use iced_web as runtime;
pub use common::{ pub use runtime::{
futures, Align, Background, Color, Command, Font, HorizontalAlignment, futures, Align, Background, Color, Command, Font, HorizontalAlignment,
Length, Point, Size, Subscription, Vector, VerticalAlignment, Length, Point, Size, Subscription, Vector, VerticalAlignment,
}; };

111
src/sandbox.rs
View file

@ -2,78 +2,89 @@ use crate::{executor, Application, Command, Element, Settings, Subscription};
/// A sandboxed [`Application`]. /// A sandboxed [`Application`].
/// ///
/// A [`Sandbox`] is just an [`Application`] that cannot run any asynchronous /// If you are a just getting started with the library, this trait offers a
/// actions. /// simpler interface than [`Application`].
/// ///
/// If you do not need to leverage a [`Command`], you can use a [`Sandbox`] /// Unlike an [`Application`], a [`Sandbox`] cannot run any asynchronous
/// instead of returning a [`Command::none`] everywhere. /// actions. However, both traits are very similar and upgrading from a
/// [`Sandbox`] is very straightforward.
///
/// Therefore, it is recommended to always start by implementing this trait and
/// upgrade only once you need to perform asynchronous work.
/// ///
/// [`Application`]: trait.Application.html /// [`Application`]: trait.Application.html
/// [`Sandbox`]: trait.Sandbox.html /// [`Sandbox`]: trait.Sandbox.html
/// [`Command`]: struct.Command.html /// [`Command`]: struct.Command.html
/// [`Command::none`]: struct.Command.html#method.none /// [`Command::none`]: struct.Command.html#method.none
/// ///
/// # Example /// # Examples
/// We can use a [`Sandbox`] to run the [`Counter` example we implemented /// [The repository has a bunch of examples] that use the [`Sandbox`] trait:
/// before](index.html#overview), instead of an [`Application`]. We just need ///
/// to remove the use of [`Command`]: /// - [`bezier_tool`], a Paint-like tool for drawing Bézier curves using
/// [`lyon`].
/// - [`counter`], the classic counter example explained in [the overview].
/// - [`custom_widget`], a demonstration of how to build a custom widget that
/// draws a circle.
/// - [`geometry`], a custom widget showcasing how to draw geometry with the
/// `Mesh2D` primitive in [`iced_wgpu`].
/// - [`pane_grid`], a grid of panes that can be split, resized, and
/// reorganized.
/// - [`progress_bar`], a simple progress bar that can be filled by using a
/// slider.
/// - [`styling`], an example showcasing custom styling with a light and dark
/// theme.
/// - [`svg`], an application that renders the [Ghostscript Tiger] by leveraging
/// the [`Svg` widget].
/// - [`tour`], a simple UI tour that can run both on native platforms and the
/// web!
///
/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.1/examples
/// [`bezier_tool`]: https://github.com/hecrj/iced/tree/0.1/examples/bezier_tool
/// [`counter`]: https://github.com/hecrj/iced/tree/0.1/examples/counter
/// [`custom_widget`]: https://github.com/hecrj/iced/tree/0.1/examples/custom_widget
/// [`geometry`]: https://github.com/hecrj/iced/tree/0.1/examples/geometry
/// [`pane_grid`]: https://github.com/hecrj/iced/tree/0.1/examples/pane_grid
/// [`progress_bar`]: https://github.com/hecrj/iced/tree/0.1/examples/progress_bar
/// [`styling`]: https://github.com/hecrj/iced/tree/0.1/examples/styling
/// [`svg`]: https://github.com/hecrj/iced/tree/0.1/examples/svg
/// [`tour`]: https://github.com/hecrj/iced/tree/0.1/examples/tour
/// [`lyon`]: https://github.com/nical/lyon
/// [the overview]: index.html#overview
/// [`iced_wgpu`]: https://github.com/hecrj/iced/tree/0.1/wgpu
/// [`Svg` widget]: widget/svg/struct.Svg.html
/// [Ghostscript Tiger]: https://commons.wikimedia.org/wiki/File:Ghostscript_Tiger.svg
///
/// ## A simple "Hello, world!"
///
/// If you just want to get started, here is a simple [`Sandbox`] that
/// says "Hello, world!":
/// ///
/// ```no_run /// ```no_run
/// use iced::{button, Button, Column, Element, Sandbox, Settings, Text}; /// use iced::{Element, Sandbox, Settings, Text};
/// ///
/// pub fn main() { /// pub fn main() {
/// Counter::run(Settings::default()) /// Hello::run(Settings::default())
/// } /// }
/// ///
/// #[derive(Default)] /// struct Hello;
/// struct Counter {
/// value: i32,
/// increment_button: button::State,
/// decrement_button: button::State,
/// }
/// ///
/// #[derive(Debug, Clone, Copy)] /// impl Sandbox for Hello {
/// enum Message { /// type Message = ();
/// IncrementPressed,
/// DecrementPressed,
/// }
/// ///
/// impl Sandbox for Counter { /// fn new() -> Hello {
/// type Message = Message; /// Hello
///
/// fn new() -> Self {
/// Self::default()
/// } /// }
/// ///
/// fn title(&self) -> String { /// fn title(&self) -> String {
/// String::from("A simple counter") /// String::from("A cool application")
/// } /// }
/// ///
/// fn update(&mut self, message: Message) { /// fn update(&mut self, _message: Self::Message) {
/// match message { /// // This application has no interactions
/// Message::IncrementPressed => {
/// self.value += 1;
/// }
/// Message::DecrementPressed => {
/// self.value -= 1;
/// }
/// }
/// } /// }
/// ///
/// fn view(&mut self) -> Element<Message> { /// fn view(&mut self) -> Element<Self::Message> {
/// Column::new() /// Text::new("Hello, world!").into()
/// .push(
/// Button::new(&mut self.increment_button, Text::new("Increment"))
/// .on_press(Message::IncrementPressed),
/// )
/// .push(
/// Text::new(self.value.to_string()).size(50),
/// )
/// .push(
/// Button::new(&mut self.decrement_button, Text::new("Decrement"))
/// .on_press(Message::DecrementPressed),
/// )
/// .into()
/// } /// }
/// } /// }
/// ``` /// ```

6
src/settings.rs
View file

@ -13,7 +13,7 @@ pub struct Settings<Flags> {
/// The data needed to initialize an [`Application`]. /// The data needed to initialize an [`Application`].
/// ///
/// [`Application`]: trait.Application.html /// [`Application`]: ../trait.Application.html
pub flags: Flags, pub flags: Flags,
/// The bytes of the font that will be used by default. /// The bytes of the font that will be used by default.
@ -26,9 +26,11 @@ pub struct Settings<Flags> {
/// primitives. /// primitives.
/// ///
/// Enabling it can produce a smoother result in some widgets, like the /// Enabling it can produce a smoother result in some widgets, like the
/// `Canvas`, at a performance cost. /// [`Canvas`], at a performance cost.
/// ///
/// By default, it is disabled. /// By default, it is disabled.
///
/// [`Canvas`]: ../widget/canvas/struct.Canvas.html
pub antialiasing: bool, pub antialiasing: bool,
} }

2
winit/src/application.rs
View file

@ -34,7 +34,7 @@ pub trait Application: Sized {
type Flags; type Flags;
/// Initializes the [`Application`] with the flags provided to /// Initializes the [`Application`] with the flags provided to
/// [`run`] as part of the [`Settings`]: /// [`run`] as part of the [`Settings`].
/// ///
/// Here is where you should return the initial state of your app. /// Here is where you should return the initial state of your app.
/// ///