Merge branch 'master' into dev/system-information

6 files changed, 130 insertions, 32 deletions

diff --git a/src/application.rs b/src/application.rs
index 14a16d61..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.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/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 cbda3c87..298beae3 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/tree/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/master/wgpu
-//! [windowing shell]: https://github.com/hecrj/iced/tree/master/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/master/web
-//! [examples]: https://github.com/hecrj/iced/tree/0.3/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
@@ -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"))]
@@ -225,8 +226,8 @@ pub use settings::Settings;
 pub use runtime::alignment;
 pub use runtime::futures;
 pub use runtime::{
-    Alignment, Background, Color, Command, ContentFit, Font, Length, Point,
-    Rectangle, Size, Subscription, Vector,
+    Alignment, Background, Color, Command, ContentFit, Font, Length, Padding,
+    Point, Rectangle, Size, Subscription, Vector,
 };
 
 #[cfg(feature = "system")]
diff --git a/src/pure.rs b/src/pure.rs
index 948183f1..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<Self::Message>;
+//! }
+//! ```
+//!
+//! 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<Message> {
+//!         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<Message> {
+//!         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
@@ -26,6 +104,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`].
diff --git a/src/pure/widget.rs b/src/pure/widget.rs
index 6628b1fb..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,
@@ -118,6 +118,15 @@ pub mod text_input {
         iced_pure::widget::TextInput<'a, Message, Renderer>;
 }
 
+pub mod tooltip {
+    //! Display a widget over another.
+    pub use iced_pure::widget::tooltip::Position;
+
+    /// A widget allowing the selection of a single value from a list of options.
+    pub type Tooltip<'a, Message> =
+        iced_pure::widget::Tooltip<'a, Message, crate::Renderer>;
+}
+
 pub use iced_pure::widget::progress_bar;
 pub use iced_pure::widget::rule;
 pub use iced_pure::widget::slider;
@@ -135,6 +144,7 @@ pub use scrollable::Scrollable;
 pub use slider::Slider;
 pub use text_input::TextInput;
 pub use toggler::Toggler;
+pub use tooltip::Tooltip;
 
 #[cfg(feature = "canvas")]
 pub use iced_graphics::widget::pure::canvas;
diff --git a/src/sandbox.rs b/src/sandbox.rs
index 2306c650..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.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/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.3/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
 ///
diff --git a/src/widget.rs b/src/widget.rs
index 9cc0832f..5e2b63fc 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,
@@ -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;