HTMLGraph | Features | Transformable Viewport

Transformable Viewport

To enable the built-in transformable viewport, call the enableUserTransformableViewport method on CanvasBuilder.

    
const element = document.getElementById(&#39;canvas&#39;);

const canvas = new CanvasBuilder(element)
  .enableUserTransformableViewport()
  .build();

Transformable Viewport

This method accepts optional configuration:

    
const element = document.getElementById(&#39;canvas&#39;);

const canvas = new CanvasBuilder(element)
  .enableUserTransformableViewport({
    scale: {
      mouseWheelSensitivity: 1.5,
      mouseWheelEventVerifier: (event) =&gt; event.ctrlKey,
      wheelFinishTimeout: 1000,
    },
    shift: {
      cursor: &#34;crosshair&#34;,
      mouseDownEventVerifier: (event) =&gt; event.ctrlKey,
      mouseUpEventVerifier: (event) =&gt; true,
    },
    transformPreprocessor: [
      {
        type: &#34;scale-limit&#34;,
        minContentScale: 0.5,
        maxContentScale: 5,
      },
      {
        type: &#34;shift-limit&#34;,
        minX: -1000,
        maxX: 1000,
        minY: -1000,
        maxY: 1000,
      },
    ],
    events: {
      onTransformStarted: () =&gt; {
        console.log(&#39;STARTED&#39;);
      },
      onTransformFinished: () =&gt; {
        console.log(&#39;FINISHED&#39;);
      },
      onBeforeTransformChange: () =&gt; {
        console.log(&#39;BEFORE TRANSFORM&#39;);
      },
      onTransformChange: () =&gt; {
        console.log(&#39;AFTER TRANSFORM&#39;);
      },
    },
  })
  .build();

Configuration Parameters

Name	Type	Description	Required	Default
`scale`	ScaleConfig	Scale-related behavior configuration	no	`{}`
`shift`	ShiftConfig	Shift-related behavior configuration	no	`{}`
`transformPreprocessor`	TransformConfig	Transformation preprocessors configuration	no	`{}`
`events`	EventsConfig	Handlers for available events	no	`{}`

ScaleConfig

Name	Type	Description	Required	Default
`mouseWheelSensitivity`	`number`	How much to scale on wheel scroll	no	`1`
`mouseWheelEventVerifier`	`function`	Function to verify if wheel event should apply scaling	no	`() => true`
`wheelFinishTimeout`	`number`	Timeout in milliseconds after which scaling with wheel regarded as finished (and `onTransformFinished` event gets triggered)	no	`500`

ShiftConfig

Name	Type	Description	Required	Default
`cursor`	`string \| null`	Cursor to set on mouse grab	no	`"grab"`
`mouseDownEventVerifier`	`function`	Function to verify if mouse event should trigger grab	no	`() => true`
`mouseUpEventVerifier`	`function`	Function to verify if mouse event should trigger release	no	`() => true`

TransformConfig

A single transformer or an array of transformers.

Transformers can be one of the following:

Scale Limit: Prevents scaling when the maximum or minimum limit is reached.

    
{
  type: &#34;scale-limit&#34;,
  minContentScale: 0.5,
  maxContentScale: 5,
}

All options are complementary.

Shift Limit: Prevents shifting when vertical or horizontal limits are reached.

    
{
  type: &#34;shift-limit&#34;,
  minX: -1000,
  maxX: 1000,
  minY: -1000,
  maxY: 1000,
}

All options are complementary.

Custom Preprocessor: Allows you to define a custom transformation preprocessor.

    
transformPreprocessor: (params) =&gt; {
  if (params.nextTransform.scale &gt; 1) {
    return params.prevTransform;
  }

  return {
    scale: params.nextTransform.scale,
    x: Math.max(params.nextTransform.x, -500),
    y: params.nextTransform.y,
  };
},

EventsConfig

Name	Description
`onTransformStarted`	Triggered when the user initiates a transform (e.g., mouse down or touch start). The transform may or may not occur next.
`onTransformFinished`	Triggered when the user finishes a transform (e.g., mouse up, touch end, or touch cancel).
`onBeforeTransformChange`	Triggered when the user performs a transform (e.g., mouse move or touch move), but the transform itself has not yet been applied.
`onTransformChange`	Triggered after the transform has been applied following user interaction.
`onResizeTransformStarted`	Triggered when transformation is about to change due to canvas element resize.
`onResizeTransformFinished`	Triggered after transformation was changed due to canvas element resize.

All events have no arguments, but the up-to-date transform state can be retrieved via the canvas.viewport property.