Fix issues with XML documentation for new shadows feature

Author: michael-hawker

Microsoft.Toolkit.Uwp.UI.Media/Shadows/AttachedCardShadow.cs

@@ -5,13 +5,18 @@
 using System.Numerics;
 using Microsoft.Graphics.Canvas.Geometry;
 using Windows.Foundation;
-using Windows.Foundation.Metadata;
 using Windows.UI;
 using Windows.UI.Composition;
 using Windows.UI.Xaml;
 
 namespace Microsoft.Toolkit.Uwp.UI.Media
 {
+    /// <summary>
+    /// A performant rectangular <see cref="DropShadow"/> which can be attached to any <see cref="FrameworkElement"/>. It uses Win2D to create a clipped area of the outline of the element such that transparent elements don't see the shadow below them, and the shadow can be attached without having to project to another surface. It is animatable, can be shared via a resource, and used in a <see cref="Style"/>.
+    /// </summary>
+    /// <remarks>
+    /// This shadow will not work on <see cref="FrameworkElement"/> which is directly clipping to its bounds (e.g. a <see cref="Windows.UI.Xaml.Controls.Border"/> using a <see cref="Windows.UI.Xaml.Controls.Control.CornerRadius"/>). An extra <see cref="Windows.UI.Xaml.Controls.Border"/> can instead be applied around the clipped border with the Shadow to create the desired effect. Most existing controls due to how they're templated will not encounter this behavior or require this workaround.
+    /// </remarks>
     public class AttachedCardShadow : AttachedShadowBase
     {
         private const float MaxBlurRadius = 72;
@@ -109,6 +114,12 @@ protected override CompositionBrush GetShadowMask(AttachedShadowElementContext c
         /// <inheritdoc/>
         protected override CompositionClip GetShadowClip(AttachedShadowElementContext context)
         {
+            // The way this shadow works without the need to project on another element is because
+            // we're clipping the inner part of the shadow which would be cast on the element
+            // itself away. This method is creating an outline so that we are only showing the
+            // parts of the shadow that are outside the element's context.
+            // Note: This does cause an issue if the element does clip itself to its bounds, as then
+            // the shadowed area is clipped as well.
             var pathGeom = context.GetResource(PathGeometryResourceKey) ??
                            context.AddResource(PathGeometryResourceKey, context.Compositor.CreatePathGeometry());
             var clip = context.GetResource(ClipResourceKey) ?? context.AddResource(ClipResourceKey, context.Compositor.CreateGeometricClip(pathGeom));

Microsoft.Toolkit.Uwp.UI.Media/Shadows/AttachedShadowBaseWithOpacityMask.cs

@@ -1,3 +1,7 @@
+// 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;
 using System.Collections.Generic;
 using System.Linq;
@@ -27,12 +31,6 @@ public class AttachedDropShadow : AttachedShadowBase
         /// <inheritdoc/>
         protected internal override bool SupportsOnSizeChangedEvent => true;
 
-        private static readonly TypedResourceKey<ContainerVisual> ShadowContainerResourceKey = "ShadowContainer";
-
-        private static readonly TypedResourceKey<CompositionPathGeometry> PathGeometryResourceKey = "PathGeometry";
-        private static readonly TypedResourceKey<CompositionRoundedRectangleGeometry> RectangleGeometryResourceKey = "RectGeometry";
-        private static readonly TypedResourceKey<CompositionGeometricClip> ClipResourceKey = "Clip";
-
         private static readonly TypedResourceKey<CompositionRoundedRectangleGeometry> RoundedRectangleGeometryResourceKey = "RoundedGeometry";
         private static readonly TypedResourceKey<CompositionSpriteShape> ShapeResourceKey = "Shape";
         private static readonly TypedResourceKey<ShapeVisual> ShapeVisualResourceKey = "ShapeVisual";
@@ -277,43 +275,6 @@ private void CustomMaskedElement_Loaded(object sender, RoutedEventArgs e)
             UpdateShadowMask(context);
         }
 
-        /// <inheritdoc/>
-        /*protected override CompositionClip GetShadowClip(AttachedShadowElementContext context)
-        {
-            var rectGeom = context.GetResource(RectangleGeometryResourceKey) ??
-               context.AddResource(RectangleGeometryResourceKey, context.Compositor.CreateRoundedRectangleGeometry());
-
-            rectGeom.Offset = Offset.ToVector2();
-            rectGeom.Size = new Vector2((float)context.Element.ActualWidth, (float)context.Element.ActualHeight);
-            rectGeom.CornerRadius = new Vector2((float)CornerRadius, (float)CornerRadius);
-
-            var clip = context.GetResource(ClipResourceKey) ?? context.AddResource(ClipResourceKey, context.Compositor.CreateGeometricClip(rectGeom));
-
-            return clip;*/
-
-            /*var pathGeom = context.GetResource(PathGeometryResourceKey) ??
-               context.AddResource(PathGeometryResourceKey, context.Compositor.CreatePathGeometry());
-
-            // Create rounded rectangle geometry at a larger size that compensates for the size of the stroke,
-            // as we want the inside edge of the stroke to match the edges of the element.
-            // Additionally, the inside edge of the stroke will have a smaller radius than the radius we specified.
-            // Using "(StrokeThickness / 2) + Radius" as our rectangle's radius will give us an inside stroke radius that matches the radius we want.
-            var radius = (MaxBlurRadius / 2) + (float)CornerRadius;
-            var canvasRectangle = context.Compositor.CreateRoundedRectangleGeometry();
-            canvasRectangle.Offset = new Vector2(-MaxBlurRadius / 2, -MaxBlurRadius / 2);
-            canvasRectangle.Size = new Vector2((float)context.Element.ActualWidth + MaxBlurRadius, (float)context.Element.ActualHeight + MaxBlurRadius);
-            canvasRectangle.CornerRadius = new Vector2(radius, radius);
-
-            var rectangleShape = context.Compositor.CreateSpriteShape(canvasRectangle);
-            rectangleShape.StrokeThickness = MaxBlurRadius;
-
-            var clip = context.GetResource(ClipResourceKey) ?? context.AddResource(ClipResourceKey, context.Compositor.CreateGeometricClip(rectangleShape.Geometry));
-
-            return clip;*/
-
-////            return null;
-        ////}
-
         /// <inheritdoc/>
         protected internal override void OnSizeChanged(AttachedShadowElementContext context, Size newSize, Size previousSize)
         {
@@ -336,13 +297,13 @@ protected override void OnPropertyChanged(AttachedShadowElementContext context,
             }
             else if (property == CornerRadiusProperty)
             {
-                //var geometry = context.GetResource(RectangleGeometryResourceKey);
-                //if (geometry != null)
-                //{
-                //    geometry.CornerRadius = new Vector2((float)(double)newValue);
-                //}
+                var geometry = context.GetResource(RoundedRectangleGeometryResourceKey);
+                if (geometry != null)
+                {
+                    geometry.CornerRadius = new Vector2((float)(double)newValue);
+                }
 
-                UpdateShadowClip(context);
+                UpdateShadowMask(context);
             }
             else
             {

Microsoft.Toolkit.Uwp.UI/Shadows/AttachedDropShadow.cs

@@ -17,7 +17,7 @@ namespace Microsoft.Toolkit.Uwp.UI
     /// <summary>
     /// The base class for attached shadows.
     /// </summary>
-    public abstract class AttachedShadowBase : DependencyObject
+    public abstract class AttachedShadowBase : DependencyObject, IAttachedShadow
     {
         /// <summary>
         /// Gets a value indicating whether or not Composition's VisualSurface is supported.
@@ -67,36 +67,28 @@ static AttachedShadowBase()
         /// </summary>
         private ConditionalWeakTable<FrameworkElement, AttachedShadowElementContext> ShadowElementContextTable { get; set; }
 
-        /// <summary>
-        /// Gets or sets the blur radius of the shadow.
-        /// </summary>
+        /// <inheritdoc/>
         public double BlurRadius
         {
             get => (double)GetValue(BlurRadiusProperty);
             set => SetValue(BlurRadiusProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the opacity of the shadow.
-        /// </summary>
+        /// <inheritdoc/>
         public double Opacity
         {
             get => (double)GetValue(OpacityProperty);
             set => SetValue(OpacityProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the offset of the shadow as a string representation of a <see cref="Vector3"/>.
-        /// </summary>
+        /// <inheritdoc/>
         public string Offset
         {
             get => (string)GetValue(OffsetProperty);
             set => SetValue(OffsetProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the color of the shadow.
-        /// </summary>
+        /// <inheritdoc/>
         public Color Color
         {
             get => (Color)GetValue(ColorProperty);
@@ -108,6 +100,14 @@ public Color Color
         /// </summary>
         protected internal abstract bool SupportsOnSizeChangedEvent { get; }
 
+        /// <summary>
+        /// Use this method as the <see cref="PropertyChangedCallback"/> for <see cref="DependencyProperty">DependencyProperties</see> in derived classes.
+        /// </summary>
+        protected static void OnDependencyPropertyChanged(object sender, DependencyPropertyChangedEventArgs args)
+        {
+            (sender as AttachedShadowBase)?.CallPropertyChangedForEachElement(args.Property, args.OldValue, args.NewValue);
+        }
+
         internal void ConnectElement(FrameworkElement element)
         {
             if (!IsSupported)
@@ -165,10 +165,7 @@ protected internal virtual void OnElementContextUninitialized(AttachedShadowElem
             ElementCompositionPreview.SetElementChildVisual(context.Element, null);
         }
 
-        /// <summary>
-        /// Get the associated <see cref="AttachedShadowElementContext"/> for the specified <see cref="FrameworkElement"/>.
-        /// </summary>
-        /// <returns>The <see cref="AttachedShadowElementContext"/> for the element.</returns>
+        /// <inheritdoc/>
         public AttachedShadowElementContext GetElementContext(FrameworkElement element)
         {
             if (ShadowElementContextTable != null && ShadowElementContextTable.TryGetValue(element, out var context))
@@ -179,10 +176,7 @@ public AttachedShadowElementContext GetElementContext(FrameworkElement element)
             return null;
         }
 
-        /// <summary>
-        /// Gets an enumerator over the current list of <see cref="AttachedShadowElementContext"/> of elements using this shared shadow definition.
-        /// </summary>
-        /// <returns>Enumeration of <see cref="AttachedShadowElementContext"/> objects.</returns>
+        /// <inheritdoc/>
         public IEnumerable<AttachedShadowElementContext> GetElementContextEnumerable()
         {
             foreach (var kvp in ShadowElementContextTable)
@@ -200,14 +194,6 @@ protected virtual void SetElementChildVisual(AttachedShadowElementContext contex
             ElementCompositionPreview.SetElementChildVisual(context.Element, context.SpriteVisual);
         }
 
-        /// <summary>
-        /// Use this method as the <see cref="PropertyChangedCallback"/> for <see cref="DependencyProperty">DependencyProperties</see> in derived classes.
-        /// </summary>
-        protected static void OnDependencyPropertyChanged(object sender, DependencyPropertyChangedEventArgs args)
-        {
-            (sender as AttachedShadowBase)?.CallPropertyChangedForEachElement(args.Property, args.OldValue, args.NewValue);
-        }
-
         private void CallPropertyChangedForEachElement(DependencyProperty property, object oldValue, object newValue)
         {
             if (ShadowElementContextTable == null)
@@ -227,6 +213,7 @@ private void CallPropertyChangedForEachElement(DependencyProperty property, obje
         /// <summary>
         /// Get a <see cref="CompositionBrush"/> in the shape of the element that is casting the shadow.
         /// </summary>
+        /// <returns>A <see cref="CompositionBrush"/> representing the shape of an element.</returns>
         protected virtual CompositionBrush GetShadowMask(AttachedShadowElementContext context)
         {
             return null;
@@ -235,6 +222,7 @@ protected virtual CompositionBrush GetShadowMask(AttachedShadowElementContext co
         /// <summary>
         /// Get the <see cref="CompositionClip"/> for the shadow's <see cref="SpriteVisual"/>
         /// </summary>
+        /// <returns>A <see cref="CompositionClip"/> for the extent of the shadowed area.</returns>
         protected virtual CompositionClip GetShadowClip(AttachedShadowElementContext context)
         {
             return null;