From 22b0a75d6afada9854eeacbcf5b21069f7d6a709 Mon Sep 17 00:00:00 2001 From: michael-hawker <24302614+michael-hawker@users.noreply.github.com> Date: Fri, 17 Sep 2021 16:25:04 -0700 Subject: [PATCH] Initial Half of Attached Shadows Doc (want to preview grid) --- docs/controls/DropShadowPanel.md | 3 ++ docs/helpers/AttachedShadows.md | 79 ++++++++++++++++++++++++++++++++ docs/toc.md | 2 + 3 files changed, 84 insertions(+) create mode 100644 docs/helpers/AttachedShadows.md diff --git a/docs/controls/DropShadowPanel.md b/docs/controls/DropShadowPanel.md index 1e5c582cf..9f4ebcbe1 100644 --- a/docs/controls/DropShadowPanel.md +++ b/docs/controls/DropShadowPanel.md @@ -10,6 +10,9 @@ dev_langs: # DropShadowPanel +> [!WARNING] +> This control has been deprecated in the Windows Community Toolkit and will be removed in a future release. Please use the new [Attached Shadow](../Helpers/AttachedShadows.md) helpers instead. + The [DropShadowPanel](/dotnet/api/microsoft.toolkit.uwp.ui.controls.dropshadowpanel) control allows the creation of a drop shadow effect for any Xaml FrameworkElement in the markup. > [!div class="nextstepaction"] diff --git a/docs/helpers/AttachedShadows.md b/docs/helpers/AttachedShadows.md new file mode 100644 index 000000000..70ae01570 --- /dev/null +++ b/docs/helpers/AttachedShadows.md @@ -0,0 +1,79 @@ +--- +title: Attached Shadows +author: michael-hawker +description: Attached Shadows allow you to easily create a shadow effects on elements. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, your control name +dev_langs: + - csharp +--- + +# Attached Shadows + +Attached Shadows allow you to more easily create beautiful shadow effects within your app with little to no modification of the visual tree required, unlike our previous [`DropShadowPanel`](../controls/DropShadowPanel.md) control. + +> **Platform APIs:** [`AttachedCardShadow`](/dotnet/api/microsoft.toolkit.uwp.ui.media.attachedcardshadow), [`AttachedDropShadow`](/dotnet/api/microsoft.toolkit.uwp.ui.attacheddropshadow) + +## Introduction + +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 following table outlines the various capabilities of each shadow type in addition to comparing to the previous `DropShadowPanel` implementation: + +| Capability | AttachedCardShadow | AttachedDropShadow | DropShadowPanel (deprecated) | +|-------------------------------|--------------------------------------------------------------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| Dependency/NuGet Package | 🟡 Win2D via
`Microsoft.Toolkit.Uwp.UI.Media` | ✅ UWP Only (Composition Effect)
`Microsoft.Toolkit.Uwp.UI` | ✅ UWP Only (Composition Effect)
`Microsoft.Toolkit.Uwp.UI` | +| Layer | Inline Composition +
Win2D Clip Geometry | Composition via
Target Element Backdrop | Composition via
`ContentControl` Container | +| Modify Visual Tree | ✅ No | 🟡 Usually requires single target element, even for multiple shadows | ❌ Individually wrap each element needing shadow | +| Extra Visual Tree Depth | ✅ 0 | 🟡 1 per sibling element to cast one or more shadows to | ❌ _**4** per Shadowed Element_ | +| Masking/Geometry | 🟡 Rectangular/Rounded-Rectangles only | ✅ Can mask images, text, and shapes (performance penalty) | ✅ Can mask images, text, and shapes (performance penalty) | +| Performance | ✅ Fast, applies rectangular clipped geometry | 🟡 Slower, especially when masking (default);
can use rounded-rectangles optimization | ❌ Slowest, no optimization for rounded-rectangles | +| ResourceDictionary Support | ✅ Yes | ✅ Yes | ❌ Limited, via complete custom control style +
still need to wrap each element to apply | +| Usable in Styles | ✅ Yes, anywhere, including app-level | 🟡 Yes, but limited to page-scope due to element target | ❌ No | +| Supports Transparent Elements | ✅ Yes, shadow is clipped and not visible | ❌ No, shadow shows through transparent element | ❌ No, shadow shows through transparent element | +| Animation Support | ✅ Yes, in XAML via [`AnimationSet`](../animations/AnimationSet.md) | 🟡 Partial, translating/moving element may desync shadow | ❌ No | + +## AttachedCardShadow (Win2D) + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://controls?sample=attachedcardshadowwin2d) + +## AttachedDropShadow (Composition) + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://controls?sample=attacheddropshadowcomposition) + +## Example + +```xaml + + + + + + + + +``` + +## Example Output + +![Alt Text of Image (not same as filename)](../resources/images/filename.png) + +## Sample Project + +[control/helper name sample page Source](sample-page-link). You can [see this in action](uwpct://CategoryName?sample=pageName) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Source Code + +- [control/helper name source code](source-code-link) + +## Related Topics + +- [Topic 1](link) +- [Topic 2](link) diff --git a/docs/toc.md b/docs/toc.md index 128c1a9f3..e9e937203 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -283,6 +283,8 @@ ### [AdvancedCollectionView](helpers/AdvancedCollectionView.md) +### [Attached Shadows](helpers/AttachedShadows.md) + ### [BackgroundTaskHelper](helpers/BackgroundTaskHelper.md) ### [BindableValueHolder](helpers/BindableValueHolder.md)