UIElement.ClipToBounds property

[Sergio0694]

This PR is part of the group being tracked in #3108.

PR Type

What kind of change does this PR introduce?

• Feature

What is the new behavior?

A XAML attached property that uses a composition InsetClip to clip the rendering coming from inside a given UIElement. All additional info can be found in the linked issue.

PR Checklist

Please check if your PR fulfills the following requirements:

• Tested code with current supported SDKs
• Pull Request has been submitted to the documentation repository instructions. Link:
• Sample in sample app has been added / updated (for bug fixes / features)
  • Icon has been created (if new sample) following the Thumbnail Style Guide and templates
• Tests for the changes have been added (for bug fixes / features) (if applicable)
• Header has been added to all new source files (run build/UpdateHeaders.bat)
• Contains NO breaking changes

Other information

Marking this as draft since I haven't created the PR for the docs yet, or added a sample in the app.

[ghost]

Thanks for opening a Pull Request! The reviewers will test the PR and highlight if there is any conflict or changes required. If the PR is approved we will proceed to merge the pull request 🙌

[michael-hawker]

Looks fine, but I think similar to the actual InsetClip docs themselves, I'm not really sure what to do with it. It'd be great for the docs to go with this had some examples (and some images) of how this can be used effectively.

Does the inside InsetClip that gets created need any of it's properties exposed? Should we expose it in another attached property or something?

[Sergio0694]

@michael-hawker If we want to create a sample app, and example of the visualization could be to have an item contained in some parent (eg. a Grid) with a looping scale transform animation. Users could toggle this InsetClip on and off and see the item either escaping the bounds of its parent, or get clipped when the attached property is enabled. Eg. I use this in Legere for my custom frame animations (they're not really frames): I'm using a composition animation to fade the content of a page away and back in when you navigate, and I'm using this property to clip the parent control so that the content doesn't bleed outside in the shell during the animation. I personally find this quite a handy property, as the alternative is to use the old XAML geometry clip, which requires you to listen to the SizeChanged event to update the size of the clipping rectangle.

As for additional properties, yeah, the InsetClip has the Top, Bottom, Left and RightInset properties. We could probably expose them too through another attached property of type Thickness, if we wanted, why not! I can give that a try if you want! 😊

[vgromfeld]

@Sergio0694 , I have a sample ready for the ClipToBounds property.
I was working on the same property and left it aside when I've seen your PR. I can still add my old sample to your PR if you agree:

  <Grid Padding="120">
    <Grid
        BorderBrush="White"
        BorderThickness="1"
        Width="148"
        Height="148"
        extensions:FrameworkElementExtensions.ClipToBounds="@[Clip to Bounds:Bool:True]">
      <Rectangle Fill="Blue" Width="100" Height="100">
        <Rectangle.RenderTransform>
          <TranslateTransform X="-50" Y="-50" />
        </Rectangle.RenderTransform>
      </Rectangle>
      <Rectangle Fill="Green" Width="100" Height="100">
        <Rectangle.RenderTransform>
          <TranslateTransform X="50" Y="50" />
        </Rectangle.RenderTransform>
      </Rectangle>
    </Grid>
  </Grid>

[Sergio0694]

Hey @vgromfeld - that'd be perfect, thank you!

I had quite a few things going on at the moment so I couldn't get to writing the sample down for this PR yet, so that'd help! Other than that I guess we should just decide whether to leave this extension as is or to also add some way for users to specifically set the exact margins (like @michael-hawker mentioned a while back), and then this PR should be good to go and ready for review 😄

[Sergio0694]

Closing this to continue the work in #3193 then 👍