DEMOS
DOCS
FEATURES
DOWNLOAD
PURCHASE
CONTACT
BLOG
Show:

Surface Class

Extends AbstractRenderer

A widget that provides pan/zoom functionality, as well as the ability to load/store state in the browser. You do not construct an instance of this class manually: you obtain an instance of Surface via a call to the render method on a jsPlumbToolkitInstance. But the supported parameters to that render method are whatever is supported by the Surface constructor, as documented here.

Constructor

Surface

(
  • params
  • [params.zoomRange=[0.05,
)

Parameters:

  • params Object

    Constructor parameters

    • container Element | Selector

      Element to convert into a Surface.

    • [elementsDraggable=true] Boolean optional

      Whether or not elements in the Surface should be draggable.

    • [dragOptions] Object optional

      Options for draggable nodes.

    • [events] Object optional

      Optional event bindings. See documentation.

    • [miniview] Object optional

      Optional miniview configuration.

      • [container] Element | String | Selector optional
        Container for the miniview. An Element, an element id, or a selector.
      • [initiallyVisible=true] Boolean optional
        Whether or not the miniview should be invisible until some data is loaded.
    • [mode="pan"] String optional

      Mode to initialize the Surface in.

    • [panDistance=50] Number optional

      How far a pan nudge should move the UI (in pixels).

    • [zoom=1] Number optional

      Initial zoom for the widget.

    • [enablePan=true] Boolean optional

      Whether or not panning (via mouse drag) is enabled.

    • [enableWheelZoom=true] Boolean optional

      Whether or not zooming with the mouse wheel is enabled.

    • [directRender=false] Boolean optional

      If this is set, pan and zoom are disabled, and elements are not draggable. After each time the layout runs, the size of the canvas is set to the extents of the contained nodes, and a transform is applied to each axis to account for any elements whose position is negative in that axis. This flag is useful for rendering a diagram in place, without pan/zoom (but with events mapped), and knowing that the container element will always fully enclose the content.

    • [enableAnimation=true] Boolean optional

      Enable animations for panning. Defaults to true.

    • [wheelFilter] String optional

      Optional CSS selector representing elements that should not respond to wheel zoom.

    • [panFilter] String | Function optional

      Optional; either a CSS selector representing elements that should allow a pan event to begin, or a function that will be called with the event target. Returning true from this function means the widget should respond to the event.

    • [wheelSensitivity=10] Number optional

      How many pixels each click of the mouse wheel represents when zooming. Note that this value, while expressed in pixels, is mapped in a variety of ways depending on the browser.

    • [wheelReverse] Boolean optional

      Optional Defaults to false. If true, the zoom direction is reversed: wheel up zooms out, and wheel down zooms in.

    • [wheelZoomMetaKey=false] Boolean optional

      If true, the "meta" key (CMD on Mac, Ctrl on windows/linux) must be pressed in order for wheel zoom to operate. This can be useful if your UI fills the screen in one or more axes and your users would not be able to scroll past the Surface widget.

    • [wheelPan] Boolean optional

      Optional Defaults, to false. If true, two finger scrolling on a trackpad will cause the surface to pan its content, and the Control (or Command on mac) key must be held down in order to zoom. Note that IE and Opera do not support horizontal scrolling at all, so if you use this you are making a decision about limiting browser support.

    • [enablePanButtons=true] Boolean optional

      Whether or not to show the pan nudge buttons on the borders of the widgets.

    • [padding] Number optional

      Optional values for padding in the x/y axes to leave around the content. This is only of any use if you have disabled panning via mouse drag, since in that case the user sees only scroll bars and has no way of navigating beyond the content. Some padding makes the UI nicer to use. Default is [0,0].

    • [lassoFilter] String optional

      Optional selector for elements on which a mousedown should not cause the lasso to activate.

    • [lassoInvert=false] Boolean optional

      If true, the lasso operates by masking the unselected parts of the display.

    • [lassoSelectionFilter] Function optional

      Optional function that can be used to filter the set of nodes a lasso drag is selecting. The function is given each candidate Node in turn; returning false indicates the Node should not be selected.

    • [consumeRightClick=true] Boolean optional

      Useful for development: set this to false if you don't want the widget to consume context menu clicks.

    • [stateHandle] String optional

      If supplied, this will be used as the default handle for state save/restore operations.

    • [clamp=true] Boolean optional

      Whether to clamp when panning such that there is always content visible.

    • [clampZoom=true] Boolean optional

      Whether to clamp when zooming such that there is always content visible.

    • [clampToBackground=false] Boolean optional

      If a background is set, whether to clamp movement such that some part of the background is always visible.

    • [clampToBackgroundExtents=false] Boolean optional

      If a background is set, whether to clamp movement such that the background fills as much of the viewport as it can.

    • [background] Object optional

      Optional background image parameters

      • [url] String optional
        URL for the background. Required for both single images and tiled backgrounds.
      • [type="simple"] String optional
        "simple" or "tiled" - the type of background.
      • [tileSize] Number optional
        For tiled backgrounds, provides the width and height of tiles. Every tile is assumed to have these dimensions, even if the tile has whitespace in it.
      • [width] Number optional
        Required for tiled backgrounds. Indicates the width of the full image.
      • [height] Number optional
        Required for tiled backgrounds. Indicates the height of the full image.
      • [maxZoom] Number optional
        Required for tiled backgrounds. Indicates the maximum zoom level. Zoom starts at 0 - fully zoomed out - and increases in integer values from there. Eash successive zoom level is twice the zoom of the previous level, meaning two times as many tiles in each direction.
    • [jsPlumb] Object optional

      Optional set of jsPlumb Defaults to use for this renderer. The format and allowed properties is that of the Defaults object in jsPlumb. You can also set display properties in the view.

    • [autoExitSelectMode=true] Boolean optional

      When true (which is the default), the Surface will automatically jump back into Pan mode after some nodes have been selected.

    • [zoomToFit=false] Boolean optional

      If true, content will be zoomed to fit the viewport when a dataLoadEnd event is received.

    • [zoomToFitIfNecessary=false] Boolean optional

      If true, content will be zoomed to fit the viewport, if necessary (meaning if it fits inside the viewport already it wont be zoomed, which is different from how zoomToFit works) when a dataLoadEnd event is received. If this and zoomToFit are both set, this takes precedence.

    • [storePositionsInModel=true] Boolean optional

      By default, the left/top positions of nodes that have been dragged will be written into the data for each node after drag stops. You can set this to false to disable that behaviour.

    • [modelLeftAttribute="left"] String optional

      Optional; specifies the name of the attribute by which to store the x position of a dragged node of storePositionsInModel is true.

    • [modelTopAttribute="top"] String optional

      Optional; specifies the name of the attribute by which to store the y position of a dragged node of storePositionsInModel is true.

    • [assignPosse] Function optional

      optional function that, given each node, can return the id of the posse to which the node belongs. a Posse is a group of nodes that should all be dragged together.

    • [relayoutOnGroupUpdate=false] Boolean optional

      If true, any change to a Group's nodes will cause a relayout.

  • [params.zoomRange=[0.05, Number

    3] ] Zoom range for the widget.

Methods

animateToSelection

(
  • [params]
)

Zooms the display so that the current selected nodes are all visible, animating the transition.

Parameters:

  • [params] Object optional

    Optional method params

    • [fill=0.90] Number optional

      A decimal indicating how much of the viewport to fill with the zoomed content.

    • [selection] optional

      Optional Selection to which to zoom. If omitted, the default is to use the Toolkit's current selection.

    • [doNotZoomIfVisible=false] Boolean optional

      If true, no action is taken if the content is currently all visible.

    • [filter] Function optional

      Optional function to use as a filter; we create the selection by running this filter by the Toolkit's filter method.

centerContent

()

Centers the content in the viewport.

centerContentHorizontally

()

Centers the content in the viewport horizontally.

centerContentVertically

()

Centers the content in the viewport vertically.

centerOn

(
  • obj
  • [params]
)

Centers the given object in the viewport. You can pass in a DOM element or a Toolkit Node here.

Parameters:

  • obj Node | Element | String

    Object to center in the viewport - a Node, Element, or Node id.

  • [params] Object optional

    Optional extra parameters.

    • [horizontal=true] Boolean optional

      Whether or not to center horizontally

    • [vertical=true] Boolean optional

      Whether or not to center vertically

    • [doNotAnimate=false] Boolean optional

      If true, animation will not be switched on for the operation.

    • [onComplete] Boolean optional

      Optional on complete callback

    • [onStep] Boolean optional

      Optional on animation step callback.

centerOnAndZoom

(
  • obj
  • [fillRatio=0.6]
)

Centers on the given element and then adjusts the zoom of the widget so that the short axis of the viewport is [1 / fillRatio] larger than its corresponding axis on the centered node. fillRatio is basically a measure of how much context you want to see around the node on which you centered.

Parameters:

  • obj Element | String

    Element, or element id, to center.

  • [fillRatio=0.6] Number optional

    Proportional ratio of the corresponding node's edge to the viewport's short edge.

centerOnHorizontally

(
  • element
)

Centers the given element in the viewport, horizontally only.

Parameters:

  • element Element | String

    Element, or element id, to center.

centerOnHorizontally

(
  • element
)

Centers the given element in the viewport, vertically only.

Parameters:

  • element Element | String

    Element, or element id, to center.

clearState

(
  • handle
)

Clears the state stored by the given handle.

Parameters:

  • handle String

    The handle to restore the state from. If this is not supplied, and stateHandle was supplied as a constructor parameter, that is used instead.

createMiniview

(
  • params
)

Creates a miniview that is associated with this Surface.

Parameters:

  • params Object

    Miniview parameters. See Minview docs.

findIntersectingGroups

(
  • origin
  • dimensions
  • [enclosed=false]
)
Object

Finds all Groups 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. A future version could take an optional third argument specifying the element whose origin to use.

Parameters:

  • origin Number

    [x,y] location for center of search. IMPORTANT: This is relative to the page origin.

  • dimensions Number

    Width and height of search area.

  • [enclosed=false] Boolean optional

    If true, returns only nodes that are enclosed by the given search area. Otherwise returns nodes that both intersect and are enclosed.

Returns:

Object:

A list of objects containing {id:id, el:element, r:bounding rect} that either intersect or are enclosed by the search area.

findIntersectingNodes

(
  • origin
  • dimensions
  • [enclosed=false]
)
Object

Finds all Nodes or Groups 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. A future version could take an optional third argument specifying the element whose origin to use.

Parameters:

  • origin Number

    [x,y] location for center of search. IMPORTANT: This is relative to the page origin.

  • dimensions Number

    Width and height of search area.

  • [enclosed=false] Boolean optional

    If true, returns only nodes that are enclosed by the given search area. Otherwise returns nodes that both intersect and are enclosed.

Returns:

Object:

A list of objects containing {id:id, el:element, r:bounding rect} that either intersect or are enclosed by the search area.

findNearbyNodes

(
  • [x,y]
  • Radius
  • [mustBeInViewport=false]
  • [filter]
)
Object

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

Parameters:

  • [x,y] Number optional

    location for center of search

  • Radius Number

    of search.

  • [mustBeInViewport=false] Boolean optional

    If true, first check that the given origin is within the viewport.

  • [filter] Function optional

    Optional filter function. This is passed the (id, node, boundingRect) of some element and should return true for elements that should be included in results.

Returns:

Object:

A list of objects containing {id:id, el:element, r:bounding rect}, sorted in ascending order of distance of the center of the bounding rectangle from the given origin.

fixElement

(
  • el
  • constraints
  • pos
)

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.

Parameters:

  • el Element

    The DOM element to append.

  • constraints Object

    Flags to indicate optional constraint to each axis.

  • pos Number

    [left,top] location of the element's origin.

floatElement

(
  • el
  • pos
)

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.

Parameters:

  • el Element

    Element to float.

  • pos Number

    Array of [x,y] positions.

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 can be 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.

Returns:

[Number[]] [left,top] of the canvas, relative to the viewport's 0,0.

getBoundsInfo

()

Gets the current bounds information.

getMiniview

() Miniview

Gets the current Miniview, if there is one. There may not be.

Returns:

Miniview:

Current Miniview, null if no Miniview is registered.

getPan

() Number

Gets the current [left,top] of the panned content.

Returns:

Number:

[left,top], in pixels, of the panned content, where [0,0] is the origin of the viewport.

getStateHandle

() String

Gets the default handle to use for state save/restore operations.

Returns:

String:

Handle in use.

getViewportCenter

() Number

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

Returns:

Number:

left,top location of the logical position on the canvas corresponding to the center of the viewport.

getViewportCenter

() Number

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

Returns:

Number:

left,top location of the logical position on the canvas corresponding to the center of the viewport.

getZoom

() Number

Gets the current zoom.

Returns:

Number:

Current zoom value

getZoomRange

() Number

Gets the current zoom range.

Returns:

Number:

Array of [min, max] current zoom values.

isInViewport

(
  • x
  • y
)
Boolean

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

Parameters:

  • 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.

mapEventLocation

(
  • e
)
Object

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

Parameters:

  • e Event

    Event to map

Returns:

Object:

The mapped location, as {left:number, top:number}

mapLocation

(
  • x
  • y
)
Object

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

Parameters:

  • x Number

    X location to map

  • y Number

    Y location to map

Returns:

Object:

The mapped location, as {left:number, top:number}

nudgeWheelZoom

(
  • delta
  • [e]
)

Nudges the wheel zoom by the given amount. This function is intended for use by components that control zoom via the mouse wheel, and not for general usage. See nudgeZoom for a more general version of this.

Parameters:

  • delta Number

    Amount to change zoom by.

  • [e] Event optional

    Original event that caused the nudge. May be null.

nudgeZoom

(
  • delta
  • [e]
)
Number

Nudges the zoom by the given amount. Zoom will be clamped to the current zoom range in effect and the value that was ultimately set is returned from this function. The value you pass in here is multiplied by 100 to give a percentage value: 1 is 100%, for instance, 0.05 is 5%.

Parameters:

  • delta Number

    Amount to change zoom by.

  • [e] Event optional

    Original event that caused the nudge. May be null.

Returns:

Number:

The zoom that was set. Zoom will be clamped to the allowed range.

pageLocation

(
  • e
)
Number

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

Parameters:

  • e Object

    Event from which to decode location

Returns:

Number:

[left, top] of the given event.

pan

(
  • dx
  • dy
  • [animate
)

Pans the content by dx and dy.

Parameters:

  • dx Number

    Amount to pan in X direction

  • dy Number

    Amount to pan in Y direction

  • [animate Boolean

    = false] Whether or not to animate the pan.

positionElementAt

(
  • el
  • x
  • y
  • [xShift=0]
  • [yShift=0]
)

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. At zoom 1, with no panning, this will be the same as the given [x,y] value relative to the viewport origin. But once the canvas has been zoomed and panned we have to map to the altered coordinates. This function also takes into account the difference between the offset of the viewport in the page and the offset of the given element. 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. Note that this method - and its relatives, positionElementAtEventLocation and positionElementAtPageLocation - are not intended for use with elements being managed by the Surface. They are for use with external elements that you need to align with the contents of the Surface.

Parameters:

  • el Selector | Element | String

    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=0] Number optional

    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=0] Number optional

    Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

positionElementAtEventLocation

(
  • el
  • evt
  • [xShift=0]
  • [yShift=0]
)

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. Note that this method - and its relatives, positionElementAt and positionElementAtPageLocation - are not intended for use with elements being managed by the Surface. They are for use with external elements that you need to align with the contents of the Surface.

Parameters:

  • el Selector | Element | String

    Element to position.

  • evt Event

    Event to position element at.

  • [xShift=0] Number optional

    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=0] Number optional

    Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

