Pass Specification #7

PoignardAzur · 2024-07-15T12:56:51Z

Formally define the semantics of the passes that Masonry runs in its event loop.

DJMcNab

I think this does significantly clarify the architecture.

The area I think needs a lot more clarification is the exact role distribution between layout and compose. I nebulously understand it, but didn't find it very clear in the text here

DJMcNab · 2024-07-15T13:33:56Z

rfcs/0007-pass-spec.md

+
+The **MUTATE** pass runs a list of callbacks with mutable access to the widget tree.
+These callbacks can be queued with the `mutate_later()` method of various context types.
+


Does this pass also run the driver, with any action from the event handler?

For now the assumption is that the RenderRoot isn't aware of the driver.

So the template for any interaction is "the platform runs a RenderRoot method, which triggers a bunch of passes, which produce a list of signals, and the platform interprets these signals how it sees fit, potentially running the driver and/or re-running the passes".

rfcs/0007-pass-spec.md

DJMcNab · 2024-07-15T13:44:52Z

rfcs/0007-pass-spec.md

+#### Compose pass
+
+The **compose** pass runs top-down and assigns transforms to children.
+Transform-only layout changes (e.g. scrolling) should request compose instead of requesting layout.


Would compose have the possibility of stashing child widgets, e.g. if they scroll off-screen.
Would that require a mutate pass to be ran?

Stashing in the sense it's currently used in the codebase still isn't implemented or documented.

Short answer is "compose could trigger a stash but it probably shouldn't".

Would that require a mutate pass to be ran?

No, because stashing doesn't change the tree structure. A stashed widget still has the same parent, a parent with stashed children still lists them as children, etc.

rfcs/0007-pass-spec.md

Co-authored-by: Daniel McNab <[email protected]>

PoignardAzur · 2024-08-02T14:52:01Z

The area I think needs a lot more clarification is the exact role distribution between layout and compose. I nebulously understand it, but didn't find it very clear in the text here

I added a paragraph to try and explain it.

Philipp-M · 2024-08-12T00:54:05Z

rfcs/0007-pass-spec.md

+#### Compose pass
+
+The **compose** pass runs top-down and assigns transforms to children.
+Transform-only layout changes (e.g. scrolling) should request compose instead of requesting layout.
+
+Compose is meant to be a cheaper way to position widgets than layout.
+Because the compose pass is more limited than layout, it's easier to recompute in many situations.
+
+For instance, if a widget in a list changes size, its siblings and parents must be re-laid out to account for the change; whereas changing a given widget's transform only affects its children.
+
+Masonry automatically calls the `compose` methods of all widgets in the tree, in depth-first preorder, where child order is determined by their position in the `children_ids()` array.


I actually hope, we can design layout in a way that this is not really necessary (e.g. by dirty tracking via the flags and only recalculating the path that is affected by this). It would be really nice if we could (unlike in the web) make layout changes really interactive, e.g. data-driven animations etc. (which I think would play nice with Xilem) But I'm no expert with layouting algorithms, so I'm not really sure...

But I guess this is mostly meant to be a more general pass than ParentWindowOrigin

Incremental layout is the goal, and there are ways to implement it, but it's not trivial. Some layout change must update sibling widgets.

For instance, if you have a widget defined as "be as wide as my widest widest child", if one of the children gets much wider, then all its siblings will have more available space and need to be re-laid out.

One of the things I'd like to implement is flags that deliberately rules out those cases, eg a flag a widget can set to say "my layout is independent from the layout of my children". Or "my height is only dependent on available width, no available height".

In any case, that's beyond this PR.

Philipp-M · 2024-08-12T00:54:10Z

rfcs/0007-pass-spec.md

+- Display passes should be pure and can be skipped occasionally, therefore their context types (`PaintCtx` and `AccessCtx`) can't set invalidation flags or send signals.
+- The `layout` and `compose` passes lay out all widgets, which are transiently invalid during the passes, therefore `LayoutCtx`and `ComposeCtx` cannot access the size and position of the `self` widget.
+They can access the layout of children if they have already been laid out.
+- For the same reason reason, `LayoutCtx`and `ComposeCtx` cannot create a `WidgetRef` reference to a child.


Suggested change

- For the same reason reason, `LayoutCtx`and `ComposeCtx` cannot create a `WidgetRef` reference to a child.

- For the same reason, `LayoutCtx`and `ComposeCtx` cannot create a `WidgetRef` reference to a child.

