xilem: docs update for label, button, sized_box, flex, grid, checkbox.

xilem/README.md

@@ -65,7 +65,7 @@ fn main() -> Result<(), EventLoopError> {
 More examples available [here](https://github.com/linebender/xilem/tree/main/xilem/examples).
 
 ### View elements
-The primitives your [Xilem] app’s view tree will generally be constructed from:
+The primitives your `Xilem` app’s view tree will generally be constructed from:
 - [`flex`]: layout defines how items will be arranged in rows or columns.
 - [`grid`]: layout divides a window into regions and defines the relationship
   between inner elements in terms of size and position.
@@ -92,8 +92,6 @@ The primitives your [Xilem] app’s view tree will generally be constructed from
 [architecture for UI in Rust]: https://raphlinus.github.io/rust/gui/2022/05/07/ui-architecture.html
 [winit]: https://crates.io/crates/winit
 [Druid]: https://crates.io/crates/druid
-[Xilem]: https://crates.io/crates/xilem
-[XilemDocs]: https://docs.rs/xilem
 [Masonry]: https://crates.io/crates/masonry
 [Vello]: https://crates.io/crates/vello
 [Parley]: https://crates.io/crates/parley
@@ -126,7 +124,7 @@ The primitives your [Xilem] app’s view tree will generally be constructed from
 
 ## Minimum supported Rust Version (MSRV)
 
-This version of Xilem has been verified to compile with **Rust 1.81** and later.
+This version of Xilem has been verified to compile with **Rust 1.82** and later.
 
 Future versions of Xilem might increase the Rust version requirement.
 It will not be treated as a breaking change and as such can even happen with small patch releases.

xilem/src/lib.rs

@@ -42,7 +42,7 @@
 //! More examples available [here](https://github.com/linebender/xilem/tree/main/xilem/examples).
 //!
 //! ## View elements
-//! The primitives your [Xilem] app’s view tree will generally be constructed from:
+//! The primitives your `Xilem` app’s view tree will generally be constructed from:
 //! - [`flex`]: layout defines how items will be arranged in rows or columns.
 //! - [`grid`]: layout divides a window into regions and defines the relationship
 //!   between inner elements in terms of size and position.
@@ -69,8 +69,6 @@
 //! [architecture for UI in Rust]: https://raphlinus.github.io/rust/gui/2022/05/07/ui-architecture.html
 //! [winit]: https://crates.io/crates/winit
 //! [Druid]: https://crates.io/crates/druid
-//! [Xilem]: https://crates.io/crates/xilem
-//! [XilemDocs]: https://docs.rs/xilem
 //! [Masonry]: https://crates.io/crates/masonry
 //! [Vello]: https://crates.io/crates/vello
 //! [Parley]: https://crates.io/crates/parley

xilem/src/view/button.rs

@@ -12,6 +12,48 @@ use crate::{Affine, MessageResult, Pod, ViewCtx, ViewId};
 use super::Transformable;
 
 /// A button which calls `callback` when the primary mouse button (normally left) is pressed.
+///
+/// # Examples
+/// To use button provide it with a button text and a closure.
+/// ```ignore
+/// use xilem::view::button;
+///
+/// struct State {
+///     int: i32,
+/// }
+///
+/// impl State {
+///     fn increase(&mut self) {
+///         self.int += 1;
+///     }
+/// }
+///
+/// button("Button", |state: &mut State| {
+///      state.increase();
+/// })
+/// ```
+///
+/// Create a `button` with a custom `label`.
+///
+/// ```ignore
+/// use xilem::view::{button, label};
+///
+/// struct State {
+///     int: i32,
+/// }
+///
+/// impl State {
+///     fn increase(&mut self) {
+///         self.int += 1;
+///     }
+/// }
+///
+/// let label = label("Button").weight(FontWeight::BOLD);
+///
+/// button(label, |state: &mut State| {
+///     state.increase();
+/// })
+/// ```
 pub fn button<State, Action>(
     label: impl Into<Label>,
     callback: impl Fn(&mut State) -> Action + Send + 'static,
@@ -40,6 +82,9 @@ pub fn button_any_pointer<State, Action>(
     }
 }
 
+/// The [`View`] created by [`button`] from a `label` and a callback.
+///
+/// See `button` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct Button<F> {
     label: Label,

xilem/src/view/checkbox.rs

@@ -9,6 +9,24 @@ use crate::{Affine, MessageResult, Pod, View, ViewCtx, ViewId};
 
 use super::Transformable;
 
+/// An element which can be in checked and unchecked state.
+///
+/// # Example
+/// ```ignore
+/// use xilem::view::checkbox;
+///
+/// struct State {
+///     value: bool,
+/// }
+///
+/// // ...
+///
+/// let new_state = false;
+///
+/// checkbox("A simple checkbox", app_state.value, |app_state: &mut State, new_state: bool| {
+/// *app_state.value = new_state;
+/// })
+/// ```
 pub fn checkbox<F, State, Action>(
     label: impl Into<ArcStr>,
     checked: bool,
@@ -25,6 +43,9 @@ where
     }
 }
 
+/// The [`View`] created by [`checkbox`] from a `label`, a bool value and a callback.
+///
+/// See `checkbox` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct Checkbox<F> {
     label: ArcStr,

xilem/src/view/flex.rs

@@ -13,6 +13,48 @@ use crate::core::{
 };
 use crate::{Affine, AnyWidgetView, Pod, ViewCtx, WidgetView};
 
+/// A layout which defines how items will be arranged in rows or columns.
+///
+/// # Example
+/// ```rust,no_run
+/// use masonry::widget::{CrossAxisAlignment, MainAxisAlignment};
+/// use winit::error::EventLoopError;
+/// use xilem::view::{button, flex, label, sized_box, Axis, FlexExt as _, FlexSpacer, Label};
+/// use xilem::{EventLoop, WidgetView, Xilem};
+///
+/// // A component to make a bigger than usual button
+/// fn big_button(
+///     label: impl Into<Label>,
+///     callback: impl Fn(&mut i32) + Send + Sync + 'static,
+/// ) -> impl WidgetView<i32> {
+///     sized_box(button(label, callback)).width(40.).height(40.)
+/// }
+///
+/// fn app_logic(data: &mut i32) -> impl WidgetView<i32> {
+///     flex((
+///         FlexSpacer::Fixed(30.0),
+///         big_button("-", |data| {
+///             *data -= 1;
+///         }),
+///         FlexSpacer::Flex(1.0),
+///         label(format!("count: {}", data)).text_size(32.).flex(5.0),
+///         FlexSpacer::Flex(1.0),
+///         big_button("+", |data| {
+///             *data += 1;
+///         }),
+///         FlexSpacer::Fixed(30.0),
+///     ))
+///     .direction(Axis::Horizontal)
+///     .cross_axis_alignment(CrossAxisAlignment::Center)
+///     .main_axis_alignment(MainAxisAlignment::Center)
+/// }
+///
+/// fn main() -> Result<(), EventLoopError> {
+///     let app = Xilem::new(0, app_logic);
+///     app.run_windowed(EventLoop::with_user_event(), "Centered Flex".into())?;
+///     Ok(())
+/// }
+/// ```
 pub fn flex<State, Action, Seq: FlexSequence<State, Action>>(
     sequence: Seq,
 ) -> Flex<Seq, State, Action> {
@@ -28,6 +70,9 @@ pub fn flex<State, Action, Seq: FlexSequence<State, Action>>(
     }
 }
 
+/// The [`View`] created by [`flex`] from a sequence.
+///
+/// See `flex` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct Flex<Seq, State, Action = ()> {
     sequence: Seq,
@@ -349,7 +394,7 @@ impl<Seq, State, Action> FlexSequence<State, Action> for Seq where
 {
 }
 
-/// A trait which extends a [`WidgetView`] with methods to provide parameters for a flex item, or being able to use it interchangeably with a spacer
+/// A trait which extends a [`WidgetView`] with methods to provide parameters for a flex item, or being able to use it interchangeably with a spacer.
 pub trait FlexExt<State, Action>: WidgetView<State, Action> {
     /// Applies [`impl Into<FlexParams>`](`FlexParams`) to this view, can be used as child of a [`Flex`] [`View`]
     ///
@@ -402,14 +447,14 @@ pub trait FlexExt<State, Action>: WidgetView<State, Action> {
 
 impl<State, Action, V: WidgetView<State, Action>> FlexExt<State, Action> for V {}
 
-/// A `WidgetView` that can be used within a [`Flex`] [`View`]
+/// A `WidgetView` that can be used within a [`Flex`] [`View`].
 pub struct FlexItem<V, State, Action> {
     view: V,
     params: FlexParams,
     phantom: PhantomData<fn() -> (State, Action)>,
 }
 
-/// Applies [`impl Into<FlexParams>`](`FlexParams`) to the [`View`] `V`, can be used as child of a [`Flex`] View
+/// Applies [`impl Into<FlexParams>`](`FlexParams`) to the [`View`] `V`, can be used as child of a [`Flex`] View.
 ///
 /// # Examples
 /// ```

xilem/src/view/grid.rs

@@ -14,6 +14,38 @@ use crate::{Affine, Pod, ViewCtx, WidgetView};
 
 use super::Transformable;
 
+/// A Grid layout divides a window into regions and defines the relationship
+/// between inner elements in terms of size and position.
+///
+/// # Example
+/// ```ignore
+/// use masonry::widget::GridParams;
+/// use xilem::view::{
+///     button, grid, label, GridExt,
+/// };
+///
+/// const GRID_GAP: f64 = 2.;
+///
+/// #[derive(Default)]
+/// struct State {
+///     int: i32,
+/// }
+///
+/// let mut state = State::default();
+///
+/// grid(
+///     (   
+///         label(state.int.to_string()).grid_item(GridParams::new(0, 0, 3, 1)),
+///         button("Decrease by 1", |state: &mut State| state.int -= 1).grid_pos(1, 1),
+///         button("To zero", |state: &mut State| state.int = 0).grid_pos(2, 1),
+///         button("Increase by 1", |state: &mut State| state.int += 1).grid_pos(3, 1),
+///         ),
+/// 3,
+/// 2,
+/// )
+/// .spacing(GRID_GAP)
+/// ```
+/// Also see Calculator example [here](https://github.com/linebender/xilem/blob/main/xilem/examples/calc.rs) to learn more about grid layout.
 pub fn grid<State, Action, Seq: GridSequence<State, Action>>(
     sequence: Seq,
     width: i32,
@@ -29,6 +61,9 @@ pub fn grid<State, Action, Seq: GridSequence<State, Action>>(
     }
 }
 
+/// The [`View`] created by [`grid`] from a sequence, which also consumes custom width and height.
+///
+/// See `grid` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct Grid<Seq, State, Action = ()> {
     sequence: Seq,
@@ -303,6 +338,7 @@ pub trait GridExt<State, Action>: WidgetView<State, Action> {
     ///     prose("a prose").grid_pos(1, 1),
     /// ), 2, 2)
     /// # }
+    /// ```
     fn grid_pos(self, x: i32, y: i32) -> GridItem<Self, State, Action>
     where
         State: 'static,

xilem/src/view/label.rs

@@ -11,6 +11,22 @@ use crate::{Affine, Color, MessageResult, Pod, TextAlignment, View, ViewCtx, Vie
 
 use super::Transformable;
 
+/// A non-interactive text element.
+/// # Example
+///
+/// ```ignore
+/// use xilem::palette;
+/// use xilem::view::label;
+/// use masonry::TextAlignment;
+/// use masonry::parley::fontique;
+///
+/// label("Text example.")
+///     .brush(palette::css::RED)
+///     .alignment(TextAlignment::Middle)
+///     .text_size(24.0)
+///     .weight(FontWeight::BOLD)
+///     .with_font(fontique::GenericFamily::Serif)
+/// ```
 pub fn label(label: impl Into<ArcStr>) -> Label {
     Label {
         label: label.into(),
@@ -23,6 +39,9 @@ pub fn label(label: impl Into<ArcStr>) -> Label {
     }
 }
 
+/// The [`View`] created by [`label`] from a text which `impl Into<`[`ArcStr`]`>`.
+///
+/// See `label` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct Label {
     // Public for button and variable_label as a semi-interim state.
@@ -36,23 +55,27 @@ pub struct Label {
 }
 
 impl Label {
+    /// In most cases brush sets text color, but gradients and images are also supported.
     #[doc(alias = "color")]
     pub fn brush(mut self, brush: impl Into<Brush>) -> Self {
         self.text_brush = brush.into();
         self
     }
 
+    /// Sets text alignment: `Start`, `Middle`, `End` or `Justified`.
     pub fn alignment(mut self, alignment: TextAlignment) -> Self {
         self.alignment = alignment;
         self
     }
 
+    /// Sets text size.
     #[doc(alias = "font_size")]
     pub fn text_size(mut self, text_size: f32) -> Self {
         self.text_size = text_size;
         self
     }
 
+    /// Sets font weight.
     pub fn weight(mut self, weight: FontWeight) -> Self {
         self.weight = weight;
         self

xilem/src/view/sized_box.rs

@@ -18,6 +18,22 @@ use super::Transformable;
 /// This widget forces its child to have a specific width and/or height (assuming values are permitted by
 /// this widget's parent). If either the width or height is not set, this widget will size itself
 /// to match the child's size in that dimension.
+///
+/// # Example
+/// See more methods for `sized_box` on [`SizedBox`] page.
+/// ```ignore
+/// use xilem::view::{sized_box, button};
+/// use xilem::palette;
+/// use vello::kurbo::RoundedRectRadii;
+/// use masonry::widget::Padding;
+///
+/// sized_box(button("Button", |data: &mut i32| *data+=1))
+///     .expand()
+///     .background(palette::css::RED)
+///     .border(palette::css::YELLOW, 20.)
+///     .rounded(RoundedRectRadii::from_single_radius(5.))
+///     .padding(Padding::from(5.))
+/// ```
 pub fn sized_box<State, Action, V>(inner: V) -> SizedBox<V, State, Action>
 where
     V: WidgetView<State, Action>,
@@ -35,6 +51,9 @@ where
     }
 }
 
+/// The [`View`] created by [`sized_box`].
+///
+/// See `sized_box` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct SizedBox<V, State, Action = ()> {
     inner: V,