[iOS] Fix downscaled images not occupying correct space

[jknaudt21]

Problem

Large iOS images would not honor their layout's specified height/width nor would they display in a way that's consistent with Android and Windows.

The problem is caused by a limitation in iOS. When calling SizeThatFits for an ImageView, the function will always return the image's dimensions regardless of what the user constrains. This is by design from Apple

This also affected image buttons.

Solution

We create our own extension method that calculates "SizeThatFits" in a way that respects the View's given constraints. When the Aspect is equal to AspectFit, we calculate the how much we need to scale down the image based on the smallest dimension that fit the image. Otherwise, we just return the original constraints.

Keep in mind that this custom implementation of "SizeThatFits" is only used for calculating space needed by the view. It does not calculate the size of the image that's inside the view; we leave that to the native ContentMode (aka the Aspect settings).

Issue Before & After Screenshots (Catalyst & iOS)

I didn't include screenshots for every issue that was reported regarding this topic because there were too many as this was a pretty significant issue.

16120 (click me!)

    <ScrollView>
        <VerticalStackLayout>
            <Image Source="tree_big.jpg" x:Name="tree" Aspect="AspectFit" BackgroundColor="AliceBlue"/>
        </VerticalStackLayout>
    </ScrollView>

Before	After

14139 (click me!)

    <ScrollView>
        <VerticalStackLayout Spacing="25" HorizontalOptions="FillAndExpand" VerticalOptions="FillAndExpand">
            <Grid>
                <Image
                    Source="image1.png"
                    Aspect="AspectFit"
                    HorizontalOptions="FillAndExpand"
                    VerticalOptions="Start"
                    BackgroundColor="Yellow"/>
                <Border HorizontalOptions="FillAndExpand" VerticalOptions="FillAndExpand" Stroke="Red" StrokeThickness="4" StrokeShape="RoundRectangle 10,10,10,10" BackgroundColor="Transparent" Margin="0" Padding="0" />
            </Grid>
        </VerticalStackLayout>
    </ScrollView>

Before	After

16921 (click me!)

(See the sample given in #16921)

iOS and Mac ran the same but I'm only including the Mac recording. Note that the small blue "button" shows how the large image should actually behave. This is because the "button" is actually a non-downscaled image.
Before

Screen.Recording.2023-08-31.at.5.55.46.PM.mov

After

Screen.Recording.2023-08-31.at.5.50.20.PM.mov

14926 (click me!)

        <Grid ColumnDefinitions="Auto,*,Auto" Margin="10">
            <Button
                VerticalOptions="Center"
                Margin="15,0,0,0"
                Text="One" />
            <Image
                BackgroundColor="Green"
                Grid.Column="1"
                HeightRequest="76"
                HorizontalOptions="Center"
                Source="logo_dark.png" />
            <Button
                Margin="0,0,15,0"
                VerticalOptions="Center"
                Grid.Column="2"
                Text="Two" />
        </Grid>

Note The green box is supposed to "overflow" to fulfill the grid's * width requirement. It is not meant to overlap with other buttons, however.

Before	After

13893 (click me!)

See customer sample in linked issue

There were many samples here, but they boiled down to similar problems, shown in the view below.

Before	After

Issues Fixed

Fixes #16120
Fixes #14139
Fixes #16921
Fixes #14606
Fixes #13893
Fixes #14926
Fixes #10481
Fixes #12359

Work Remaining

• Write tests
• Include screenshots
• Solve specific case for ImageButtons
• Fix tests

[jknaudt21]

Images.zip
To make testing this PR easier for reviewers I'm uploading the images folder

[tj-devel709]

Sorry! I tested out all the attached scenarios and a few alterations locally previously and they all looked good to me!

[mattleibow]

Is it possible to add some image comparison tests? The current tests look like they just check for "is this color somewhere" and that will not catch much.

[mattleibow]

For tests:

maui/src/Controls/tests/UITests/Tests/Issues/Issue15330.cs

Lines 16 to 23 in e25d331

	public void Issue15330Test()
	{
	this.IgnoreIfPlatforms(new TestDevice[] { TestDevice.iOS },
	"Currently fails on iOS; see https://github.com/dotnet/maui/issues/17125");
	App.WaitForElement("WaitForStubControl");
	VerifyScreenshot();
	}

maui/src/Controls/tests/DeviceTests/Elements/Label/LabelTests.cs

Lines 288 to 323 in e25d331

	public async Task FormattedStringSpanTextHasCorrectLayoutWhenAligned(TextAlignment alignment)
	{
	var formattedLabel = new Label
	{
	WidthRequest = 200,
	HeightRequest = 50,
	HorizontalTextAlignment = alignment,
	FormattedText = new FormattedString
	{
	Spans =
	{
	new Span { Text = "short" },
	new Span { Text = " long second string"}
	}
	},
	};
	var normalLabel = new Label
	{
	WidthRequest = 200,
	HeightRequest = 50,
	HorizontalTextAlignment = alignment,
	Text = "short long second string"
	};
	await InvokeOnMainThreadAsync(async () =>
	{
	var formattedHandler = CreateHandler<LabelHandler>(formattedLabel);
	var formattedBitmap = await formattedHandler.PlatformView.ToBitmap(MauiContext);
	var normalHandler = CreateHandler<LabelHandler>(normalLabel);
	var normalBitmap = await normalHandler.PlatformView.ToBitmap(MauiContext);
	await normalBitmap.AssertEqualAsync(formattedBitmap);
	});
	}

[mattleibow]

I missed the image size tests, so this is OK for now

[mattleibow]

/backport to release/8.0.1xx-rc2.1

[github-actions]

Started backporting to release/8.0.1xx-rc2.1: https://github.com/dotnet/maui/actions/runs/6593944764