positionElementAtPageLocation

(
  • el
  • x
  • y
  • [xShift=0]
  • [yShift=0]
)

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. Note that this method - and its relatives, positionElementAtEventLocation and positionElementAt - are not intended for use with elements being managed by the Surface. They are for use with external elements that you need to align with the contents of the Surface.

Parameters:

  • el Selector | Element | String

    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=0] Number optional

    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=0] Number optional

    Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

registerDroppableNodes

(
  • params
)

Allows you to register a list of droppables that can be dropped onto the surface. This function also supports configuring the Surface to accept files dragged from the user's desktop, but it is limited to supporting one file at a time.

Parameters:

  • params Object

    Parameters for droppables, including node list, drop options etc

    • [typeExtractor] Function optional

      Optional function to use to extract the related node type for some element that was dropped on the Surface.

    • [dataGenerator] Function optional

      Optional function to use to generate some initial data for a node of some given type. The function is passed type as argument, which may be null, so program defensively.

    • [droppables] Element optional

      List of elements identifying the elements to be configured as droppable. Either provide this, or provide source and selector. It is only in this latter case that you will be able to call refresh to subsequently add newly added elements to the set of droppables.

    • [source] Element optional

      Source element on which to execute querySelectorAll with the given selector in order to get the list of elements to be configured as droppable.

    • [selector] Element optional

      Selector that specifies child nodes of source that should be configured as droppable.

    • [dragOptions] Object optional

      Optional set of drag options, in a format specific to your underlying library.

    • [dropOptions] Object optional

      Optional set of drop options, in a format specific to your underlying library.

    • [start] Function optional

      Function to call when a droppable starts to be dragged.

    • [drag] Function optional

      Function to call as a droppable is being dragged.

    • [stop] Function optional

      Function to call when a droppable stops being dragged.

    • [drop] Function optional

      Function to call when a droppable has been dropped, before the Toolkit code is run. Returning false from this function causes the drop to be aborted.

