diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/application.rs | 18 | ||||
| -rw-r--r-- | src/lib.rs | 21 | ||||
| -rw-r--r-- | src/pure.rs | 79 | ||||
| -rw-r--r-- | src/pure/widget.rs | 12 | ||||
| -rw-r--r-- | src/sandbox.rs | 22 | ||||
| -rw-r--r-- | src/widget.rs | 10 |
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/ @@ -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; |