Private _unrenderedlist of edges that are as-yet unrendered due to one or both of their vertices not having been rendered.
list of vertices that have been passed to the renderer but which have not yet been reported as rendered.
Private _sizePrivate sizes the current
Optional focusPosition: PointXYPrivate _trackPrivate TODO strictly speaking this breaks the concept of multiple renderers, since this event goes on the Toolkit's stack and it may not be relevant for some other renderer. Plus some other renderer could execute an undo and cause changes in this renderer. The solution for that is I guess to have an undo stack per renderer, which wraps the Toolkit's undo.
Track group size changes by firing an event through the Toolkit.
Run an adhoc layout on the given group. The layout will be applied one time, and then the previous layout will be restored (but not run, of course, otherwise the results of this adhoc layout would be overwritten!).
Run an adhoc layout on the viewport. The layout will be applied one time, and then the previous layout will be restored (but not run, of course, otherwise the results of this adhoc layout would be overwritten!)
Adds a class to the DOM element represented by el, which can be a Selection, or an instance of many
different types - see the SupportsClassManipulation interface for a complete list.
Add a plugin to the Surface. You can provide a type parameter to this method to avoid having to cast the return value, if you need to retain a reference to the plugin.
Bind an event listener. This method can be used with a type parameter by call sites; although it's not necessary it can be helpful to use this to ensure you've thought about what the payload to your event handler is going to be.
Name of the event(s) to bind to.
Function to bind to the given event(s)
Optional e: anyOptional insertAtStart: booleanWhether or not to insert this listener at the head of the listener queue. Defaults to false.
Binds to a mouse event occurring on a given model object. This is a wrapper around the on event binding method, which
searches for an associated model object for the given event. For instance, you might have a node template that has a button inside of it
that you want to respond to. When the button is clicked you want to know the node associated with the button. This method provides that.
It is possible to find the associated model object yourself, via the getObjectInfo method of the Surface, called with the event's target,
but this method does that for you.
You can, optionally, provide a type hint to this method in order to fix the type of the returned model object, but note that this is erased at runtime and the type of the returned object is not guaranteed by the surface.
This method binds a delegated event handler on the container element used by the surface. You do not need to provide an element to which to bind; you just need to provide an appropriate selector
Name of the event to bind to.
CSS3 selector that identifies children of a vertex DOM element on which the event handler should be bound.
Function to call when the event is fired.
Centers the tracked content inside the viewport, but does not adjust the current zoom (so the content may still extend past the viewport bounds)
Optional params: CenterContentOptionsMethod parameters.
Center on the current object and zoom in on it.
The element to center. Can be a DOM element, vertex id, or a Node/Group
Optional fillRatio: numberHow much of the viewport to fill with the object we zoom in on. This will be limited by the current zoom range. Defaults to 0.6.
Optional doNotAnimate: booleanby default, this operation will be animated.
Cleans up the Surface. When using a library integration such as Angular/React/Vue, this method will be called automatically when the associated component is unloaded. If you're using vanilla Toolkit, you might want to call this method if you're cleaning up your UI and you don't need this Surface any longer.
Finds vertices - Nodes or Groups - that intersect a rectangle defined by the given origin and dimensions.
Origin of the rectangle to test
Width and height of the rectangle to test
Optional enclosed: booleanIf true, vertices must be fully enclosed by the rectangle
Optional dontIncludeGroups: booleanIf true, Groups are omitted from the search
Optional dontIncludeNodes: booleanIf true, Nodes are omitted from the search
Optional dontIncludeNodesInsideGroups: booleanIf true, Nodes inside Groups are omitted from the search
Optional dontIncludeNestedGroups: booleanIf true, Groups that are nested inside other Groups are omitted from the search
Appends an element to the viewport 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.
The DOM element to append.
Location of the element's origin.
Optional constraints: FixedElementConstraintsFlags to indicate optional constraint to each axis.
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.
Element to float.
Position to float the element at.
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.
X location
Y location
The mapped location, as a PointXY object.
Gather the elements in the display. If focus is provided the elements will be gathered around it. Otherwise, the elements will be
gathered around the computed center of all the elements.
Optional focus: string | VertexOptional ID of a Vertex, or the Vertex itself, around which to gather elements.
Returns the apparent {x,y} 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 {x,y} 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.
Top left location of the canvas, relative to the viewport's 0,0.
Gets the current bounds information.
Gets the origin and size of the DOM element representing a Vertex that is being managed by the Surface. Origin is reported in pixels, relative to the parent container of the given Vertex: for a Vertex inside a group, the parent container is group's DOM element (or the group's DOM element's internal parent for children); for a Vertex that is at the root level of the dataset, the container is the canvas.
Vertex id, element, or Vertex to get position for.
Optional relativeToCanvasRoot: booleanDefaults to false, meaning the behaviour is as described above. If true, then all values are reported with respect to the canvas origin. This flag is used, for instance, in the copy/paste module, for determining the canvas offset for some node being copied out of a group into the root of the dataset.
A RectangleXY if element was found, otherwise null.
For a given element, retrieve the model object it represents.
Optional searchAncestors: booleanDefaults to false. If true, ancestors of the given element are searched, up to the underlying container element.
a Port, Node, Edge, Group, or null.
Decodes the given input into a data structure containing a model object, its type, its ID, and the DOM element used to represent it. Always returns a value even if no model object could be resolved for the given input, but the fields of the return value may be null.
Object to decode. Can be in many different forms - an existing model object, a vertex id, a DOM element, a Connection, some backing data.
Gets a Path from some source Vertex to some target Vertex. This method is a wrapper around the Toolkit's getPath
method, adding a few ui specific functions to the result.
Path spec options
A Path object. Even if no path exists you will get a return value - but it will just be empty.
Gets the plugin registered for the given type, null if nothing matching found.
For the given object or object ID, retrieve the element that represents it in the UI. This method may return null, specifically in the case that you pass in a Port or Port ID, and that Port is represented as an Endpoint.
HTMLElement that represents the given node, group or port.
Gets the underlying jsPlumb Endpoint that was rendered for the given Port or Vertex.
The Port/Node/Group, or the ID of the Port/Node/Group, to retrieve the Endpoint for.
A jsPlumb Endpoint, null if not found.
Gets the DOM node that was rendered for the Port with the given id (does not retrieve jtk-endpoint elements)
Port id for which to retrieve the rendered element. Note that you must supply the "full" id here, that is in dotted notation with the id of the Node on which the port resides.
DOM element for the given Port id, null if not found.
Returns whether the DOM element represented by el - which can be an Edge, Connection, Node, Group, DOM element, or
ID of some model object - has the given class.
Magnetize the elements in the display, using the given point as the origin.
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.
Amount to change zoom by.
Optional e: anyOriginal event that caused the nudge. May be null.
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%.
Amount to change zoom by.
Optional e: anyOriginal event that caused the nudge. May be null.
The zoom that was set. Zoom will be clamped to the allowed range.
Unbind an event listener from the given DOM Element. This is a utility function that can be used on any element in the DOM, not just things rendered by the Toolkit.
Element, or elements, from which to remove the event binding.
Name of the event to unbind
The function to unbind
Bind an event listener to the given DOM Element. This is a utility function that can be used on any element in the DOM, not just things rendered by the Toolkit.
Element, or elements, to bind the event listener to.
Name of the event to bind to
Either a callback, or if 4 args are given, this is a selector identifying some element(s) within the given element.
Optional callback: FunctionEvent callback.
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.
Element to position.
X location on canvas to move element's left edge to.
Y location on canvas to move element's top edge to.
Optional xShift: numberOptional 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.
Optional yShift: numberOptional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.
Optional ensureOnScreen: booleanIf true, will ensure that x and y positions are never negative.
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.
Element to position.
Event to position element at.
Optional xShift: numberOptional 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.
Optional yShift: numberOptional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.
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.
Element to position.
X location on canvas to move element's left edge to.
Y location on canvas to move element's top edge to.
Optional xShift: numberOptional 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.
Optional yShift: numberOptional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.
Register a custom tag on the Surface. This will only take effect if the Surface is using the Toolkit's default template renderer.
Removes a class from the DOM element represented by el, which can be a Selection, or an instance of many
different types - see the SupportsClassManipulation interface for a complete list.
Rotate the given vertex by the given number of degrees. The DOM element representing the vertex is rotated and the view is updated.
Either a vertex ID, or a Node/Group
Amount - in degrees - to rotate.
Selects a set of Edges. Parameters are the same as for selectEdges; the difference here is that when you're working with Vertices, this method will return all of the vertex's Edges as well as those of all the Ports registered on the Vertex.
Selection parameters
Optional element?: string | BrowserElement | VertexSource or target node, as a Node/Group, a DOM element, or a string (including support for wildcard '*')
Optional source?: string | BrowserElement | VertexSource node, as a Node/Group, a DOM element, or a string (including support for wildcard '*')
Optional target?: string | BrowserElement | VertexTarget node, as a Node/Group, a DOM element, or a string (including support for wildcard '*')
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.
Selection parameters
Optional element?: string | BrowserElement | VertexSource or target node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')
Optional source?: string | BrowserElement | VertexSource node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')
Optional target?: string | BrowserElement | VertexTarget node, as a Node, a DOM element, a selector, or a String (including support for wildcard '*')
Sets the apparent canvas location - see the notes for getApparentCanvasLocation.
Value in pixels for left edge of canvas.
Value in pixels for top edge of canvas.
Location of the actual origin set, after clamping.
Sets the current grid for element dragging, magnetization and group sizing.
Grid to use. If you provide null as the value the grid will be cleared.
Apply the given layout to the viewport, by default refreshing the viewport afterwards.
Sets the position of the given node/group and runs the magnetizer. This operation is wrapped in a transaction on the Toolkit so if undo is called then every element affected by the magnetize is relocated.
Optional doNotUpdateElement: booleanSets the current mode for the surface.
Optional doNotClearSelection: booleanDefaults to false - when true, a mode change will not first cause the selection in the underlying Toolkit to be cleared.
Sets the visible state of the overlays specified by obj
An edge, array of edges, Selection or Path.
True to make the object(s) visible, false to make them invisible.
Rest ...ids: string[]Optional list of overlay ids to operate on. Without this, all overlays on each edge in obj are targeted.
Sets the position of the panned content's origin.
Position in pixels of the left edge of the panned content.
Position in pixels of the top edge of the panned content.
Optional animate: booleanWhether or not to animate the pan. Defaults to false.
Optional onComplete: ((p) => any)If animate is set to true, an optional callback for the end of the pan
Sets the pan and zoom for the Surface in one pass.
Value for pan in x axis
Value for pan in Y axis
Value fo zoom
Optional animate: booleanDefaults to false. If true, the changes will be made with the widget animating.
Sets the position of the given vertex, snapping it to a grid and applying the magnetizer, if necessary. If the given vertex is the child of some group then the group's layout is updated with the new position (and no magnetizer is run); otherwise the main layout is updated with the new position.
Other elements may be moved as a result of this method due to the magnetizer potentially running (Although if it runs, it is not guaranteed to move other elements). For each moved element, a node moved event is fired. All of the move events are contained within a single transaction on the Toolkit so if you undo this operation, all of the affected elements will return to where they were prior to the move.
The vertex to set the position for
X position to set
Y position to set
Sets the visible state of some model object or group of model objects. If the object is a vertex, the visible state will be applied to all edges connected to the given vertex.
By default this method will, for groups and nodes, cascade down to any nested vertices.
Edge, Group, Node or Port, and array of these, or a FilterableDataset, such as a Selection.
True if edges should be visible, false otherwise.
Optional doNotCascade: booleanDefaults to false. If true, don't cascade down to any nested vertices.
Sets the current zoom, clamping it to the allowed range.
Zoom value. If this is outside the allowed bounds it will be clamped.
Optional animate: booleanIf true, the surface will animate the transition in zoom by stepping through several intermediate levels in succession.
Current zoom. This may or may not be the value you asked for - it might have been clamped to the current allowed zoom range.
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.
New range, as an array consisting of [lower, upper] values. Lower must be less than upper.
Optional doNotClamp: booleanIf true, will not check the current zoom to ensure it falls within the new range.
Array of [min, max] current zoom values.
Snaps one or all vertices to the current grid or to the grid provided to this method.
Optional el: string | Element | VertexID of vertex, Vertex, or DOM element representing a Vertex.
Optional grid: GridOptional grid to snap to. If not provided, the Surface will use the grid passed in to its constructor. If that is
also null, nothing will be snapped.
Start editing the given edge or connection, optionally with the given edit parameters.
Optional params: TWrites the current position for each node into the data model. A common use case is to run an auto layout the first time some dataset is seen, and then to save the locations of all the vertices once a human being has moved things around.
Optional params: { Parameters
Optional leftName of the attribute to use for the left position. Default is 'left'
Optional topName of the attribute to use for the top position. Default is 'top'
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.
X location
Y location
The mapped location, as a PointXY object.
Toggles a class on the DOM element represented by el, which can be a Selection, or an instance of many
different types - see the SupportsClassManipulation interface for a complete list.
Unbind the given event listener, or all listeners. If you call this method with no arguments then all event listeners are unbound.
Optional eventOrListener: string | FunctionEither an event name, or an event handler function
Optional listener: FunctionIf eventOrListener is defined, this is the event handler to unbind.
Unbinds a listener for a model event.
Name of the event to unbind.
Function to unbind.
Zooms the display so that the background (if one is set) fits inside the viewport.
Optional doIf true, centering content will not use animation.
Optional onOptional function to call on operation complete (centering may be animated).
Zooms the viewport so that all of the given elements are visible.
Optional doOptional doOptional doOptional fill?: numberOptional onOptional onZooms 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:true on the
parameters to this method.
Optional params: { Optional doBy default, the centering content step does not use animation. This is due to this method being used most often to initially setup a UI.
Optional doDefaults to false. If true, no action is taken if the content is currently all visible.
Optional fill?: numberAmount of the viewport to fill. By default, this method will zoom so that the content is 0.9 times the size of the viewport. Aesthetically this makes for a more pleasing result than filling the viewport entirely.
Optional onOptional function to call on operation complete (centering may be animated).
Optional onOptional function to call on operation step (centering may be animated).
Optional padding?: numberOptional padding to leave around all elements. Defaults to 0.
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).
Optional params: { Optional doBy default, the centering content step does not use animation. This is due to this method being used most often to initially setup a UI.
Optional fill?: numberAmount of the viewport to fill. By default, this method will zoom so that the content is 0.9 times the size of the viewport. Aesthetically this makes for a more pleasing result than filling the viewport entirely.
Optional onOptional function to call on operation complete (centering may be animated).
Optional onOptional function to call on operation step (centering may be animated).
Optional padding?: numberOptional padding to leave around all elements. Defaults to 0.
Zooms the display so that the current selected nodes are all visible, optionally animating the transition.
Optional method params
Optional doBy default the widget does not animate this operation. You can override that behaviour by setting doNotAnimate:false.
Optional doIf true, no action is taken if the content is currently all visible. Defaults to false.
Optional fill?: numberA decimal indicating how much of the viewport to fill with the zoomed content. Defaults to a value of 0.90.
Optional filter?: ((o) => boolean | ObjectData)Optional function to use as a filter; we create the selection by running this filter by the Toolkit's filter method.
Optional selection?: Selection<Edge | Node | Group>Optional Selection to which to zoom. If omitted, the default is to use the Toolkit's current selection.
An infinite panning canvas support pan/zoom, templating and plugins, with a number of useful methods for navigating the UI. This class is the core of the JsPlumb UI.