Add more samples for the ConstrainedBox control

components/Primitives/samples/ConstrainedBox.md

@@ -17,8 +17,6 @@ icon: Assets/ConstrainedBox.png
 
 > **Platform APIs:** [`ConstrainedBox`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.constrainedbox), [`AspectRatio`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.aspectratio)
 
-> [!SAMPLE ConstrainedBoxSample]
-
 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.
@@ -31,14 +29,22 @@ If a `ConstrainedBox` is placed in a container which doesn't restrict its size i
 
 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
+## Aspect Ratios
+
+The most common use-case for the `ConstrainedBox` is to maintain the aspect ratio of an image. For instance the following example maintains a 16:3 aspect ratio of the image at the top of its container (like a page) and center on the image's content:
+
+> [!SAMPLE ConstrainedBoxAspectSample]
+
+## Scaling
+
+Another scenario may be for keeping a 'safe' margin around the content on your page. You may want this to not be a fixed margin but be proportional to a viewport.
+
+This sample demonstrates that using `ScaleX`/`ScaleY`:
+
+> [!SAMPLE ConstrainedBoxScaleSample]
+
+## Multiples
 
-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:
+The next sample shows how you can use the `MultipleX` property to snap the size of a component to the pattern of an image:
 
-```xaml
-  <controls:ConstrainedBox AspectRatio="16:9" VerticalAlignment="Top">
-    <Image Source="/Assets/Photos/WestSeattleView.jpg"
-           Stretch="UniformToFill"
-           VerticalAlignment="Center"/> <!-- Center viewport on image -->
-  </controls:ConstrainedBox>
-```
+> [!SAMPLE ConstrainedBoxMultipleSample]

components/Primitives/samples/ConstrainedBox/ConstrainedBoxAspectSample.xaml

@@ -0,0 +1,18 @@
+<!--  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="PrimitivesExperiment.Samples.ConstrainedBoxAspectSample"
+      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:controls="using:CommunityToolkit.WinUI.Controls"
+      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+      xmlns:local="using:PrimitivesExperiment.Samples"
+      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
+      mc:Ignorable="d">
+
+    <controls:ConstrainedBox VerticalAlignment="Top"
+                             AspectRatio="16:3">
+        <Image VerticalAlignment="Center"
+               Source="ms-appx:///Assets/WestSeattleView.jpg"
+               Stretch="UniformToFill" />
+    </controls:ConstrainedBox>
+</Page>

components/Primitives/samples/ConstrainedBoxSample.xaml.cs → components/Primitives/samples/ConstrainedBox/ConstrainedBoxAspectSample.xaml.cs

@@ -6,10 +6,10 @@
 
 namespace PrimitivesExperiment.Samples;
 
-[ToolkitSample(id: nameof(ConstrainedBoxSample), "ConstrainedBox", description: $"A sample for showing how to create and use a {nameof(ConstrainedBox)}.")]
-public sealed partial class ConstrainedBoxSample : Page
+[ToolkitSample(id: nameof(ConstrainedBoxAspectSample), "ConstrainedBox Aspect", description: $"A sample for showing how to use a {nameof(ConstrainedBox)} for aspect ratios.")]
+public sealed partial class ConstrainedBoxAspectSample : Page
 {
-    public ConstrainedBoxSample()
+    public ConstrainedBoxAspectSample()
     {
         this.InitializeComponent();
     }

components/Primitives/samples/ConstrainedBox/ConstrainedBoxMultipleSample.xaml

@@ -0,0 +1,25 @@
+<!--  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="PrimitivesExperiment.Samples.ConstrainedBoxMultipleSample"
+      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:brushes="using:CommunityToolkit.WinUI.Media"
+      xmlns:controls="using:CommunityToolkit.WinUI.Controls"
+      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      xmlns:ui="using:CommunityToolkit.WinUI"
+      mc:Ignorable="d">
+
+    <StackPanel Orientation="Horizontal">
+        <controls:ConstrainedBox x:Name="CheckerPattern"
+                                 MinWidth="64"
+                                 MaxWidth="512"
+                                 AspectRatio="1:1"
+                                 MultipleX="64">
+            <Image ui:UIElementExtensions.ClipToBounds="True"
+                   Source="ms-appx:///Assets/checker.png"
+                   Stretch="None" />
+        </controls:ConstrainedBox>
+        <controls:ContentSizer HorizontalAlignment="Right"
+                               TargetControl="{x:Bind CheckerPattern}" />
+    </StackPanel>
+</Page>

components/Primitives/samples/ConstrainedBox/ConstrainedBoxMultipleSample.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.Controls;
+
+namespace PrimitivesExperiment.Samples;
+
+[ToolkitSample(id: nameof(ConstrainedBoxMultipleSample), "ConstrainedBox Multiple", description: $"A sample for showing how to use a {nameof(ConstrainedBox)} for a tile pattern.")]
+public sealed partial class ConstrainedBoxMultipleSample : Page
+{
+    public ConstrainedBoxMultipleSample()
+    {
+        this.InitializeComponent();
+    }
+}

components/Primitives/samples/ConstrainedBox/ConstrainedBoxScaleSample.xaml

@@ -0,0 +1,18 @@
+<!--  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="PrimitivesExperiment.Samples.ConstrainedBoxScaleSample"
+      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:brushes="using:CommunityToolkit.WinUI.Media"
+      xmlns:controls="using:CommunityToolkit.WinUI.Controls"
+      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      xmlns:ui="using:CommunityToolkit.WinUI"
+      mc:Ignorable="d">
+
+    <!--  Set MaxHeight here as sample has infinite height which doesn't make sense for this scenario  -->
+    <controls:ConstrainedBox MaxHeight="512"
+                             ScaleX="0.8"
+                             ScaleY="0.5">
+        <Grid Background="{ThemeResource AccentFillColorDefaultBrush}" />
+    </controls:ConstrainedBox>
+</Page>

components/Primitives/samples/ConstrainedBox/ConstrainedBoxScaleSample.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.Controls;
+
+namespace PrimitivesExperiment.Samples;
+
+[ToolkitSample(id: nameof(ConstrainedBoxScaleSample), "ConstrainedBox Scale", description: $"A sample for showing how to use a {nameof(ConstrainedBox)} for percent buffers over margins.")]
+public sealed partial class ConstrainedBoxScaleSample : Page
+{
+    public ConstrainedBoxScaleSample()
+    {
+        this.InitializeComponent();
+    }
+}

components/Primitives/samples/Primitives.Samples.csproj

@@ -8,6 +8,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\Extensions\src\CommunityToolkit.WinUI.Extensions.csproj"></ProjectReference>
+    <ProjectReference Include="..\..\Sizers\src\CommunityToolkit.WinUI.Controls.Sizers.csproj"></ProjectReference>
   </ItemGroup>
 
   <ItemGroup>