Add AttachedCardShadow samples to Media Samples

Moves AttachedCardShadow doc to the Media Samples Move AttachedDropShadow samples to their own folder
CommunityToolkit · Sep 2, 2023 · 3217d31 · 3217d31
1 parent 2428107
commit 3217d31
Show file tree

Hide file tree

Showing 14 changed files with 117 additions and 29 deletions.
diff --git a/components/Extensions/samples/AttachedShadows.md b/components/Extensions/samples/AttachedShadows.md
@@ -15,11 +15,11 @@ icon: Assets/Shadow.png
 
 There are two types of attached shadows available today, the `AttachedCardShadow` and the `AttachedDropShadow`. It is recommended to use the `AttachedCardShadow` where possible, if you don't mind the dependency on Win2D. The `AttachedCardShadow` provides an easier to use experience that is more performant and easier to apply across an entire set of elements, assuming those elements are rounded-rectangular in shape. The `AttachedDropShadow` provides masking support and can be leveraged in any UWP app without adding an extra dependency.
 
-### Capability Comparison
+## Capability Comparison
 
 The following table outlines the various capabilities of each shadow type in addition to comparing to the previous `DropShadowPanel` implementation:
 
-| Capability                    | AttachedCardShadow                                                 | AttachedDropShadow                                              | DropShadowPanel (deprecated)                                                              |
+| Capability                    | AttachedCardShadow                                                 | AttachedDropShadow                                              | DropShadowPanel (deprecated/removed)                                                       |
 |-------------------------------|--------------------------------------------------------------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------|
 | Dependency/NuGet Package      | 🟡 Win2D via<br>`CommunityToolkit.WinUI.Media`                       | ✅ Framework Only (Composition Effect)<br>`CommunityToolkit.WinUI.Effects`  | ✅ Framework Only (Composition Effect)<br>`Microsoft.Toolkit.Uwp.UI.Controls` (legacy)                              |
 | Layer                         | Inline Composition +<br>Win2D Clip Geometry                           | Composition via<br>Target Element Backdrop                         | Composition via<br>`ContentControl` Container                                                |
@@ -40,7 +40,7 @@ The great benefit to the `AttachedCardShadow` is that no extra surface or elemen
 
 ## AttachedDropShadow (Composition)
 
-The `AttachedDropShadow` provides masking support to a wide variety of elements including transparent images, shapes, and text. Masking to a custom shape that's not rectangular or rounded-rectangular is the main scenario where an `AttachedDropShadow` will be useful. Unlike it's predecessor, the [`DropShadowPanel`](../Controls/DropShadowPanel.md), the `AttachedDropShadow` doesn't need to wrap the element being shadowed; however, it does require another element to cast the shadow on to.
+The `AttachedDropShadow` provides masking support to a wide variety of elements including transparent images, shapes, and text. Masking to a custom shape that's not rectangular or rounded-rectangular is the main scenario where an `AttachedDropShadow` will be useful. Unlike it's predecessor, the `DropShadowPanel`, the `AttachedDropShadow` doesn't need to wrap the element being shadowed; however, it does require another element to cast the shadow on to.
 
 This makes it a bit more complex to use than the `AttachedCardShadow` and the `DropShadowPanel`, but since multiple `AttachedDropShadow` elements can share the same surface, this makes it much more performant than its predecessor.
 

diff --git a/...amples/AttachedDropShadowBasicSample.xaml → ...hadows/AttachedDropShadowBasicSample.xaml b/...amples/AttachedDropShadowBasicSample.xaml → ...hadows/AttachedDropShadowBasicSample.xaml
@@ -1,5 +1,5 @@
 <!--  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.  -->
-<Page x:Class="ExtensionsExperiment.Samples.AttachedDropShadowBasicSample"
+<Page x:Class="ExtensionsExperiment.Samples.Shadows.AttachedDropShadowBasicSample"
       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"

diff --git a/...les/AttachedDropShadowBasicSample.xaml.cs → ...ows/AttachedDropShadowBasicSample.xaml.cs b/...les/AttachedDropShadowBasicSample.xaml.cs → ...ows/AttachedDropShadowBasicSample.xaml.cs
@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-namespace ExtensionsExperiment.Samples;
+namespace ExtensionsExperiment.Samples.Shadows;
 
 [ToolkitSample(id: nameof(AttachedDropShadowBasicSample), "Basic Attached Drop Shadow", description: "A sample for showing how to create an AttachedDropShadow on an element.")]
 public sealed partial class AttachedDropShadowBasicSample : Page

