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
/// document.
///
/// An [`Application`](trait.Application.html) can execute asynchronous actions
/// by returning a [`Command`](struct.Command.html) in some of its methods. If
/// An [`Application`] can execute asynchronous actions by returning a
/// [`Command`](struct.Command.html) in some of its methods. If
/// you do not intend to perform any background work in your program, the
/// [`Sandbox`](trait.Sandbox.html) trait offers a simplified interface.
///
/// # Example
/// Let's say we want to run the [`Counter` example we implemented
/// before](index.html#overview). We just need to fill in the gaps:
/// [`Application`]: trait.Application.html
///
/// # 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
/// use iced::{button, executor, Application, Button, Column, Command, Element, Settings, Text};
/// use iced::{executor, Application, Command, Element, Settings, Text};
///
/// pub fn main() {
/// Counter::run(Settings::default())
/// Hello::run(Settings::default())
/// }
///
/// #[derive(Default)]
/// struct Counter {
/// value: i32,
/// increment_button: button::State,
/// decrement_button: button::State,
/// }
/// struct Hello;
///
/// #[derive(Debug, Clone, Copy)]
/// enum Message {
/// IncrementPressed,
/// DecrementPressed,
/// }
///
/// impl Application for Counter {
/// impl Application for Hello {
/// type Executor = executor::Null;
/// type Message = Message;
/// type Message = ();
/// type Flags = ();
///
/// fn new(_flags: ()) -> (Self, Command<Message>) {
/// (Self::default(), Command::none())
/// fn new(_flags: ()) -> (Hello, Command<Self::Message>) {
/// (Hello, Command::none())
/// }
///
/// fn title(&self) -> String {
/// String::from("A simple counter")
/// String::from("A cool application")
/// }
///
/// fn update(&mut self, message: Message) -> Command<Message> {
/// match message {
/// Message::IncrementPressed => {
/// self.value += 1;
/// }
/// Message::DecrementPressed => {
/// self.value -= 1;
/// }
/// }
///
/// fn update(&mut self, _message: Self::Message) -> Command<Self::Message> {
/// Command::none()
/// }
///
/// fn view(&mut self) -> Element<Message> {
/// Column::new()
/// .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()
/// fn view(&mut self) -> Element<Self::Message> {
/// Text::new("Hello, world!").into()
/// }
/// }
/// ```
@ -101,7 +102,7 @@ pub trait Application: Sized {
type Flags;
/// 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.
///

2
src/executor.rs
View file

@ -1,5 +1,5 @@
//! 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;

11
src/lib.rs
View file

@ -166,13 +166,14 @@
//! 1. Draw the resulting user interface.
//!
//! # Usage
//! Take a look at the [`Application`] trait, which streamlines all the process
//! described above for you!
//! The [`Application`] and [`Sandbox`] traits should get you started quickly,
//! streamlining all the process described above!
//!
//! [Elm]: https://elm-lang.org/
//! [The Elm Architecture]: https://guide.elm-lang.org/architecture/
//! [examples]: https://github.com/hecrj/iced/tree/master/examples
//! [`Application`]: trait.Application.html
//! [`Sandbox`]: trait.Sandbox.html
#![deny(missing_docs)]
#![deny(missing_debug_implementations)]
#![deny(unused_results)]
@ -198,12 +199,12 @@ pub use sandbox::Sandbox;
pub use settings::Settings;
#[cfg(not(target_arch = "wasm32"))]
use iced_winit as common;
use iced_winit as runtime;
#[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,
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 [`Sandbox`] is just an [`Application`] that cannot run any asynchronous
/// actions.
/// If you are a just getting started with the library, this trait offers a
/// simpler interface than [`Application`].
///
/// If you do not need to leverage a [`Command`], you can use a [`Sandbox`]
/// instead of returning a [`Command::none`] everywhere.
/// Unlike an [`Application`], a [`Sandbox`] cannot run any asynchronous
/// 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
/// [`Sandbox`]: trait.Sandbox.html
/// [`Command`]: struct.Command.html
/// [`Command::none`]: struct.Command.html#method.none
///
/// # Example
/// We can use a [`Sandbox`] to run the [`Counter` example we implemented
/// before](index.html#overview), instead of an [`Application`]. We just need
/// to remove the use of [`Command`]:
/// # Examples
/// [The repository has a bunch of examples] that use the [`Sandbox`] trait:
///
/// - [`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
/// use iced::{button, Button, Column, Element, Sandbox, Settings, Text};
/// use iced::{Element, Sandbox, Settings, Text};
///
/// pub fn main() {
/// Counter::run(Settings::default())
/// Hello::run(Settings::default())
/// }
///
/// #[derive(Default)]
/// struct Counter {
/// value: i32,
/// increment_button: button::State,
/// decrement_button: button::State,
/// }
/// struct Hello;
///
/// #[derive(Debug, Clone, Copy)]
/// enum Message {
/// IncrementPressed,
/// DecrementPressed,
/// }
/// impl Sandbox for Hello {
/// type Message = ();
///
/// impl Sandbox for Counter {
/// type Message = Message;
///
/// fn new() -> Self {
/// Self::default()
/// fn new() -> Hello {
/// Hello
/// }
///
/// fn title(&self) -> String {
/// String::from("A simple counter")
/// String::from("A cool application")
/// }
///
/// fn update(&mut self, message: Message) {
/// match message {
/// Message::IncrementPressed => {
/// self.value += 1;
/// }
/// Message::DecrementPressed => {
/// self.value -= 1;
/// }
/// }
/// fn update(&mut self, _message: Self::Message) {
/// // This application has no interactions
/// }
///
/// fn view(&mut self) -> Element<Message> {
/// Column::new()
/// .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()
/// fn view(&mut self) -> Element<Self::Message> {
/// Text::new("Hello, world!").into()
/// }
/// }
/// ```

6
src/settings.rs
View file

@ -13,7 +13,7 @@ pub struct Settings<Flags> {
/// The data needed to initialize an [`Application`].
///
/// [`Application`]: trait.Application.html
/// [`Application`]: ../trait.Application.html
pub flags: Flags,
/// The bytes of the font that will be used by default.
@ -26,9 +26,11 @@ pub struct Settings<Flags> {
/// primitives.
///
/// 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.
///
/// [`Canvas`]: ../widget/canvas/struct.Canvas.html
pub antialiasing: bool,
}

2
winit/src/application.rs
View file

@ -34,7 +34,7 @@ pub trait Application: Sized {
type Flags;
/// 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.
///