ICanvas.cs

using System.Numerics;
using Microsoft.Maui.Graphics.Text;

namespace Microsoft.Maui.Graphics
{
	/// <summary>
	/// Represents a platform-agnostic canvas on which 2D graphics can be drawn using types from the <see cref="Microsoft.Maui.Graphics"/> namespace.
	/// </summary>
	public interface ICanvas
	{
		/// <summary>
		/// Gets or sets a value that represents the scaling factor to scale the UI by. 
		/// </summary>
		public float DisplayScale { get; set; }

		/// <summary>
		/// Sets the width of the stroke used to draw an object's outline.
		/// </summary>
		public float StrokeSize { set; }

		/// <summary>
		/// Sets the limit of the miter length of line joins in an object.
		/// </summary>
		public float MiterLimit { set; }

		/// <summary>
		/// Sets the <see cref="Color"/> used to paint an object's outline.
		/// </summary>
		public Color StrokeColor { set; }

		/// <summary>
		/// Sets the shape at the start and end of a line.
		/// </summary>
		public LineCap StrokeLineCap { set; }

		/// <summary>
		/// Sets the type of join used at the vertices of a shape.
		/// </summary>
		public LineJoin StrokeLineJoin { set; }

		/// <summary>
		/// Sets the pattern of dashes and gaps that are used to outline an object.
		/// </summary>
		public float[] StrokeDashPattern { set; }

		/// <summary>
		/// Sets the distance within the dash pattern where a dash begins.
		/// </summary>
		public float StrokeDashOffset { set; }

		/// <summary>
		/// Sets the color used to paint an object's interior.
		/// </summary>
		public Color FillColor { set; }

		/// <summary>
		/// Sets the font color when drawing text.
		/// </summary>
		public Color FontColor { set; }

		/// <summary>
		/// Sets the font used when drawing text.
		/// </summary>
		public IFont Font { set; }

		/// <summary>
		/// Sets the size of the font used when drawing text.
		/// </summary>
		public float FontSize { set; }

		/// <summary>
		/// Sets the opacity of am object.
		/// </summary>
		public float Alpha { set; }

		/// <summary>
		/// Sets a value that indicates whether to use anti-aliasing is enabled.
		/// </summary>
		public bool Antialias { set; }

		/// <summary>
		/// Sets the blend mode, which determines what happens when an object is rendered on top of an existing object.
		/// </summary>
		public BlendMode BlendMode { set; }

		/// <summary>
		/// Draws the specified <paramref name="path"/> onto the canvas.
		/// </summary>
		/// <param name="path">The path to be drawn.</param>
		public void DrawPath(PathF path);

		/// <summary>
		/// Draws and fills the specified <paramref name="path"/> onto the canvas.
		/// </summary>
		/// <param name="path">The path to be drawn.</param>
		/// <param name="windingMode">The fill algorithm to be used.</param>
		public void FillPath(PathF path, WindingMode windingMode);

		/// <summary>
		/// Clips an object so that only the area outside the of a rectangle will be visible.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate of the rectangle.</param>
		/// <param name="y">Starting <c>y</c> coordinate of the rectangle.</param>
		/// <param name="width">Width of the rectangle.</param>
		/// <param name="height">Height of the rectangle.</param>
		public void SubtractFromClip(float x, float y, float width, float height);

		/// <summary>
		/// Clips an object so that only the area outside of a <see cref="PathF"/> object will be visible.
		/// </summary>
		/// <param name="path">The path used to clip the object</param>
		/// <param name="windingMode">Fill algorithm used for the path. Default is <see cref="WindingMode.NonZero"/>.</param>
		public void ClipPath(PathF path, WindingMode windingMode = WindingMode.NonZero);

		/// <summary>
		/// Clips an object so that only the area that's within the region of the rectangle will be visible.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate of the rectangle.</param>
		/// <param name="y">Starting <c>y</c> coordinate of the rectangle.</param>
		/// <param name="width">Width of the rectangle.</param>
		/// <param name="height">Height of the rectangle.</param>
		public void ClipRectangle(float x, float y, float width, float height);

		/// <summary>
		/// Draws a line between two points onto the canvas.
		/// </summary>
		/// <param name="x1">Starting <c>x</c> coordinate.</param>
		/// <param name="y1">Starting <c>y</c> coordinate.</param>
		/// <param name="x2">Ending <c>x</c> coordinate.</param>
		/// <param name="y2">Ending <c>x</c> coordinate.</param>
		public void DrawLine(float x1, float y1, float x2, float y2);

