Add initial ConstrainedBox control for AspectRatio and Scaling

Microsoft.Toolkit.Uwp.SampleApp/Microsoft.Toolkit.Uwp.SampleApp.csproj

@@ -1,4 +1,4 @@
-<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
   <PropertyGroup>
     <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
@@ -130,6 +130,7 @@
     <!-- A reference to the entire .Net Framework and Windows SDK are automatically included -->
     <Content Include="Assets\BrushAssets\TileTexture.png" />
     <Content Include="Assets\BrushAssets\NoiseTexture.png" />
+    <Content Include="Assets\checker.png" />
     <Content Include="Assets\Llama.mp3" />
     <Content Include="Assets\mslogo.png" />
     <Content Include="Assets\NotificationAssets\Cloudy-Square.png" />
@@ -271,6 +272,7 @@
     <Content Include="SamplePages\Graph\LoginButton.png" />
     <Content Include="SamplePages\Graph\PeoplePicker.png" />
     <Content Include="SamplePages\Graph\PersonView.png" />
+    <Content Include="SamplePages\Primitives\ConstrainedBox.png" />
     <Content Include="SamplePages\Primitives\SwitchPresenter.png" />
     <Content Include="SamplePages\TabbedCommandBar\TabbedCommandBar.png" />
     <Content Include="SamplePages\Animations\Effects\FadeBehavior.png" />
@@ -621,6 +623,9 @@
     <Content Include="SamplePages\Graph\PeoplePickerXaml.bind" />
     <Content Include="SamplePages\Graph\PersonViewXaml.bind" />
     <Content Include="SamplePages\ListViewExtensions\ListViewExtensionsCode.bind" />
+    <Content Include="SamplePages\Primitives\ConstrainedBox.bind">
+      <SubType>Designer</SubType>
+    </Content>
   </ItemGroup>
   <ItemGroup>
     <Compile Include="App.xaml.cs">

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Primitives/ConstrainedBox.bind

@@ -0,0 +1,28 @@
+<Page
+    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:controls="using:Microsoft.Toolkit.Uwp.UI.Controls"
+    xmlns:brushes="using:Microsoft.Toolkit.Uwp.UI.Media"
+    mc:Ignorable="d">
+
+  <Grid>
+    <controls:ConstrainedBox AspectRatio="16:3" VerticalAlignment="Top">
+      <Image Source="/Assets/Photos/WestSeattleView.jpg"
+             Stretch="UniformToFill"
+             VerticalAlignment="Center"/> <!-- Center on the City -->
+    </controls:ConstrainedBox>
+    <controls:ConstrainedBox MultipleX="64"
+                             AspectRatio="1:1"
+                             MinWidth="64" MaxWidth="512">
+        <controls:ConstrainedBox.Background>
+            <!-- TODO: TilesBrush doesn't support Dpi image loading for this scenario
+                 This example is configured for 100% DPI at the moment.
+                 See https://github.com/CommunityToolkit/WindowsCommunityToolkit/issues/4150
+                 -->
+            <brushes:TilesBrush TextureUri="ms-appx:///Assets/checker.png"/>
+        </controls:ConstrainedBox.Background>
+    </controls:ConstrainedBox>
+  </Grid>
+</Page>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/XamlOnlyPage.xaml

@@ -47,6 +47,7 @@
                 <controls:Case IsDefault="True" />
             </controls:CaseCollection>
         </controls:SwitchPresenter>
+        <controls:ConstrainedBox x:Key="ConstrainedBoxControl" />
     </Page.Resources>
 
     <Grid>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/samples.json

@@ -475,6 +475,15 @@
         "XamlCodeFile": "/SamplePages/Primitives/SwitchPresenter.bind",
         "Icon": "/SamplePages/Primitives/SwitchPresenter.png",
         "DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/controls/SwitchPresenter.md"