repaint

(
  • obj
)

Repaints the element for the given object.

Parameters:

  • obj String | Port | Node | Element

    Object to repaint, including any associated connections. This can be a Toolkit Node or Port, a String (representing a Node or Node.Port id) or a DOM element.

repaintEverything

()

Repaints every element in the UI.

restoreState

(
  • handle
)

Restores the current state of the UI, either from local storage or a cookie, depending on the browser's capabilities.

Parameters:

  • handle String

    The handle to restore the state from, If this is not supplied, and stateHandle was supplied as a constructor parameter, that is used instead.

saveState

(
  • handle
)

Saves the current state of the UI, either to local storage or a cookie, depending on the browser's capabilities.

Parameters:

  • handle String

    The handle to save the state as, If this is not supplied, and stateHandle was supplied as a constructor parameter, that is used instead.

selectAllEdges

(
  • params
)

Selects a set of Edges. Parameters are the same as for selectEdges; the difference here is that when you're working with Nodes, this method will return all of the Node's Edges as well as those of all the Ports registered on the Node.

Parameters:

  • params Object

    Selection parameters

    • [source] String | Element | Node | Selector optional

      Source node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')

    • [target] String | Element | Node | Selector optional

      Target node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')

    • [element] String | Element | Node | Selector optional

      Source or target node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')

