diff --git a/docs/.template.md b/docs/.template.md index f82b5f401..2cd7f5c17 100644 --- a/docs/.template.md +++ b/docs/.template.md @@ -7,9 +7,12 @@ dev_langs: - csharp --- - + + + + # Title @@ -30,7 +33,7 @@ with the namespace and the class name. Without any country/region 'en-us' identi > Some warning note --> -> **Platform APIs:** Include a comma separated list of links of any APIs used in the document in the following format: [`Class/InterfaceName`](API-Link). +> **Platform APIs:** [`Class/InterfaceName`](API-Link) diff --git a/docs/controls/ConstrainedBox.md b/docs/controls/ConstrainedBox.md new file mode 100644 index 000000000..ef0bfba5e --- /dev/null +++ b/docs/controls/ConstrainedBox.md @@ -0,0 +1,58 @@ +--- +title: ConstrainedBox +author: michael-hawker +description: Constrain a child element by aspect ratio, scale, or multiple. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, viewbox, content decorator, ConstrainedBox +dev_langs: + - csharp +--- + +# ConstrainedBox + +The [ConstrainedBox](/dotnet/api/microsoft.toolkit.uwp.ui.controls.constrainedbox) is a simple `FrameworkElement` content decorator control which allows the developer to constrain its child content by one or more various properties including aspect ratio, scale, and aligning to a multiple boundary. + +> [!NOTE] +> For technical reasons this control inherits from `ContentPresenter`; however, it should be treated as a `FrameworkElement` and its border and template properties should not be used for compatibility in the future when it can inherit from FrameworkElement directly. + +> **Platform APIs:** [`ConstrainedBox`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.constrainedbox), [`AspectRatio`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.aspectratio) + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://controls?sample=constrainedbox) + +The three constraints provided by the `ConstrainedBox` control can be used individually & independently or combined to provide a wide-variety of responsive layout options. When used in combination, for the properties used, they are always applied in the following order: + +1. `ScaleX`/`ScaleY`: Scaling is applied first to restrict the overall available size in each axis from the parent container based on a percentage value from 0.0-1.0. The default value is 1.0 to use all available size. + +2. `MultipleX`/`MultipleY`: The multiple values allow a developer to snap the layout size of the child to a specific multiple value. For instance, by providing a value of 4, you would ensure the child element is closest to the size of 16, 20, 24, etc... The floor is taken so the child element is always smaller within the bounds of its parent. By default this value is not set so that no extra layout rounding occurs. + +3. `AspectRatio`: The aspect ratio can be provided by a double value or a colon separated aspect (e.g. "16:9") and will restrict the layout of the child element to that available space. Therefore if you stretch your child element you can ensure it maintains the desired aspect ratio. By default, no aspect ratio constraint is applied. + +If a `ConstrainedBox` is placed in a container which doesn't restrict its size in both the horizontal and vertical directions, it will try to determine its constraints based on the desired size of its child element. If only one direction has infinite size, the control will attempt to use the fixed dimension to measure all constraints against. + +The Min/Max and Alignment properties of the `ConstrainedBox` itself and its child can also be set to provide other constraints on how layout is performed with the control, as with any regular XAML layout. + +## Example + +The following example shows how to align a 16:9 view of an image with the top of its container (like a page) and center on the image's content: + +```xaml + + + +``` + +## Sample Project + +[ConstrainedBox sample page Source](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Primitives/ConstrainedBox.bind). You can [see this in action](uwpct://controls?sample=constrainedbox) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Source Code + +- [ConstrainedBox source code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Primitives/ConstrainedBox) + +## Related Topics + +- [UseLayoutRounding](/uwp/api/windows.ui.xaml.uielement.uselayoutrounding) +- [FrameworkElement](/uwp/api/windows.ui.xaml.frameworkelement) +- [Viewbox](/uwp/api/windows.ui.xaml.controls.viewbox) 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..6834435e7 --- /dev/null +++ b/docs/helpers/AttachedShadows.md @@ -0,0 +1,174 @@ +--- +title: Attached Shadows +author: michael-hawker +description: Attached Shadows allow you to easily create shadow effects on elements. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, shadow, shadows, dropshadow, dropshadowpanel, attachedshadow, attacheddropshadow, attachedcardshadow +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 `AttachedDropShadow` provides masking support and can be leveraged in any UWP app without adding an extra dependency. + +### 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) | +|-------------------------------|--------------------------------------------------------------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| 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 in 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) + +The `AttachedCardShadow` is the easiest to use and most performant shadow. It is recommended to use it where possible, if taking a Win2D dependency is not a concern. It's only drawbacks are the extra dependency required and that it only supports rectangular and rounded-rectangular geometries (as described in the table above). + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://controls?sample=attachedcardshadow%20%28win2d%29) + +The great benefit to the `AttachedCardShadow` is that no extra surface or element is required to add the shadow. This reduces the complexity required in development and allows shadows to easily be added at any point in the development process. It also supports transparent elements, without displaying the shadow behind them! + +### Example + +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:Microsoft.Toolkit.Uwp.UI" + xmlns:media="using:Microsoft.Toolkit.Uwp.UI.Media"/> + + + + + + + + +