add clip to bound framework element extension

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

@@ -525,6 +525,9 @@
     <Compile Include="SamplePages\Eyedropper\EyedropperPage.xaml.cs">
       <DependentUpon>EyedropperPage.xaml</DependentUpon>
     </Compile>
+    <Compile Include="SamplePages\FrameworkElementExtensions.ClipToBounds\FrameworkElementExtensionsClipToBoundsPage.xaml.cs">
+      <DependentUpon>FrameworkElementExtensionsClipToBoundsPage.xaml</DependentUpon>
+    </Compile>
     <Compile Include="SamplePages\ImageEx\ImageExLazyLoadingControl.xaml.cs">
       <DependentUpon>ImageExLazyLoadingControl.xaml</DependentUpon>
     </Compile>
@@ -938,6 +941,13 @@
       <SubType>Designer</SubType>
       <Generator>MSBuild:Compile</Generator>
     </Page>
+    <Content Include="SamplePages\FrameworkElementExtensions.ClipToBounds\FrameworkElementExtensionsClipToBoundsCode.bind">
+      <SubType>Designer</SubType>
+    </Content>
+    <Page Include="SamplePages\FrameworkElementExtensions.ClipToBounds\FrameworkElementExtensionsClipToBoundsPage.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/FrameworkElementExtensions.ClipToBounds/FrameworkElementExtensionsClipToBoundsCode.bind

@@ -0,0 +1,28 @@
+<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: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>
+</Page>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/FrameworkElementExtensions.ClipToBounds/FrameworkElementExtensionsClipToBoundsPage.xaml

@@ -0,0 +1,13 @@
+<Page
+    x:Class="Microsoft.Toolkit.Uwp.SampleApp.SamplePages.FrameworkElementExtensionsClipToBoundsPage"
+    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:FrameworkElementExtensions.ClipToBounds="True"/>
+
+</Page>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/FrameworkElementExtensions.ClipToBounds/FrameworkElementExtensionsClipToBoundsPage.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 FrameworkElementExtensionsClipToBoundsPage : Page
+    {
+        public FrameworkElementExtensionsClipToBoundsPage() => 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": "FrameworkElementExtensions.ClipToBounds",
+        "Type": "FrameworkElementExtensionsClipToBoundsPage",
+        "About": "Extension to clip the FrameworkElement inner controls inside its bounds.",
+        "CodeUrl": "https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.UI/Extensions/FrameworkElement",
+        "XamlCodeFile": "FrameworkElementExtensionsClipToBoundsCode.bind",
+        "Icon": "/Assets/Helpers.png",
+        "DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/extensions/FrameworkElementExtensions.md"
+      },
       {
         "Name": "StringExtensions",
         "Type": "StringExtensionsPage",

Microsoft.Toolkit.Uwp.UI/Extensions/FrameworkElement/FrameworkElementExtensions.ClipToBounds.cs

@@ -0,0 +1,70 @@
+// 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 System.Diagnostics;
+using Windows.Foundation;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Media;
+
+namespace Microsoft.Toolkit.Uwp.UI.Extensions
+{
+    /// <summary>
+    /// Provides attached dependency properties for the <see cref="Windows.UI.Xaml.FrameworkElement"/>
+    /// </summary>
+    public static partial class FrameworkElementExtensions
+    {
+        /// <summary>
+        /// Attached <see cref="DependencyProperty"/> to activate clipping of a <see cref="FrameworkElement"/> content inside the element bounds.
+        /// </summary>
+        /// <remarks>
+        /// This property comes from WPF but is not supported natively in UWP apps.
+        /// See https://docs.microsoft.com/en-us/dotnet/api/system.windows.uielement.cliptobounds?view=netframework-4.8.
+        /// </remarks>
+        public static readonly DependencyProperty ClipToBoundsProperty = DependencyProperty.RegisterAttached(
+            "ClipToBounds",
+            typeof(bool),
+            typeof(FrameworkElementExtensions),
+            new PropertyMetadata(false, OnClipToBoundsPropertyChanged));
+
+        /// <summary>
+        /// Get the value of <see cref="ClipToBoundsProperty"/>.
+        /// </summary>
+        /// <param name="obj">The object that will host the value.</param>
+        /// <returns>The property value. <see cref="ClipToBoundsProperty"/>.</returns>
+        public static bool GetClipToBounds(DependencyObject obj) => (bool)obj.GetValue(ClipToBoundsProperty);
+
+        /// <summary>
+        /// Set the value of <see cref="ClipToBoundsProperty"/>.
+        /// </summary>
+        /// <param name="obj">The target object where to store the value.</param>
+        /// <param name="value">The value to store.</param>
+        public static void SetClipToBounds(DependencyObject obj, bool value) => obj.SetValue(ClipToBoundsProperty, value);
+
+        private static void OnClipToBoundsPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+        {
+            var element = d as FrameworkElement;
+            Debug.Assert(element != null, "Property should only be attached to FrameworkElement");
+
+            void OnSizeChanged(object sender, SizeChangedEventArgs sizeChangedEventArgs) => UpdateClipToBounds(element);
+
+            var newValue = (bool)e.NewValue;
+            if (newValue)
+            {
+                element.SizeChanged += OnSizeChanged;
+                UpdateClipToBounds(element);
+            }
+            else
+            {
+                element.SizeChanged -= OnSizeChanged;
+                element.Clip = null;
+            }
+        }
+
+        private static void UpdateClipToBounds(FrameworkElement element)
+            => element.Clip = new RectangleGeometry
+            {
+                Rect = new Rect(0, 0, element.ActualWidth, element.ActualHeight),
+            };
+    }
+}