selectEdges

(
  • params
)

Selects a set of edges. If you supply a DOM element for any of the arguments here, the underlying graph object - a Node or a Port - will be determined, and the edges for that object will be retrieved. Note that for a Port this method does the same thing as selectAllEdges, but for a Node, which may have Ports registered on it, this method will retrieve only the Edges directly registered on the Node itself. You may need to use selectAllEdges if you want everything from some Node.

Parameters:

  • params Object

    Selection parameters

    • [source] String | Element | Node | Selector optional

      Source node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')

    • [target] String | Element | Node | Selector optional

      Target node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')

    • [element] String | Element | Node | Selector optional

      Source or target node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')

setApparentCanvasLocation

(
  • left
  • top
)
Number

Sets the apparent canvas location - see the notes for getApparentCanvasLocation.

Parameters:

  • left Number

    Value in pixels for left edge of canvas.

  • top Number

    Value in pixels for top edge of canvas.

Returns:

Number:

[left,top] of the actual origin set, after clamping.

setElementsDraggable

(
  • d
)

Sets whether or not elements will be made draggable. This does not disable dragging on elements that are already draggable.

Parameters:

  • d Boolean

    If false, elements will not be made draggable. If null or true, they will.

setEnabled

(
  • obj
  • state
)

Sets whether or not a given Node or Port is currently enabled as a connection target and source in the UI.

