Enhance DrawingView and DrawingViewService to provide the ability to export the full image size

[bijington]

Description of Change

The aim of this PR is to allow developers to export their drawings in multiple ways:

• The current approach which only exports the lines with a tiny amount of padding
• The full canvas to fully represent what was on screen

The following image shows the result in the Files app in the simulator on iOS based on using the sample application from the toolkit.

The change allows a developer to provide an ImageOutputOption value to the DrawingView:

/// <summary>
/// Enumeration of the options available when generating an image stream using the DrawingView.
/// </summary>
public enum DrawingViewOutputOption
{
	/// <summary>
	/// Outputs the area covered by the top-left to the bottom-right most points.
	/// </summary>
	Lines,
	
	/// <summary>
	/// Outputs the full area displayed within the drawing view.
	/// </summary>
	FullCanvas
}

This will then pass into the DrawingViewService the bounds of the current DrawingView. Developers can then also supply their out dimensions should they wish to the DrawingViewService.

Linked Issues

• Fixes DrawingView.GetImageStream Size has no affect #1397

PR Checklist

• Has a linked Issue, and the Issue has been approved(bug) or Championed (feature/proposal)
• Has tests (if omitted, state reason in description)
• Has samples (if omitted, state reason in description)
• Rebased on top of main at time of PR
• Changes adhere to coding standard
• Documentation created or updated: Include the details surrounding the new overloads for GetImageStream MicrosoftDocs/CommunityToolkit#469

Additional information

[bijington]

@VladislavAntonyuk what do you think to this approach to enable developers to export the whole canvas should they wish?

It needs to be completed for all platforms but I have the PoC working for Apple platforms

[VladislavAntonyuk]

Thanks @bijington , looks good. What do you think about renaming imageSize to lineBounds? Because ImageSize and CanvasSize may be confused.

[bijington]

@VladislavAntonyuk great idea! I will carry on then and include that suggestion thanks.

Also sadly I can't work out how to make this non breaking so I'll add the breaking label

[VladislavAntonyuk]

To make it not a breaking change, we can move the canvasSize parameter to the last position, but it's not good to have something after CancellationToken. However, I don't think it's a problem as we had breaking changes before. We can probably merge it with .net 9 support

[bijington]

To make it not a breaking change, we can move the canvasSize parameter to the last position, but it's not good to have something after CancellationToken. However, I don't think it's a problem as we had breaking changes before. We can probably merge it with .net 9 support

I did originally try that but one of our analysis rules complained as it is 'best practise' to keep the CancellationToken parameter at the end.

[bijington]

Or I guess rather than a default parameter we have an overload and therefore the current behaviour will stay as the default... That might work

[bijington]

The latest push removes the breaking nature of this PR

[bijington]

FYI I haven't tested Android, Windows or Tizen yet. The last 2 I wrote on a Mac so I don't even know if it compiles yet...

[bijington]

I am unable to test on Windows or Tizen right now as my home network is down while we do some renovations. If anyone can test either platform that would be really helpful. Otherwise I will move onto the docs

Copilot reviewed 5 out of 15 changed files in this pull request and generated no suggestions.

Files not reviewed (10)

• samples/CommunityToolkit.Maui.Sample/Pages/Views/DrawingViewPage.xaml: Language not supported
• samples/CommunityToolkit.Maui.Sample/Pages/Views/DrawingViewPage.xaml.cs: Evaluated as low risk
• samples/CommunityToolkit.Maui.Sample/ViewModels/Views/DrawingViewViewModel.cs: Evaluated as low risk
• src/CommunityToolkit.Maui.Core/Interfaces/IDrawingLine.shared.cs: Evaluated as low risk
• src/CommunityToolkit.Maui.Core/Interfaces/IDrawingView.shared.cs: Evaluated as low risk
• src/CommunityToolkit.Maui.Core/Primitives/DrawingViewOutputOption.shared.cs: Evaluated as low risk
• src/CommunityToolkit.Maui.Core/Views/DrawingView/DrawingLine.shared.cs: Evaluated as low risk
• src/CommunityToolkit.Maui.Core/Views/DrawingView/Service/DrawingViewService.android.cs: Evaluated as low risk
• src/CommunityToolkit.Maui.Core/Views/DrawingView/Service/DrawingViewService.macios.cs: Evaluated as low risk
• src/CommunityToolkit.Maui.Core/Views/DrawingView/Service/DrawingViewService.net.cs: Evaluated as low risk

[ne0rrmatrix]

Looks well done! I have tested in Windows, Android, and IOS. It works as intended. I have noticed you have implemented an options class which tidies things up a lot. That works well and makes things look clean. I have a few suggestions for fixing the tests.

On line 105 in DrawingLineTests.cs I would replace

var stream = await DrawingLine.GetImageStream(Array.Empty<PointF>(), new Size(10, 10), 5, Colors.Yellow, Colors.Blue.AsPaint(), CancellationToken.None);

with

ImagePointOptions pointOptions = new([], Size.Zero, 0, Colors.Transparent, new SolidPaint(Colors.Transparent), Size.Zero);
var stream = await DrawingLine.GetImageStream(pointOptions, CancellationToken.None); 

Line 162 in DrawingViewTests.cs I would replace

await Assert.ThrowsAsync<OperationCanceledException>(async () => await DrawingView.GetImageStream([new DrawingLine()], Size.Zero, Colors.Blue, cts.Token));  

with

ImageLineOptions options = ImageLineOptions.JustLines([new DrawingLine()], Size.Zero, new SolidPaint(Colors.Transparent));
await Assert.ThrowsAsync<OperationCanceledException>(async () => await DrawingView.GetImageStream(options, cts.Token)); 

On line 173 to 175 of the same file I would replace:

await Assert.ThrowsAsync<OperationCanceledException>(async () => await DrawingView.GetImageStream([
			new DrawingLine()
		], Size.Zero, Colors.Blue, cts.Token)); 

with:

ImageLineOptions options = ImageLineOptions.JustLines([new DrawingLine()], Size.Zero, new SolidPaint(Colors.Transparent));
await Assert.ThrowsAsync<OperationCanceledException>(async () => await DrawingView.GetImageStream(options, cts.Token));  

This will fix the unit tests. Once you have fixed the unit tests I would say this is good to go. I would be happy to approve it. I can't test for tizen as I do not believe it supports dotnet 9 at all atm? I think they are still on dotnet 8?

[ne0rrmatrix]

Good Catch on tizen. The fixes for tests look good. the tests passed locally. I am happy to approve this now.

[ne0rrmatrix]

Approved. Can't wait for this to be merged. Excited to see this in the Community toolkit! I ran the unit test changes through a local test loop for a bit to see if there would be any issues. None to be found!