Navigating the canvas

The surface widget offers a number of methods for you to navigate your way around the rendered dataset.

Positioning

Several methods are available to assist you with positioning the surface canvas. These are discussed in greater detail in the API documentation:

centerOn

Home > @jsplumbtoolkit/browser-ui > Surface > centerOn

Surface.centerOn() method

Takes a node/group as argument and positions the surface canvas such that the given node is at the center in both axes.

Signature:

centerOn(element: string | Vertex | Element): void;

Parameters

Parameter	Type	Description
element	string | Vertex | Element	The element to center. Can be a DOM element, vertex id, or a Node/Group.

Returns:

void

centerOnHorizontally

Home > @jsplumbtoolkit/browser-ui > Surface > centerOnHorizontally

Surface.centerOnHorizontally() method

Takes a node/group as argument and positions the surface canvas such that the given node is at the center in the horizontal axis.

Signature:

centerOnHorizontally(element: string | Vertex | Element): void;

Parameters

Parameter	Type	Description
element	string | Vertex | Element	The element to center. Can be a DOM element, vertex id, or a Node/Group

Returns:

void

centerOnVertically

Home > @jsplumbtoolkit/browser-ui > Surface > centerOnVertically

Surface.centerOnVertically() method

Takes a node/group as argument and positions the surface canvas such that the given node is at the center in the vertical axis.

Signature:

centerOnVertically(element: string | Vertex | Element): void;

Parameters

Parameter	Type	Description
element	string | Vertex | Element	The element to center. Can be a DOM element, vertex id, or a Node/Group

Returns:

void

centerContent

Home > @jsplumbtoolkit/browser-ui > Surface > centerContent

Surface.centerContent() method

Centers the tracked content inside the viewport, but does not adjust the current zoom (so the content may still extend past the viewport bounds)

Signature:

centerContent(params?: {
        bounds?: ViewportBounds;
        horizontal?: boolean;
        vertical?: boolean;
        doNotFirePanEvent?: boolean;
        onComplete?: (p: PointXY) => any;
        doNotAnimate?: boolean;
        onStep?: () => any;
    }): void;

Parameters

Parameter	Type	Description
params	{ bounds?: ViewportBounds; horizontal?: boolean; vertical?: boolean; doNotFirePanEvent?: boolean; onComplete?: (p: PointXY) => any; doNotAnimate?: boolean; onStep?: () => any; }	Method parameters.

Returns:

void

pan

Home > @jsplumbtoolkit/browser-ui > Surface > pan

Surface.pan() method

Pans the canvas by a given amount in X and Y.

Signature:

pan(dx: number, dy: number, doNotAnimate?: boolean): void;

Parameters

Parameter	Type	Description
dx	number	Amount to pan in X direction
dy	number	Amount to pan in Y direction
doNotAnimate	boolean	By default this operation uses animation.

Returns:

void

setPan

Home > @jsplumbtoolkit/browser-ui > Surface > setPan

Surface.setPan() method

Sets the position of the panned content's origin.

Signature:

setPan(left: number, top: number, animate?: boolean, onComplete?: (p: PointXY) => any): void;

Parameters

Parameter	Type	Description
left	number	Position in pixels of the left edge of the panned content.
top	number	Position in pixels of the top edge of the panned content.
animate	boolean	Whether or not to animate the pan. Defaults to false.
onComplete	(p: PointXY) => any	If animate is set to true, an optional callback for the end of the pan

Returns:

void

positionElementAt

Home > @jsplumbtoolkit/browser-ui > Surface > positionElementAt

Surface.positionElementAt() method

Positions a DOM element at a given X,Y on the canvas, in canvas coordinates (meaning it takes into account the current zoom and pan). This is not intended for use with elements the surface is managing: it is designed to be used with elements such as pop-ups that you may wish to position relative to the content in your canvas.

Signature:

positionElementAt(el: Element, x: number, y: number, xShift?: number, yShift?: number, ensureOnScreen?: boolean): void;

Parameters

Parameter	Type	Description
el	Element	Element to position.
x	number	X location on canvas to move element's left edge to.
y	number	Y location on canvas to move element's top edge to.
xShift	number	Optional absolute number of pixels to shift the element by in the x axis after calculating its position relative to the canvas. Typically you'd use this to place something other than the top left corner of your element at the desired location.
yShift	number	Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.
ensureOnScreen	boolean	If true, will ensure that x and y positions are never negative.

Returns:

void

positionElementAtEventLocation

Home > @jsplumbtoolkit/browser-ui > Surface > positionElementAtEventLocation

Surface.positionElementAtEventLocation() method

Positions a DOM element at the apparent canvas location corresponding to the page location given by some event. This is not intended for use with elements the surface is managing: it is designed to be used with elements such as pop-ups that you may wish to position relative to the content in your canvas.

Signature:

positionElementAtEventLocation(el: Element, evt: Event, xShift?: number, yShift?: number): void;

Parameters

Parameter	Type	Description
el	Element	Element to position.
evt	Event	Event to position element at.
xShift	number	Optional absolute number of pixels to shift the element by in the x axis after calculating its position relative to the canvas. Typically you'd use this to place something other than the top left corner of your element at the desired location.
yShift	number	Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

Returns:

void

positionElementAtPageLocation

Home > @jsplumbtoolkit/browser-ui > Surface > positionElementAtPageLocation

Surface.positionElementAtPageLocation() method

