Merge pull request #2587 from iced-rs/improve-api-reference

Add widget examples to API reference and update `README`

README.md

@@ -15,11 +15,11 @@
 A cross-platform GUI library for Rust focused on simplicity and type-safety.
 Inspired by [Elm].
 
-<a href="https://iced.rs/examples/todos.mp4">
-  <img src="https://iced.rs/examples/todos.gif" width="275px">
+<a href="https://github.com/squidowl/halloy">
+  <img src="https://iced.rs/showcase/halloy.gif" width="460px">
 </a>
-<a href="https://iced.rs/examples/tour.mp4">
-  <img src="https://iced.rs/examples/tour.gif" width="273px">
+<a href="https://github.com/hecrj/icebreaker">
+  <img src="https://iced.rs/showcase/icebreaker.gif" width="360px">
 </a>
 
 </div>
@@ -34,34 +34,28 @@ Inspired by [Elm].
 * Custom widget support (create your own!)
 * [Debug overlay with performance metrics]
 * First-class support for async actions (use futures!)
-* [Modular ecosystem] split into reusable parts:
+* Modular ecosystem split into reusable parts:
   * A [renderer-agnostic native runtime] enabling integration with existing systems
-  * Two [built-in renderers] leveraging [`wgpu`] and [`tiny-skia`]
+  * Two built-in renderers leveraging [`wgpu`] and [`tiny-skia`]
     * [`iced_wgpu`] supporting Vulkan, Metal and DX12
     * [`iced_tiny_skia`] offering a software alternative as a fallback
   * A [windowing shell]
-  * A [web runtime] leveraging the DOM
 
-__Iced is currently experimental software.__ [Take a look at the roadmap],
-[check out the issues], and [feel free to contribute!]
+__Iced is currently experimental software.__ [Take a look at the roadmap] and
+[check out the issues].
 
 [Cross-platform support]: https://raw.githubusercontent.com/iced-rs/iced/master/docs/images/todos_desktop.jpg
 [text inputs]: https://iced.rs/examples/text_input.mp4
 [scrollables]: https://iced.rs/examples/scrollable.mp4
 [Debug overlay with performance metrics]: https://iced.rs/examples/debug.mp4
-[Modular ecosystem]: ECOSYSTEM.md
 [renderer-agnostic native runtime]: runtime/
 [`wgpu`]: https://github.com/gfx-rs/wgpu
 [`tiny-skia`]: https://github.com/RazrFalcon/tiny-skia
 [`iced_wgpu`]: wgpu/
 [`iced_tiny_skia`]: tiny_skia/
-[built-in renderers]: ECOSYSTEM.md#Renderers
 [windowing shell]: winit/
-[`dodrio`]: https://github.com/fitzgen/dodrio
-[web runtime]: https://github.com/iced-rs/iced_web
 [Take a look at the roadmap]: ROADMAP.md
 [check out the issues]: https://github.com/iced-rs/iced/issues
-[feel free to contribute!]: #contributing--feedback
 
 ## Overview
 
@@ -164,33 +158,25 @@ Read the [book], the [documentation], and the [examples] to learn more!
 ## Implementation details
 
 Iced was originally born as an attempt at bringing the simplicity of [Elm] and
-[The Elm Architecture] into [Coffee], a 2D game engine I am working on.
+[The Elm Architecture] into [Coffee], a 2D game library I am working on.
 
 The core of the library was implemented during May 2019 in [this pull request].
 [The first alpha version] was eventually released as
 [a renderer-agnostic GUI library]. The library did not provide a renderer and
 implemented the current [tour example] on top of [`ggez`], a game library.
 
 Since then, the focus has shifted towards providing a batteries-included,
-end-user-oriented GUI library, while keeping [the ecosystem] modular:
-
-<p align="center">
-  <a href="ECOSYSTEM.md">
-    <img alt="The Iced Ecosystem" src="docs/graphs/ecosystem.png" width="80%">
-  </a>
-</p>
+end-user-oriented GUI library, while keeping the ecosystem modular.
 
 [this pull request]: https://github.com/hecrj/coffee/pull/35
 [The first alpha version]: https://github.com/iced-rs/iced/tree/0.1.0-alpha
 [a renderer-agnostic GUI library]: https://www.reddit.com/r/rust/comments/czzjnv/iced_a_rendereragnostic_gui_library_focused_on/
 [tour example]: examples/README.md#tour
 [`ggez`]: https://github.com/ggez/ggez
