Scroll settings in Angular Diagram component

10 Dec 202424 minutes to read

The diagram can be scrolled using both the vertical and horizontal scrollbars. Additionally, the mouse wheel can be used to scroll the diagram. The diagram’s scrollSettings allow you to read the current scroll status, view port size, current zoom level, and zoom factor. These settings also provide the capability to programmatically control the scrolling of the diagram.

Access and Customize Scroll Settings

Scroll settings in a diagram allow you to access and customize various properties such as horizontalOffset, verticalOffset, viewPortWidth, viewPortHeight, currentZoom, zoomFactor, maxZoom, minZoom, scrollLimit, canAutoScroll, autoScrollBorder, padding, scrollableArea

These properties enable you to read and adjust the scroll status, scroll offset, zoom levels, and more. For a comprehensive overview of these properties, refer to the Scroll Settings

Define scroll offset

The diagram allows you to pan before loading, ensuring that any desired region of a large diagram is visible. You can programmatically pan the diagram using the horizontalOffset and verticalOffset properties of the scroll settings. The following code illustrates how to programmatically pan the diagram upon initialization also defined scrollLimit as ‘Infinity’ to scroll infinitely in diagram. To learn more about scrollLimit refer to scrollLimit.

In the example below, the vertical scrollbar is scrolled down by 100 px, and the horizontal scrollbar is scrolled to the right by 100 px.

import { Component, ViewEncapsulation, OnInit, ViewChild } from '@angular/core';
import { DiagramModule, DiagramComponent, Diagram, ScrollSettingsModel, RulerSettingsModel } from '@syncfusion/ej2-angular-diagrams';

