From ac35fe3edf78c1674fe85b37549002e006b0ff13 Mon Sep 17 00:00:00 2001 From: Héctor Ramón Jiménez Date: Sat, 30 Apr 2022 13:54:07 +0200 Subject: Point repository links to `0.4` branch in documentation --- src/application.rs | 18 +++++++++--------- src/lib.rs | 10 +++++----- src/pure/widget.rs | 2 +- src/sandbox.rs | 22 +++++++++++----------- src/widget.rs | 2 +- 5 files changed, 27 insertions(+), 27 deletions(-) (limited to 'src') diff --git a/src/application.rs b/src/application.rs index 14a16d61..c5434c24 100644 --- a/src/application.rs +++ b/src/application.rs @@ -37,15 +37,15 @@ use crate::{Color, Command, Element, Executor, Settings, Subscription}; /// 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.3/examples -/// [`clock`]: https://github.com/hecrj/iced/tree/0.3/examples/clock -/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.3/examples/download_progress -/// [`events`]: https://github.com/hecrj/iced/tree/0.3/examples/events -/// [`game_of_life`]: https://github.com/hecrj/iced/tree/0.3/examples/game_of_life -/// [`pokedex`]: https://github.com/hecrj/iced/tree/0.3/examples/pokedex -/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.3/examples/solar_system -/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.3/examples/stopwatch -/// [`todos`]: https://github.com/hecrj/iced/tree/0.3/examples/todos +/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.4/examples +/// [`clock`]: https://github.com/hecrj/iced/tree/0.4/examples/clock +/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.4/examples/download_progress +/// [`events`]: https://github.com/hecrj/iced/tree/0.4/examples/events +/// [`game_of_life`]: https://github.com/hecrj/iced/tree/0.4/examples/game_of_life +/// [`pokedex`]: https://github.com/hecrj/iced/tree/0.4/examples/pokedex +/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.4/examples/solar_system +/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.4/examples/stopwatch +/// [`todos`]: https://github.com/hecrj/iced/tree/0.4/examples/todos /// [`Sandbox`]: crate::Sandbox /// [`Canvas`]: crate::widget::Canvas /// [PokéAPI]: https://pokeapi.co/ diff --git a/src/lib.rs b/src/lib.rs index 84e872c7..e407b10d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -24,13 +24,13 @@ //! [scrollables]: https://gfycat.com/perkybaggybaboon-rust-gui //! [Debug overlay with performance metrics]: https://gfycat.com/incredibledarlingbee //! [Modular ecosystem]: https://github.com/hecrj/iced/blob/master/ECOSYSTEM.md -//! [renderer-agnostic native runtime]: https://github.com/hecrj/iced/tree/master/native +//! [renderer-agnostic native runtime]: https://github.com/hecrj/iced/0.4/master/native //! [`wgpu`]: https://github.com/gfx-rs/wgpu-rs -//! [built-in renderer]: https://github.com/hecrj/iced/tree/master/wgpu -//! [windowing shell]: https://github.com/hecrj/iced/tree/master/winit +//! [built-in renderer]: https://github.com/hecrj/iced/tree/0.4/wgpu +//! [windowing shell]: https://github.com/hecrj/iced/tree/0.4/winit //! [`dodrio`]: https://github.com/fitzgen/dodrio -//! [web runtime]: https://github.com/hecrj/iced/tree/master/web -//! [examples]: https://github.com/hecrj/iced/tree/0.3/examples +//! [web runtime]: https://github.com/hecrj/iced/tree/0.4/web +//! [examples]: https://github.com/hecrj/iced/tree/0.4/examples //! [repository]: https://github.com/hecrj/iced //! //! # Overview diff --git a/src/pure/widget.rs b/src/pure/widget.rs index 2a506f73..c84edde3 100644 --- a/src/pure/widget.rs +++ b/src/pure/widget.rs @@ -47,7 +47,7 @@ pub mod pane_grid { //! The [`pane_grid` example] showcases how to use a [`PaneGrid`] with resizing, //! drag and drop, and hotkey support. //! - //! [`pane_grid` example]: https://github.com/iced-rs/iced/tree/0.3/examples/pane_grid + //! [`pane_grid` example]: https://github.com/iced-rs/iced/tree/0.4/examples/pane_grid pub use iced_pure::widget::pane_grid::{ Axis, Configuration, Direction, DragEvent, Line, Node, Pane, ResizeEvent, Split, State, StyleSheet, diff --git a/src/sandbox.rs b/src/sandbox.rs index 2306c650..177c43f9 100644 --- a/src/sandbox.rs +++ b/src/sandbox.rs @@ -35,19 +35,19 @@ use crate::{ /// - [`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.3/examples -/// [`bezier_tool`]: https://github.com/hecrj/iced/tree/0.3/examples/bezier_tool -/// [`counter`]: https://github.com/hecrj/iced/tree/0.3/examples/counter -/// [`custom_widget`]: https://github.com/hecrj/iced/tree/0.3/examples/custom_widget -/// [`geometry`]: https://github.com/hecrj/iced/tree/0.3/examples/geometry -/// [`pane_grid`]: https://github.com/hecrj/iced/tree/0.3/examples/pane_grid -/// [`progress_bar`]: https://github.com/hecrj/iced/tree/0.3/examples/progress_bar -/// [`styling`]: https://github.com/hecrj/iced/tree/0.3/examples/styling -/// [`svg`]: https://github.com/hecrj/iced/tree/0.3/examples/svg -/// [`tour`]: https://github.com/hecrj/iced/tree/0.3/examples/tour +/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.4/examples +/// [`bezier_tool`]: https://github.com/hecrj/iced/tree/0.4/examples/bezier_tool +/// [`counter`]: https://github.com/hecrj/iced/tree/0.4/examples/counter +/// [`custom_widget`]: https://github.com/hecrj/iced/tree/0.4/examples/custom_widget +/// [`geometry`]: https://github.com/hecrj/iced/tree/0.4/examples/geometry +/// [`pane_grid`]: https://github.com/hecrj/iced/tree/0.4/examples/pane_grid +/// [`progress_bar`]: https://github.com/hecrj/iced/tree/0.4/examples/progress_bar +/// [`styling`]: https://github.com/hecrj/iced/tree/0.4/examples/styling +/// [`svg`]: https://github.com/hecrj/iced/tree/0.4/examples/svg +/// [`tour`]: https://github.com/hecrj/iced/tree/0.4/examples/tour /// [`Canvas widget`]: crate::widget::Canvas /// [the overview]: index.html#overview -/// [`iced_wgpu`]: https://github.com/hecrj/iced/tree/0.3/wgpu +/// [`iced_wgpu`]: https://github.com/hecrj/iced/tree/0.4/wgpu /// [`Svg` widget]: crate::widget::Svg /// [Ghostscript Tiger]: https://commons.wikimedia.org/wiki/File:Ghostscript_Tiger.svg /// diff --git a/src/widget.rs b/src/widget.rs index 9cc0832f..83df0052 100644 --- a/src/widget.rs +++ b/src/widget.rs @@ -63,7 +63,7 @@ pub mod pane_grid { //! The [`pane_grid` example] showcases how to use a [`PaneGrid`] with resizing, //! drag and drop, and hotkey support. //! - //! [`pane_grid` example]: https://github.com/iced-rs/iced/tree/0.3/examples/pane_grid + //! [`pane_grid` example]: https://github.com/iced-rs/iced/tree/0.4/examples/pane_grid pub use iced_native::widget::pane_grid::{ Axis, Configuration, Direction, DragEvent, Line, Node, Pane, ResizeEvent, Split, State, StyleSheet, -- cgit From 68e9eb0a9b45b86713ce5d0e9c2273a60f2cc11c Mon Sep 17 00:00:00 2001 From: Héctor Ramón Jiménez Date: Sat, 30 Apr 2022 14:20:52 +0200 Subject: Fix broken intra-doc links in documentation --- src/pure.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src') diff --git a/src/pure.rs b/src/pure.rs index 948183f1..5776de40 100644 --- a/src/pure.rs +++ b/src/pure.rs @@ -26,6 +26,7 @@ pub use application::Application; pub use sandbox::Sandbox; pub use iced_pure::helpers::*; +pub use iced_pure::Widget; pub use iced_pure::{Pure, State}; /// A generic, pure [`Widget`]. -- cgit From e7d595c7de3854e165fd68f05ab2292cae69dbc4 Mon Sep 17 00:00:00 2001 From: Héctor Ramón Jiménez Date: Mon, 2 May 2022 20:16:00 +0200 Subject: Write documentation for `iced_pure` --- src/pure.rs | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) (limited to 'src') diff --git a/src/pure.rs b/src/pure.rs index 5776de40..7785a104 100644 --- a/src/pure.rs +++ b/src/pure.rs @@ -14,6 +14,84 @@ //! offers an alternate [`Application`] trait with a completely pure `view` //! method. //! +//! # The Elm Architecture, purity, and continuity +//! As you may know, applications made with `iced` use [The Elm Architecture]. +//! +//! In a nutshell, this architecture defines the initial state of the application, a way to `view` it, and a way to `update` it after a user interaction. The `update` logic is called after a meaningful user interaction, which in turn updates the state of the application. Then, the `view` logic is executed to redisplay the application. +//! +//! Since `view` logic is only run after an `update`, all of the mutations to the application state must only happen in the `update` logic. If the application state changes anywhere else, the `view` logic will not be rerun and, therefore, the previously generated `view` may stay outdated. +//! +//! However, the `Application` trait in `iced` defines `view` as: +//! +//! ```ignore +//! pub trait Application { +//! fn view(&mut self) -> Element; +//! } +//! ``` +//! +//! As a consequence, the application state can be mutated in `view` logic. The `view` logic in `iced` is __impure__. +//! +//! This impurity is necessary because `iced` puts the burden of widget __continuity__ on its users. In other words, it's up to you to provide `iced` with the internal state of each widget every time `view` is called. +//! +//! If we take a look at the classic `counter` example: +//! +//! ```ignore +//! struct Counter { +//! value: i32, +//! increment_button: button::State, +//! decrement_button: button::State, +//! } +//! +//! // ... +//! +//! impl Counter { +//! pub fn view(&mut self) -> Column { +//! Column::new() +//! .push( +//! Button::new(&mut self.increment_button, Text::new("+")) +//! .on_press(Message::IncrementPressed), +//! ) +//! .push(Text::new(self.value.to_string()).size(50)) +//! .push( +//! Button::new(&mut self.decrement_button, Text::new("-")) +//! .on_press(Message::DecrementPressed), +//! ) +//! } +//! } +//! ``` +//! +//! We can see how we need to keep track of the `button::State` of each `Button` in our `Counter` state and provide a mutable reference to the widgets in our `view` logic. The widgets produced by `view` are __stateful__. +//! +//! While this approach forces users to keep track of widget state and causes impurity, I originally chose it because it allows `iced` to directly consume the widget tree produced by `view`. Since there is no internal state decoupled from `view` maintained by the runtime, `iced` does not need to compare (e.g. reconciliate) widget trees in order to ensure continuity. +//! +//! # Stateless widgets +//! As the library matures, the need for some kind of persistent widget data (see #553) between `view` calls becomes more apparent (e.g. incremental rendering, animations, accessibility, etc.). +//! +//! If we are going to end up having persistent widget data anyways... There is no reason to have impure, stateful widgets anymore! +//! +//! With the help of this module, we can now write a pure `counter` example: +//! +//! ```ignore +//! struct Counter { +//! value: i32, +//! } +//! +//! // ... +//! +//! impl Counter { +//! fn view(&self) -> Column { +//! Column::new() +//! .push(Button::new("Increment").on_press(Message::IncrementPressed)) +//! .push(Text::new(self.value.to_string()).size(50)) +//! .push(Button::new("Decrement").on_press(Message::DecrementPressed)) +//! } +//! } +//! ``` +//! +//! Notice how we no longer need to keep track of the `button::State`! The widgets in `iced_pure` do not take any mutable application state in `view`. They are __stateless__ widgets. As a consequence, we do not need mutable access to `self` in `view` anymore. `view` becomes __pure__. +//! +//! [The Elm Architecture]: https://guide.elm-lang.org/architecture/ +//! //! [the original widgets]: crate::widget //! [`button::State`]: crate::widget::button::State //! [impure `Application`]: crate::Application -- cgit From aecbd46123eb556fa1193cdf3b9eb96cfd4beff2 Mon Sep 17 00:00:00 2001 From: Héctor Ramón Jiménez Date: Mon, 2 May 2022 20:25:47 +0200 Subject: Replace `hecrj` in links with `iced-rs` --- src/application.rs | 18 +++++++++--------- src/lib.rs | 16 ++++++++-------- src/sandbox.rs | 22 +++++++++++----------- 3 files changed, 28 insertions(+), 28 deletions(-) (limited to 'src') diff --git a/src/application.rs b/src/application.rs index c5434c24..11735b93 100644 --- a/src/application.rs +++ b/src/application.rs @@ -37,15 +37,15 @@ use crate::{Color, Command, Element, Executor, Settings, Subscription}; /// 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.4/examples -/// [`clock`]: https://github.com/hecrj/iced/tree/0.4/examples/clock -/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.4/examples/download_progress -/// [`events`]: https://github.com/hecrj/iced/tree/0.4/examples/events -/// [`game_of_life`]: https://github.com/hecrj/iced/tree/0.4/examples/game_of_life -/// [`pokedex`]: https://github.com/hecrj/iced/tree/0.4/examples/pokedex -/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.4/examples/solar_system -/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.4/examples/stopwatch -/// [`todos`]: https://github.com/hecrj/iced/tree/0.4/examples/todos +/// [The repository has a bunch of examples]: https://github.com/iced-rs/iced/tree/0.4/examples +/// [`clock`]: https://github.com/iced-rs/iced/tree/0.4/examples/clock +/// [`download_progress`]: https://github.com/iced-rs/iced/tree/0.4/examples/download_progress +/// [`events`]: https://github.com/iced-rs/iced/tree/0.4/examples/events +/// [`game_of_life`]: https://github.com/iced-rs/iced/tree/0.4/examples/game_of_life +/// [`pokedex`]: https://github.com/iced-rs/iced/tree/0.4/examples/pokedex +/// [`solar_system`]: https://github.com/iced-rs/iced/tree/0.4/examples/solar_system +/// [`stopwatch`]: https://github.com/iced-rs/iced/tree/0.4/examples/stopwatch +/// [`todos`]: https://github.com/iced-rs/iced/tree/0.4/examples/todos /// [`Sandbox`]: crate::Sandbox /// [`Canvas`]: crate::widget::Canvas /// [PokéAPI]: https://pokeapi.co/ diff --git a/src/lib.rs b/src/lib.rs index e407b10d..e154d9c7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -19,19 +19,19 @@ //! //! Check out the [repository] and the [examples] for more details! //! -//! [Cross-platform support]: https://github.com/hecrj/iced/blob/master/docs/images/todos_desktop.jpg?raw=true +//! [Cross-platform support]: https://github.com/iced-rs/iced/blob/master/docs/images/todos_desktop.jpg?raw=true //! [text inputs]: https://gfycat.com/alertcalmcrow-rust-gui //! [scrollables]: https://gfycat.com/perkybaggybaboon-rust-gui //! [Debug overlay with performance metrics]: https://gfycat.com/incredibledarlingbee -//! [Modular ecosystem]: https://github.com/hecrj/iced/blob/master/ECOSYSTEM.md -//! [renderer-agnostic native runtime]: https://github.com/hecrj/iced/0.4/master/native +//! [Modular ecosystem]: https://github.com/iced-rs/iced/blob/master/ECOSYSTEM.md +//! [renderer-agnostic native runtime]: https://github.com/iced-rs/iced/0.4/master/native //! [`wgpu`]: https://github.com/gfx-rs/wgpu-rs -//! [built-in renderer]: https://github.com/hecrj/iced/tree/0.4/wgpu -//! [windowing shell]: https://github.com/hecrj/iced/tree/0.4/winit +//! [built-in renderer]: https://github.com/iced-rs/iced/tree/0.4/wgpu +//! [windowing shell]: https://github.com/iced-rs/iced/tree/0.4/winit //! [`dodrio`]: https://github.com/fitzgen/dodrio -//! [web runtime]: https://github.com/hecrj/iced/tree/0.4/web -//! [examples]: https://github.com/hecrj/iced/tree/0.4/examples -//! [repository]: https://github.com/hecrj/iced +//! [web runtime]: https://github.com/iced-rs/iced_web +//! [examples]: https://github.com/iced-rs/iced/tree/0.4/examples +//! [repository]: https://github.com/iced-rs/iced //! //! # Overview //! Inspired by [The Elm Architecture], Iced expects you to split user diff --git a/src/sandbox.rs b/src/sandbox.rs index 177c43f9..e7e97920 100644 --- a/src/sandbox.rs +++ b/src/sandbox.rs @@ -35,19 +35,19 @@ use crate::{ /// - [`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.4/examples -/// [`bezier_tool`]: https://github.com/hecrj/iced/tree/0.4/examples/bezier_tool -/// [`counter`]: https://github.com/hecrj/iced/tree/0.4/examples/counter -/// [`custom_widget`]: https://github.com/hecrj/iced/tree/0.4/examples/custom_widget -/// [`geometry`]: https://github.com/hecrj/iced/tree/0.4/examples/geometry -/// [`pane_grid`]: https://github.com/hecrj/iced/tree/0.4/examples/pane_grid -/// [`progress_bar`]: https://github.com/hecrj/iced/tree/0.4/examples/progress_bar -/// [`styling`]: https://github.com/hecrj/iced/tree/0.4/examples/styling -/// [`svg`]: https://github.com/hecrj/iced/tree/0.4/examples/svg -/// [`tour`]: https://github.com/hecrj/iced/tree/0.4/examples/tour +/// [The repository has a bunch of examples]: https://github.com/iced-rs/iced/tree/0.4/examples +/// [`bezier_tool`]: https://github.com/iced-rs/iced/tree/0.4/examples/bezier_tool +/// [`counter`]: https://github.com/iced-rs/iced/tree/0.4/examples/counter +/// [`custom_widget`]: https://github.com/iced-rs/iced/tree/0.4/examples/custom_widget +/// [`geometry`]: https://github.com/iced-rs/iced/tree/0.4/examples/geometry +/// [`pane_grid`]: https://github.com/iced-rs/iced/tree/0.4/examples/pane_grid +/// [`progress_bar`]: https://github.com/iced-rs/iced/tree/0.4/examples/progress_bar +/// [`styling`]: https://github.com/iced-rs/iced/tree/0.4/examples/styling +/// [`svg`]: https://github.com/iced-rs/iced/tree/0.4/examples/svg +/// [`tour`]: https://github.com/iced-rs/iced/tree/0.4/examples/tour /// [`Canvas widget`]: crate::widget::Canvas /// [the overview]: index.html#overview -/// [`iced_wgpu`]: https://github.com/hecrj/iced/tree/0.4/wgpu +/// [`iced_wgpu`]: https://github.com/iced-rs/iced/tree/0.4/wgpu /// [`Svg` widget]: crate::widget::Svg /// [Ghostscript Tiger]: https://commons.wikimedia.org/wiki/File:Ghostscript_Tiger.svg /// -- cgit From 84c28a73e2a7ace8547e892f675bfc497d157bcb Mon Sep 17 00:00:00 2001 From: Héctor Ramón Jiménez Date: Mon, 2 May 2022 21:01:25 +0200 Subject: Indicate feature-flagged modules in documentation --- src/lib.rs | 1 + src/widget.rs | 8 ++++++++ 2 files changed, 9 insertions(+) (limited to 'src') diff --git a/src/lib.rs b/src/lib.rs index e154d9c7..bbc60746 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -196,6 +196,7 @@ pub mod widget; pub mod window; #[cfg(feature = "pure")] +#[cfg_attr(docsrs, doc(cfg(feature = "pure")))] pub mod pure; #[cfg(all(not(feature = "glow"), feature = "wgpu"))] diff --git a/src/widget.rs b/src/widget.rs index 83df0052..5e2b63fc 100644 --- a/src/widget.rs +++ b/src/widget.rs @@ -167,9 +167,11 @@ pub use toggler::Toggler; pub use tooltip::Tooltip; #[cfg(feature = "canvas")] +#[cfg_attr(docsrs, doc(cfg(feature = "canvas")))] pub use iced_graphics::widget::canvas; #[cfg(feature = "image")] +#[cfg_attr(docsrs, doc(cfg(feature = "image")))] pub mod image { //! Display images in your user interface. pub use iced_native::image::Handle; @@ -182,9 +184,11 @@ pub mod image { } #[cfg(feature = "qr_code")] +#[cfg_attr(docsrs, doc(cfg(feature = "qr_code")))] pub use iced_graphics::widget::qr_code; #[cfg(feature = "svg")] +#[cfg_attr(docsrs, doc(cfg(feature = "svg")))] pub mod svg { //! Display vector graphics in your application. pub use iced_native::svg::Handle; @@ -192,13 +196,17 @@ pub mod svg { } #[cfg(feature = "canvas")] +#[cfg_attr(docsrs, doc(cfg(feature = "canvas")))] pub use canvas::Canvas; #[cfg(feature = "image")] +#[cfg_attr(docsrs, doc(cfg(feature = "image")))] pub use image::Image; #[cfg(feature = "qr_code")] +#[cfg_attr(docsrs, doc(cfg(feature = "qr_code")))] pub use qr_code::QRCode; #[cfg(feature = "svg")] +#[cfg_attr(docsrs, doc(cfg(feature = "svg")))] pub use svg::Svg; -- cgit