Parameters:

  • obj String | Node | Port | Element

    Node/Port or Node/Port ID, or a DOM element to disable as both a connection target and source.

  • state Boolean

    true if enabled, false if not.

setFilter

(
  • filterFn
)

Sets (or clears) the filter that will be called if the widget needs to know whether to respond to an event that would start a pan. By default, the widget responds to down events on the viewport or the canvas, but not on child nodes. You can supply a function that the widget will call in the event that the down event did not occur on the viewport or the canvas; returning true from this function will cause the pan to begin.

Parameters:

  • filterFn Function

    Function to set as the filter; may be null if you wish to clear it. The function should return true if it wants to honour the down event on the given element.

setLassoSelectionFilter

(
  • fn
)

Sets the current lasso selection filter function.

Parameters:

  • fn Function

    A function that takes Nodes as argument and returns false if the Node should not be selected. Any other return value will cause the Node to be selected.

setMode

(
  • mode
  • [doNotClearSelection=false]
)

Sets the current mode - "pan", "select" or "disabled", then fires an event notifying any listeners subscribed to the modeChanged event.

Parameters:

  • mode String

    Mode to set. Must be one of Surface.PAN, Surface.SELECT or Surface.DISABLED.

  • [doNotClearSelection=false] Boolean optional

    By default, when switching into Select mode, the current selection is cleared. Setting this to false prevents the selection from being cleared.