		/// <summary>
		/// Draws an arc onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the arc.</param>
		/// <param name="height">Height of the arc.</param>
		/// <param name="startAngle">The angle from the x-axis to the start point of the arc.</param>
		/// <param name="endAngle">The angle from the x-axis to the end point of the arc.</param>
		/// <param name="clockwise"><see langword="true"/> to draw the arc in a clockwise direction; <see langword="false"/> to draw the arc counterclockwise.</param>
		/// <param name="closed"><see langword="true"/> to specify whether the end point of the arc will be connected to the start point; <see langword="false"/> otherwise.</param>
		public void DrawArc(float x, float y, float width, float height, float startAngle, float endAngle, bool clockwise, bool closed);

		/// <summary>
		/// Draws a filled arc onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the arc.</param>
		/// <param name="height">Height of the arc.</param>
		/// <param name="startAngle">The angle from the x-axis to the start point of the arc.</param>
		/// <param name="endAngle">The angle from the x-axis to the end point of the arc.</param>
		/// <param name="clockwise"><see langword="true"/> to draw the arc in a clockwise direction; <see langword="false"/> to draw the arc counterclockwise.</param>
		public void FillArc(float x, float y, float width, float height, float startAngle, float endAngle, bool clockwise);

		/// <summary>
		/// Draws a rectangle onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the rectangle.</param>
		/// <param name="height">Height of the rectangle.</param>
		public void DrawRectangle(float x, float y, float width, float height);

		/// <summary>
		/// Draws a filled rectangle onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the rectangle.</param>
		/// <param name="height">Height of the rectangle.</param>
		public void FillRectangle(float x, float y, float width, float height);

		/// <summary>
		/// Draws a rectangle with rounded corners onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the rectangle.</param>
		/// <param name="height">Height of the rectangle.</param>
		/// <param name="cornerRadius">The radius used to round the corners of the rectangle.</param>
		public void DrawRoundedRectangle(float x, float y, float width, float height, float cornerRadius);

		/// <summary>
		/// Draws a filled rectangle with rounded corners onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the rectangle.</param>
		/// <param name="height">Height of the rectangle.</param>
		/// <param name="cornerRadius">The radius used to round the corners of the rectangle.</param>
		public void FillRoundedRectangle(float x, float y, float width, float height, float cornerRadius);

		/// <summary>
		/// Draws an ellipse onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the ellipse.</param>
		/// <param name="height">Height of the ellipse.</param>
		public void DrawEllipse(float x, float y, float width, float height);

		/// <summary>
		/// Draws a filled ellipse onto the canvas.
		/// </summary>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="width">Width of the ellipse.</param>
		/// <param name="height">Height of the ellipse.</param>
		public void FillEllipse(float x, float y, float width, float height);

		/// <summary>
		/// Draws a text string onto the canvas.
		/// </summary>
		/// <remarks>To draw attributed text, use <see cref="DrawText(IAttributedText, float, float, float, float)"/> instead.</remarks>
		/// <param name="value">Text to be displayed.</param>
		/// <param name="x">Starting <c>x</c> coordinate.</param>
		/// <param name="y">Starting <c>y</c> coordinate.</param>
		/// <param name="horizontalAlignment">Horizontal alignment options to align the string.</param>
		public void DrawString(string value, float x, float y, HorizontalAlignment horizontalAlignment);

		/// <summary>
		/// Draws a text string within a bounding box onto the canvas.
		/// </summary>
		/// <param name="value">Text to be displayed.</param>
		/// <param name="x">Starting <c>x</c> coordinate of the bounding box.</param>
		/// <param name="y">Starting <c>y</c> coordinate of the bounding box.</param>
		/// <param name="width">Width of the bounding box.</param>
		/// <param name="height">Height of the bounding box.</param>
		/// <param name="horizontalAlignment">Horizontal alignment options to align the string within the bounding box.</param>
		/// <param name="verticalAlignment">Vertical alignment options to align the string within the bounding box.</param>
		/// <param name="textFlow">Specifies whether text will be clipped in case it overflows the bounding box. Default is <see cref="TextFlow.ClipBounds"/>.</param>
		/// <param name="lineSpacingAdjustment">Spacing adjustment between lines. Default is 0.</param>
		public void DrawString(
			string value,
			float x,
			float y,
			float width,
			float height,
			HorizontalAlignment horizontalAlignment,
			VerticalAlignment verticalAlignment,
			TextFlow textFlow = TextFlow.ClipBounds,
			float lineSpacingAdjustment = 0);

