Refactor Layouts to use [BindableProperty] partial properties (#3016)

ne0rrmatrix · TheCodeTraveler · web-flow · commit 80512991a22c · 2026-01-10T14:09:12.000-08:00
* Update Bindable Properties for Layouts

* Add default values and `EnsureDefault()` tests

* Use `PropertyChangingMethodName` for validation, Fix Method Names

* Update XML Comments

* `dotnet format`

---------

Co-authored-by: Brandon Minnick &lt;13558917+TheCodeTraveler@users.noreply.github.com&gt;
diff --git a/src/CommunityToolkit.Maui.Core/Essentials/FileSaver/FileSaverImplementation.macios.cs b/src/CommunityToolkit.Maui.Core/Essentials/FileSaver/FileSaverImplementation.macios.cs
@@ -12,7 +12,7 @@ Task<string> InternalSaveAsync(string fileName, Stream stream, IProgress<double>
 	{
 		return InternalSaveAsync("/", fileName, stream, progress, cancellationToken);
 	}
-	
+
 	async Task<string> InternalSaveAsync(
 		string initialPath,
 		string fileName,
@@ -23,8 +23,8 @@ async Task<string> InternalSaveAsync(
 		cancellationToken.ThrowIfCancellationRequested();
 
 		var currentViewController = Platform.GetCurrentUIViewController()
-		                            ?? throw new FileSaveException(
-			                            "Cannot present file picker: No active view controller found. Ensure the app is active with a visible window.");
+									?? throw new FileSaveException(
+										"Cannot present file picker: No active view controller found. Ensure the app is active with a visible window.");
 
 		var fileManager = NSFileManager.DefaultManager;
 
@@ -71,22 +71,22 @@ await WriteStream(
 			picker.DidPickDocumentAtUrls -= OnPicked;
 			picker.WasCancelled -= OnCancelled;
 		}
-		
+
 		void OnPicked(object? sender, UIDocumentPickedAtUrlsEventArgs e)
 		{
 			if (e.Urls.Length is 0)
 			{
 				tcs.TrySetException(new FileSaveException("No file was selected."));
 				return;
 			}
-			
+
 			var path = e.Urls[0].Path;
 			if (path is null)
 			{
 				tcs.TrySetException(new FileSaveException("File path cannot be null."));
 				return;
 			}
-			
+
 			tcs.TrySetResult(path);
 		}
 
diff --git a/src/CommunityToolkit.Maui.Core/Essentials/FileSaver/FileSaverResult.shared.cs b/src/CommunityToolkit.Maui.Core/Essentials/FileSaver/FileSaverResult.shared.cs
@@ -16,7 +16,7 @@ public record FileSaverResult(string? FilePath, Exception? Exception)
 	[MemberNotNullWhen(true, nameof(FilePath))]
 	[MemberNotNullWhen(false, nameof(Exception))]
 	public bool IsSuccessful => Exception is null;
-	
+
 	/// <summary>
 	/// Check if the operation was cancelled.
 	/// </summary>
diff --git a/src/CommunityToolkit.Maui.Core/Essentials/FolderPicker/FolderPickerImplementation.macios.cs b/src/CommunityToolkit.Maui.Core/Essentials/FolderPicker/FolderPickerImplementation.macios.cs
@@ -14,13 +14,13 @@ Task<Folder> InternalPickAsync(CancellationToken cancellationToken)
 	{
 		return InternalPickAsync("/", cancellationToken);
 	}
-	
+
 	async Task<Folder> InternalPickAsync(string initialPath, CancellationToken cancellationToken)
 	{
 		cancellationToken.ThrowIfCancellationRequested();
 
 		var currentViewController = Platform.GetCurrentUIViewController()
-		                            ?? throw new FolderPickerException("Unable to get a window where to present the folder picker UI.");
+									?? throw new FolderPickerException("Unable to get a window where to present the folder picker UI.");
 
 		var tcs = new TaskCompletionSource<Folder>(
 			TaskCreationOptions.RunContinuationsAsynchronously);
@@ -44,7 +44,7 @@ async Task<Folder> InternalPickAsync(string initialPath, CancellationToken cance
 			picker.DidPickDocumentAtUrls -= OnPicked;
 			picker.WasCancelled -= OnCancelled;
 		}
-		
+
 		void OnPicked(object? sender, UIDocumentPickedAtUrlsEventArgs e)
 		{
 			if (e.Urls.Length is 0)
diff --git a/src/CommunityToolkit.Maui.Core/Primitives/Defaults/DockLayoutDefaults.shared.cs b/src/CommunityToolkit.Maui.Core/Primitives/Defaults/DockLayoutDefaults.shared.cs
@@ -0,0 +1,8 @@
+﻿namespace CommunityToolkit.Maui.Core;
+
+static class DockLayoutDefaults
+{
+	public const bool ShouldExpandLastChild = true;
+	public const double HorizontalSpacing = 0.0d;
+	public const double VerticalSpacing = 0.0d;
+}
diff --git a/src/CommunityToolkit.Maui.Core/Primitives/Defaults/UniformItemLayoutDefaults.shared.cs b/src/CommunityToolkit.Maui.Core/Primitives/Defaults/UniformItemLayoutDefaults.shared.cs
@@ -0,0 +1,7 @@
+﻿namespace CommunityToolkit.Maui.Core;
+
+static class UniformItemLayoutDefaults
+{
+	public const int MaxRows = int.MaxValue;
+	public const int MaxColumns = int.MaxValue;
+}
diff --git a/src/CommunityToolkit.Maui.UnitTests/Behaviors/NumericValidationBehaviorTests.cs b/src/CommunityToolkit.Maui.UnitTests/Behaviors/NumericValidationBehaviorTests.cs
@@ -85,7 +85,7 @@ public async Task IsNull()
 			Text = text
 		};
 		entry.Behaviors.Add(behavior);
-		
+
 		//Act
 		await behavior.ForceValidate(TestContext.Current.CancellationToken);
 
diff --git a/src/CommunityToolkit.Maui.UnitTests/ImageSources/GravatarImageSource/GravatarImageSourceTests.cs b/src/CommunityToolkit.Maui.UnitTests/ImageSources/GravatarImageSource/GravatarImageSourceTests.cs
@@ -111,14 +111,14 @@ public void DefaultUri()
 		var gravatarImageSource = new GravatarImageSource();
 		Assert.Equal(GravatarImageSourceDefaults.Uri, gravatarImageSource.Uri);
 	}
-	
+
 	[Fact]
 	public void DefaultParentHeight()
 	{
 		var gravatarImageSource = new GravatarImageSource();
 		Assert.Equal(GravatarImageSourceDefaults.ParentHeight, gravatarImageSource.ParentHeight);
 	}
-	
+
 	[Fact]
 	public void DefaultParentWidth()
 	{
diff --git a/src/CommunityToolkit.Maui.UnitTests/Layouts/DockLayoutTests.cs b/src/CommunityToolkit.Maui.UnitTests/Layouts/DockLayoutTests.cs
@@ -41,6 +41,15 @@ public DockLayoutTests()
 		DockLayout.SetDockPosition(childBottomView, DockPosition.Bottom);
 	}
 
+	[Fact]
+	public void EnsureDefaults()
+	{
+		var layout = new DockLayout();
+		Assert.Equal(DockLayoutDefaults.ShouldExpandLastChild, layout.ShouldExpandLastChild);
+		Assert.Equal(DockLayoutDefaults.HorizontalSpacing, layout.HorizontalSpacing);
+		Assert.Equal(DockLayoutDefaults.VerticalSpacing, layout.VerticalSpacing);
+	}
+
 	#region Measure
 
 	[Fact]
diff --git a/src/CommunityToolkit.Maui.UnitTests/Layouts/UniformItemsLayoutTests.cs b/src/CommunityToolkit.Maui.UnitTests/Layouts/UniformItemsLayoutTests.cs
@@ -1,4 +1,5 @@
-﻿using CommunityToolkit.Maui.Layouts;
+﻿using CommunityToolkit.Maui.Core;
+using CommunityToolkit.Maui.Layouts;
 using FluentAssertions;
 using Xunit;
 
@@ -109,6 +110,14 @@ public void ArrangeChildrenUniformItemsLayout()
 		Assert.Equal(childSize * childCount, actualSize);
 	}
 
+	[Fact]
+	public void EnsureDefaults()
+	{
+		var layout = new UniformItemsLayout();
+		Assert.Equal(UniformItemLayoutDefaults.MaxRows, layout.MaxRows);
+		Assert.Equal(UniformItemLayoutDefaults.MaxColumns, layout.MaxColumns);
+	}
+
 	class TestView : View
 	{
 		readonly Size size;
diff --git a/src/CommunityToolkit.Maui/Layouts/DockLayout.shared.cs b/src/CommunityToolkit.Maui/Layouts/DockLayout.shared.cs
@@ -16,55 +16,26 @@ public partial class DockLayout : Layout, IDockLayout
 																									typeof(DockPosition),
 																									typeof(DockLayout),
 																									DockPosition.None,
-																									propertyChanged: OnDockPositionPropertyChanged);
+																							propertyChanged: OnDockPositionPropertyChanged);
 
 	/// <summary>
 	/// If true, the last child is expanded to fill the remaining space (default: true).
 	/// </summary>
-	public static readonly BindableProperty ShouldExpandLastChildProperty = BindableProperty.Create(nameof(ShouldExpandLastChild),
-																										typeof(bool),
-																										typeof(DockLayout),
-																										true,
-																										propertyChanged: OnShouldExpandLastChildPropertyChanged);
+	[BindableProperty(PropertyChangedMethodName = nameof(OnShouldExpandLastChildPropertyChanged))]
+	public partial bool ShouldExpandLastChild { get; set; } = DockLayoutDefaults.ShouldExpandLastChild;
 
 	/// <summary>
-	/// Horizontal spacing between docked views.
+	/// Gets or sets the horizontal spacing between docked views.
 	/// </summary>
-	public static readonly BindableProperty HorizontalSpacingProperty = BindableProperty.Create(nameof(HorizontalSpacing),
-																									typeof(double),
-																									typeof(DockLayout),
-																									0.0d,
-																									propertyChanged: OnHorizontalSpacingPropertyChanged);
+	[BindableProperty(PropertyChangedMethodName = nameof(OnHorizontalSpacingPropertyChanged))]
+	public partial double HorizontalSpacing { get; set; } = DockLayoutDefaults.HorizontalSpacing;
 
 	/// <summary>
-	/// Vertical spacing between docked views.
+	/// Gets or sets the vertical spacing between docked views.
 	/// </summary>
-	public static readonly BindableProperty VerticalSpacingProperty = BindableProperty.Create(nameof(VerticalSpacing),
-																								typeof(double),
-																								typeof(DockLayout),
-																								0.0d,
-																								propertyChanged: OnVerticalSpacingPropertyChanged);
-
-	/// <inheritdoc/>
-	public bool ShouldExpandLastChild
-	{
-		get => (bool)GetValue(ShouldExpandLastChildProperty);
-		set => SetValue(ShouldExpandLastChildProperty, value);
-	}
-
-	/// <inheritdoc/>
-	public double HorizontalSpacing
-	{
-		get => (double)GetValue(HorizontalSpacingProperty);
-		set => SetValue(HorizontalSpacingProperty, value);
-	}
+	[BindableProperty(PropertyChangedMethodName = nameof(OnVerticalSpacingPropertyChanged))]
+	public partial double VerticalSpacing { get; set; } = DockLayoutDefaults.VerticalSpacing;
 
-	/// <inheritdoc/>
-	public double VerticalSpacing
-	{
-		get => (double)GetValue(VerticalSpacingProperty);
-		set => SetValue(VerticalSpacingProperty, value);
-	}
 
 	/// <summary>
 	/// Gets the docking position for a view.
diff --git a/src/CommunityToolkit.Maui/Layouts/UniformItemsLayout.shared.cs b/src/CommunityToolkit.Maui/Layouts/UniformItemsLayout.shared.cs
@@ -12,49 +12,40 @@ namespace CommunityToolkit.Maui.Layouts;
 public partial class UniformItemsLayout : Layout, IUniformItemsLayout
 {
 	/// <summary>
-	/// Backing BindableProperty for the <see cref="MaxRows"/> property.
+	/// Gets or sets the maximum number of rows to display or process.
 	/// </summary>
-	public static readonly BindableProperty MaxRowsProperty = BindableProperty.Create(nameof(MaxRows), typeof(int), typeof(UniformItemsLayout), int.MaxValue);
+	[BindableProperty(PropertyChangingMethodName = nameof(OnMaxRowsPropertyChanging))]
+	public partial int MaxRows { get; set; } = UniformItemLayoutDefaults.MaxRows;
 
 	/// <summary>
-	/// Backing BindableProperty for the <see cref="MaxColumns"/> property.
+	/// Gets or sets the maximum number of columns to display in the layout.
 	/// </summary>
-	public static readonly BindableProperty MaxColumnsProperty = BindableProperty.Create(nameof(MaxColumns), typeof(int), typeof(UniformItemsLayout), int.MaxValue);
+	/// <remarks>
+	/// Set this property to limit the number of columns arranged by the layout. The value must be greater
+	/// than or equal to 1. The default value is <see cref="int.MaxValue"/>, which allows an unlimited number of
+	/// columns.
+	/// </remarks>
+	[BindableProperty(PropertyChangingMethodName = nameof(OnMaxColumnsPropertyChanging))]
+	public partial int MaxColumns { get; set; } = UniformItemLayoutDefaults.MaxColumns;
 
-	/// <summary>
-	/// Max rows
-	/// </summary>
-	public int MaxRows
+	/// <inheritdoc	/>
+	protected override ILayoutManager CreateLayoutManager() => new UniformItemsLayoutManager(this);
+
+	static void OnMaxRowsPropertyChanging(BindableObject bindable, object oldValue, object newValue)
 	{
-		get => (int)GetValue(MaxRowsProperty);
-		set
+		var maxRows = (int)newValue;
+		if (maxRows < 1)
 		{
-			if (value < 1)
-			{
-				throw new ArgumentOutOfRangeException(nameof(value), value, $"{nameof(MaxRows)} must be greater or equal to 1.");
-			}
-
-			SetValue(MaxRowsProperty, value);
+			throw new ArgumentOutOfRangeException(nameof(newValue), newValue, $"{nameof(MaxRows)} must be greater or equal to 1.");
 		}
 	}
 
-	/// <summary>
-	/// Max columns
-	/// </summary>
-	public int MaxColumns
+	static void OnMaxColumnsPropertyChanging(BindableObject bindable, object oldValue, object newValue)
 	{
-		get => (int)GetValue(MaxColumnsProperty);
-		set
+		var maxColumns = (int)newValue;
+		if (maxColumns < 1)
 		{
-			if (value < 1)
-			{
-				throw new ArgumentOutOfRangeException(nameof(value), value, $"{nameof(MaxColumns)} must be greater or equal to 1.");
-			}
-
-			SetValue(MaxColumnsProperty, value);
+			throw new ArgumentOutOfRangeException(nameof(newValue), newValue, $"{nameof(MaxColumns)} must be greater or equal to 1.");
 		}
 	}
-
-	/// <inheritdoc	/>
-	protected override ILayoutManager CreateLayoutManager() => new UniformItemsLayoutManager(this);
 }

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ Task<string> InternalSaveAsync(string fileName, Stream stream, IProgress<double>`
`12`	`12`	`{`
`13`	`13`	`return InternalSaveAsync("/", fileName, stream, progress, cancellationToken);`
`14`	`14`	`}`
`15`		`-`
	`15`	`+`
`16`	`16`	`async Task<string> InternalSaveAsync(`
`17`	`17`	`string initialPath,`
`18`	`18`	`string fileName,`
`@@ -23,8 +23,8 @@ async Task<string> InternalSaveAsync(`
`23`	`23`	`cancellationToken.ThrowIfCancellationRequested();`
`24`	`24`
`25`	`25`	`var currentViewController = Platform.GetCurrentUIViewController()`
`26`		`- ?? throw new FileSaveException(`
`27`		`- "Cannot present file picker: No active view controller found. Ensure the app is active with a visible window.");`
	`26`	`+ ?? throw new FileSaveException(`
	`27`	`+ "Cannot present file picker: No active view controller found. Ensure the app is active with a visible window.");`
`28`	`28`
`29`	`29`	`var fileManager = NSFileManager.DefaultManager;`
`30`	`30`
`@@ -71,22 +71,22 @@ await WriteStream(`
`71`	`71`	`picker.DidPickDocumentAtUrls -= OnPicked;`
`72`	`72`	`picker.WasCancelled -= OnCancelled;`
`73`	`73`	`}`
`74`		`-`
	`74`	`+`
`75`	`75`	`void OnPicked(object? sender, UIDocumentPickedAtUrlsEventArgs e)`
`76`	`76`	`{`
`77`	`77`	`if (e.Urls.Length is 0)`
`78`	`78`	`{`
`79`	`79`	`tcs.TrySetException(new FileSaveException("No file was selected."));`
`80`	`80`	`return;`
`81`	`81`	`}`
`82`		`-`
	`82`	`+`
`83`	`83`	`var path = e.Urls[0].Path;`
`84`	`84`	`if (path is null)`
`85`	`85`	`{`
`86`	`86`	`tcs.TrySetException(new FileSaveException("File path cannot be null."));`
`87`	`87`	`return;`
`88`	`88`	`}`
`89`		`-`
	`89`	`+`
`90`	`90`	`tcs.TrySetResult(path);`
`91`	`91`	`}`
`92`	`92`
Original file line number	Diff line number	Diff line change
`@@ -14,13 +14,13 @@ Task<Folder> InternalPickAsync(CancellationToken cancellationToken)`
`14`	`14`	`{`
`15`	`15`	`return InternalPickAsync("/", cancellationToken);`
`16`	`16`	`}`
`17`		`-`
	`17`	`+`
`18`	`18`	`async Task<Folder> InternalPickAsync(string initialPath, CancellationToken cancellationToken)`
`19`	`19`	`{`
`20`	`20`	`cancellationToken.ThrowIfCancellationRequested();`
`21`	`21`
`22`	`22`	`var currentViewController = Platform.GetCurrentUIViewController()`
`23`		`- ?? throw new FolderPickerException("Unable to get a window where to present the folder picker UI.");`
	`23`	`+ ?? throw new FolderPickerException("Unable to get a window where to present the folder picker UI.");`
`24`	`24`
`25`	`25`	`var tcs = new TaskCompletionSource<Folder>(`
`26`	`26`	`TaskCreationOptions.RunContinuationsAsynchronously);`
`@@ -44,7 +44,7 @@ async Task<Folder> InternalPickAsync(string initialPath, CancellationToken cance`
`44`	`44`	`picker.DidPickDocumentAtUrls -= OnPicked;`
`45`	`45`	`picker.WasCancelled -= OnCancelled;`
`46`	`46`	`}`
`47`		`-`
	`47`	`+`
`48`	`48`	`void OnPicked(object? sender, UIDocumentPickedAtUrlsEventArgs e)`
`49`	`49`	`{`
`50`	`50`	`if (e.Urls.Length is 0)`
Original file line number	Diff line number	Diff line change
`@@ -111,14 +111,14 @@ public void DefaultUri()`
`111`	`111`	`var gravatarImageSource = new GravatarImageSource();`
`112`	`112`	`Assert.Equal(GravatarImageSourceDefaults.Uri, gravatarImageSource.Uri);`
`113`	`113`	`}`
`114`		`-`
	`114`	`+`
`115`	`115`	`[Fact]`
`116`	`116`	`public void DefaultParentHeight()`
`117`	`117`	`{`
`118`	`118`	`var gravatarImageSource = new GravatarImageSource();`
`119`	`119`	`Assert.Equal(GravatarImageSourceDefaults.ParentHeight, gravatarImageSource.ParentHeight);`
`120`	`120`	`}`
`121`		`-`
	`121`	`+`
`122`	`122`	`[Fact]`
`123`	`123`	`public void DefaultParentWidth()`
`124`	`124`	`{`