Home > @jsplumbtoolkit/browser-ui > Surface
Surface class
Signature:
export declare class Surface extends OptimisticEventGenerator implements ToolkitRenderer<Element>
Extends: OptimisticEventGenerator
Implements: ToolkitRenderer<Element>
Constructors
| Constructor | Modifiers | Description |
|---|---|---|
| (constructor)(params, templateRenderer) | Constructs a new instance of the Surface class |
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| _$_layoutMap | Map<string, AbstractLayout<any>> | ||
| _$_simpleEdgeStyles | boolean | ||
| _debug | boolean | ||
| _ignoreToolkitEvents | boolean | ||
| _layout | AbstractLayout<any> | ||
| _modelLeftAttribute | string | ||
| _modelTopAttribute | string | ||
| _unrenderedVertices | Map<string, { vertex: Vertex; def: any; eventInfo: any; }> | list of vertices that have been passed to the renderer but which have not yet been reported as rendered. | |
| autoExitSelectMode | boolean | ||
| canvasElement | Element | ||
| connMap | Record<string, Connection> | ||
| container | Element | ||
| containerElement | Element | ||
| containerId | string | ||
| contentBounds | any | ||
| dataSource | DataSource | ||
| decorators | Array<Decorator> | ||
| dragOptions | SurfaceDragOptions | ||
| elementsDraggable | boolean | ||
| enhancedView | boolean | ||
| id | string | ||
| jsplumb | BrowserJsPlumbInstance | ||
| logicalPorts | boolean | Defaults to false. When true, if a port is added to a vertex programmatically, the surface treats the vertex's DOM element as the DOM element for the port if it cannot find a specific element for the port. | |
| mode | SurfaceMode | ||
| objectFilter | (b: Base) => boolean | ||
| panZoom | PanZoom | ||
| pluginMap | Map<string, SurfacePlugin> | ||
| plugins | Array<SurfacePlugin> | ||
| refreshLayoutOnEdgeConnect | boolean | ||
| toolkitInstance | BrowserUIBase | ||
| type | static | string | |
| vertexList | Array<Node> | ||
| view | BrowserUIModel | ||
| viewport | Viewport<{ E: Element; }> | ||
| wheelReverse | boolean | ||
| zoomToFitOnLoad | boolean |
Methods
| Method | Modifiers | Description |
|---|---|---|
| _loadExistingData(params) | ||
| 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. | |
| 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!) | |
| 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. | |
| bindModelEvent(event, selector, callback) | Binds to a mouse event occurring on a given model object. This is a wrapper around the 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 (so the content may still extend past the viewport bounds) | |
| centerOn(element) | Takes a node/group as argument and positions the surface canvas such that the given node is at the center in both axes. | |
| centerOnAndZoom(element, fillRatio, doNotAnimate) | Center on the current object and zoom in on it. | |
| centerOnHorizontally(element) | Takes a node/group as argument and positions the surface canvas such that the given node is at the center in the horizontal axis. | |
| centerOnVertically(element) | Takes a node/group as argument and positions the surface canvas such that the given node is at the center in the vertical axis. | |
| collapseGroup(group) | Collapse the given group | |
| destroy() | 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. | |
| 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 {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. | |
| 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, relativeToCanvasRoot) | 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. | |
| 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) | 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. | |
| getPan() | Gets the current origin 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. | |
| 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 (does not retrieve jtk-endpoint elements) | |
| getRenderedVertex(vertexId) | Gets the DOM node that was rendered for the Node/Group with the given id. | |
| 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/ | |
| isDataLoading() | ||
| isInViewport(x, y) | Returns whether or not the given point (relative to page origin) is within the viewport for the widget. | |
| isSuspendRendering() | ||
| 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, doNotAnimate) | Pans the canvas by a given amount in X and Y. | |
| positionElementAt(el, x, y, xShift, yShift, ensureOnScreen) | 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. | |
| positionElementAtEventLocation(el, evt, xShift, yShift) | 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. | |
| positionElementAtPageLocation(el, x, y, xShift, yShift) | 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. | |
| refresh(_internal) | Refresh the layout and update all connections. | |
| relayout(newParameters) | Clears and re-runs the layout, optionally with a new set of parameters. | |
| reload() | When the Surface is rendering a Selection, this method triggers a reload on the selection, causing the UI to be cleared and recreated. | |
| 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. | |
| repaintEverything() | Redraw all connections. | |
| 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(clamping) | 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. | |
| setDraggable(el, draggable) | Sets whether or not the given element, or element representing the given vertex, is draggable. | |
| 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. | |
| setOverlaysVisible(obj, state, ids) | Sets the visible state of the overlays specified by obj | |
| setPan(left, top, animate, onComplete) | 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. 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. | |
| 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. | |
| setView(view) | Sets the current view for this renderer. | |
| setVisible(obj, state, doNotCascade) | 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. | |
| 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) | Writes the current position for the given vertex into the data model. | |
| 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. | |
| zoomToBackground(params) | Zooms the display so that the background (if one is set) fits inside the viewport. | |
| 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. |