setPan

(
  • left
  • top
  • [animate
  • [onComplete]
  • [onStep]
)

Sets the position of the panned content's origin.

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

    = false] Whether or not to animate the pan.

  • [onComplete] Function optional

    If animate is set to true, an optional callback for the end of the pan.

  • [onStep] Function optional

    If animate is set to true, an optional callback for each frame in the pan.

setPanFilter

(
  • f
)

Sets the filter used to determine whether or not a given event should begin a pan.

Parameters:

  • f String | Function

    Either a CSS selector to use as a whitelist on the event target, or a function that will be given the target of the current mouse event. You must return true from the function if you wish for a pan to begin.

setSourceEnabled

(
  • obj
)

Sets whether or not a given Node or Port is currently enabled as a connection source in the UI.

Parameters:

  • obj String | Node | Port | Element

    Node/Port or Node/Port ID, or a DOM element to disable as a connection source.

setStateHandle

(
  • handle
)

Sets the default handle to use for state save/restore operations.

Parameters:

  • handle String

    Handle to use.

setTargetEnabled

(
  • obj
)

Sets whether or not a given Node or Port is currently enabled as a connection target in the UI.

Parameters:

  • obj String | Node | Port | Element

    Node/Port or Node/Port ID, or a DOM element to disable as a connection target.

setViewportCenter

(
  • xy
)

Sets the location of the canvas such that the given point appears at the center of the viewport.

Parameters:

  • xy Number

    left, top location of the point on the canvas to position in the center of the viewport.

setWheelFilter

(
  • filter
)

Sets the filter used to determine whether or not a given wheel event should be responded to.

Parameters:

  • filter String

    A CSS selector to use as a blacklist on the event target.

setZoom

(
  • zoom
)
Number

Sets the current zoom, clamping it to the allowed range.

Parameters:

  • zoom Number

    Zoom value. If this is outside the allowed bounds it will be clamped.

Returns:

Number:

Current zoom. This may or may not be the value you asked for - it might have been clamped to the current allowed zoom range.

setZoomRange

(
  • zr
  • [doNotClamp]
)
Number

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.

Parameters:

  • zr Number

    New range, as an array consisting of [lower, upper] values. Lower must be less than upper.

  • [doNotClamp] Boolean optional

    If true, will not check the current zoom to ensure it falls within the new range.

Returns:

Number:

Array of [min, max] current zoom values.

startEditing

(
  • edgeOrConnection
  • [params]
)

Starts editing of the given Edge, Connection, or Edge ID.

Parameters:

  • edgeOrConnection String | Edge | Connection

    Either an Edge, or a Connection, or an Edge ID.

  • [params] Object optional

    Optional params for the start edit call.

State.clear

()

Clears the state that was stored against the given handle.

State.clearAll

()

Removes all saved UI state information.

State.deserialize

(
  • value
)

Restores the UI state to the serialized state given.

Parameters:

  • value String

    Serialized state.

State.restore

(
  • [handle]
  • [preprocessor]
)

Restores the UI state to the state it was in when it was saved with the given handle. If the handle does not exist, nothing happens. It is possible a future incarnation of this could support animating a UI back to some state.

Parameters:

  • [handle] String optional

    The handle to restore the state from, If this is not supplied, and stateHandle was supplied as a constructor parameter, that is used instead.

  • [preprocessor] Function optional

    Optional preprocessor which is given the serialized state before saving to localStorage. Useful if you wish to compress the data, for instance.

State.save

(
  • [handle]
  • [preprocessor]
)

Writes the current location of each node in the UI to local storage (using either a cookie or html5 storage, depending on browser capabilities). You pass this function a 'handle' argument, which is used to restore the state at some stage in the future.