-[the ecosystem]: ECOSYSTEM.md
 
 ## Contributing / Feedback
 
-Contributions are greatly appreciated! If you want to contribute, please
-read our [contributing guidelines] for more details.
+If you want to contribute, please read our [contributing guidelines] for more details.
 
 Feedback is also welcome! You can create a new topic in [our Discourse forum] or
 come chat to [our Discord server].

core/src/widget/text.rs

@@ -1,4 +1,25 @@
-//! Write some text for your users to read.
+//! Text widgets display information through writing.
+//!
+//! # Example
+//! ```no_run
+//! # mod iced { pub mod widget { pub fn text<T>(t: T) -> iced_core::widget::Text<'static, iced_core::Theme, ()> { unimplemented!() } }
+//! #            pub use iced_core::color; }
+//! # pub type State = ();
+//! # pub type Element<'a, Message> = iced_core::Element<'a, Message, iced_core::Theme, ()>;
+//! use iced::widget::text;
+//! use iced::color;
+//!
+//! enum Message {
+//!     // ...
+//! }
+//!
+//! fn view(state: &State) -> Element<'_, Message> {
+//!     text("Hello, this is iced!")
+//!         .size(20)
+//!         .color(color!(0x0000ff))
+//!         .into()
+//! }
+//! ```
 use crate::alignment;
 use crate::layout;
 use crate::mouse;
@@ -13,7 +34,28 @@ use crate::{
 
 pub use text::{LineHeight, Shaping, Wrapping};
 
-/// A paragraph of text.
+/// A bunch of text.
+///
+/// # Example
+/// ```no_run
+/// # mod iced { pub mod widget { pub fn text<T>(t: T) -> iced_core::widget::Text<'static, iced_core::Theme, ()> { unimplemented!() } }
+/// #            pub use iced_core::color; }
+/// # pub type State = ();
+/// # pub type Element<'a, Message> = iced_core::Element<'a, Message, iced_core::Theme, ()>;
+/// use iced::widget::text;
+/// use iced::color;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     text("Hello, this is iced!")
+///         .size(20)
+///         .color(color!(0x0000ff))
+///         .into()
+/// }
+/// ```
 #[allow(missing_debug_implementations)]
 pub struct Text<'a, Theme, Renderer>
 where

futures/src/subscription.rs

@@ -138,11 +138,16 @@ impl<T> Subscription<T> {
     /// and returning the `Sender` as a `Message` for the `Application`:
     ///
     /// ```
-    /// use iced_futures::subscription::{self, Subscription};
-    /// use iced_futures::stream;
-    /// use iced_futures::futures::channel::mpsc;
-    /// use iced_futures::futures::sink::SinkExt;
-    /// use iced_futures::futures::Stream;
+    /// # mod iced {
+    /// #     pub use iced_futures::Subscription;   
+    /// #     pub use iced_futures::futures;
+    /// #     pub use iced_futures::stream;
+    /// # }
+    /// use iced::futures::channel::mpsc;
+    /// use iced::futures::sink::SinkExt;
+    /// use iced::futures::Stream;
+    /// use iced::stream;
+    /// use iced::Subscription;
     ///
     /// pub enum Event {
     ///     Ready(mpsc::Sender<Input>),

src/lib.rs

@@ -380,16 +380,18 @@
 //! #     use iced::{Element, Task};
 //! #     pub struct Contacts;
 //! #     impl Contacts {
-//! #         pub fn update(&mut self, message: Message) -> Task<Message> { unimplemented!() }
+//! #         pub fn update(&mut self, message: Message) -> Action { unimplemented!() }
 //! #         pub fn view(&self) -> Element<Message> { unimplemented!() }
 //! #     }
 //! #     #[derive(Debug)]
 //! #     pub enum Message {}
+//! #     pub enum Action { None, Run(Task<Message>), Chat(()) }
 //! # }
 //! # mod conversation {
 //! #     use iced::{Element, Task};
 //! #     pub struct Conversation;
 //! #     impl Conversation {
+//! #         pub fn new(contact: ()) -> (Self, Task<Message>) { unimplemented!() }
 //! #         pub fn update(&mut self, message: Message) -> Task<Message> { unimplemented!() }
 //! #         pub fn view(&self) -> Element<Message> { unimplemented!() }
 //! #     }
@@ -419,7 +421,19 @@
 //!     match message {
 //!         Message::Contacts(message) => {
 //!             if let Screen::Contacts(contacts) = &mut state.screen {
-//!                 contacts.update(message).map(Message::Contacts)
+//!                 let action = contacts.update(message);
+//!
+//!                 match action {
+//!                     contacts::Action::None => Task::none(),
+//!                     contacts::Action::Run(task) => task.map(Message::Contacts),
+//!                     contacts::Action::Chat(contact) => {
+//!                         let (conversation, task) = Conversation::new(contact);
+//!
+//!                         state.screen = Screen::Conversation(conversation);
+//!
+//!                         task.map(Message::Conversation)
+//!                     }
+//!                  }
 //!             } else {
 //!                 Task::none()    
 //!             }
@@ -442,8 +456,16 @@
 //! }
 //! ```
 //!
-//! Functor methods like [`Task::map`], [`Element::map`], and [`Subscription::map`] make this
-//! approach seamless.
+//! The `update` method of a screen can return an `Action` enum that can be leveraged by the parent to
+//! execute a task or transition to a completely different screen altogether. The variants of `Action` can
+//! have associated data. For instance, in the example above, the `Conversation` screen is created when
+//! `Contacts::update` returns an `Action::Chat` with the selected contact.
+//!
+//! Effectively, this approach lets you "tell a story" to connect different screens together in a type safe
+//! way.
+//!
+//! Furthermore, functor methods like [`Task::map`], [`Element::map`], and [`Subscription::map`] make composition
+//! seamless.
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/iced-rs/iced/bdf0430880f5c29443f5f0a0ae4895866dfef4c6/docs/logo.svg"
 )]

