Canvas

This page focuses on the role of the Canvas object, the central point to interact with content.

Different types of canvas

There are currently four different classes of canvas:

• InteractiveInkCanvas provides interactive ink technology leveraging the offscreen mode with Websocket protocol. It is based on a Raw Content part type that is very flexible and allows you to take advantage of all of iink's interactive features.

• InkCanvas provides ink capture and display as well as batch recognition leveraging the REST recognizer endpoint, which can be used either for Text, Math, Raw Content, or Shape recognition. This online example illustrates Raw Content recognition:

• InteractiveInkSSRCanvas provides interactive ink technology with Server Side Rendering (SSR) with Websocket protocol. It is either based on a Math or a Text part type and allows you to take advantage of limited iink's interactive features.
• InkCanvasDeprecated provides ink capture and display as well as batch recognition leveraging the REST batch endpoint.

How to choose my canvas

To get the most out of iink, we recommend you to use an InteractiveInkCanvas to get full interactivity: gestures, lasso, math solving, etc. There is nothing particular to do to benefit from gestures: The SDK will take care of detecting and applying the effect of the gestures from the provided input without any plumbing needed.

For the situations where you only want to get the ink recognition, you may prefer to use REST, so we recommend you to use an InkCanvas but in this case you only benefit from iink recognition features.

How to create a canvas

There are two ways to create an canvas:

• You can instantiate it directly with its configuration options. For instance, to use a InteractiveInkCanvas you can use the following code:

let canvas = new InteractiveInkCanvas(rootElement, options as TInteractiveInkCanvasOptions)

await canvas.initialize()

• You can use the Canvas load method, which will create the right canvas according to its type and configuration options arguments:

  const canvasElement = document.getElementById('canvas');

  const canvas = await iink.canvas.load(canvasElement, "INTERACTIVE_INK",
        configuration: {
            server: {
                applicationKey: '#YOUR MYSCRIPT DEVELOPER APPLICATION KEY#',
                hmacKey: '#YOUR MYSCRIPT DEVELOPER HMAC KEY#'
            }
        }
  });

Configuration options of the canvas

Since not all configuration options are relevant for each canvas type, each canvas type comes with a default configuration, which is defined in its own object:

All options have sensible defaults, and the configuration can be customized during the creation of the canvas by using any subset of the configuration options to the Canvas.load() function. Keys that are not set keep their default value.

This sample gives you an overview of all configuration options with their default values for the InteractiveInkCanvasConfiguration:

Monitoring changes and errors

CanvasEventName lists all events that can be listened to on the Canvas or DOM element, which allows you, as a developer, to plug in custom logic when they occur.

You can run code on a particular CanvasEventName by registering an event listener on it. For example, to listen to canvas state changes:

canvas.event.addEventListener(CanvasEventName.CHANGED, (evt) => console.log(evt.detail))

The main events are:

• loaded: Fired when the canvas is fully loaded.
• changed: Fired when the canvas state changes, e.g. when undo/redo is available or not.
• converted: Fired when the canvas content is converted.
• exported: Fired when the canvas content export is available.
• idle: Fired when the canvas idle state changes, when asked.
• error: Fired when an error occurs.
• cleared: Triggered when clearing is complete.

The method waitForIdle() provided by iinkTS will raise an idle event when server and browser processing are over. This may be useful for instance in the case you want some synchronous recognition.

The following example let you explore by yourself how to observe changed and selected events, to display a real-time snapshot of canvas state: Same logic could be applied with any other event.