Add MultipleX and MultipleY to ConstrainedBox for floor snap to a multiple value.

Author: michael-hawker

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

@@ -14,34 +14,10 @@
 namespace Microsoft.Toolkit.Uwp.UI.Controls
 {
     /// <summary>
-    /// The <see cref="ConstrainedBox"/> is a <see cref="FrameworkElement"/> control akin to <see cref="Viewbox"/>
-    /// which can modify the behavior of it's child element's layout. <see cref="ConstrainedBox"/> restricts the
-    /// available size for its content based on a scale factor and/or a specific <see cref="AspectRatio"/>.
-    /// This is performed as a layout calculation modification.
+    /// Dependency properties for the <see cref="ConstrainedBox"/> class.
     /// </summary>
-    /// <remarks>
-    /// Note that this class being implemented as a <see cref="ContentPresenter"/> is an implementation detail, and
-    /// is not meant to be used as one with a template. It is recommended to avoid styling the frame of the control
-    /// with borders and not using <see cref="ContentPresenter.ContentTemplate"/> for future compatibility of your
-    /// code if moving to WinUI 3 in the future.
-    /// </remarks>
     public partial class ConstrainedBox
     {
-        /// <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));
-
         /// <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>
@@ -72,6 +48,51 @@ public double ScaleY
         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)

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

@@ -86,6 +86,10 @@ protected override Size ArrangeOverride(Size finalSize)
 
         private void CalculateConstrainedSize(ref Size availableSize)
         {
+            // 1) We check for Infinity, in the case we have no constraint from parent
+            //    we'll request the child's measurements first, so we can use that as
+            //    a starting point to constrain it's dimensions based on the criteria
+            //    set in our properties.
             var hasWidth = IsPositiveRealNumber(availableSize.Width);
             var hasHeight = IsPositiveRealNumber(availableSize.Height);
 
@@ -106,13 +110,39 @@ private void CalculateConstrainedSize(ref Size availableSize)
                 }
             }
 
-            // Scale size first before we constrain aspect ratio
+            // 2) Apply Scales to constrain based on a percentage
+            // --------------------------------------------------
             availableSize.Width *= ScaleX;
             availableSize.Height *= ScaleY;
 
-            // If we don't have an Aspect Ratio, just return the scaled value.
+            // 3) Apply Multiples
+            // ------------------
+            // These floor the Width/Height values to the nearest multiple of the property (if set).
+            // For instance you may have a responsive 4x4 repeated checkerboard pattern for transparency and
+            // want to snap to the nearest interval of 4 so the checkerboard is consistency across the layout.
+            if (hasWidth &&
+                ReadLocalValue(MultipleXProperty) != DependencyProperty.UnsetValue &&
+                MultipleX > 0)
+            {
+                availableSize.Width -= availableSize.Width % MultipleX;
+            }
+
+            if (hasHeight &&
+                ReadLocalValue(MultipleYProperty) != DependencyProperty.UnsetValue &&
+                MultipleY > 0)
+            {
+                availableSize.Height -= availableSize.Height % MultipleY;
+            }
+
+            // 4) Apply AspectRatio
+            // --------------------
+            // Finally, we apply the AspectRatio property after we've determined the general
+            // area we have to work with based on the other constraints.
+            // Devs should be careful if they use both a MultipleX&Y that the AspectRatio is also
+            // within that same ratio. The Ratio will take preference here as the last step.
             if (ReadLocalValue(AspectRatioProperty) == DependencyProperty.UnsetValue)
             {
+                // Skip as last constraint if we have nothing to do.
                 return;
             }