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

[VladislavAntonyuk]

What do you think about moving parameters in Options class?
So new method signature looks like this:

Suggested change

	public static ValueTask<Stream> GetImageStream(IList<PointF> points, Size desiredSize, float lineWidth, Color strokeColor, Paint? background, CancellationToken token = default) =>
	public static ValueTask<Stream> GetImageStream(IList<PointF> points, ImageOptions options, CancellationToken token = default)

In this case we may easily extend image options without breaking changes.

[bijington]

Great idea!