Philipp-M · 2024-08-12T00:54:17Z

rfcs/0007-pass-spec.md

+Instead, widgets should be created and added to the widget tree as a single atomic operation.
+To keep the WidgetPod logic simple and avoid too many corner cases, this is only allowed inside the MUTATE pass.


I wonder how that will look like in practice?
I.e. with different constructors for different kind of widgets.
so is something like this still valid (more pseudocode, this is wrong of course):

let button = Button::new(..); // later e.g. for a flex flex_widget.insert_flex_child_pod(button);

Or how should that roughly look like?
Is the constructor for a widget just a data container, and gets properly constructed when adding that child to whatever widget it contains?

(But the general idea sounds good)

Yeah, we're still trying to figure that out.

See this discussion on zulip.

Philipp-M · 2024-08-12T00:54:23Z

rfcs/0007-pass-spec.md

+Instead, widgets should be created and added to the widget tree as a single atomic operation.
+To keep the WidgetPod logic simple and avoid too many corner cases, this is only allowed inside the MUTATE pass.
+
+`MutateCtx` should have an `add_child` and a `remove_child` method. 


I wonder how moving a child from A -> B can be modeled (as mentioned in the explicit-identity zulip topic), so that ideally properties where it makes sense can be animated.

Yeah, there's a reason "Reparenting children" is in future possibilities.

FWIW, I favor something like the View Transition API.

rfcs/0007-pass-spec.md

This is a first step in implementing the "Pass Specification" RFC: linebender/rfcs#7 Create a `passes` module. Create event passes. Create the update_pointer pass. Remove `WidgetPod::update_hot_state` method. Move mouse-cursor-handling code to update_pointer pass. Implement pointer capture. Refactor the TreeArena code. --------- Co-authored-by: Daniel McNab <[email protected]>

Philipp-M · 2024-08-13T19:29:35Z

rfcs/0007-pass-spec.md

+To avoid infinite loops in those cases, the number of reruns has a static limit.
+If passes are still requested past that limit, they're delayed to a later frame.


