Navigating the canvas
The surface widget offers a number of methods you can use to assist your users in navigating their way around the canvas. You'll need to access the surface to use these methods programmatically - expand the section below for details.
How to access the surface
Positioning
centerOn
Takes a single node/group, or an array of nodes/groups, and positions the surface canvas such that the given vertex/vertices is/are at the center in both axes. It does NOT change the zoom.
Signature
centerOn(element:string | Element | Vertex | Array<string | Element | Vertex>, doNotAnimate:boolean)
Parameters
| element | string | Element | Vertex | Array<string | Element | Vertex> | The element(s) to center. Can be a DOM element, vertex id, or a Node/Group, or an array of these. |
| doNotAnimate | boolean |
Return value
voidcenterOnHorizontally
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 | Element | Vertex)
Parameters
| element | string | Element | Vertex | The element to center. Can be a DOM element, vertex id, or a Node/Group |
Return value
voidcenterOnVertically
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 | Element | Vertex)
Parameters
| element | string | Element | Vertex | The element to center. Can be a DOM element, vertex id, or a Node/Group |
Return value
voidcenterContent
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(options:CenterContentOptions)
Parameters
| options | CenterContentOptions | Method parameters. |
Return value
voidpan
Pans the canvas by a given amount in X and Y.
Signature
pan(dx:number, dy:number, doNotAnimate:boolean)
Parameters
| dx | number | Amount to pan in X direction |
| dy | number | Amount to pan in Y direction |
| doNotAnimate | boolean | By default this operation uses animation. |
Return value
voidsetPan
Sets the position of the panned content's origin.
Signature
Parameters
| 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 |
Return value
voidalignContent
Pan the canvas to align the content in one or both axes.
Signature
alignContent(options:AlignContentOptions)
Parameters
| options | AlignContentOptions |
Return value
voidalignContentLeft
Pan the canvas to align the content such that the left edge of the leftmost element is at the left of the viewport.
Signature
alignContentLeft(options:AlignContentToFaceOptions)
Parameters
| options | AlignContentToFaceOptions |
Return value
voidalignContentRight
Pan the canvas to align the content such that the right edge of the rightmost element is at the right of the viewport.
Signature
alignContentRight(options:AlignContentToFaceOptions)
Parameters
| options | AlignContentToFaceOptions |
Return value
voidalignContentTop
Pan the canvas to align the content such that the top edge of the topmost element is at the top of the viewport.
Signature
alignContentTop(options:AlignContentToFaceOptions)
Parameters
| options | AlignContentToFaceOptions |
Return value
voidalignContentBottom
Pan the canvas to align the content such that the bottom edge of the bottom element is at the bottom of the viewport.
Signature
alignContentBottom(options:AlignContentToFaceOptions)
Parameters
| options | AlignContentToFaceOptions |
Return value
voidZooming
You can zoom the canvas in a number of different ways:
zoomToFit
Zooms the display so that all the tracked elements fit inside the viewport. This method will also, by default, increase the zoom if necessary - meaning the default behaviour is to adjust the zoom so that the content fills the viewport. You can suppress zoom increase by setting
doNotZoomIfVisible:trueSignature
zoomToFit(params:ZoomToFitOptions)
Parameters
| params | ZoomToFitOptions |
Return value
voidzoomToFitIfNecessary
Zooms the display so that all the tracked elements fit inside the viewport, but does not make any adjustments to zoom if all the elements are currently visible (it still does center the content though).
Signature
zoomToFitIfNecessary(params:ZoomToFitIfNecessaryOptions)
Parameters
| params | ZoomToFitIfNecessaryOptions |
Return value
voidzoomToElements
Zooms the viewport so that all of the given elements are visible.
Signature
zoomToElements(zParams:ZoomToElementsOptions<BrowserElement>)
Parameters
| zParams | ZoomToElementsOptions<BrowserElement> |
Return value
voidzoomToExtents
Zooms the display to fit the given extents, which may be a single box or an array of boxes; in the latter case VisuallyJs will calculate a minimum bounding box for all the boxes provided.
Signature
zoomToExtents(zParams:ZoomToExtentsOptions)
Parameters
| zParams | ZoomToExtentsOptions | Options for the zoom |
Return value
voidzoomToDecorator
Zooms the display to fit the canvas and content plus any elements added by the given decorator.
Signature
zoomToDecorator(zParams:{
decorator:string | Decorator,
doNotAnimate:boolean,
doNotFirePanEvent:boolean,
doNotZoomIfVisible:boolean,
fill:number,
onComplete:(p:PointXY) => any,
onStep:() => any
})
decorator:string | Decorator,
doNotAnimate:boolean,
doNotFirePanEvent:boolean,
doNotZoomIfVisible:boolean,
fill:number,
onComplete:(p:PointXY) => any,
onStep:() => any
})
Parameters
| zParams | {
decorator:string | Decorator, doNotAnimate:boolean, doNotFirePanEvent:boolean, doNotZoomIfVisible:boolean, fill:number, onComplete:(p:PointXY) => any, onStep:() => any } |
Return value
voidFinding elements
Several methods are available to assist you to find elements in the canvas.
findIntersectingVertices
Finds all of the vertices that intersect the rectangle described by
origindimensionsSignature
findIntersectingVertices(options:IntersectingVerticesOptions)
Parameters
| options | IntersectingVerticesOptions | Options for the find operation. |
Return value
Array<IntersectingVertex<BrowserElement>>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
Returns whether or not the given point (relative to page origin) is within the viewport for the widget.
Signature
isInViewport(x:number, y:number)
Parameters
| x | number | X location of point to test |
| y | number | Y location of point to test |
Return value
booleanfromPageLocation
Maps the given page location to a value relative to the canvas origin, allowing for zoom and pan of the canvas.
This takes into account the offset of the canvas in the page so that what you get back is the mapped position
relative to the target element's [left,top] corner
This takes into account the offset of the canvas in the page so that what you get back is the mapped position
relative to the target element's [left,top] corner
Signature
fromPageLocation(left:number, top:number, roundValues:boolean)
Parameters
| left | number | X location |
| top | number | Y location |
| roundValues | boolean | If true, the location is returned as integers for x/y. |
Return value
PointXYtoPageLocation
Maps the given canvas location to a page location, allowing for zoom and pan of the canvas. Note that
pagetoWindowLocationSignature
toPageLocation(left:number, top:number)
Parameters
| left | number | X location |
| top | number | Y location |
Return value
PointXYfromWindowLocation
Maps the given window location to a value relative to the canvas origin. The window means the browser's visible
window, and is not the same as the page, because of scroll.
window, and is not the same as the page, because of scroll.
Signature
fromWindowLocation(left:number, top:number, roundValues:boolean)
Parameters
| left | number | |
| top | number | |
| roundValues | boolean |
Return value
PointXY