# BinkCanvas (Component)

`Bit.Bink.BinkCanvas` - inherits `ComponentBase` - implements `IAsyncDisposable`, `IComponent`, `IHandleAfterRender`, `IHandleEvent`

A drawing surface: pointer, touch and stylus input, high-quality ink rendering, tools, undo/redo and export.

The component is a thin shell around the engine in Bit.Bink. It owns two canvases: the document surface holding committed elements, and an overlay holding the live stroke and tool previews. Pointer input never triggers a Blazor render: samples arrive from the browser once per animation frame, the active tool processes them, and only the affected canvas layer is redrawn.

A signature pad:

```
<BinkCanvas @ref="canvas" Width="400px" Height="180px" AriaLabel="Signature" />
@code {
    private BinkCanvas? canvas;
    private void Clear() => canvas!.Clear();
    private string Save() => canvas!.ExportSvg();
}
```

## Parameter

- **ActiveLayerId** : `Guid?` - The layer new elements are added to. Defaults to the top-most editable layer.
- **AdditionalAttributes** : `IReadOnlyDictionary<string, object>` - Additional attributes applied to the container element.
- **AriaLabel** : `string` = `"Drawing canvas"` - Accessible name of the canvas.
- **Brush** : `BinkBrush` - The brush used by drawing tools.
- **ChildContent** : `RenderFragment` - Content rendered above the canvas, for toolbars or overlays positioned by the application.
- **Class** : `string` - Extra CSS classes for the container.
- **Document** : `BinkDocument` - The document to edit. When null the component creates and owns one, which is what a signature pad or a simple drawing field wants.
- **DocumentChanged** : `EventCallback<BinkDocumentChangedEventArgs>` = `new EventCallback<BinkDocumentChangedEventArgs>()` - Raised after any change to the document.
- **EnableKeyboardShortcuts** : `bool` = `true` - Whether the built-in keyboard shortcuts (undo, redo, delete, select all, escape) are handled.
- **EnableTouchGestures** : `bool` = `false` - Whether two-finger pan and pinch zoom are handled by the canvas. When false, touch gestures scroll the page instead, which is usually what a small signature field in a form wants.
- **Focusable** : `bool` = `true` - Whether the canvas can receive keyboard focus. Required for keyboard shortcuts.
- **Height** : `string` = `"300px"` - CSS height of the canvas element.
- **HistoryChanged** : `EventCallback` = `new EventCallback()` - Raised when the undo or redo stack changes.
- **HistoryLimit** : `int` = `200` - Maximum number of undo steps. Zero disables history.
- **ReadOnly** : `bool` = `false` - When true, input is ignored and the drawing is display-only.
- **Ready** : `EventCallback<BinkInputCapabilities>` = `new EventCallback<BinkInputCapabilities>()` - Raised once the canvas is attached and the device capabilities are known.
- **RejectTouchWhilePen** : `bool` = `true` - Whether a finger touch is ignored while a pen is in contact, so a resting palm does not draw.
- **SelectionChanged** : `EventCallback` = `new EventCallback()` - Raised when the selection changes.
- **ShapeStyle** : `BinkShapeStyle` - The style applied to newly created shapes and annotations.
- **StrokeCompleted** : `EventCallback<BinkStrokeEventArgs>` = `new EventCallback<BinkStrokeEventArgs>()` - Raised when a stroke is committed to the document.
- **StrokeStarted** : `EventCallback<BinkStrokeEventArgs>` = `new EventCallback<BinkStrokeEventArgs>()` - Raised when a stroke begins. Raised only for drawing tools (BinkDrawTool and subclasses other than the eraser), the same tools whose strokes BinkCanvas.StrokeCompleted reports; selecting, panning, placing a shape or editing text does not raise it.
- **Style** : `string` - Extra inline styles for the container.
- **Tool** : `IBinkTool` - The active tool. Defaults to freehand drawing.
- **Unavailable** : `EventCallback<string>` = `new EventCallback<string>()` - Raised instead of BinkCanvas.Ready when the browser layer cannot start, for example because a content security policy blocks its script, with the reason. The canvas stays inert; BinkCanvas.AttachFailed holds the same reason afterwards.
- **Viewport** : `BinkViewport` = `BinkViewport.Identity` - The viewport (pan and zoom). Supports two-way binding.
- **ViewportChanged** : `EventCallback<BinkViewport>` = `new EventCallback<BinkViewport>()` - Raised when the viewport changes, for two-way binding.
- **WetInk** : `bool?` - Whether a provisional trail is drawn in the browser while a sample batch travels to the server. Ignored in WebAssembly, where the engine already runs locally. Defaults to on for interactive server rendering.
- **Width** : `string` = `"100%"` - CSS width of the canvas element, for example "100%" or "400px".

