document views mod

src/views/mod.rs

@@ -21,65 +21,51 @@
 //!     )),
 //! ));
 //! ```
+//! Views in Floem can also be easily refactored.
+//! ## Example: Refactored Counter
+//! ```rust
+//! use floem::prelude::*;
 //!
-//! ### Stacks and Lists
-//! There are a few different stacks and lists that you can use to group your views and each is discussed here.
-//! There are basic [stacks](stack()) and [lists](list()), a [dynamic stack](dyn_stack()), and [virtual stacks](virtual_stack()) and [virtual_lists](virtual_list()).
-//! The basic stacks and basic lists are static and always contain the same elements in the same order, but the children can still get reactive updates.
-//! The dynamic stack can dynamically change the elements in the stack by reactively updating the list of items provided to the [dyn_stack](dyn_stack()).
-//! Virtual stacks and virtual lists are like the dynamic stack but they also lazily load the items as they appear in a [scroll view](scroll()) and do not support the flexbox nor grid layout algorithms.
-//! Instead, they give every element a consistent size and use a basic layout.
-//! This is done for performance and allows for lists of millions of items to be used with very high performance.
-//!
-//! Lists differ from stacks in that they also have built-in support for the selection of items: up and down using arrow keys, top and bottom control using the home and end keys, and for the "acceptance" of an item using the Enter key.
-//! You could build this manually yourself using stacks but it is common enough that it is built-in as a list.
+//! let mut counter = RwSignal::new(0);
 //!
-//! For the most direct documentation for Floem Views see the [Functions](#functions) section of this module documentation.
-
-//! # View and Widget Traits
+//! let counter_label = label(move || format!("Value: {counter}"));
+//!
+//! let increment_button = button("Increment").action(move || counter += 1);
+//! let decrement_button = button("Decrement").action(move || counter -= 1);
 //!
-//! Views are self-contained components that can be composed together to create complex UIs.
-//! Views are the main building blocks of Floem.
+//! let button_stack = (increment_button, decrement_button).h_stack();
 //!
-//! Views are structs that implement the View and widget traits. Many of these structs will also contain a child field that also implements View. In this way, views can be composed together easily to create complex UIs. This is the most common way to build UIs in Floem. For more information on how to compose views check out the [Views](crate::views) module.
+//! (counter_label, button_stack).v_stack();
+//! ```
 //!
-//! Creating a struct and manually implementing the View and Widget traits is typically only needed for building new widgets and for special cases. The rest of this module documentation is for help when manually implementing View and Widget on your own types.
 //!
+//! ### Stacks and Lists
+//! There are a few different stacks and lists that you can use to group your views and each is discussed here.
 //!
-//! ## The View and Widget Traits
-//! The [View](crate::View) trait is the trait that Floem uses to build  and display elements. The trait contains the methods for implementing updates, styling, layout, events, and painting.
 //!
-//! ## State management
+//! They are:
+//! - basic [stack](stack())
+//!     - static and always contains the same elements in the same order
+//! - [dynamic stack](dyn_stack())
+//!     - can dynamically change the elements in the stack by reactively updating the list of items provided
+//! - [virtual stack](virtual_stack::virtual_stack())
+//!     - can dynamically change the elements in the stack
+//!     - can lazily load the items as they appear in a [scroll view](scroll())
 //!
-//! For all reactive state that your type contains, either in the form of signals or derived signals, you need to process the changes within an effect.
-//! The most common pattern is to [get](floem_reactive::SignalGet::get) the data in an effect and pass it in to `id.update_state()` and then handle that data in the `update` method of the View trait.
+//! There is also a basic [list](list()) and a [virtual list](virtual_list::virtual_list()).
+//! Lists are like their stack counterparts but they also have built-in support for the selection of items: up and down using arrow keys, top and bottom control using the home and end keys, and for the "acceptance" of an item using the Enter key.
+//! You could build this manually yourself using stacks but it is common enough that it is built-in as a list.
 //!
-//! For example a minimal slider might look like the following. First, we define the struct that contains the [ViewId](crate::ViewId).
-//! Then, we use a function to construct the slider. As part of this function we create an effect that will be re-run every time the signals in the  `percent` closure change.
-//! In the effect we send the change to the associated [ViewId](crate::ViewId). This change can then be handled in the [View::update](crate::View::update) method.
-//! ```rust
-//! use floem::ViewId;
-//! use floem::reactive::*;
-//!
-//! struct Slider {
-//!     id: ViewId,
-//! }
-//! pub fn slider(percent: impl Fn() -> f32 + 'static) -> Slider {
-//!    let id = ViewId::new();
-//!
-//!    // If the following effect is not created, and `percent` is accessed directly,
-//!    // `percent` will only be accessed a single time and will not be reactive.
-//!    // Therefore the following `create_effect` is necessary for reactivity.
-//!    create_effect(move |_| {
-//!        let percent = percent();
-//!        id.update_state(percent);
-//!    });
-//!    Slider {
-//!        id,
-//!    }
-//! }
-//! ```
+//! ## View Trait
+//! The [View](crate::View) trait is the trait that Floem uses to build and display elements.
+//! The trait contains the methods for implementing updates, styling, layout, events, and painting.
+//!
+//! Views are types that implement `View`.
+//! Many of these types will also be built with a child that also implements `View`.
+//! In this way, views can be composed together easily to create complex UIs.
+//! This composition is the most common way to build UIs in Floem.
 //!
+//! Creating a type and manually implementing the View trait is typically only needed for building new widgets and for special cases.
 
 mod label;
 pub use label::*;