UIElement.ClipToBounds property

Microsoft.Toolkit.Uwp.SampleApp/Microsoft.Toolkit.Uwp.SampleApp.csproj

@@ -512,6 +512,9 @@
     <Compile Include="SamplePages\Eyedropper\EyedropperPage.xaml.cs">
       <DependentUpon>EyedropperPage.xaml</DependentUpon>
     </Compile>
+    <Compile Include="SamplePages\ClipToBounds\ClipToBoundsPage.xaml.cs">
+      <DependentUpon>ClipToBoundsPage.xaml</DependentUpon>
+    </Compile>
     <Compile Include="SamplePages\ImageEx\ImageExLazyLoadingControl.xaml.cs">
       <DependentUpon>ImageExLazyLoadingControl.xaml</DependentUpon>
     </Compile>
@@ -925,6 +928,13 @@
       <SubType>Designer</SubType>
       <Generator>MSBuild:Compile</Generator>
     </Page>
+    <Content Include="SamplePages\ClipToBounds\ClipToBoundsCode.bind">
+      <SubType>Designer</SubType>
+    </Content>
+    <Page Include="SamplePages\ClipToBounds\ClipToBoundsPage.xaml">
+      <SubType>Designer</SubType>
+      <Generator>MSBuild:Compile</Generator>
+    </Page>
     <Page Include="SamplePages\ImageEx\ImageExLazyLoadingControl.xaml">
       <SubType>Designer</SubType>
       <Generator>MSBuild:Compile</Generator>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/ClipToBounds/ClipToBoundsCode.bind

@@ -0,0 +1,29 @@
+<Page
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:extensions="using:Microsoft.Toolkit.Uwp.UI.Extensions"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d">
+
+  <Grid Padding="120">
+    <Grid
+        BorderBrush="White"
+        BorderThickness="1"
+        Width="148"
+        Height="148"
+        extensions:UIElementExtensions.ClipToBounds="@[Clip to Bounds:Bool:True]">
+      <!-- We translate the inner rectangles outside of the bounds of the container. -->
+      <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>
+</Page>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/ClipToBounds/ClipToBoundsPage.xaml

@@ -0,0 +1,13 @@
+<Page
+    x:Class="Microsoft.Toolkit.Uwp.SampleApp.SamplePages.ClipToBoundsPage"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:extensions="using:Microsoft.Toolkit.Uwp.UI.Extensions"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d">
+
+    <Grid x:Name="TargetObject"
+        extensions:UIElementExtensions.ClipToBounds="True"/>
+
+</Page>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/ClipToBounds/ClipToBoundsPage.xaml.cs

@@ -0,0 +1,16 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Windows.UI.Xaml.Controls;
+
+namespace Microsoft.Toolkit.Uwp.SampleApp.SamplePages
+{
+    /// <summary>
+    /// A page that shows how to use the ClipToBounds extension.
+    /// </summary>
+    public sealed partial class ClipToBoundsPage : Page
+    {
+        public ClipToBoundsPage() => InitializeComponent();
+    }
+}

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/samples.json

@@ -1069,6 +1069,15 @@
         "Icon": "/Assets/Helpers.png",
         "DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/extensions/FrameworkElementExtensions.md"
       },
+      {
+        "Name": "ClipToBounds",
+        "Type": "ClipToBoundsPage",
+        "About": "Extension to clip the UIElement inner controls inside its bounds.",
+        "CodeUrl": "https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.UI/Extensions/FrameworkElement",
+        "XamlCodeFile": "ClipToBoundsCode.bind",
+        "Icon": "/Assets/Helpers.png",
+        "DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/extensions/UIElementExtensions.md"
+      },
       {
         "Name": "StringExtensions",
         "Type": "StringExtensionsPage",

Microsoft.Toolkit.Uwp.UI/Extensions/UIElement/UIElementExtensions.cs

@@ -0,0 +1,51 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Hosting;
+
+namespace Microsoft.Toolkit.Uwp.UI.Extensions
+{
+    /// <summary>
+    /// Provides attached dependency properties for the <see cref="Windows.UI.Xaml.UIElement"/>
+    /// </summary>
+    public static class UIElementExtensions
+    {
+        /// <summary>
+        /// Attached <see cref="DependencyProperty"/> that indicates whether or not the contents of the target <see cref="UIElement"/> should always be clipped to their parent's bounds.
+        /// </summary>
+        public static readonly DependencyProperty ClipToBoundsProperty = DependencyProperty.RegisterAttached(
+            "ClipToBounds",
+            typeof(bool),
+            typeof(UIElementExtensions),
+            new PropertyMetadata(DependencyProperty.UnsetValue, OnClipToBoundsPropertyChanged));
+
+        /// <summary>
+        /// Gets the value of <see cref="ClipToBoundsProperty"/>
+        /// </summary>
+        /// <param name="element">The <see cref="UIElement"/> to read the property value from</param>
+        /// <returns>The <see cref="bool"/> associated with the <see cref="FrameworkElement"/></returns>.
+        public static bool GetClipToBounds(UIElement element) => (bool)element.GetValue(ClipToBoundsProperty);
+
+        /// <summary>
+        /// Sets the value of <see cref="ClipToBoundsProperty"/>
+        /// </summary>
+        /// <param name="element">The <see cref="UIElement"/> to set the property to</param>
+        /// <param name="value">The new value of the attached property</param>
+        public static void SetClipToBounds(UIElement element, bool value) => element.SetValue(ClipToBoundsProperty, value);
+
+        private static void OnClipToBoundsPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+        {
+            var element = d as UIElement;
+            if (element is null)
+            {
+                return;
+            }
+
+            var clipToBounds = (bool)e.NewValue;
+            var visual = ElementCompositionPreview.GetElementVisual(element);
+            visual.Clip = clipToBounds ? visual.Compositor.CreateInsetClip() : null;
+        }
+    }
+}