@Component({
imports: [
         DiagramModule
    ],

providers: [ ],
standalone: true,
    selector: "app-container",
    template: `<ejs-diagram #diagram id="diagram" width="100%" height="580px" [scrollSettings]="scrollSettings" [rulerSettings]="rulerSettings" (created)='created($event)'>
        <e-nodes>
            <e-node id='node1' [offsetX]=200 [offsetY]=200>
            </e-node>
        </e-nodes>
    </ejs-diagram>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent {
    @ViewChild("diagram")
    public diagram?: DiagramComponent;
    public rulerSettings: RulerSettingsModel = { showRulers: true}
    public scrollSettings?: ScrollSettingsModel;
    ngOnInit(): void {
        // Defines the pageSettings for the diagram
        this.scrollSettings = {
            scrollLimit: 'Infinity',
        }
    }
    //Sets scroll status
    public created(args: Object): void {
        (this.diagram as Diagram).scrollSettings.horizontalOffset = 100;
        (this.diagram as Diagram).scrollSettings.verticalOffset = 100;
        (this.diagram as Diagram).dataBind();
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Update scroll offset at runtime

There are several ways to update the scroll offset at runtime:

  • Scrollbar: Use the horizontal and vertical scrollbars of the diagram.
  • Mousewheel: Scroll vertically with the mouse wheel. Hold the Shift key while scrolling to scroll horizontally.
  • Pan Tool: Activate the ZoomPan tool in the diagram to scroll by panning.
  • Touch: Use touch pad gestures for scrolling.

Programmatically update Scroll Offset

You can programmatically change the scroll offsets of diagram by customizing the horizontalOffset and verticalOffset of Scroll Settings at runtime. The following code illustrates how to change the scroll offsets at runtime.

import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import { DiagramModule, DiagramComponent, Diagram, RulerSettingsModel, ScrollSettingsModel } from '@syncfusion/ej2-angular-diagrams';

@Component({
imports: [
         DiagramModule
    ],

providers: [ ],
standalone: true,
    selector: "app-container",
    template: `
    <div class="button">
        <button id="UpdateScrollOffset" (click)='onClick($event)'>Update Scroll Offset</button>
    </div>
    <ejs-diagram #diagram id="diagram" width="100%" height="580px" [rulerSettings]="rulerSettings" [scrollSettings]="scrollSettings">
    </ejs-diagram>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent {
    @ViewChild("diagram")
    public diagram?: DiagramComponent;
    public rulerSettings: RulerSettingsModel = { showRulers: true}
    public scrollSettings?: ScrollSettingsModel = {
        scrollLimit: 'Infinity',
    }
    onClick = (args: MouseEvent) => {
        //Updates scroll settings
        (this.diagram as Diagram).scrollSettings.horizontalOffset = 200;
        (this.diagram as Diagram).scrollSettings.verticalOffset = 100;
        (this.diagram as Diagram).dataBind();
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Update zoom at runtime

Zoom using mouse wheel

Another way to zoom in and out the diagram is by using the mouse wheel. This method is a quick and convenient way to zoom in and out without having to use any additional tools or gestures.

  • Zoom in: Press Ctrl+mouse wheel, then scroll upward.

  • Zoom out: Press Ctrl+mouse wheel, then scroll downward.

Zoom using Keyboard Shortcuts

Using keyboard shortcuts is a quick and easy way to zoom the diagram without having to use the mouse or touch pad.

  • Zoom in: Press Ctrl and the plus(+) key.

  • Zoom out: Press Ctrl and the minus(-) key.

Programmatically update zoom

You can programmatically change the current zoom of diagram by utilizing the zoomTo public method.

ZoomOptions

The zoomTo method takes one parameter zoomOptions. In that zoomOptions we can specify the focusPoint , type and zoomFactor

The following example shows how to zoom-in and zoom-out the diagram using zoomTo method

import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import { DiagramModule, DiagramComponent, Diagram, RulerSettingsModel, ScrollSettingsModel, ZoomOptions } from '@syncfusion/ej2-angular-diagrams';

@Component({
imports: [
         DiagramModule
    ],

providers: [ ],
standalone: true,
    selector: "app-container",
    template: `
    <div class="button">
        <button id="zoomIn" (click)='onZoomInClick($event)'>Zoom In</button>
        <button id="zoomOut" (click)='onZoomOutClick($event)'>Zoom Out</button>
    </div>
    <ejs-diagram #diagram id="diagram" width="100%" height="580px" [rulerSettings]="rulerSettings" [scrollSettings]="scrollSettings">
        <e-nodes>
            <e-node id='node1' [offsetX]=300 [offsetY]=300>
            </e-node>
        </e-nodes>
    </ejs-diagram>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent {
    @ViewChild("diagram")
    public diagram?: DiagramComponent;
    public rulerSettings: RulerSettingsModel = { showRulers: true}
    public scrollSettings?: ScrollSettingsModel = {
        scrollLimit: 'Infinity',
    }
    public zoomInOptions: ZoomOptions = {
        type: 'ZoomIn',
        zoomFactor: 0.2,
        focusPoint: { x: 0.5, y: 0.5 },
    };
    public zoomOutOptions: ZoomOptions = {
        type: 'ZoomOut',
        zoomFactor: 0.2,
        focusPoint: { x: 0.5, y: 0.5 },
      };
    onZoomInClick = (args: MouseEvent) => {
        (this.diagram as Diagram).zoomTo(this.zoomInOptions);
        (this.diagram as Diagram).dataBind();
    }
    onZoomOutClick = (args: MouseEvent) => {
        (this.diagram as Diagram).zoomTo(this.zoomOutOptions);
        (this.diagram as Diagram).dataBind();
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

For more information on various ways to zoom and pan the diagram, refer to zoomPan with various ways

AutoScroll

The autoscroll feature automatically scrolls the diagram when a node or connector is moved beyond its boundary. This ensures that the element remains visible during operations like dragging, resizing, and selection.

The autoscroll behavior triggers automatically when any of the following actions occur towards the edges of the diagram:

  • Node dragging or resizing
  • Connector control point editing
  • Rubber band selection

The client-side event ScrollChange is triggered when autoscroll occurs, allowing for customizations. Refer scrollChange-event for more information.

Autoscroll behavior can be enabled or disabled using the canAutoScroll property of the diagram.

Autoscroll border

The autoscroll border defines the maximum distance from the mouse pointer to the diagram edge that triggers autoscroll. By default, this distance is set to 15 pixels for all sides (left, right, top, and bottom). You can adjust this using the autoScrollBorder property of the scroll settings.

The following example demonstrates how to configure autoscroll:

import { Component, ViewEncapsulation, OnInit, ViewChild } from '@angular/core';
import { DiagramModule, DiagramComponent, PointModel, RulerSettingsModel, ScrollSettingsModel } from '@syncfusion/ej2-angular-diagrams';

@Component({
imports: [
         DiagramModule
    ],

providers: [ ],
standalone: true,
    selector: "app-container",
    template: `<ejs-diagram #diagram id="diagram" width="100%" height="580px" [rulerSettings]="rulerSettings" [scrollSettings]="scrollSettings">
        <e-nodes>
            <e-node id='node1' [offsetX]=200 [offsetY]=300 [width]=100 [height]=100>
                <e-node-annotations>
                    <e-node-annotation content="Drag or resize the node to activate autoscroll">
                    </e-node-annotation>
                </e-node-annotations>
            </e-node>
        </e-nodes>
        <e-connectors>
            <e-connector id='connector' type='Orthogonal' [sourcePoint]='sourcePoint1' [targetPoint]='targetPoint1'>
                <e-connector-annotations>
                    <e-connector-annotation content='Adjust control point or end point to autoScroll' alignment='After'>
                    </e-connector-annotation>
                </e-connector-annotations>
            </e-connector>
        </e-connectors>
    </ejs-diagram>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent {
    @ViewChild("diagram")
    public diagram?: DiagramComponent;
    public rulerSettings: RulerSettingsModel = { showRulers: true}
    public scrollSettings?: ScrollSettingsModel;
    public sourcePoint1?: PointModel;
    public targetPoint1?: PointModel;
    ngOnInit(): void {
        this.sourcePoint1 = { x: 100, y: 100 };
        this.targetPoint1 = { x: 300, y: 100 };
        this.scrollSettings = {
            scrollLimit: 'Infinity',
            canAutoScroll: true,
            autoScrollBorder: { left: 100, right: 100, top: 100, bottom: 100 },
        } as ScrollSettingsModel;
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

NOTE

To use auto scroll the scrollLimit should be set as ‘Infinity’

Controlling Autoscroll Speed

You can control how often the scrolling needs to be performed automatically in the Diagram component during the auto-scrolling behavior. You can now adjust the frequency, ranging from slow and smooth to quick and rapid, to suit their preferences. To configure, set the value in milliseconds to the autoScrollFrequency property within the scrollSettings class, allowing precise control over how often auto-scrolling occurs.

AutoscrollFrequency

Scroll limit

The scrollLimit allows you to define the scrollable region of the diagram. It includes the following options:

  • Infinity: Allows scrolling in all directions without any restriction.
  • Diagram: Allows scrolling within the diagram region.
  • Limited: Allows scrolling within a specified scrollable area.

The scrollLimit property in scroll settings helps to define these limits.

Scrollable Area

Scrolling beyond a particular rectangular area can be restricted by using the scrollableArea property in scrollSettings . To restrict scrolling beyond a custom region, set the scrollLimit to “limited” and define the desired bounds in scrollableArea property.

The following code example illustrates how to specify the scroll limit and customize the scrollable area.

import { Component, ViewEncapsulation, OnInit, ViewChild } from '@angular/core';
import { DiagramModule, DiagramComponent, Diagram, ScrollSettingsModel, RulerSettingsModel } from '@syncfusion/ej2-angular-diagrams';

@Component({
imports: [
         DiagramModule
    ],

providers: [ ],
standalone: true,
    selector: "app-container",
    template: `
    <div id='container'>
      <label>Scrollable Area</label>
      <select id="scrollLimit" (change)="onScrollLimitChange($event)">
        <option value="Limited">Limited</option>
        <option value="Infinity">Infinity</option>
        <option value="Diagram">Diagram</option>
      </select>
    </div>
    <ejs-diagram #diagram id="diagram" width="100%" height="580px" [scrollSettings]="scrollSettings" [rulerSettings]="rulerSettings">
        <e-nodes>
            <e-node id='node1' [offsetX]=150 [offsetY]=150 [width]=100 [height]=100>
            </e-node>
        </e-nodes>
    </ejs-diagram>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent {
    @ViewChild("diagram")
    public diagram?: DiagramComponent;
    public scrollSettings?: ScrollSettingsModel;
    public rulerSettings: RulerSettingsModel = { showRulers: true}
    ngOnInit(): void {
        // Defines the pageSettings for the diagram
        this.scrollSettings = {
            canAutoScroll: true,
            //Sets the scroll limit
            scrollLimit: 'Limited',
            //Sets the scrollable Area
            scrollableArea: {
                x: 0,
                y: 0,
                width: 1500,
                height: 1500
            }
        } as any;
    } 
    public onScrollLimitChange(args: any): void {
        (this.diagram as Diagram).scrollSettings.scrollLimit = args.target.value;
        (this.diagram as Diagram).dataBind();
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Scroll padding

The padding property of the scroll settings allows you to extend the scrollable region based on the scroll limit. This property is useful for adding extra space around the diagram content, making it easier to navigate and interact with elements near the edges.

The following code example illustrates how to set scroll padding for the diagram region:

import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import { DiagramModule, DiagramComponent, NodeModel, ScrollSettingsModel,RulerSettingsModel, MarginModel } from '@syncfusion/ej2-angular-diagrams';

@Component({
imports: [
         DiagramModule
    ],

providers: [ ],
standalone: true,
    selector: "app-container",
    template: `<ejs-diagram #diagram id="diagram" width="100%" height="580px" [scrollSettings]="scrollSettings" [rulerSettings]="rulerSettings" [nodes] ="nodes">
    </ejs-diagram>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent {
    public nodes: NodeModel[] = [
        {
            id: 'Start',
            width: 100, height: 100,
            offsetX: 350, offsetY: 350,
        }]
    @ViewChild("diagram")
    public diagram?: DiagramComponent;
    public scrollSettings?: ScrollSettingsModel;
    public rulerSettings: RulerSettingsModel = { showRulers: true};
    ngOnInit(): void {
        // Defines the pageSettings for the diagram
        this.scrollSettings = {
            //Sets the scroll limit
             padding: { left: 100, top: 100 }
        }
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));

Reset scroll

The reset method resets the zoom and scroller offsets to their default values.

//Resets the scroll and zoom to default values
(this.diagram as Diagram).reset();

UpdateViewport

The updateViewPort method is used to update the dimensions of the diagram viewport.

//Updates diagram viewport
(this.diagram as Diagram).updateViewPort();

Events

Scroll change event

The scrollChange event is triggered whenever the scrollbar is updated. This can occur during actions such as zooming in, zooming out, using the mouse wheel, or panning. The following example shows how to capture the scrollChange event.

import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import { DiagramModule, DiagramComponent, DiagramTools, IScrollChangeEventArgs } from '@syncfusion/ej2-angular-diagrams';

@Component({
imports: [
         DiagramModule
    ],

providers: [ ],
standalone: true,
    selector: "app-container",
    template: `<ejs-diagram #diagram id="diagram" width="100%" height="580px"  (scrollChange)="scrollChange($event)" [tool]='tool'>
        <e-nodes>
            <e-node id='node1' [offsetX]=150 [offsetY]=150 [width]=100 [height]=100>
            </e-node>
        </e-nodes>
    </ejs-diagram>`,
    encapsulation: ViewEncapsulation.None
})
export class AppComponent {
    @ViewChild("diagram")
    public diagram?: DiagramComponent;
    public tool?: DiagramTools;
    ngOnInit(): void {
        this.tool = DiagramTools.ZoomPan
    }
    public scrollChange(args: IScrollChangeEventArgs): void {
        console.log(args.panState);
        // Handle scrollChange event for custom logic
    }
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));