Skip to main content

Home > @jsplumbtoolkit/browser-ui > Surface

Surface class#

Signature:

export declare class Surface extends OptimisticEventGenerator implements ToolkitRenderer<Element> 

Extends: OptimisticEventGenerator

Implements: ToolkitRenderer<Element>

Constructors#

ConstructorModifiersDescription
(constructor)(params, templateRenderer)Constructs a new instance of the Surface class

Properties#

PropertyModifiersTypeDescription
_debugboolean
_ignoreToolkitEventsboolean
_layoutAbstractLayout<any>
_layoutMapMap<string, AbstractLayout<any>>
_modelLeftAttributestring
_modelTopAttributestring
_refreshAutomaticallyboolean
_suspendRenderingboolean
autoExitSelectModeboolean
canvasElementElement
connMapDictionary<Connection>
containerElement
containerElementElement
containerIdstring
contentBoundsany
dataSourceDataSource
decoratorsArray<Decorator>
directRenderboolean
dragGroupAssigner(v: Vertex) => DragGroupSpec
dragOptionsSurfaceDragOptions
elementsDraggableboolean
enhancedViewboolean
groupRendererObjectRenderer<Element, Group>
idstring
jsplumbBrowserJsPlumbInstance
modeSurfaceMode
nodeRendererObjectRenderer<Element, Node>
objectFilter(b: Base) => boolean
panZoomPanZoom
pluginMapMap<string, SurfacePlugin>
pluginsArray<SurfacePlugin>
portRendererObjectRenderer<Element, Port>
refreshLayoutOnEdgeConnectboolean
toolkitInstanceBrowserUIBase
typestaticstring
unrenderedEdgesArray<Edge>
vertexListArray<Node>
viewBrowserUIModel
viewportViewport<{ E: Element; }>
wheelReverseboolean
zoomToFitOnLoadboolean

Methods#

