Navigating your dataset

The Surface widget exposes a host of useful methods for navigating your dataset. This page gives you a summary of each; if you want to know more, check out the API docs for the Surface widget.

Positioning the canvas

centerContent

Pans the canvas, without changing the zoom, so that the content is centered both horizontally and vertically. Since zoom does not change, this method can result in content being outside the viewport.


centerContentHorizontally

Pans the canvas, without changing the zoom, so that the content is centered horizontally. Since zoom does not change, this method can result in content being outside the viewport.


centerContentVertically

Pans the canvas, without changing the zoom, so that the content is centered vertically. Since zoom does not change, this method can result in content being outside the viewport.


setPan(x, y)

Sets the current location of the canvas.


pan(dx, dy)

Pans the canvas by the given amounts in the x and y axes.


setViewportCenter(xy[])

Sets the location of the canvas such that the given point appears at the center of the viewport. The coordinates given are relative to the canvas (ie. independent of zoom).

TOP


Zooming the Canvas

zoomToFit

surface.zoomToFit();

Zooms the canvas so that all of the content fits inside the viewport, and ensures that the content is centered. By default, this method zooms to the point that the content fills 90% of the viewport, which makes for a more readable UI for users. This value can be changed by passing in a fill parameter:

 surface.zoomToFit({fill:0.75});

Here we've said we want the content to fill 75% of the viewport (the Surface will apply this to the smaller of the two axes).


zoomToFitIfNecessary

Checks to see if all of the content is currently visible in the viewport. If not, zooms the canvas so that all of the content fits inside the viewport, and ensures that the content is centered. If all content is already visible, no action is taken.

This method also supports the fill parameter supported by zoomToFit.


zoomToBackground

Zooms the canvas so that the entire background is visible. The Toolkit ships with two background types - Image and TiledImage, but you can also write your own.


zoomToSelection

Zooms the canvas so that the currently selected elements are all visible and centered. The currently selected elements are those elements that correspond to the Toolkit's current selection. The linked page provides details on how to add items to the current selection. One way is to add items one at a time, which we'll show here for the purposes of providing an example:

toolkit.addToSelection("someNodeId");
renderer.zoomToSelection();
Zooming to an adhoc selection

You can also provide your own selection to run zoomToSelection on an adhoc basis. For example, you might use the filter method to get a Selection, and then zoom in so that the entire selection is visible:

var adhocSelection = toolkit.filter(function(obj) {
    return obj.objectType === "Node" && obj.data.status === "GREEN";
});

renderer.zoomToSelection({
    selection:adhocSelection
});

setZoom(zoom)

Clamps the given zoom value to the current zoom range and then changes the widget zoom accordingly.


setZoomRange(bounds)

Sets the current zoom range as an array of [lower, upper] bounds.


nudgeZoom(amount)

Nudges the zoom by the given amount. A value of 1 indicates 100%. You can pass in negative values. The zoom value resulting from this operation will be clamped to the current zoom range.

TOP


Navigating to Nodes

In all of these methods, node can refer to a DOM element, a Node object, or a Node ID (String).

centerOn(node)

Pans the canvas so that the given node is centered both horizontally and vertically.


centerOnHorizontally(node)

Pans the canvas so that the given node is centered horizontally.


centerOnVertically(node)

Pans the canvas so that the given node is centered vertically.


centerOnAndZoom(node, ratio)

Pans and zooms the canvas so that the given node is centered, and fills the viewport (within the constraints of the current zoom range) to a given ratio. Ratio is applied by first calculating which axis is the short edge of the viewport. Call this viewportLength. The corresponding edge of the focus node is then measured; call this nodeLength. Zoom is then calculated such that nodeLength = viewportLength * ratio. The default value for ratio is 0.6. But note again: the current zoom range will constrain the result of this calculation.

TOP


Positioning Elements Over the Canvas

positionElementAt(element, x, y

Places (using style.left and style.top) the given element at the given x,y, which is taken to mean an [x,y] value on the canvas.


positionElementAtEventLocation(element, event)

Places (using style.left and style.top) the given element at the page x,y corresponding to the given event. It is assumed, just because of what this method does, that the given element will be positioned absolute, but this method does nothing to ensure that.


positionElementAtPageLocation(element, x, y)

Places (using style.left and style.top) the given element at the given page x,y. It is assumed, just because of what this method does, that the given element will be positioned absolute, but this method does nothing to ensure that.


floatElement(element, xy[])

Appends an element to the viewport so that it floats above the content that is being zoomed and panned. The element will have position:absolute set on it. You can float any element you like, but note that the responsibility for setting an appropriate z index is yours.


fixElement(element, constraints)

Appends an element to the content such that it is zoomed with everything else, but constrains pan in one or both axes so that the element remains fixed with respect to the viewport origin.

TOP


Inspecting the canvas state

getPan

Gets the current pan in each axis as an array of [x,y] values.


getZoom

Gets the current zoom. A value of 1 mean 100%.


getZoomRange

Gets the current zoom range as an array of [lower, upper] bounds.


getViewportCenter

Gets the canvas location that corresponds to the center of the viewport. Note that this may describe a point outside of the content bounds.


getApparentCanvasLocation

Returns the apparent [left,top] of the canvas inside the viewport - the coordinates, in real pixel values, of where the origin of the canvas appears to be. This apparent origin is not necessarily the same as the [left,top] values of the canvas, because the transform origin and zoom values change things. This function is used in conjunction with the content bounds by widgets such as the miniview, to calculate what is actually visible in the viewport at some point in time.

TOP


Utility Methods

pageLocation(event)

Decodes the page location from the given event, taking touch devices into account.


mapLocation(x, y)

Maps the given page location to an [x,y] location in the Surface's canvas.


mapEventLocation(event)

Maps the page location of the given event to an [x,y] location in the Surface's canvas.


findNearbyNodes(xy[], radius)

Finds all nodes whose centers are within a rectangle with origin as its center, and a width and height of radius / 2.


findIntersectingNodes(xy[], wh[])

Finds all nodes that intersect to any extent the rectangle defined by the given origin and dimensions. This rectangle is taken to be in the coordinate space of the document, ie. a value of [0,0] for the origin means the document's top/left corner.


isInViewport(x, y)

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

TOP