UI Scrolling

[Piefayth]

Objective

• Fixes Support scrollable UI nodes (Overflow::Scroll?) #8074
• Adopts / Supersedes WIP: Support scrolling (Overflow::Scroll) in bevy_ui #8104

Solution

Adapted from #8104 and affords the same benefits.

Additions

• Update scrolling on relayout (height of node or contents may have changed)
• Make ScrollPosition component optional for ui nodes to avoid checking every node on scroll
• Nested scrollviews

Omissions

• Removed input handling for scrolling from bevy_ui. Users should update ScrollPosition directly.

Implementation

Adds a new ScrollPosition component. Updating this component on a Node with an overflow axis set to OverflowAxis::Scroll will reposition its children by that amount when calculating node transforms. As before, no impact on the underlying Taffy layout.

Calculating this correctly is trickier than it was in #8104 due to "Update scrolling on relayout".

Background

When ScrollPosition is updated directly by the user, it can be trivially handled in-engine by adding the parent's scroll position to the final location of each child node. However, other layout actions may result in a situation where ScrollPosition needs to be updated. Consider a 1000 pixel tall vertically scrolling list of 100 elements, each 100 pixels tall. Scrolled to the bottom, the ScrollPosition.offset_y is 9000, just enough to display the last element in the list. When removing an element from that list, the new desired ScrollPosition.offset_y is 8900, but, critically, that is not known until after the sizes and positions of the children of the scrollable node are resolved.

All user scrolling code today handles this by delaying the resolution by one frame. One notable disadvantage of this is the inability to support WinitSettings::desktop_app(), since there would need to be an input AFTER the layout change that caused the scroll position to update for the results of the scroll position update to render visually.

I propose the alternative in this PR, which allows for same-frame resolution of scrolling layout.

Resolution

When recursively iterating the children of a node, each child now returns a Vec2 representing the location of their own bottom right corner. Then, [[0,0, [x,y]] represents a bounding box containing the scrollable area filled by that child. Scrollable parents aggregate those areas into the bounding box of all children, then consider that result against ScrollPosition to ensure its validity.

In the event that resolution of the layout of the children invalidates the ScrollPosition (e.g. scrolled further than there were children to scroll to), all children of that node must be recursively repositioned. The position of each child must change as a result of the change in scroll position.

Therefore, this implementation takes care to only spend the cost of the "second layout pass" when a specific node actually had a ScrollPosition forcibly updated by the layout of its children.

Luckily, this is exactly what Taffy's Layout::content_size does. So we use it here to avoid this "second pass" entirely!

Testing

Examples in ui/scroll.rs. There may be more complex node/style interactions that were unconsidered.

---

Showcase

Alternatives

• bevy_ui doesn't support scrolling.
• bevy_ui implements scrolling with a one-frame delay on reactions to layout changes.

[alice-i-cecile]

These docs should clearly describe the units.

[alice-i-cecile]

A bit more context about how this is used would be nice.

[alice-i-cecile]

Suggested change

//!

[alice-i-cecile]

Really pleased to see this adopted, and this is looking good. Just a few small suggestions.

[alice-i-cecile]

Shouldn't this 20 scale factor be pulled out into a constant and used for the font size?

[Piefayth]

Well, we won't get perfectly 20 pixel tall text out of that anyway. But what I DID do was define it as LINE_HEIGHT and force the scrolled children in the vertical scroll example to be exactly that height.

Great idea!!

[ickshonpe]

Agree that a one-frame delay is completely unacceptable. I'm worried that the changes here introduce too much unnecessary extra complexity to ui_layout_system though and I really don't like having to query for Style again in the update_uinode_geometry_recursive function.

I've not gone through the PR in detail though, maybe there's no other way. I'll try and find time to take a longer look this weekend or on Monday.

[Piefayth]

Agree that a one-frame delay is completely unacceptable. I'm worried that the changes here introduce too much unnecessary extra complexity to ui_layout_system though and I really don't like having to query for Style again in the update_uinode_geometry_recursive function.

I've not gone through the PR in detail though, maybe there's no other way. I'll try and find time to take a longer look this weekend or on Monday.

Cool, we are aligned. I've greatly reduced the complexity thanks to @nicoburns.

Regarding Style, I did find that one of my usages of it was extraneous / leftover from my work in progress. So all I use it for now is to force the local scroll_position to zero if that axis isn't set to OverflowAxis::Scroll. This could alternatively be accomplished by moving that logic to a separate system that validates and sanitizes the actual ScrollPosition component before layout runs.

[nicoburns]

This logic seems correct and necessary to me, but perhaps is_scrollable in each axis could be copied somewhere else ahead of time if accessing Style here is undesirable.

[alice-i-cecile]

Much simpler. Good recommendations @nicoburns!

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1693 if you'd like to help out.