From a0b552baf2e52444c81f7f086017f0a3b62879cf Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Fri, 10 Jan 2025 18:22:41 +0100
Subject: [PATCH 1/4] Rewrite tutorial

---
 masonry/src/doc/02_implementing_widget.md     | 232 ++++++++++++------
 .../doc/03_implementing_container_widget.md   |  20 +-
 2 files changed, 167 insertions(+), 85 deletions(-)

diff --git a/masonry/src/doc/02_implementing_widget.md b/masonry/src/doc/02_implementing_widget.md
index c77a60518..1ca92e7f1 100644
--- a/masonry/src/doc/02_implementing_widget.md
+++ b/masonry/src/doc/02_implementing_widget.md
@@ -21,9 +21,7 @@ This tutorial explains how to create a simple leaf widget.
 
 ## The Widget trait
 
-Widgets are types which implement the [`Widget`] trait.
-
-This trait includes a set of methods that must be implemented to hook into Masonry's internals:
+Widgets are types which implement the [`Widget`] trait:
 
 ```rust,ignore
 trait Widget {
@@ -44,9 +42,6 @@ trait Widget {
 }
 ```
 
-These methods are called by the framework at various points, with a `FoobarCtx` parameter giving information about the current widget (for example its size, position, or whether it's currently hovered).
-The information accessible from the context argument depends on the method.
-
 In the course of a frame, Masonry will run a series of passes over the widget tree, which will call these methods at different points:
 
 - `on_pointer_event`, `on_text_event` and `on_access_event` are called once after a user-initiated event (like a mouse click or keyboard input).
@@ -55,61 +50,11 @@ In the course of a frame, Masonry will run a series of passes over the widget tr
 - `layout` is called during Masonry's layout pass. It takes size constraints and returns the widget's desired size.
 - `paint`, `accessibility_role` and `accessibility` are called roughly every frame for every widget, to allow them to draw to the screen and describe their structure to assistive technologies.
 
-Most passes will skip most widgets by default.
-For instance, the paint pass will only call a widget's `paint` method once, and then cache the resulting scene.
-If your widget's appearance is changed by another method, you need to call `ctx.request_render()` to tell the framework to re-run the paint and accessibility passes.
-
-Most context types include these methods for requesting future passes:
-
-- `request_render()`
-- `request_paint_only()`
-- `request_accessibility_update()`
-- `request_layout()`
-- `request_anim_frame()`
-
-
-## Widget mutation
-
-In Masonry, widgets generally can't be mutated directly.
-That is to say, even if you own a window, and even if that window holds a widget tree with a `Label` instance, you can't get a `&mut Label` directly from that window.
-
-Instead, there are two ways to mutate `Label`:
-
-- Inside a Widget method. Most methods (`on_pointer_event`, `update`, `layout`, etc) take a `&mut self` argument.
-- Through a [`WidgetMut`] wrapper. So, to change your label's text, you will call `WidgetMut::<Label>::set_text()`. This helps Masonry make sure that internal metadata is propagated after every widget change.
-
-As mentioned in the previous chapter, a `WidgetMut` is a smart reference type to the Widget tree.
-Most Widgets will implement methods that let their users "project" a WidgetMut from a parent to its child.
-For example, `WidgetMut<Portal<MyWidget>>` has a `get_child_mut()` method that returns a `WidgetMut<MyWidget>`.
-
-So far, we've seen one way to get a WidgetMut: the [`RenderRoot::edit_root_widget()`] method.
-This methods returns a WidgetMut to the root widget, which you can then project into a WidgetMut reference to its descendants.
-
-### Using WidgetMut in your custom Widget code
-
-The WidgetMut type only has two fields, both public:
-
-```rust,ignore
-pub struct WidgetMut<'a, W: Widget> {
-    pub ctx: MutateCtx<'a>,
-    pub widget: &'a mut W,
-}
-```
-
-`W` is your widget type. `MutateCtx` is yet another context type, with methods that let you get information about your widget and report that it changed in some ways.
-
-If you want your widget to be mutable outside of its pass methods, you should write setter functions taking WidgetMut as a parameter.
-
-These functions should modify the internal values of your widget, then set flags using `MutateCtx` depending on which values changed.
-For instance, a `set_padding()` function should probably call `ctx.request_layout()`, whereas a `set_background_color()` function should probably call `ctx.request_render()` or `ctx.request_paint_only()`.
-
-
-## Example widget: ColorRectangle
 
-<!-- TODO - Interleave this with above documentation. -->
+## Our example widget: `ColorRectangle`
 
-Let's implement a very simple widget: `ColorRectangle`.
-This Widget has a size, a color, and emits a `ButtonPressed` action when the user left-clicks on it (on mouse press; we ignore mouse release).
+Let's implement a very simple widget named `ColorRectangle`.
+This widget has a size, a color, and will notify Masonry when the user left-clicks on it (on mouse press; we'll ignore mouse release).
 
 First, let's create our struct:
 
@@ -130,9 +75,10 @@ impl ColorRectangle {
 ```
 
 This widget doesn't have children and doesn't really need to keep track of any transient state, so its definition is pretty simple.
-Note that we store a size, and not a position: our widget's position is picked by its parent.
+Note that we store a size, and not a position: our widget's position is tracked by its parent.
+
 
-### Implementing the Widget trait
+### Event methods
 
 First we implement event methods:
 
@@ -166,15 +112,23 @@ impl Widget for ColorRectangle {
 }
 ```
 
-Here we've written a simple handler which filters pointer events for left clicks, and submits a [`ButtonPressed`] action.
+We handle pointer events and accessibility events the same way: we check the event type, and if it's a left-click, we submit an action.
+
+Submitting an action lets Masonry that a semantically meaningful event has occurred; Masonry will call `AppDriver::on_action()` with the action before the end of the frame.
+This lets higher-level frameworks like Xilem react to UI events, like a button being pressed.
+
+Implementing `on_access_event` lets us emulate click behaviors for people using assistive technologies.
 
-We've also implemented the `on_access_event` method, which emulates the click behaviors for people using assistive technologies.
+We don't handle any text events.
 
-Next we can leave the `on_anim_frame` and `update` implementations empty:
+
+### Animation and update
+
+Since our widget isn't animated and doesn't react to changes in status, we can leave the `on_anim_frame` and `update` implementations empty:
 
 ```rust,ignore
 use masonry::{
-    UpdateCtx
+    UpdateCtx, Update,
 };
 
 impl Widget for ColorRectangle {
@@ -187,6 +141,8 @@ impl Widget for ColorRectangle {
 }
 ```
 
+### Layout
+
 Next we implement layout:
 
 ```rust,ignore
@@ -207,6 +163,8 @@ impl Widget for ColorRectangle {
 
 Our size is static, and doesn't depend on size constraints passed by our parent or context information like "the widget is currently hovered", so it can be written as a one-liner.
 
+### Render methods
+
 Next we write our render methods:
 
 ```rust,ignore
@@ -244,7 +202,7 @@ impl Widget for ColorRectangle {
 
 In our `paint` method, we're given a [`vello::Scene`] and paint a rectangle into it.
 
-The rectangle's position is zero (because coordinates in our scenes are local to our widget), and its size is `ctx.size()`, which is the value returned by `layout()`; though we could also have used `self.size`.
+The rectangle's position is zero (because coordinates in our scene are local to our widget), and its size is `ctx.size()`, which is the value returned by `layout()`; though we could also have used `self.size`.
 
 Next we define our accessibility role.
 Returning [`Role::Button`] means that screen readers will report our widget as a button, which roughly makes sense since it is clickable.
@@ -255,6 +213,8 @@ In `accessibility`, we define a default action of `Click`, which is how we regis
 
 <!-- TODO - Is that actually true? I'm not sure what set_default_action does. -->
 
+### Other methods
+
 We also write a `make_trace_span()` method, which is useful for debugging with the [tracing](https://docs.rs/tracing/latest/tracing/) framework.
 
 ```rust,ignore
@@ -291,9 +251,131 @@ impl Widget for ColorRectangle {
 
 Don't worry about what they mean for now.
 
-Finally, we want to define some setters for external users:
 
-<!-- TODO - Rewrite once we've decided how WidgetMut should be implemented. -->
+## Context arguments
+
+The methods of the [`Widget`] trait take `***Ctx` context arguments, which you can use to get information about the current widget.
+For instance, our `paint()` method used [`PaintCtx::size()`] to get the widget's size.
+The information accessible from the context argument depends on the method.
+
+### Status flags
+
+All context types have getters to check some status information:
+
+- `is_hovered()`
+- `has_pointer_capture()`
+- `is_focused()`
+- `is_disabled()`
+- `is_stashed()`
+
+See the ["Concepts and definitions"](06_masonry_concepts.md#widget-status) documentation for more information on what they mean.
+
+### Requesting passes
+
+Most passes will skip most widgets by default.
+
+For example, the animate pass will only run on widgets running an animation, and the paint pass will only call a widget's `paint` method once, after which it caches the resulting scene.
+
+If your widget's appearance is changed by another method, you need to call `ctx.request_render()` to tell the framework to re-run the paint and accessibility passes.
+
+Most context types include these methods for requesting future passes:
+
+- `request_render()`
+- `request_paint_only()`
+- `request_accessibility_update()`
+- `request_layout()`
+- `request_anim_frame()`
+
+
+### Using context in `ColorRectangle`
+
+To show how context types are used in practice, let's add a feature to `ColorRectangle`: the widget will now be painted in white when hovered.
+
+First, we need to detect hover changes. Let's re-implement the `update` method:
+
+```rust,ignore
+impl Widget for ColorRectangle {
+    // ...
+
+    fn update(&mut self, ctx: &mut UpdateCtx, event: &Update) {
+        match event {
+            Update::HoveredChanged(_) | Update::FocusChanged(_) | Update::DisabledChanged(_) => {
+                ctx.request_paint_only();
+            }
+            _ => {}
+        }
+    }
+
+    // ...
+}
+```
+
+Then, we update our paint method:
+
+```rust,ignore
+impl Widget for ColorRectangle {
+    // ...
+
+    fn paint(&mut self, ctx: &mut PaintCtx, scene: &mut Scene) {
+        let rect = ctx.size().to_rect();
+        let color = if ctx.is_hovered() {
+            Color::WHITE
+        } else {
+            self.color
+        };
+        scene.fill(
+            Fill::NonZero,
+            Affine::IDENTITY,
+            color,
+            Some(Affine::IDENTITY),
+            &rect,
+        );
+    }
+
+    // ...
+}
+```
+
+
+## Widget mutation
+
+In Masonry, widgets generally can't be mutated directly.
+That is to say, even if you own a window, and even if that window holds a widget tree with a `Label` instance, you can't get a `&mut Label` directly from that window.
+
+Instead, there are two ways to mutate `Label`:
+
+- Inside a Widget method. Most methods (`on_pointer_event`, `update`, `layout`, etc) take a `&mut self` argument.
+- Through a [`WidgetMut`] wrapper. So, to change your label's text, you will call `WidgetMut::<Label>::set_text()`. This helps Masonry make sure that internal metadata is propagated after every widget change.
+
+As mentioned in the previous chapter, a `WidgetMut` is a smart reference type to the Widget tree.
+Most Widgets will implement methods that let their users "project" a WidgetMut from a parent to its child.
+For example, `WidgetMut<Portal<MyWidget>>` has a `get_child_mut()` method that returns a `WidgetMut<MyWidget>`.
+
+So far, we've seen one way to get a WidgetMut: the [`RenderRoot::edit_root_widget()`] method.
+This methods returns a WidgetMut to the root widget, which you can then project into a WidgetMut reference to its descendants.
+
+### Using WidgetMut in your custom Widget code
+
+The WidgetMut type only has two fields, both public:
+
+```rust,ignore
+pub struct WidgetMut<'a, W: Widget> {
+    pub ctx: MutateCtx<'a>,
+    pub widget: &'a mut W,
+}
+```
+
+`W` is your widget type. `MutateCtx` is yet another context type, with methods that let you get information about your widget and report that it changed in some ways.
+
+If you want your widget to be mutable outside of its pass methods, you should write setter functions taking WidgetMut as a parameter.
+
+These functions should modify the internal values of your widget, then set flags using `MutateCtx` depending on which values changed.
+For instance, a `set_padding()` function should probably call `ctx.request_layout()`, whereas a `set_background_color()` function should probably call `ctx.request_render()` or `ctx.request_paint_only()`.
+
+
+### Mutating `ColorRectangle`
+
+Let's define some setters for `ColorRectangle`:
 
 ```rust,ignore
 struct ColorRectangle {
@@ -301,15 +383,15 @@ struct ColorRectangle {
     color: Color,
 }
 
-impl WidgetMut<'_, ColorRectangle> {
-    pub fn set_color(&mut self, color: Color) {
-        self.widget.color = color;
-        self.ctx.request_paint_only();
+impl ColorRectangle {
+    pub fn set_color(this: &mut WidgetMut<'_, Self>, color: Color) {
+        this.widget.color = color;
+        this.ctx.request_paint_only();
     }
 
-    pub fn set_size(&mut self, size: Size) {
-        self.widget.size = size;
-        self.ctx.request_layout();
+    pub fn set_size(this: &mut WidgetMut<'_, Self>, size: Size) {
+        this.widget.size = size;
+        this.ctx.request_layout();
     }
 }
 ```
diff --git a/masonry/src/doc/03_implementing_container_widget.md b/masonry/src/doc/03_implementing_container_widget.md
index 8bfed8d41..48d7e3589 100644
--- a/masonry/src/doc/03_implementing_container_widget.md
+++ b/masonry/src/doc/03_implementing_container_widget.md
@@ -198,20 +198,20 @@ Widgets will usually be added or removed through a [`WidgetMut`] wrapper.
 Let's write WidgetMut methods for our `VerticalStack`:
 
 ```rust,ignore
-impl WidgetMut<'_, VerticalStack> {
-    pub fn add_child(&mut self, child: WidgetPod<Box<dyn Widget>>) {
-        self.widget.children.push(child);
-        self.ctx.children_changed();
+impl VerticalStack {
+    pub fn add_child(this: &mut WidgetMut<'_, Self>, child: WidgetPod<Box<dyn Widget>>) {
+        this.widget.children.push(child);
+        this.ctx.children_changed();
     }
 
-    pub fn remove_child(&mut self, n: usize) {
-        self.widget.children.remove(n);
-        self.ctx.children_changed();
+    pub fn remove_child(this: &mut WidgetMut<'_, Self>, n: usize) {
+        this.widget.children.remove(n);
+        this.ctx.children_changed();
     }
 
-    pub fn clear_children(&mut self) {
-        self.widget.children.clear();
-        self.ctx.children_changed();
+    pub fn clear_children(this: &mut WidgetMut<'_, Self>) {
+        this.widget.children.clear();
+        this.ctx.children_changed();
     }
 }
 ```

From 29e044263b84ef895885a04c73b92c30abaf5461 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Fri, 10 Jan 2025 18:27:59 +0100
Subject: [PATCH 2/4] Fix doc error

---
 masonry/src/doc/02_implementing_widget.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/masonry/src/doc/02_implementing_widget.md b/masonry/src/doc/02_implementing_widget.md
index 1ca92e7f1..c1214931f 100644
--- a/masonry/src/doc/02_implementing_widget.md
+++ b/masonry/src/doc/02_implementing_widget.md
@@ -408,6 +408,7 @@ The next one is about creating a container widgets, and the complications it add
 
 [`Widget`]: crate::Widget
 [`WidgetMut`]: crate::widget::WidgetMut
+[`PaintCtx::size()`]: crate::PaintCtx::size
 [`ButtonPressed`]: crate::Action::ButtonPressed
 [`vello::Scene`]: crate::vello::Scene
 [`Role::Button`]: accesskit::Role::Button

From 7cd84e82c41c974f9e8056520ede3b78658c99d6 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Mon, 13 Jan 2025 12:42:21 +0100
Subject: [PATCH 3/4] Doc changes to adress code review

---
 masonry/src/doc/02_implementing_widget.md | 58 +++++++++++++----------
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/masonry/src/doc/02_implementing_widget.md b/masonry/src/doc/02_implementing_widget.md
index c1214931f..bd8341666 100644
--- a/masonry/src/doc/02_implementing_widget.md
+++ b/masonry/src/doc/02_implementing_widget.md
@@ -75,7 +75,7 @@ impl ColorRectangle {
 ```
 
 This widget doesn't have children and doesn't really need to keep track of any transient state, so its definition is pretty simple.
-Note that we store a size, and not a position: our widget's position is tracked by its parent.
+Note that we store a size, and not a position: our widget's position is managed by its parent.
 
 
 ### Event methods
@@ -153,15 +153,18 @@ use masonry::{
 impl Widget for ColorRectangle {
     // ...
 
-    fn layout(&mut self, _ctx: &mut LayoutCtx, _bc: &BoxConstraints) -> Size {
-        self.size
+    fn layout(&mut self, _ctx: &mut LayoutCtx, bc: &BoxConstraints) -> Size {
+        bc.contrain(self.size)
     }
 
     // ...
 }
 ```
 
-Our size is static, and doesn't depend on size constraints passed by our parent or context information like "the widget is currently hovered", so it can be written as a one-liner.
+Our size is static, and doesn't perform complex operations like line-breaking, or depend on context information like "the widget is currently hovered", so it can be written as a one-liner.
+
+`BoxConstraints` are the minimum and maximum size our parent expects this widget to respect. It's possible to ignore them, but we choose not to.
+We return our stored size, clamped between the min and max constraints.
 
 ### Render methods
 
@@ -202,7 +205,7 @@ impl Widget for ColorRectangle {
 
 In our `paint` method, we're given a [`vello::Scene`] and paint a rectangle into it.
 
-The rectangle's position is zero (because coordinates in our scene are local to our widget), and its size is `ctx.size()`, which is the value returned by `layout()`; though we could also have used `self.size`.
+The rectangle's origin is zero (because coordinates in our scene are local to our widget), and its size is `ctx.size()`, which is the value returned by `layout()`.
 
 Next we define our accessibility role.
 Returning [`Role::Button`] means that screen readers will report our widget as a button, which roughly makes sense since it is clickable.
@@ -291,26 +294,7 @@ Most context types include these methods for requesting future passes:
 
 To show how context types are used in practice, let's add a feature to `ColorRectangle`: the widget will now be painted in white when hovered.
 
-First, we need to detect hover changes. Let's re-implement the `update` method:
-
-```rust,ignore
-impl Widget for ColorRectangle {
-    // ...
-
-    fn update(&mut self, ctx: &mut UpdateCtx, event: &Update) {
-        match event {
-            Update::HoveredChanged(_) | Update::FocusChanged(_) | Update::DisabledChanged(_) => {
-                ctx.request_paint_only();
-            }
-            _ => {}
-        }
-    }
-
-    // ...
-}
-```
-
-Then, we update our paint method:
+First, we update our paint method:
 
 ```rust,ignore
 impl Widget for ColorRectangle {
@@ -336,6 +320,26 @@ impl Widget for ColorRectangle {
 }
 ```
 
+Next, we need to detect hover changes so the paint method actually gets called.
+
+Let's re-implement the `update` method:
+
+```rust,ignore
+impl Widget for ColorRectangle {
+    // ...
+
+    fn update(&mut self, ctx: &mut UpdateCtx, event: &Update) {
+        match event {
+            Update::HoveredChanged(_) => {
+                ctx.request_render();
+            }
+            _ => {}
+        }
+    }
+
+    // ...
+}
+```
 
 ## Widget mutation
 
@@ -345,7 +349,7 @@ That is to say, even if you own a window, and even if that window holds a widget
 Instead, there are two ways to mutate `Label`:
 
 - Inside a Widget method. Most methods (`on_pointer_event`, `update`, `layout`, etc) take a `&mut self` argument.
-- Through a [`WidgetMut`] wrapper. So, to change your label's text, you will call `WidgetMut::<Label>::set_text()`. This helps Masonry make sure that internal metadata is propagated after every widget change.
+- Through a [`WidgetMut`] wrapper. So, to change your label's text, you will call [`Label::set_text()`], which takes a [`WidgetMut`] argument. This helps Masonry make sure that internal metadata is propagated after every widget change.
 
 As mentioned in the previous chapter, a `WidgetMut` is a smart reference type to the Widget tree.
 Most Widgets will implement methods that let their users "project" a WidgetMut from a parent to its child.
@@ -409,7 +413,9 @@ The next one is about creating a container widgets, and the complications it add
 [`Widget`]: crate::Widget
 [`WidgetMut`]: crate::widget::WidgetMut
 [`PaintCtx::size()`]: crate::PaintCtx::size
+[`UpdateCtx::request_paint_only()`]: crate::UpdateCtx::request_paint_only
 [`ButtonPressed`]: crate::Action::ButtonPressed
 [`vello::Scene`]: crate::vello::Scene
 [`Role::Button`]: accesskit::Role::Button
 [`RenderRoot::edit_root_widget()`]: crate::RenderRoot::edit_root_widget
+[`Label::set_text()`]: crate::widget::Label::set_text

From dd370cb50347e4ab555b6404a7e2f4a03c4379d2 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Mon, 13 Jan 2025 12:45:25 +0100
Subject: [PATCH 4/4] Fix typo

---
 masonry/src/doc/02_implementing_widget.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/masonry/src/doc/02_implementing_widget.md b/masonry/src/doc/02_implementing_widget.md
index bd8341666..3519f8e75 100644
--- a/masonry/src/doc/02_implementing_widget.md
+++ b/masonry/src/doc/02_implementing_widget.md
@@ -154,7 +154,7 @@ impl Widget for ColorRectangle {
     // ...
 
     fn layout(&mut self, _ctx: &mut LayoutCtx, bc: &BoxConstraints) -> Size {
-        bc.contrain(self.size)
+        bc.constrain(self.size)
     }
 
     // ...