Parameters:

  • [handle] String optional

    The handle to save the state as, If this is not supplied, and stateHandle was supplied as a constructor parameter, that is used instead.

  • [preprocessor] Function optional

    Optional preprocessor which is given the serialized state, and a callback function, before saving to localStorage. Useful if you wish to compress the data, for instance.

State.serialize

()

Serializes the UI state to a String.

stopEditing

()

Stops editing, if editing is happening right now. Otherwise does nothing.

zoomToBackground

(
  • [params]
)

Zooms the display so that the background fits inside the viewport.

Parameters:

  • [params] Object optional
    • [onComplete] Function optional

      Optional function to call on operation complete (centering may be animated).

    • [onStep] Function optional

      Optional function to call on operation step (centering may be animated).

    • [doNotAnimate=false] Boolean optional

      If true, centering content will not use animation.

zoomToFit

(
  • [params]
)

Zooms the display so that all the tracked elements fit into 90% of the viewport. NOTE: this will zoom to include all nodes, even those that are not currently visible. See #zoomToVisible if you wish to zoom only to visible nodes. 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:true on the parameters to this method. You can supply a fill parameter to tell the Surface how much of the viewport you wish to fill with the zoomed content if 90% is not to your liking.

Parameters:

  • [params] Object optional
    • [fill=0.90] Number optional

      A decimal indicating how much of the viewport to fill with the zoomed content.

    • [padding=20] Number optional

      Optional padding to leave around all elements.

    • [onComplete] Function optional

      Optional function to call on operation complete (centering may be animated).

    • [onStep] Function optional

      Optional function to call on operation step (centering may be animated).

    • [doNotAnimate=true] Boolean optional

      By default, the centering content step does not use animation. This is due to this method being used most often to initially setup a UI.

    • [doNotZoomIfVisible=false] Boolean optional

      If true, no action is taken if the content is currently all visible.

    • [doNotFirePanEvent=false] Boolean optional

      If true, a pan event will not be fired.

zoomToFitIfNecessary

(
  • [params]
  • [params.padding
)

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).

Parameters:

  • [params] Object optional
    • [onComplete] Function optional

      Optional function to call on operation complete (centering may be animated).

    • [onStep] Function optional

      Optional function to call on operation step (centering may be animated).

    • [doNotAnimate=true] Boolean optional

      By default, the centering content step does not use animation. This is due to this method being used most often to initially setup a UI.

  • [params.padding Number

    = 20] Optional padding to leave around all elements.

zoomToSelection

(
  • [params]
)

Zooms the display so that the current selected nodes are all visible, optionally animating the transition.

Parameters:

  • [params] Object optional

    Optional method params

    • [fill=0.90] Number optional

      A decimal indicating how much of the viewport to fill with the zoomed content.

    • [selection] optional

      Optional Selection to which to zoom. If omitted, the default is to use the Toolkit's current selection.

    • [doNotZoomIfVisible=false] Boolean optional

      If true, no action is taken if the content is currently all visible.

    • [doNotAnimate=true] Boolean optional

      By default the widget does not animate this operation. You can override that behaviour by setting doNotAnimate:false.

    • [filter] Function optional

      Optional function to use as a filter; we create the selection by running this filter by the Toolkit's filter method.

zoomToVisible

(
  • [params]
)

Zooms the display so that all the visible tracked elements fit into 90% of 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:true on the parameters to this method. You can supply a fill parameter to tell the Surface how much of the viewport you wish to fill with the zoomed content if 90% is not to your liking.

Parameters:

  • [params] Object optional
    • [fill=0.90] Number optional

      A decimal indicating how much of the viewport to fill with the zoomed content.

    • [padding=20] Number optional

      Optional padding to leave around all elements.

    • [onComplete] Function optional

      Optional function to call on operation complete (centering may be animated).

    • [onStep] Function optional

      Optional function to call on operation step (centering may be animated).

    • [doNotAnimate=true] Boolean optional

      By default, the centering content step does not use animation. This is due to this method being used most often to initially setup a UI.

    • [doNotZoomIfVisible=false] Boolean optional

      If true, no action is taken if the content is currently all visible.

    • [doNotFirePanEvent=false] Boolean optional

      If true, a pan event will not be fired.

Properties

DISABLED

String

Constant for the Disabled mode.

PAN

String

Constant for the Pan mode.

SELECT

String

Constant for the Select mode.