Positions a DOM element at the apparent canvas location corresponding to the given page location. This is not intended for use with elements the surface is managing: it is designed to be used with elements such as pop-ups that you may wish to position relative to the content in your canvas.

Signature:

positionElementAtPageLocation(el: Element, x: number, y: number, xShift?: number, yShift?: number): void;

Parameters

Parameter	Type	Description
el	Element	Element to position.
x	number	X location on canvas to move element's left edge to.
y	number	Y location on canvas to move element's top edge to.
xShift	number	Optional absolute number of pixels to shift the element by in the x axis after calculating its position relative to the canvas. Typically you'd use this to place something other than the top left corner of your element at the desired location.
yShift	number	Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

Returns:

void

---

Finding elements

Several methods are available to assist you to find elements in the canvas.

findIntersectingVertices

Home > @jsplumbtoolkit/browser-ui > Surface > findIntersectingVertices

Surface.findIntersectingVertices() method

Finds vertices - Nodes or Groups - that intersect a rectangle defined by the given origin and dimensions.

Signature:

findIntersectingVertices<T extends Node>(origin: PointXY, dimensions: Size, enclosed?: boolean, dontIncludeGroups?: boolean, dontIncludeNodes?: boolean, dontIncludeNodesInsideGroups?: boolean, dontIncludeNestedGroups?: boolean): Array<IntersectingVertex<T>>;

Parameters

Parameter	Type	Description
origin	PointXY	Origin of the rectangle to test
dimensions	Size	Width and height of the rectangle to test
enclosed	boolean	If true, vertices must be fully enclosed by the rectangle
dontIncludeGroups	boolean	If true, Groups are omitted from the search
dontIncludeNodes	boolean	If true, Nodes are omitted from the search
dontIncludeNodesInsideGroups	boolean	If true, Nodes inside Groups are omitted from the search
dontIncludeNestedGroups	boolean	If true, Groups that are nested inside other Groups are omitted from the search

Returns:

Array<IntersectingVertex<T>>

findIntersectingNodes

Home > @jsplumbtoolkit/browser-ui > Surface > findIntersectingNodes

Surface.findIntersectingNodes() method

Finds Nodes (not Groups) - that intersect a rectangle defined by the given origin and dimensions.

Signature:

findIntersectingNodes(origin: PointXY, dimensions: Size, enclosed?: boolean, dontIncludeNodesInsideGroups?: boolean): Array<IntersectingVertex<Node>>;

Parameters

Parameter	Type	Description
origin	PointXY	Origin of the rectangle to test
dimensions	Size	Width and height of the rectangle to test
enclosed	boolean	If true, vertices must be fully enclosed by the rectangle
dontIncludeNodesInsideGroups	boolean	If true, Nodes inside Groups are omitted from the search

Returns:

Array<IntersectingVertex<Node>>

findIntersectingGroups

Home > @jsplumbtoolkit/browser-ui > Surface > findIntersectingGroups

Surface.findIntersectingGroups() method

Finds Groups (not Nodes) - that intersect a rectangle defined by the given origin and dimensions.

Signature:

findIntersectingGroups(origin: PointXY, dimensions: Size, enclosed?: boolean, dontIncludeNestedGroups?: boolean): Array<IntersectingVertex<Group>>;

Parameters

Parameter	Type	Description
origin	PointXY	Origin of the rectangle to test
dimensions	Size	Width and height of the rectangle to test
enclosed	boolean	If true, vertices must be fully enclosed by the rectangle
dontIncludeNestedGroups	boolean	If true, Nodes inside Groups are omitted from the search

Returns:

Array<IntersectingVertex<Group>>

---

Mapping coordinates

Every now and then you'll likely want to map between the surface's coordinate system and the page coordinate system. The surface offers a few methods to assist with this.

isInViewport

Home > @jsplumbtoolkit/browser-ui > Surface > isInViewport

Surface.isInViewport() method

Returns whether or not the given point (relative to page origin) is within the viewport for the widget.

Signature:

isInViewport(x: number, y: number): boolean;

Parameters

Parameter	Type	Description
x	number	X location of point to test
y	number	Y location of point to test

Returns:

boolean

True if the point is within the viewport, false if not.

fromPageLocation

Home > @jsplumbtoolkit/browser-ui > Surface > fromPageLocation

Surface.fromPageLocation() method

Maps the given page location to a value relative to the viewport origin, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner. If you wish, you can supply true for 'doNotAdjustForOffset', to suppress that behavior.

Signature:

fromPageLocation(left: number, top: number, doNotAdjustForOffset?: boolean): PointXY;

Parameters

Parameter	Type	Description
left	number	X location
top	number	Y location
doNotAdjustForOffset	boolean	Whether or not to adjust for the offset of the viewport in the page. Defaults to false.

Returns:

PointXY

The mapped location, as a PointXY object.

toPageLocation

Home > @jsplumbtoolkit/browser-ui > Surface > toPageLocation

Surface.toPageLocation() method

Maps the given location relative to the viewport origin, to a page location, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner. If you wish, you can supply true for 'doNotAdjustForOffset', to suppress that behavior.

Signature:

toPageLocation(left: number, top: number, doNotAdjustForOffset?: boolean): PointXY;

Parameters

Parameter	Type	Description
left	number	X location
top	number	Y location
doNotAdjustForOffset	boolean	Whether or not to adjust for the offset of the viewport in the page. Defaults to false.

Returns:

PointXY

The mapped location, as a PointXY object.