Skip to content

Latest commit

 

History

History
140 lines (105 loc) · 5.16 KB

README.md

File metadata and controls

140 lines (105 loc) · 5.16 KB
Raw

Excubo.Blazor.Canvas

Nuget Nuget GitHub

Excubo.Blazor.Canvas is wrapper library around the HTML canvas API. It is written purely in C# (i.e., there is absolutely no javascript code you need to add to your project).

Demo on github.io using Blazor Webassembly

How to use

1. Install the nuget package Excubo.Blazor.Canvas

Excubo.Blazor.Canvas is distributed via nuget.org. Nuget

Package Manager:

Install-Package Excubo.Blazor.Canvas

.NET Cli:

dotnet add package Excubo.Blazor.Canvas

Package Reference

<PackageReference Include="Excubo.Blazor.Canvas" />

2. Use a canvas, or the helper component Canvas

@using Excubo.Blazor.Canvas

<Canvas @ref="helper_canvas" width="150px" height="300px" />
<!--OR-->
@inject Microsoft.JSInterop.IJSRuntime js;
<canvas @ref="normal_canvas" width="600px" height="300px"></canvas>
@code {
    private Canvas helper_canvas;
    private ElementReference normal_canvas;
    protected override async Task OnAfterRenderAsync(bool first_render)
    {
        if (first_render)
        {
            await using (var ctx1 = await helper_canvas.GetContext2DAsync())
            {
                await ctx1.FontAsync("48px solid");
                await ctx1.FillTextAsync("Hello", 0, 150);
            }
            await using (var ctx2 = await js.GetContext2DAsync(normal_canvas))
            {
                await ctx2.FontAsync("48px serif");
                await ctx2.StrokeTextAsync("Excubo.Blazor.Canvas", 0, 150);
            }
        }
    }
}

Have a look at the fully working examples provided in the sample project. A demo is available here.

JS naming convention

You want to use the canvas API in C# and use the same method names as you would in javascript? No problem! Starting with v2.0.0 of Excubo.Blazor.Canvas, you can write context.JS instead of context and you'll have what you're used to. Note that this is only a different name. The cost of the method calls are still the same and every call is still async and therefore should be awaited.

// C# naming convention
await using (var ctx = await helper_canvas.GetContext2DAsync())
{
    await ctx.FontAsync("48px solid");
    await ctx.FillTextAsync("Hello", 0, 150);
}
// JS naming convention
await using (var ctx = await helper_canvas.GetContext2DAsync())
{
    await ctx.JS.font("48px solid");
    await ctx.JS.fillText("Hello", 0, 150);
}

Helper groups for API regions

The HTML canvas API is a large collection of methods and fields. This sometimes makes it hard to find the right method for your task. In Excubo.Blazor.Canvas, the methods are additionally grouped into

  • Canvas state
  • Compositing
  • Drawing images
  • Drawing paths
  • Drawing rectangles
  • Drawing text
  • Fill and stroke styles
  • Filters
  • Image smoothing
  • Line styles
  • Paths
  • Pixel manipulation
  • Shadows
  • Text styles
  • Transformations

You can make use of this by writing e.g. await context.Shadows.BlurAsync(2.0); await context.CanvasState.SaveAsync(); instead of await context.ShadowBlurAsync(2.0); await context.SaveAsync();. This helps make the intent of the code clearer, and helps finding the right method quicker.

Groups are a feature made possible by Excubo.Generators.Grouping.

Design principles

  • Type-safety

Users get a type-safe API that is fully compatible with the canvas API.

  • Performance

By combining calls into a batch, high performance is achieved. Whenever you perform a larger amount of calls, you should batch them. The library does this by combining the operations into just one JS interop call and minimizing the payload by grouping consecutive operations of the same type (e.g. multiple lineTo calls).

  • No JS payload

There's no need to load any javascript to use this library.

Roadmap

For the current implementation state, see the projects overview

Changes

Version 3.X.Y

Starting with version 3.0.0, only the net6.0 TFM is targeted. This is a change to simplify dependency management and we strongly encourage all users to upgrade to net6.0.

Version 2.6.5

Due to a change in implementation, CreateBatchAsync no longer performs any asynchronous work. A new synchronous method CreateBatch was added. It is recommended to replace any use of await context.CreateBatchAsync() with context.CreateBatch().