I guess that's relevant for frame-pacing, would it make sense to instead use a max duration limit (possibly relevant for layout too)?
(infinite-loop detection would be even better I guess, but that's out of scope for now I guess)

The reason for this design is that the only infinite loops would be pathological cases, and we expect any reasonable scene to only require 2 or maybe 3 cycles. That is, it's a bug in your app if you hit this fallback, so it's not a problem to have it present.

This is part of the "Pass Specification" RFC: linebender/rfcs#7 Rename WidgetCtx to MutateCtx. Add a mutate pass. Add a `mutate_later` context method to trigger that pass. Refactor `edit_root_widget` to use a version of that pass. Add a separate constructor for the synthetic WidgetState created in RenderRoot.

This is part of the "Pass Specification" RFC: linebender/rfcs#7 Rename WidgetCtx to MutateCtx. Add a mutate pass. Add a `mutate_later` context method to trigger that pass. Refactor `edit_root_widget` to use a version of that pass. Add a separate constructor for the synthetic WidgetState created in RenderRoot. --------- Co-authored-by: Philipp Mildenberger <[email protected]> Co-authored-by: Daniel McNab <[email protected]>

This is part of the Pass Specification RFC: linebender/rfcs#7 Note: This PRs comes with a lot of new TODO items. Addressing most of these items is difficult without major refactors, because Portal code deals with accessing values across multiple widgets, which is still hard to do elegantly.

This is part of the Pass Specification RFC: linebender/rfcs#7 --------- Co-authored-by: Daniel McNab <[email protected]>

Make Textbox Widget tab-focusable. This is part of the Pass Specification RFC: linebender/rfcs#7

PoignardAzur · 2024-10-06T13:25:31Z

This RFC is now in its quasi-final state. I'd like to flesh out the "prior art" part, but finding documentation on GUI frameworks' internals is still really hard.

Other than that, I think the current text of the RFC reflects how we've implemented things, and future work outside of its scope won't need to refer to this document.

PoignardAzur added 2 commits July 15, 2024 14:56

Add "pass spec" RFC

94a6c50

Attribute PR number to pass-spec RFC.

5601009

PoignardAzur marked this pull request as draft July 15, 2024 12:57

Fix pass spec typos

a812197

DJMcNab changed the title ~~Add "pass spec" RFC~~ Pass Specification Jul 15, 2024

DJMcNab reviewed Jul 15, 2024

View reviewed changes

Fix typo in code example

c0e7df3

Co-authored-by: Daniel McNab <[email protected]>

DJMcNab mentioned this pull request Jul 29, 2024

Calculator example: jumpy relayout and panic when changing window size on macOS linebender/xilem#455

Open

PoignardAzur added 2 commits August 2, 2024 16:36

Tweak pass spec RFC to address review comments.

39d5494

Clarify compose pass.

6b951be

DJMcNab mentioned this pull request Aug 5, 2024

Run tests in CI, and fix fonts for snapshot testing linebender/xilem#233

Merged

Philipp-M reviewed Aug 12, 2024

View reviewed changes

Small fixes

dba8cc1

PoignardAzur mentioned this pull request Aug 12, 2024

Implement event and update_pointer passes from pass spec RFC linebender/xilem#488

Merged

PoignardAzur mentioned this pull request Aug 13, 2024

Implement mutate pass from pass spec RFC linebender/xilem#510

Merged

Philipp-M reviewed Aug 13, 2024

View reviewed changes

DJMcNab mentioned this pull request Aug 26, 2024

Implement update_anim pass linebender/xilem#539

Merged

This was referenced Aug 30, 2024

Implement update_scrolls pass linebender/xilem#550

Merged

Implement update_focus pass linebender/xilem#538

Merged

github-merge-queue bot pushed a commit to linebender/xilem that referenced this pull request Sep 12, 2024

Implement update_anim pass (#539)

2fa8a05

This is part of the Pass Specification RFC: linebender/rfcs#7 --------- Co-authored-by: Daniel McNab <[email protected]>

github-merge-queue bot pushed a commit to linebender/xilem that referenced this pull request Sep 12, 2024

Implement update_focus pass (#538)

4746766

Make Textbox Widget tab-focusable. This is part of the Pass Specification RFC: linebender/rfcs#7

DJMcNab mentioned this pull request Sep 19, 2024

Run the focus pass in post-processing for all events linebender/xilem#604

Merged

Rework RFC to include recent changes

153c69a

PoignardAzur marked this pull request as ready for review October 6, 2024 13:23

PoignardAzur requested a review from Philipp-M October 6, 2024 13:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Pass Specification #7

Pass Specification #7

PoignardAzur commented Jul 15, 2024 •

edited by DJMcNab

Loading

DJMcNab left a comment •

edited

Loading

DJMcNab Jul 15, 2024

PoignardAzur Aug 2, 2024

DJMcNab Jul 15, 2024

PoignardAzur Jul 15, 2024 •

edited

Loading

PoignardAzur commented Aug 2, 2024

Philipp-M Aug 12, 2024

PoignardAzur Aug 12, 2024

Philipp-M Aug 12, 2024

Philipp-M Aug 12, 2024

PoignardAzur Aug 12, 2024

Philipp-M Aug 12, 2024

PoignardAzur Aug 12, 2024

Philipp-M Aug 13, 2024

DJMcNab Aug 14, 2024

PoignardAzur commented Oct 6, 2024


		The MUTATE pass runs a list of callbacks with mutable access to the widget tree.
		These callbacks can be queued with the `mutate_later()` method of various context types.

	- For the same reason reason, `LayoutCtx`and `ComposeCtx` cannot create a `WidgetRef` reference to a child.
	- For the same reason, `LayoutCtx`and `ComposeCtx` cannot create a `WidgetRef` reference to a child.

		Instead, widgets should be created and added to the widget tree as a single atomic operation.
		To keep the WidgetPod logic simple and avoid too many corner cases, this is only allowed inside the MUTATE pass.

		To avoid infinite loops in those cases, the number of reruns has a static limit.
		If passes are still requested past that limit, they're delayed to a later frame.

Pass Specification #7

Are you sure you want to change the base?

Pass Specification #7

Conversation

PoignardAzur commented Jul 15, 2024 • edited by DJMcNab Loading

DJMcNab left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PoignardAzur Jul 15, 2024 • edited Loading

Choose a reason for hiding this comment

PoignardAzur commented Aug 2, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PoignardAzur commented Oct 6, 2024

PoignardAzur commented Jul 15, 2024 •

edited by DJMcNab

Loading

DJMcNab left a comment •

edited

Loading

PoignardAzur Jul 15, 2024 •

edited

Loading