		/// <summary>
		/// Draws attributed text within a bounding box onto the canvas.
		/// </summary>
		/// <param name="value">Attributed text to be displayed.</param>
		/// <param name="x">Starting <c>x</c> coordinate of the bounding box.</param>
		/// <param name="y">Starting <c>y</c> coordinate of the bounding box.</param>
		/// <param name="width">Width of the bounding box.</param>
		/// <param name="height">Height of the bounding box.</param>
		public void DrawText(
			IAttributedText value,
			float x,
			float y,
			float width,
			float height);

		/// <summary>
		/// Rotates a graphical object around a point.
		/// </summary>
		/// <remarks>Rotation is clockwise for increasing angles. Negative angles and angles greater than 360 are allowed.</remarks>
		/// <param name="degrees">Rotation angle.</param>
		/// <param name="x"><c>x</c> coordinate of the rotation point.</param>
		/// <param name="y"><c>y</c> coordinate of the rotation point.</param>
		public void Rotate(float degrees, float x, float y);

		/// <summary>
		/// Rotates a graphical object around the upper-left corner of the canvas (0,0).
		/// </summary>
		/// <remarks>Rotation is clockwise for increasing angles. Negative angles and angles greater than 360 are allowed.</remarks>
		public void Rotate(float degrees);


		/// <summary>
		/// Changes the size of a graphical object by scaling it.
		/// </summary>
		/// <remarks>Can cause starting coordinates to move when an object is made larger.</remarks>
		/// <param name="sx">Value for horizontal scaling.</param>
		/// <param name="sy">Value for vertical scaling.</param>
		public void Scale(float sx, float sy);

		/// <summary>
		/// Shifts a graphical object in horizontal and vertical directions.
		/// </summary>
		/// <param name="tx">Horizontal shift. Negative values move the object to the left, while positive values move it to the right.</param>
		/// <param name="ty">Vertical shift. Negative values move the object down, while positive values move it up.</param>
		public void Translate(float tx, float ty);

		/// <summary>
		/// Applies transformation specified by <paramref name="transform"/> to a graphical object.
		/// </summary>
		/// <param name="transform">Affine transformation matrix.</param>
		public void ConcatenateTransform(Matrix3x2 transform);

		/// <summary>
		/// Saves the current graphics state.
		/// </summary>
		public void SaveState();

		/// <summary>
		/// Restores the graphics state to the most recently saved state.
		/// </summary>
		/// <returns><see langword="true"/> if the restore was succesful, <see langword="false"/> otherwise.</returns>
		public bool RestoreState();

		/// <summary>
		/// Resets the graphics state to its default values.
		/// </summary>
		public void ResetState();

		/// <summary>
		/// Adds a shadow to a graphical object.
		/// </summary>
		/// <param name="offset">Represents the position of a light source that creates the shadow.</param>
		/// <param name="blur">Amount of blur to apply to the shadow.</param>
		/// <param name="color">Color of the shadow.</param>
		public void SetShadow(SizeF offset, float blur, Color color);

		/// <summary>
		/// Sets <paramref name="paint"/> as the fill of a graphical object.
		/// </summary>
		/// <param name="paint">Paint to set as fill</param>
		/// <param name="rectangle">Rectangle to apply a gradient on if the <paramref name="paint"/> supports it.</param>
		public void SetFillPaint(Paint paint, RectF rectangle);

		/// <summary>
		/// Draws an image onto the canvas.
		/// </summary>
		/// <param name="image">Image to display</param>
		/// <param name="x">Top left corner <c>x</c> coordinate.</param>
		/// <param name="y">Top left corner <c>y</c> coordinate.</param>
		/// <param name="width">Width of the image.</param>
		/// <param name="height">Height of the image.</param>
		public void DrawImage(IImage image, float x, float y, float width, float height);

		/// <summary>
		/// Calculates the area a string would occupy if drawn on the canvas.
		/// </summary>
		/// <param name="value">String to calculate the size on.</param>
		/// <param name="font">The string's font type.</param>
		/// <param name="fontSize">The string's font size.</param>
		/// <returns>The area the string would occupy on the canvas.</returns>
		public SizeF GetStringSize(string value, IFont font, float fontSize);

		/// <summary>
		/// Calculates the area a string would occupy if drawn on the canvas.
		/// </summary>
		/// <param name="value">String to calculate the size on.</param>
		/// <param name="font">The string's font type.</param>
		/// <param name="fontSize">The string's font size.</param>
		/// <param name="horizontalAlignment">Horizontal alignment options for the string.</param>
		/// <param name="verticalAlignment">Vertical alignment options for the string.</param>
		/// <returns>The area the string would occupy on the canvas.</returns>
		public SizeF GetStringSize(string value, IFont font, float fontSize, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment);
	}
}