[Proposal] Add AbsoluteLayout Flags Extension Methods

[brminnick]

Feature name

Update AbsoluteLayout Flags Extensions

Progress tracker

• Android Implementation
• iOS Implementation
• MacCatalyst Implementation
• Windows Implementation
• Tizen Implementation
• Unit Tests
• Samples
• Documentation: Update AbsoluteLayoutFlags Functionality MicrosoftDocs/CommunityToolkit#271

Summary

This Proposal adds two new APIs to AbsoluteLayoutExtensions and updates the functionality of the existing .LayoutFlags() API to add existing AbsoluteLayoutFlags instead of overwriting existing AbsoluteLayoutFlags.

public static TBindable ClearLayoutFlags<TBindable>(this TBindable bindable) where TBindable : BindableObject;

public static TBindable LayoutFlags<TBindable>(this TBindable bindable, params AbsoluteLayoutFlags[] flags) where TBindable : BindableObject;

Motivation

1. .ClearLayoutFlags()

public static TBindable ClearLayoutFlags<TBindable>(this TBindable bindable) where TBindable : BindableObject;

Adding .ClearLayoutFlags() allows developers to easily remove any existing AbsoluteLayoutFlags using fluent APIs.

2. .LayoutFlags()

public static TBindable LayoutFlags<TBindable>(this TBindable bindable, params AbsoluteLayoutFlags[] flags) where TBindable : BindableObject;

Allowing this new .LayoutFlags() API helps developers (especially new developers) who may be unfamiliar with using Bitwise OR operator. This new API allows developers to pass in multiple AbsoluteLayoutFlags by listing them sequentially which provides a more natural feel and may be what some developers expect, like so:

new Label()
  .LayoutFlags(AbsoluteLayoutFlags.XProportional, AbsoluteLayoutFlags.WidthProportional)

Detailed Design

/// <summary>
/// Removes all <see cref="AbsoluteLayoutFlags"/>, reverting to the default configuraion of <see cref="AbsoluteLayoutFlags.None"/>.
/// </summary>
/// <typeparam name="TBindable"></typeparam>
/// <param name="bindable"></param>
/// <returns></returns>
public static TBindable ClearLayoutFlags<TBindable>(this TBindable bindable) where TBindable : BindableObject
{
  AbsoluteLayout.SetLayoutFlags(bindable, AbsoluteLayoutFlags.None);
  return bindable;
}

/// <summary>
/// Set an <see cref="AbsoluteLayoutFlags"/> that indicates whether the layout bounds position and size values for a child are proportional to the size of the <see cref="AbsoluteLayout"/>.
/// </summary>
/// <typeparam name="TBindable"></typeparam>
/// <param name="bindable"></param>
/// <param name="flags"></param>
/// <returns></returns>
public static TBindable LayoutFlags<TBindable>(this TBindable bindable, params AbsoluteLayoutFlags[] flags) where TBindable : BindableObject
{
  var newFlags = AbsoluteLayoutFlags.None;
  
  foreach(var flag in flags)
  {
	  newFlags |= flag;
  }
  
  AbsoluteLayout.SetLayoutFlags(bindable, newFlags);

  return bindable;
}

Usage Syntax

using Microsoft.Maui.Layouts;

namespace CommunityToolkit.Maui.Markup.Sample.Pages;

sealed class SettingsPage : BaseContentPage<SettingsViewModel>
{
	public SettingsPage(SettingsViewModel settingsViewModel) : base(settingsViewModel, "Settings")
	{
		Content = new AbsoluteLayout
		{
			Children =
			{
				new Image().Source("dotnet_bot.png").Opacity(0.25).IsOpaque(false).Aspect(Aspect.AspectFit)
					.ClearLayoutFlags()
					.LayoutFlags(AbsoluteLayoutFlags.SizeProportional | AbsoluteLayoutFlags.PositionProportional)
					.LayoutBounds(0.5, 0.5, 0.5, 0.5)
					.AutomationIsInAccessibleTree(false),

				new Label()
					.Text("Top Stories To Fetch")
					.AppThemeBinding(Label.TextColorProperty,AppStyles.BlackColor, AppStyles.PrimaryTextColorDark)
					.LayoutFlags(AbsoluteLayoutFlags.XProportional | AbsoluteLayoutFlags.WidthProportional)
					.LayoutBounds(0, 0, 1, 40)
					.TextCenterHorizontal()
					.TextBottom()
					.Assign(out Label topNewsStoriesToFetchLabel),

				new Entry { Keyboard = Keyboard.Numeric }
					.BackgroundColor(Colors.White)
					.Placeholder($"Provide a value between {SettingsService.MinimumStoriesToFetch} and {SettingsService.MaximumStoriesToFetch}", Colors.Grey)
					.LayoutFlags(AbsoluteLayoutFlags.XProportional, AbsoluteLayoutFlags.WidthProportional)
					.LayoutBounds(0.5, 45, 0.8, 40)
					.Behaviors(new NumericValidationBehavior
					{
						Flags = ValidationFlags.ValidateOnValueChanged,
						MinimumValue = SettingsService.MinimumStoriesToFetch,
						MaximumValue = SettingsService.MaximumStoriesToFetch,
						ValidStyle = AppStyles.ValidEntryNumericValidationBehaviorStyle,
						InvalidStyle = AppStyles.InvalidEntryNumericValidationBehaviorStyle,
					})
					.TextCenter()
					.SemanticDescription(topNewsStoriesToFetchLabel.Text)
					.Bind(Entry.TextProperty, static (SettingsViewModel vm) => vm.NumberOfTopStoriesToFetch, static (SettingsViewModel vm, int text) => vm.NumberOfTopStoriesToFetch = text),

				new Label()
					.Bind(
						Label.TextProperty,
						binding1: new Binding { Source = SettingsService.MinimumStoriesToFetch },
						binding2: new Binding { Source = SettingsService.MaximumStoriesToFetch },
						convert: ((int minimum, int maximum) values) => string.Format(CultureInfo.CurrentUICulture, $"The number must be between {values.minimum} and {values.maximum}."),
						mode: BindingMode.OneTime)
					.LayoutFlags(AbsoluteLayoutFlags.XProportional | AbsoluteLayoutFlags.WidthProportional)
					.LayoutBounds(0, 90, 1, 40)
					.TextCenter()
					.AppThemeColorBinding(Label.TextColorProperty,AppStyles.BlackColor, AppStyles.PrimaryTextColorDark)
					.Font(size: 12, italic: true)
					.SemanticHint($"The minimum and maximum possible values for the {topNewsStoriesToFetchLabel.Text} field above.")
			}
		};
	}
}

Drawbacks

None

Alternatives

To clear existing AbsoluteLayoutFlags, a developer can use the existing method:

.LayoutFlags(AbsoluteLayoutFlags.None)

To add multiple AbsoluteLayoutFlags, a developer can use the existing method:

.LayoutFlags(AbsoluteLayoutFlags.XProportional | AbsoluteLayoutFlags.WidthProportional)

[VladislavAntonyuk]

approve

[brminnick]

I approve this feature ✅

[bijington]

Approve

[ghost]

Reopening Proposal.

Only Proposals moved to the Closed Project Column and Completed Project Column can be closed.