Objective

Limited implementation of the CSS property overflow-clip-margin
https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-clip-margin

Allows you to control the visible area for clipped content when using overfllow-clip, -hidden, or -scroll and expand it with a margin.

Based on #15442

Fixes #15468

Solution

Adds a new field to Style: overflow_clip_margin: OverflowClipMargin.
The field is ignored unless overflow-clip, -hidden or -scroll is set on at least one axis.

OverflowClipMargin has these associated constructor functions:

pub const fn content_box() -> Self;
pub const fn padding_box() -> Self;
pub const fn border_box() -> Self;

You can also use the method with_margin to increases the size of the visible area:

commands
  .spawn(NodeBundle {
      style: Style {
          width: Val::Px(100.),
          height: Val::Px(100.),
          padding: UiRect::all(Val::Px(20.)),
          border: UiRect::all(Val::Px(5.)),
          overflow: Overflow::clip(),
          overflow_clip_margin: OverflowClipMargin::border_box().with_margin(25.),
          ..Default::default()
      },
      border_color: Color::BLACK.into(),
      background_color: GRAY.into(),
      ..Default::default()
  })

with_margin expects a length in logical pixels, negative values are clamped to zero.

Notes

• To keep this PR as simple as possible I omitted responsive margin values support. This could be added in a follow up if we want it.
• CSS also supports a margin-box option but we don't have access to the margin values in Node so it's probably not feasible to implement atm.

Testing

cargo run --example overflow_clip_margin

Migration Guide

Style has a new field OverflowClipMargin. It allows users to set the visible area for clipped content when using overflow-clip, -hidden, or -scroll and expand it with a margin.

There are three associated constructor functions content_box, padding_box and border_box:

• content_box: elements painted outside of the content box area (the innermost part of the node excluding the padding and border) of the node are clipped. This is the new default behaviour.
• padding_box: elements painted outside outside of the padding area of the node are clipped.
• border_box: elements painted outside of the bounds of the node are clipped. This matches the behaviour from Bevy 0.14.

There is also a with_margin method that increases the size of the visible area by the given number in logical pixels, negative margin values are clamped to zero.

OverflowClipMargin is ignored unless overflow-clip, -hidden or -scroll is also set on at least one axis of the UI node.