Navigating the dataset
The surface widget offers a number of methods for you to navigate your way around the rendered dataset.
Panning
The surface widget is an 'infinite pan' canvas that does not use scrollbars. To pan the canvas, the user drags using the left mouse button, or, on touch devices, by dragging a single touch.
Disabling Panning
Panning is normally enabled, but a surface can be initialized with panning disabled by setting enablePan to false:
const surface = toolkit.render(someElement, {
enablePan:false
});
You can also disable a surface entirely via the setMode method:
surface.setMode(Surface.DISABLED);
Filtering Panning
It's a fairly common use case that there be some set of elements in your canvas on which a drag should not cause a pan to occur. To handle this, the surface has the panFilter parameter. This is either a string that is a CSS selector representing elements that should allow a pan to begin, or a function from which you should return true if you would like a pan to begin.
CSS Selector Filter
let surface = toolkit.render(someElement, {
panFilter:".someClassName"
});
Function filter
const surface = toolkit.render(someElement, {
panFilter:(eventTarget) => {
return someLogic(eventTarget);
}
});
Zooming
The default behaviour of the surface is to support zooming via the mouse wheel, or on touch devices, via pinch to zoom.
Specifying zoom range
The surface can be zoomed within a given range, whose default value is:
[0.05, 3]
meaning the surface can zoom between 5% and 300%. You can set this when you create a surface:
const surface = toolkit.render(someElement, {
zoomRange:[1, 2]
});
You can also change the zoom range at runtime, via the setZoomRange method:
Home > @jsplumbtoolkit/browser-ui > Surface > setZoomRange
Surface.setZoomRange() method
Sets the current zoom range. By default, this method checks if the current zoom is within the new range, and if it is not then setZoom is called, which will cause the zoom to be clamped to an allowed value in the new range. You can disable this by passing true for doNotClamp.
Signature:
setZoomRange(zr: ZoomRange, doNotClamp?: boolean): ZoomRange;
Parameters
| Parameter | Type | Description |
|---|---|---|
| zr | ZoomRange | New range, as an array consisting of [lower, upper] values. Lower must be less than upper. |
| doNotClamp | boolean | If true, will not check the current zoom to ensure it falls within the new range. |
Returns:
Array of [min, max] current zoom values.
Wheel zoom
const surface = toolkit.render(someElement, {
enableWheelZoom:false
});
enableWheelZoom defaults to true. Whether or not zooming with the mouse wheel is enabled.
Filtering wheel events
const surface = toolkit.render(someElement, {
wheelFilter:".someElementClass"
});
wheelFilter is an optional CSS selector representing elements that should not respond to wheel zoom. Defaults to empty.
Wheel zoom meta key
const surface = toolkit.render(someElement, {
wheelZoomMetaKey:true
});
wheelZoomMetaKey defaults to false. If true, the wheel zoom only fires when Ctrl (or CMD on Mac) is pressed and the wheel is rotated.
Wheel direction
const surface = toolkit.render(someElement, {
wheelReverse:true
});
wheelReverse Defaults to false. If true, the zoom direction is reversed: wheel up zooms out, and wheel down zooms in.
Zoom Methods
There are a few helper methods for zooming exposed on the surface.
zoomToFit(options)
Zooms the display so that all tracked elements fit inside the viewport (including invisible nodes). This method will also increase the zoom if necessary in order that the content fills the 90% of the shortest axis of the viewport.
The most basic call you can make is this:
surface.zoomToFit();
zoomToFit supports a number of parameters:
- fill A decimal indicating how much of the viewport to fill with the zoomed content. Defaults to 0.9.
- padding Padding to leave around all elements. Default is 20 pixels.
- onComplete Optional function to call on operation complete (centering may be animated).
- onStep Optional function to call on operation step (centering may be animated).
- doNotAnimate By default, the centering content step does not use animation (this parameter is set to true). This is due to this method being used most often to initially setup a UI.
- doNotZoomIfVisible Defaults to false. If true, no action is taken if the content is currently all visible.
An example showing the surface animating the content until it fits 80% of the viewport and then popping up an alert:
surface.zoomToFit({
fill:0.8,
doNotAnimate:false,
onComplete:function() { alert("done!"); }
});
To zoom to show only visible nodes, see zoomToVisible.
zoomToFitIfNecessary(options)
Works like zoomToFit but if all tracked elements are currently visible does not adjust the zoom.
surface.zoomToFitIfNecessary();
All of the parameters supported by zoomToFit are supported by zoomToFitIfNecessary.
zoomToBackground(options)
If a background was set, zooms the widget such that the entire background is visible.
surface.zoomToBackground({
onComplete:() => { alert("done!"); }
});
This method also supports onStep and doNotAnimate.
zoomToSelection(options)
Zoom to either the current selected set of nodes in the Toolkit (defaults to the current selection filling 90% of the shortest axis in the viewport):
surface.zoomToSelection();
or provide a selection of your own to which to zoom:
surface.zoomToSelection({
fill:0.8,
selection:some Toolkit Selection
});
To find our more about Selections, see here.
This method also supports an optional filter function, which is used to create a Selection by running it through the Toolkit's filter method. For instance, this is how you could create what the zoomToVisible method (described below) does:
surface.zoomToSelection({
filter:(obj) => { return obj.objectType === "Node" && surface.isVisible(obj); }
});
zoomToVisible(options)
Zooms to display all the currently visible nodes. All animation options are supported by this method - it is a wrapper around zoomToSelection in which we first create a selection representing all the visible nodes.
zoomToVisibleIfNecessary(options)
This method is to zoomToVisible as zoomToFitIfNecessary is to zoomToFit - the content will be centered, but the zoom level will be changed only if all of the currently visible nodes are not visible in the viewport.
setZoom(value)
Sets the current zoom level. This must be a positive decimal number. If it is outside of the current zoom range, it will be clamped to the zoom range.
surface.setZoom(0.5);
Here we have set the zoom to 50%.
nudgeZoom(amount)
Nudges the current zoom level by some value (negative or positive).
// nudge the zoom by 5%
surface.nudgeZoom(0.05);
// nudge the zoom by -15%
surface.nudgeZoom(-0.15);
setZoomRange(range, doNotClamp)
Sets the current zoom range. By default, this method checks if the current zoom is within the new range, and if it is not then setZoom is called, which will cause the zoom to be clamped to an allowed value in the new range. You can disable this by passing true for doNotClamp.
surface.setZoomRange(0.5, 2);
here we have set the zoom range to be 50% minimum, 200% maximum. If the current zoom was outside of this range, it was clamped to be within.
Let's set the zoom to 2, the top of our current range, and then adjust the zoom range without affecting the widget's zoom:
surface.setZoom(2);
surface.setZoomRange([0.5, 1], true);
Clamping
Pan Movement
By default, the surface will clamp movement when panning so that some content is always visible. This can be overridden:
const surface = toolkit.render(someElement, {
...
clamp:false,
...
});
Zoom Movement
It is also default behaviour to clamp the movement of the canvas when the user zooms such that some content is always visible. Without this, it's quite easy for a user to accidentally zoom in such a way that all of the content disappears (consider the case that the canvas is zoomed out a long way and the user then zooms in on some whitespace that is a long way from any content).
As with pan clamping, you can also switch off zoom clamping if you wish:
const surface = toolkit.render(someElement, {
...
clampZoom:false,
...
});
Background
Backgrounds are discussed in a separate page, but a brief mention should be made of the fact that you can also tell the surface to clamp movement such that part of the background is always visible:
const surface = toolkit.render(someElement, {
...
clampToBackground:true,
...
});
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.