MethodModifiersDescription
_loadExistingData(params)
activateState(stateId, target)Activates the UI state with the given ID on the objects contained in the given target. If target is not supplied, the state is activated against the entire dataset.
addClass(el, clazz)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.
addPlugin(pluginSpec)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.
addToDragGroup(spec, objects)Adds the given objects to the given drag group.
adHocLayout(layoutParams)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!)
assignToDragGroup(objects)Runs each of the given objects through the code that automatically assigns them to a drag group.
autoSizeGroups(force)Run the group auto size routine on every group in the Surface.
batch(fn)Wraps the underlying Toolkit's batch function with the added step of first suspending events being fired from this renderer.
bind(evt, fn)Bind the given handler to the event with the given name.
bindModelEvent(event, selector, callback)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
centerContent(params)Centers the tracked content inside the viewport, but does not adjust the current zoom.
centerOnAndZoom(element, fillRatio)Center on the current object and zoom in on it.
collapseGroup(group)Collapse the given group
deactivateState(stateId, target)Deactivates the UI state with the given ID on the objects contained in the given target. If target is not supplied, the state is deactivated against the entire dataset.
destroy()
expandGroup(group)Expand the given group
findIntersectingGroups(origin, dimensions, enclosed, dontIncludeNestedGroups)Finds Groups (not Nodes) - that intersect a rectangle defined by the given origin and dimensions.
findIntersectingNodes(origin, dimensions, enclosed, dontIncludeNodesInsideGroups)Finds Nodes (not Groups) - that intersect a rectangle defined by the given origin and dimensions.
findIntersectingVertices(origin, dimensions, enclosed, dontIncludeGroups, dontIncludeNodes, dontIncludeNodesInsideGroups, dontIncludeNestedGroups)Finds vertices - Nodes or Groups - that intersect a rectangle defined by the given origin and dimensions.
fireNodeAdded(p)
fixElement(el, constraints, pos)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.
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.
fromPageLocation(left, top, doNotAdjustForOffset)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.
gather(focus)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.
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.
getBoundsInfo()Gets the current bounds information.
getConnectionForEdge(edge)Gets the underlying connection for the given Edge. Used internally.
getConnectionsForEdges(edges)Gets an array of Connections for the given array of Edges.
getContainer()Returns the element used as container for the Surface.
getCoordinates(el)Gets the origin and size of an element that is being managed by the Surface.
getGrid()Get the current grid.
getGroups()
getLabelLocationAttribute(edge)Gets the name of the attribute that is used to determine the label for the given edge.
getModelObjectFromElement(el, searchAncestors)For a given element, retrieve the model object it represents.
getModelObjectFromEndpoint(ep)For a given endpoint, retrieve the model object it represents.
getModelPositionAttributes()Gets the name of the attributes used to determine location from an object's backing data.
getNodes()
getObjectInfo(obj)
getOffset(el)Gets the offset for the given DOM element.
getPan()Gets the current [left,top] of the panned content.
getPath(params)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.
getPlugin(pluginType)Gets the plugin registered for the given type, null if nothing matching found.
getPosition(el)Gets the position of the given vertex, null if no matching vertex found.
getRenderedConnection(edgeId)Gets the underlying jsPlumb connection that was rendered for the Edge with the given id.
getRenderedElement(obj)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.
getRenderedEndpoint(vertexId)Gets the underlying jsPlumb Endpoint that was rendered for the given Port or Vertex.
getRenderedPort(portId)Gets the DOM node that was rendered for the Port with the given id.
getRenderedVertex(vertexId)Gets the DOM node that was rendered for the Node/Group with the given id.
getViewportPosition(obj)For the given vertex, retrieve its position in the viewport, including any current rotation.
getViewportPositionById(id)For the given vertex id, retrieve its position in the viewport, including any current rotation.
getZoom()Gets the current zoom.
getZoomRange()Gets the current zoom range.
hasClass(el, clazz)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.
isClamping()Returns whether or not the widget clamps the movement of the canvas during pan/zoom/
isInViewport(x, y)Returns whether or not the given point (relative to page origin) is within the viewport for the widget.
magnetize(focus)Magnetize the elements in the display. If focus is provided it will be used as the origin for magnetization, and not moved. If no focus is provided, the computed center of all the elements will be used as the origin.
magnetizeAtEvent(event)Magnetize the elements in the display, using the location of the given event as the origin.
magnetizeAtPoint(origin)Magnetize the elements in the display, using the given point as the origin.
mapEventLocation(event, doNotAdjustForOffset)Maps the location of the given event on the page onto the coordinate space of this widget, returning a value representing where the given event appears to be with respect to the origin of the Surface's viewport.
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.
nudgeZoom(delta, e)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%.
off(el, event, handler)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.
on(el, event, callbackOrSelector, callback)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.
pan(dx, dy, animate)Pans the content by dx and dy.
refresh(_internal)Refresh the layout and update all connections.
relayout(newParameters)
relayoutGroup(group)Relayout the given group.
relayoutGroups()Relayout all of the groups in the Surface.
reload()
removeClass(el, clazz)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.
removeFromDragGroup(objects)Removes the given object(s) from any drag group they may belong to. You don't need to specify the name of the drag group since an object may belong to only one at a time.
repaint(obj, alsoResetToLayoutPosition)Repaint the given vertex.
repaintEverything()Redraw all connections.
resetState()Resets (clears) the UI state of all objects in the current dataset.
rotate(obj, amountInDegrees)Rotate the given vertex by the given number of degrees. The DOM element representing the vertex is rotated and the view is updated.
selectAllEdges(params)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.
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.
setAbsolutePosition(el, p)Set the absolute position of the given element. Does not update the pan/zoom or any plugins - this is meant to be used as a helper method for positioning elements not directly under the Surface's control.
setApparentCanvasLocation(left, top)Sets the apparent canvas location - see the notes for getApparentCanvasLocation.
setClamping(c)Sets whether or not the widget clamps the movement of the canvas during pan/zoom to ensure that the managed content never disappears from view.
setEnabled(v, state)Sets whether the given vertex is enabled for connection drag/drop.
setGrid(grid)Sets the current grid for element dragging, magnetization and group sizing.
setHoverSuspended(s)Sets whether hover events are currently suspended. Used by some plugins.
setLayout(layoutParams, doNotRefresh)Apply the given layout to the viewport, by default refreshing the viewport afterwards.
setMagnetizedPosition(vertex, x, y, doNotUpdateElement)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.
setMode(mode, doNotClearSelection)Sets the current mode for the surface.
setPan(left, top, animate, onComplete, onStep)Sets the position of the panned content's origin.
setPanAndZoom(x, y, zoom, animate)Sets the pan and zoom for the Surface in one pass.
setPosition(vertex, x, y)Sets the position of the given vertex, snapping it to a grid and applying the magnetizer, if necessary. Other elements may be moved as a result of this method due to the magnetizer. 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.
setRefreshAutomatically(refreshAutomatically)
setSize(id, w, h)Sets the size of element representing the given vertex in the DOM, updating the layout.
setSuspendRendering(val, thenRefresh)Sets whether rendering is suspended or not.
setVertexPosition(vertex, left, top)Set the position of the given node/group, updating the pan/zoom bounds and repainting any edges attached to the given vertex.
setView(view)Sets the current view for this renderer.
setVisible(obj, state, doNotCascade)Sets the visible state of either an Edge, or of the Edges connected to some Vertex. By default this method will, for groups and nodes, cascade down to any nested vertices.
setZoom(zoom, animate)Sets the current zoom, clamping it to the allowed range.
setZoomRange(zr, 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.
sizeGroupToFit(group, force)Run the group auto size routine on a given groups.
snapToGrid(el, grid)Snaps one or all vertices to the current grid or to the grid provided to this method.
storePositionInModel(params)
storePositionsInModel(params)Writes 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.
toggleClass(el, clazz)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.
toggleGroup(group)Expand/collapse the given group, depending on the current state.
toPageLocation(left, top, doNotAdjustForOffset)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.
unbindModelEvent(event, handler)Unbinds a listener for a model event.
whileIgnoringToolkitEvents(fn)Run the given function with events suspended.
zoomToElements(zParams)Zooms the viewport so that all of the given elements are visible.
zoomToFit(params)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:true on the parameters to this method.
zoomToFitIfNecessary(params)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).
zoomToSelection(params)Zooms the display so that the current selected nodes are all visible, optionally animating the transition.