widget/src/button.rs

@@ -1,4 +1,21 @@
-//! Allow your users to perform actions by pressing a button.
+//! Buttons allow your users to perform actions by pressing them.
+//!
+//! # Example
+//! ```no_run
+//! # mod iced { pub mod widget { pub use iced_widget::*; } }
+//! # pub type State = ();
+//! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+//! use iced::widget::button;
+//!
+//! #[derive(Clone)]
+//! enum Message {
+//!     ButtonPressed,
+//! }
+//!
+//! fn view(state: &State) -> Element<'_, Message> {
+//!     button("Press me!").on_press(Message::ButtonPressed).into()
+//! }
+//! ```
 use crate::core::border::{self, Border};
 use crate::core::event::{self, Event};
 use crate::core::layout;
@@ -16,34 +33,39 @@ use crate::core::{
 
 /// A generic widget that produces a message when pressed.
 ///
+/// # Example
 /// ```no_run
-/// # type Button<'a, Message> = iced_widget::Button<'a, Message>;
-/// #
+/// # mod iced { pub mod widget { pub use iced_widget::*; } }
+/// # pub type State = ();
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+/// use iced::widget::button;
+///
 /// #[derive(Clone)]
 /// enum Message {
 ///     ButtonPressed,
 /// }
 ///
-/// let button = Button::new("Press me!").on_press(Message::ButtonPressed);
+/// fn view(state: &State) -> Element<'_, Message> {
+///     button("Press me!").on_press(Message::ButtonPressed).into()
+/// }
 /// ```
 ///
 /// If a [`Button::on_press`] handler is not set, the resulting [`Button`] will
 /// be disabled:
 ///
-/// ```
-/// # type Button<'a, Message> = iced_widget::Button<'a, Message>;
-/// #
+/// ```no_run
+/// # mod iced { pub mod widget { pub use iced_widget::*; } }
+/// # pub type State = ();
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+/// use iced::widget::button;
+///
 /// #[derive(Clone)]
 /// enum Message {
 ///     ButtonPressed,
 /// }
 ///
-/// fn disabled_button<'a>() -> Button<'a, Message> {
-///     Button::new("I'm disabled!")
-/// }
-///
-/// fn enabled_button<'a>() -> Button<'a, Message> {
-///     disabled_button().on_press(Message::ButtonPressed)
+/// fn view(state: &State) -> Element<'_, Message> {
+///     button("I am disabled!").into()
 /// }
 /// ```
 #[allow(missing_debug_implementations)]