diff --git a/...les/AttachedDropShadowResourceSample.xaml → ...ows/AttachedDropShadowResourceSample.xaml b/...les/AttachedDropShadowResourceSample.xaml → ...ows/AttachedDropShadowResourceSample.xaml
@@ -1,5 +1,5 @@
 <!--  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.  -->
-<Page x:Class="ExtensionsExperiment.Samples.AttachedDropShadowResourceSample"
+<Page x:Class="ExtensionsExperiment.Samples.Shadows.AttachedDropShadowResourceSample"
       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"

diff --git a/.../AttachedDropShadowResourceSample.xaml.cs → .../AttachedDropShadowResourceSample.xaml.cs b/.../AttachedDropShadowResourceSample.xaml.cs → .../AttachedDropShadowResourceSample.xaml.cs
@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-namespace ExtensionsExperiment.Samples;
+namespace ExtensionsExperiment.Samples.Shadows;
 
 [ToolkitSample(id: nameof(AttachedDropShadowResourceSample), "Attached Drop Shadow as Resource", description: "A sample for showing how to create an AttachedDropShadow on an element when defined as a resource.")]
 public sealed partial class AttachedDropShadowResourceSample : Page

diff --git a/...amples/AttachedDropShadowStyleSample.xaml → ...hadows/AttachedDropShadowStyleSample.xaml b/...amples/AttachedDropShadowStyleSample.xaml → ...hadows/AttachedDropShadowStyleSample.xaml
@@ -1,5 +1,5 @@
 <!--  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.  -->
-<Page x:Class="ExtensionsExperiment.Samples.AttachedDropShadowStyleSample"
+<Page x:Class="ExtensionsExperiment.Samples.Shadows.AttachedDropShadowStyleSample"
       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"

diff --git a/...les/AttachedDropShadowStyleSample.xaml.cs → ...ows/AttachedDropShadowStyleSample.xaml.cs b/...les/AttachedDropShadowStyleSample.xaml.cs → ...ows/AttachedDropShadowStyleSample.xaml.cs
@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-namespace ExtensionsExperiment.Samples;
+namespace ExtensionsExperiment.Samples.Shadows;
 
 [ToolkitSample(id: nameof(AttachedDropShadowStyleSample), "Attached Drop Shadow as Style", description: "A sample for showing how to create an AttachedDropShadow when used in a Style.")]
 public sealed partial class AttachedDropShadowStyleSample : Page

diff --git a/components/Media/samples/Assets/OwlShadow.jpg b/components/Media/samples/Assets/OwlShadow.jpg
diff --git a/.../Extensions/samples/AttachedCardShadow.md → ...nents/Media/samples/AttachedCardShadow.md b/.../Extensions/samples/AttachedCardShadow.md → ...nents/Media/samples/AttachedCardShadow.md
@@ -18,23 +18,12 @@ The great benefit to the `AttachedCardShadow` is that no extra surface or elemen
 
 The example shows how easy it is to not only apply an `AttachedCardShadow` to an element, but use it in a style to apply to multiple elements as well:
 
-```xaml
-    xmlns:ui="using:CommunityToolkit.WinUI"
-    xmlns:media="using:CommunityToolkit.WinUI.Media"/>
-
-    <Page.Resources>
-        <media:AttachedCardShadow x:Key="CommonShadow" Offset="4"/>
-
-        <Style TargetType="Button" BasedOn="{StaticResource DefaultButtonStyle}">
-            <Setter Property="ui:Effects.Shadow" Value="{StaticResource CommonShadow}"/>
-            <Setter Property="HorizontalAlignment" Value="Center"/>
-        </Style>
-    </Page.Resources>
-
-    <StackPanel Spacing="32" VerticalAlignment="Center">
-        <Button Content="I Have a Shadow!"/>
-        <Image ui:Effects.Shadow="{StaticResource CommonShadow}"
-               Height="100" Width="100"
-               Source="ms-appx:///Assets/Photos/Owl.jpg"/>
-    </StackPanel>
-```
+> [!SAMPLE AttachedCardShadowBasicSample]
+
+You can see the `AttachedCardShadow` defined as a resource so it can be shared across multiple components. It also supports binding/animations to update at runtime.
+
+## Layer Ordering
+
+There can be cases, especially direct usage on untemplated elements, where the AttachedCardShadow may require a parent element to create the desired effect, as seen in this example:
+
+> [!SAMPLE AttachedCardShadowUntemplatedSample]
diff --git a/components/Media/samples/Media.Samples.csproj b/components/Media/samples/Media.Samples.csproj
@@ -9,12 +9,16 @@
   <ItemGroup>
     <None Remove="Assets\Bloom.jpg" />
     <None Remove="Assets\EffectAnimations.png" />