+      },
+      {
+        "Name": "ConstrainedBox",
+        "Subcategory": "Layout",
+        "About": "The ConstrainedBox is a FrameworkElement which can allow a developer to constrain the scale, multiple of, or aspect ratio of its content.",
+        "CodeUrl": "https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/main/Microsoft.Toolkit.Uwp.UI.Controls.Primitives/ConstrainedBox",
+        "XamlCodeFile": "/SamplePages/Primitives/ConstrainedBox.bind",
+        "Icon": "/SamplePages/Primitives/ConstrainedBox.png",
+        "DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/controls/ConstrainedBox.md"
       }
     ]
   },
@@ -1259,4 +1268,4 @@
       }
     ]
   }
-]
+]

Microsoft.Toolkit.Uwp.UI.Controls.Primitives/ConstrainedBox/AspectRatio.cs

@@ -0,0 +1,94 @@
+// 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 System;
+
+namespace Microsoft.Toolkit.Uwp.UI.Controls
+{
+    /// <summary>
+    /// The <see cref="AspectRatio"/> structure is used by the <see cref="ConstrainedBox"/> control to
+    /// define a specific ratio to restrict its content.
+    /// </summary>
+    [Windows.Foundation.Metadata.CreateFromString(MethodName = "Microsoft.Toolkit.Uwp.UI.Controls.AspectRatio.ConvertToAspectRatio")]
+    public readonly struct AspectRatio
+    {
+        /// <summary>
+        /// Gets the width component of the aspect ratio or the aspect ratio itself (and height will be 1).
+        /// </summary>
+        public double Width { get; }
+
+        /// <summary>
+        /// Gets the height component of the aspect ratio.
+        /// </summary>
+        public double Height { get; }
+
+        /// <summary>
+        /// Gets the raw numeriucal aspect ratio value itself (Width / Height).
+        /// </summary>
+        public double Value => Width / Height;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AspectRatio"/> struct with the provided width and height.
+        /// </summary>
+        /// <param name="width">Width side of the ratio.</param>
+        /// <param name="height">Height side of the ratio.</param>
+        public AspectRatio(double width, double height)
+        {
+            Width = width;
+            Height = height;
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AspectRatio"/> struct with the specific numerical aspect ratio.
+        /// </summary>
+        /// <param name="ratio">Raw Aspect Ratio, Height will be 1.</param>
+        public AspectRatio(double ratio)
+        {
+            Width = ratio;
+            Height = 1;
+        }
+
+        /// <summary>
+        /// Implicit conversion operator to convert an <see cref="AspectRatio"/> to a <see cref="double"/> value.
+        /// This lets you use them easily in mathmatical expressions.
+        /// </summary>
+        /// <param name="aspect"><see cref="AspectRatio"/> instance.</param>
+        public static implicit operator double(AspectRatio aspect) => aspect.Value;
+
+        /// <summary>
+        /// Implicit conversion operator to convert a <see cref="double"/> to an <see cref="AspectRatio"/> value.
+        /// This allows for x:Bind to bind to a double value.
+        /// </summary>
+        /// <param name="ratio"><see cref="double"/> value representing the <see cref="AspectRatio"/>.</param>
+        public static implicit operator AspectRatio(double ratio) => new AspectRatio(ratio);
+
+        /// <summary>
+        /// Converter to take a string aspect ration like "16:9" and convert it to an <see cref="AspectRatio"/> struct.
+        /// Used automatically by XAML.
+        /// </summary>
+        /// <param name="rawString">The string to be converted in format "Width:Height" or a decimal value.</param>
+        /// <returns>The <see cref="AspectRatio"/> struct representing that ratio.</returns>
+        public static AspectRatio ConvertToAspectRatio(string rawString)
+        {
+            string[] ratio = rawString.Split(":");
+
+            if (ratio.Length == 2)
+            {
+                return new AspectRatio(Convert.ToDouble(ratio[0]), Convert.ToDouble(ratio[1]));
+            }
+            else if (ratio.Length == 1)
+            {
+                return new AspectRatio(Convert.ToDouble(ratio[0]));
+            }
+
+            return new AspectRatio(1);
+        }
+
+        /// <inheritdoc/>
+        public override string ToString()
+        {
+            return Width + ":" + Height;
+        }
+    }
+}

Microsoft.Toolkit.Uwp.UI.Controls.Primitives/ConstrainedBox/ConstrainedBox.Properties.cs

@@ -0,0 +1,104 @@
+// 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 System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using Windows.Foundation;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Controls;
+
+namespace Microsoft.Toolkit.Uwp.UI.Controls
+{
+    /// <summary>
+    /// Dependency properties for the <see cref="ConstrainedBox"/> class.
+    /// </summary>
+    public partial class ConstrainedBox
+    {
+        /// <summary>
+        /// Gets or sets the scale for the width of the panel. Should be a value between 0-1.0. Default is 1.0.
+        /// </summary>
+        public double ScaleX
+        {
+            get { return (double)GetValue(ScaleXProperty); }
+            set { SetValue(ScaleXProperty, value); }
+        }
+
+        /// <summary>
+        /// Identifies the <see cref="ScaleX"/> property.
+        /// </summary>
+        public static readonly DependencyProperty ScaleXProperty =
+            DependencyProperty.Register(nameof(ScaleX), typeof(double), typeof(ConstrainedBox), new PropertyMetadata(1.0, ConstraintPropertyChanged));
+
+        /// <summary>
+        /// Gets or sets the scale for the height of the panel. Should be a value between 0-1.0. Default is 1.0.
+        /// </summary>
+        public double ScaleY
+        {
+            get { return (double)GetValue(ScaleYProperty); }
+            set { SetValue(ScaleYProperty, value); }
+        }
+
+        /// <summary>
+        /// Identifies the <see cref="ScaleY"/> property.
+        /// </summary>
+        public static readonly DependencyProperty ScaleYProperty =
+            DependencyProperty.Register(nameof(ScaleY), typeof(double), typeof(ConstrainedBox), new PropertyMetadata(1.0, ConstraintPropertyChanged));
+
+        /// <summary>
+        /// Gets or sets the integer multiple that the width of the panel should be floored to. Default is null (no snap).
+        /// </summary>
+        public int MultipleX
+        {
+            get { return (int)GetValue(MultipleXProperty); }
+            set { SetValue(MultipleXProperty, value); }
+        }
+
+        /// <summary>
+        /// Identifies the <see cref="MultipleX"/> property.
+        /// </summary>
+        public static readonly DependencyProperty MultipleXProperty =
+            DependencyProperty.Register(nameof(MultipleX), typeof(int), typeof(ConstrainedBox), new PropertyMetadata(null));
+
+        /// <summary>
+        /// Gets or sets the integer multiple that the height of the panel should be floored to. Default is null (no snap).
+        /// </summary>
+        public int MultipleY
+        {
+            get { return (int)GetValue(MultipleYProperty); }
+            set { SetValue(MultipleYProperty, value); }
+        }
+
+        /// <summary>
+        /// Identifies the <see cref="MultipleY"/> property.
+        /// </summary>
+        public static readonly DependencyProperty MultipleYProperty =
+            DependencyProperty.Register(nameof(MultipleY), typeof(int), typeof(ConstrainedBox), new PropertyMetadata(null));
+
+        /// <summary>
+        /// Gets or sets aspect Ratio to use for the contents of the Panel (after scaling).
+        /// </summary>
+        public AspectRatio AspectRatio
+        {
+            get { return (AspectRatio)GetValue(AspectRatioProperty); }
+            set { SetValue(AspectRatioProperty, value); }
+        }
+
+        /// <summary>
+        /// Identifies the <see cref="AspectRatio"/> property.
+        /// </summary>
+        public static readonly DependencyProperty AspectRatioProperty =
+            DependencyProperty.Register(nameof(AspectRatio), typeof(AspectRatio), typeof(ConstrainedBox), new PropertyMetadata(null, ConstraintPropertyChanged));
+
+        private static void ConstraintPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+        {
+            if (d is ConstrainedBox panel)
+            {
+                panel.InvalidateMeasure();
+            }
+        }
+    }
+}