## Property

- **ActiveTool** : `IBinkTool` - The active tool.
- **AttachFailed** : `string` - The reason the browser layer could not be attached, or null when everything is working. Applications can surface this to explain why the canvas is not responding.
- **Capabilities** : `BinkInputCapabilities` = `BinkInputCapabilities.None` - What the current device and browser support. Valid once BinkCanvas.Ready has been raised.
- **CurrentDocument** : `BinkDocument` - The document being edited.
- **CurrentViewport** : `BinkViewport` = `BinkViewport.Identity` - The current viewport.
- **ElementId** : `string` - The id of the container element, useful for labelling and testing.
- **History** : `BinkHistoryManager` - Undo and redo for this canvas.
- **Selection** : `BinkSelection` - The current selection.
- **UsesFastRenderPath** : `bool` = `false` - True when the zero-copy WebAssembly rendering path is in use.
- **ViewSize** : `Vector2` = `<0, 0>` - The canvas size in CSS pixels.

## Method

- **AddImageAsync**(BinkImageSource source, Vector2? position = null, float maxWidth = 600) : `Task<BinkImageElement>` - Adds an image to the document, sized to its natural dimensions.
- **Announce**(string message) : `void` - Announces a message to screen readers through the canvas live region.
- **Clear**() : `void` - Removes every element, as one undoable step.
- **DeleteSelection**() : `void` - Deletes the selected elements.
- **DisposeAsync**() : `ValueTask`
- **ExportPngAsync**(BinkPngExportOptions options = null, CancellationToken cancellationToken = null) : `Task<Byte[]>` - Exports the drawing as a PNG. Rendering happens in the browser, so real fonts and every image format the browser supports are included.
- **ExportSvg**(BinkSvgExportOptions options = null) : `string` - Exports the drawing as SVG. This is synchronous work: SVG generation happens entirely in .NET and needs nothing from the browser.
- **ExportSvgAsync**(BinkSvgExportOptions options = null) : `Task<string>` - Exports the drawing as SVG. Provided for symmetry with BinkCanvas.ExportPngAsync; the work itself is synchronous, so BinkCanvas.ExportSvg is equivalent and avoids a needless state machine.
- **LoadDocument**(BinkDocument document) : `void` - Replaces the document being edited and resets history and selection.
- **LoadImageAsync**(BinkImageSource source) : `Task<BinkImageSource>` - Decodes an image in the browser without adding it to the document, and returns the source with its natural size filled in. Use it before a history group or batch that places the image: the decode is a browser round trip, and a group left open across one disables undo until it closes.
- **Redo**() : `bool` - Redoes the last undone change. Returns false when there is nothing to redo.
- **Refresh**() : `void` - Requests a redraw of the whole canvas.
- **ResetViewport**() : `void` - Resets pan and zoom.
- **SavePngAsync**(string fileName = "drawing.png", BinkPngExportOptions options = null, CancellationToken cancellationToken = null) : `Task` - Exports the drawing as a PNG and offers it to the user as a file download.
- **SaveSvgAsync**(string fileName = "drawing.svg", BinkSvgExportOptions options = null) : `Task` - Exports the drawing as SVG and offers it to the user as a file download.
- **SelectAll**() : `void` - Selects every element on unlocked, visible layers.
- **SetTool**(IBinkTool tool) : `void` - Replaces the active tool.
- **SetViewport**(BinkViewport viewport) : `void` - Sets the viewport, notifying BinkCanvas.ViewportChanged.
- **Undo**() : `bool` - Undoes the last change. Returns false when there is nothing to undo.
- **ZoomBy**(float factor) : `void` - Zooms around the center of the view.
- **ZoomToFit**(float padding = 24) : `void` - Fits the drawing into the visible area.