Skip to content

Commit 22b0a75

Browse files
michael-hawkermichael-hawker
committed
Initial Half of Attached Shadows Doc (want to preview grid)
1 parent 5c6b70e commit 22b0a75

File tree

3 files changed

+84
-0
lines changed

3 files changed

+84
-0
lines changed

‎docs/controls/DropShadowPanel.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ dev_langs:
1010

1111
# DropShadowPanel
1212

13+
> [!WARNING]
14+
> 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.
15+
1316
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.
1417

1518
> [!div class="nextstepaction"]

‎docs/helpers/AttachedShadows.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: Attached Shadows
3+
author: michael-hawker
4+
description: Attached Shadows allow you to easily create a shadow effects on elements.
5+
keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, your control name
6+
dev_langs:
7+
- csharp
8+
---
9+
10+
# Attached Shadows
11+
12+
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.
13+
14+
> **Platform APIs:** [`AttachedCardShadow`](/dotnet/api/microsoft.toolkit.uwp.ui.media.attachedcardshadow), [`AttachedDropShadow`](/dotnet/api/microsoft.toolkit.uwp.ui.attacheddropshadow)
15+
16+
## Introduction
17+
18+
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.
19+
20+
The following table outlines the various capabilities of each shadow type in addition to comparing to the previous `DropShadowPanel` implementation:
21+
22+
| Capability | AttachedCardShadow | AttachedDropShadow | DropShadowPanel (deprecated) |
23+
|-------------------------------|--------------------------------------------------------------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------|
24+
| Dependency/NuGet Package | 🟡 Win2D via<br>`Microsoft.Toolkit.Uwp.UI.Media` | ✅ UWP Only (Composition Effect)<br>`Microsoft.Toolkit.Uwp.UI` | ✅ UWP Only (Composition Effect)<br>`Microsoft.Toolkit.Uwp.UI` |
25+
| Layer | Inline Composition +<br>Win2D Clip Geometry | Composition via<br>Target Element Backdrop | Composition via<br>`ContentControl` Container |
26+
| Modify Visual Tree | ✅ No | 🟡 Usually requires single target element, even for multiple shadows | ❌ Individually wrap each element needing shadow |
27+
| Extra Visual Tree Depth | ✅ 0 | 🟡 1 per sibling element to cast one or more shadows to | ❌ _**4** per Shadowed Element_ |
28+
| Masking/Geometry | 🟡 Rectangular/Rounded-Rectangles only | ✅ Can mask images, text, and shapes (performance penalty) | ✅ Can mask images, text, and shapes (performance penalty) |
29+
| Performance | ✅ Fast, applies rectangular clipped geometry | 🟡 Slower, especially when masking (default);<br>can use rounded-rectangles optimization | ❌ Slowest, no optimization for rounded-rectangles |
30+
| ResourceDictionary Support | ✅ Yes | ✅ Yes | ❌ Limited, via complete custom control style +<br>still need to wrap each element to apply |
31+
| Usable in Styles | ✅ Yes, anywhere, including app-level | 🟡 Yes, but limited to page-scope due to element target | ❌ No |
32+
| Supports Transparent Elements | ✅ Yes, shadow is clipped and not visible | ❌ No, shadow shows through transparent element | ❌ No, shadow shows through transparent element |
33+
| Animation Support | ✅ Yes, in XAML via [`AnimationSet`](../animations/AnimationSet.md) | 🟡 Partial, translating/moving element may desync shadow | ❌ No |
34+
35+
## AttachedCardShadow (Win2D)
36+
37+
> [!div class="nextstepaction"]
38+
> [Try it in the sample app](uwpct://controls?sample=attachedcardshadowwin2d) <!-- TODO: Don't know what magic we need here, probably () throwing it -->
39+
40+
## AttachedDropShadow (Composition)
41+
42+
> [!div class="nextstepaction"]
43+
> [Try it in the sample app](uwpct://controls?sample=attacheddropshadowcomposition)
44+
45+
## Example
46+
47+
```xaml
48+
<Rectangle RadiusX="32" RadiusY="32"
49+
Height="100" Width="100"
50+
Stroke="Blue" StrokeThickness="1">
51+
<Rectangle.Fill>
52+
<ImageBrush ImageSource="ms-appx:///Assets/Photos/Owl.jpg"/>
53+
</Rectangle.Fill>
54+
<ui:Effects.Shadow>
55+
<media:AttachedCardShadow BlurRadius="8"
56+
CornerRadius="32"
57+
Color="Black"
58+
Offset="4,4"
59+
Opacity="1"/>
60+
</ui:Effects.Shadow>
61+
</Rectangle>
62+
```
63+
64+
## Example Output
65+
66+
![Alt Text of Image (not same as filename)](../resources/images/filename.png)
67+
68+
## Sample Project
69+
70+
[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).
71+
72+
## Source Code
73+
74+
- [control/helper name source code](source-code-link)
75+
76+
## Related Topics
77+
78+
- [Topic 1](link)
79+
- [Topic 2](link)

‎docs/toc.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,8 @@
283283

284284
### [AdvancedCollectionView](helpers/AdvancedCollectionView.md)
285285

286+
### [Attached Shadows](helpers/AttachedShadows.md)
287+
286288
### [BackgroundTaskHelper](helpers/BackgroundTaskHelper.md)
287289

288290
### [BindableValueHolder](helpers/BindableValueHolder.md)

0 commit comments

Comments
 (0)