+    <None Remove="Assets\OwlShadow.jpg" />
 
     <Content Include="Assets\Bloom.jpg">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>
     <Content Include="Assets\EffectAnimations.png">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>
+    <Content Include="Assets\OwlShadow.jpg">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
   </ItemGroup>
 </Project>
diff --git a/components/Media/samples/Shadows/AttachedCardShadowBasicSample.xaml b/components/Media/samples/Shadows/AttachedCardShadowBasicSample.xaml
@@ -0,0 +1,29 @@
+<Page x:Class="MediaExperiment.Samples.Shadows.AttachedCardShadowBasicSample"
+      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:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      xmlns:media="using:CommunityToolkit.WinUI.Media"
+      xmlns:ui="using:CommunityToolkit.WinUI"
+      mc:Ignorable="d">
+
+    <Page.Resources>
+        <media:AttachedCardShadow x:Key="CommonShadow"
+                                  Offset="4" />
+
+        <Style BasedOn="{StaticResource DefaultButtonStyle}"
+               TargetType="Button">
+            <Setter Property="ui:Effects.Shadow" Value="{StaticResource CommonShadow}" />
+            <Setter Property="HorizontalAlignment" Value="Center" />
+        </Style>
+    </Page.Resources>
+
+    <StackPanel VerticalAlignment="Center"
+                Spacing="32">
+        <Button Content="I Have a Shadow!" />
+        <Image Width="100"
+               Height="100"
+               ui:Effects.Shadow="{StaticResource CommonShadow}"
+               Source="ms-appx:///Assets/OwlShadow.jpg" />
+    </StackPanel>
+</Page>
diff --git a/components/Media/samples/Shadows/AttachedCardShadowBasicSample.xaml.cs b/components/Media/samples/Shadows/AttachedCardShadowBasicSample.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 CommunityToolkit.WinUI.Media;
+
+namespace MediaExperiment.Samples.Shadows;
+
+[ToolkitSample(id: nameof(AttachedCardShadowBasicSample), "Basic Attached Card Shadow", description: $"A sample for showing how to create an {nameof(AttachedCardShadow)} on an element.")]
+public sealed partial class AttachedCardShadowBasicSample : Page
+{
+    public AttachedCardShadowBasicSample()
+    {
+        this.InitializeComponent();
+    }
+}
diff --git a/components/Media/samples/Shadows/AttachedCardShadowUntemplatedSample.xaml b/components/Media/samples/Shadows/AttachedCardShadowUntemplatedSample.xaml
@@ -0,0 +1,34 @@
+<Page x:Class="MediaExperiment.Samples.Shadows.AttachedCardShadowUntemplatedSample"
+      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:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      xmlns:media="using:CommunityToolkit.WinUI.Media"
+      xmlns:ui="using:CommunityToolkit.WinUI"
+      mc:Ignorable="d">
+
+    <!--
+        If you want to apply a shadow directly in your visual tree to an untemplated element
+        You need to at least have a layer of depth as seen in this next example.
+    -->
+    <Border Width="100"
+            Height="100">
+        <Border BorderBrush="White"
+                BorderThickness="1"
+                CornerRadius="32">
+            <Border.Background>
+                <ImageBrush ImageSource="ms-appx:///Assets/OwlShadow.jpg" />
+            </Border.Background>
+        </Border>
+        <!--
+            We need to put the Shadow on a parent element here as otherwise the
+            rounding of the border of the image above clips the shadow itself.
+            This is easier to perform with the Composition only based shadow as the
+            Shadow is projected to another element.
+        -->
+        <ui:Effects.Shadow>
+            <media:AttachedCardShadow CornerRadius="32"
+                                      Offset="4,4" />
+        </ui:Effects.Shadow>
+    </Border>
+</Page>
diff --git a/components/Media/samples/Shadows/AttachedCardShadowUntemplatedSample.xaml.cs b/components/Media/samples/Shadows/AttachedCardShadowUntemplatedSample.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 CommunityToolkit.WinUI.Media;
+
+namespace MediaExperiment.Samples.Shadows;
+
+[ToolkitSample(id: nameof(AttachedCardShadowUntemplatedSample), "Untemplated Attached Card Shadow", description: $"A sample for showing how to create an {nameof(AttachedCardShadow)} on an untemplated element.")]
+public sealed partial class AttachedCardShadowUntemplatedSample : Page
+{
+    public AttachedCardShadowUntemplatedSample()
+    {
+        this.InitializeComponent();
+    }
+}