[Proposal] Update `LayoutFlags()` Functionality

[brminnick]

Feature name

Update LayoutFlags() Functionality

Progress tracker

• Android Implementation
• iOS Implementation
• MacCatalyst Implementation
• Windows Implementation
• Tizen Implementation
• Unit Tests
• Samples
• Documentation

Summary

Current Functionality

The current functionality of LayoutFlags overwrites any existing AbsoluteLayoutFlags that are already defined by the BindableObject.

For example, the resulting AbosluteLayoutFlag property of the Label in the following sample will be only AbsoluteLayoutFlags.PositionProportional, because the current functionality overwrites any existing AbsoluteLayoutFlag.

new Label() // Final `AbsoluteLayoutFlags` value is `AbsoluteLayoutFlags.PositionProportional`
  .LayoutFlags(AbsoluteLayoutFlags.SizeProportional)
  .LayoutFlags(AbsoluteLayoutFlags.PositionProportional)  // Overwrites existing `AbsoluteLayoutFlags`

Updated Functionality

The updated functionality of LayoutFlags will append the incoming AbsoluteLayoutFlags to every existing AbsoluteLayoutFlags.

For example, the resulting AbosluteLayoutFlag property of the Label in the following sample will be AbsoluteLayoutFlags.PositionProportional | AbsoluteLayoutFlags.PositionProportional, because the incoming value combined with any existing AbsoluteLayoutFlag values using a bitwise OR operator.

new Label() // Final `AbsoluteLayoutFlags` value is `AbsoluteLayoutFlags.PositionProportional | AbsoluteLayoutFlags.SizeProportional `
  .LayoutFlags(AbsoluteLayoutFlags.SizeProportional)
  .LayoutFlags(AbsoluteLayoutFlags.PositionProportional)  // Combined with existing `AbsoluteLayoutFlags`

Motivation

Updating the functionality of .LayoutFlags() to append the AbsoluteLayoutFlags input allows the ability to chain multiple LayoutFlags() methods together without overriding previous AbsoluteLayoutFlags

Detailed Design

///

/// Set an that indicates whether the layout bounds position and size values for a child are proportional to the size of the .
/// Appends to existing
///

///
/// To clear existing , use
///
///
///
///
///
public static TBindable LayoutFlags(this TBindable bindable, AbsoluteLayoutFlags flag) where TBindable : BindableObject
{
var currentFlags = AbsoluteLayout.GetLayoutFlags(bindable);

AbsoluteLayout.SetLayoutFlags(bindable, currentFlags | flag);
return bindable;
}

Usage Syntax

new Image().Source("dotnet_bot.png").Opacity(0.25).IsOpaque(false).Aspect(Aspect.AspectFit)
  .LayoutFlags(AbsoluteLayoutFlags.SizeProportional)
  .LayoutFlags(AbsoluteLayoutFlags.PositionProportional)
  .LayoutBounds(0.5, 0.5, 0.5, 0.5);

Drawbacks

There is one drawback to updating the LayoutFlags functionality: no other fluent extension method in CommunityToolkit.Maui.Markup appends the input; every other fluent API overwrites the existing property.

That being said appending the value of AbsoluteLayoutFlags does feel natural and does feel appropriate. Whereas, for other fluent APIs, like .BackgroundColor(), appending the input to the existing settings is not intuitive and does not make much sense.

Alternatives

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

.LayoutFlags(AbsoluteLayoutFlags.XProportional | AbsoluteLayoutFlags.WidthProportional)

Unresolved Questions

None