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.

Hierarchy (view full)

Implements

  • ToolkitRenderer<BrowserElement>

Properties

Methods

_sizeElasticGroupFrame _trackGroupSizeChanges adHocGroupLayout adHocLayout addClass addPlugin autoSizeGroups batch bind bindModelEvent centerContent centerOn centerOnAndZoom centerOnHorizontally centerOnVertically clearPathEdits collapseGroup destroy expandGroup findAllIntersectingVerticesInCanvas findIntersectingGroups findIntersectingNodes findIntersectingVertices fire fixElement floatElement fromPageLocation gather getApparentCanvasLocation getBoundsInfo getConnectionForEdge getConnectionsForEdges getContainer getCoordinates getDecorator getGrid getLabelLocationAttribute getListener getModelObjectFromElement getModelPositionAttributes getObjectInfo getPan getPath getPlugin getRenderedConnection getRenderedElement getRenderedEndpoint getRenderedPort getRenderedVertex getZoom getZoomRange hasClass isClamping isInViewport isSuspendEvents isSuspendRendering magnetize magnetizeAtEvent magnetizeAtPoint mapEventLocation nudgeWheelZoom nudgeZoom off on pan positionElementAt positionElementAtEventLocation positionElementAtPageLocation refresh registerTag relayout relayoutGroup reload removeClass repaintEverything rotate selectAllEdges selectEdges setApparentCanvasLocation setClamping setDraggable setEnabled setGrid setHoverSuspended setLayout setMagnetizedPosition setMode setOverlaysVisible setPan setPanAndZoom setPosition setSize setSuspendEvents setSuspendRendering setVisible setZoom setZoomRange silently sizeGroupToFit snapToGrid startEditingPath stopEditingPath storePositionInModel storePositionsInModel toPageLocation toggleClass toggleGroup unbind unbindModelEvent unfixElement zoomToBackground zoomToDecorator zoomToElements zoomToExtents zoomToFit zoomToFitIfNecessary zoomToSelection

Properties

_unrenderedEdges: Edge[] = []

list of edges that are as-yet unrendered due to one or both of their vertices not having been rendered.

_unrenderedVertices: Map<string, {
    def: any;
    eventInfo: any;
    vertex: Vertex;
}> = ...

list of vertices that have been passed to the renderer but which have not yet been reported as rendered.

Type declaration

  • def: any
  • eventInfo: any
  • vertex: Vertex

Methods

  • Private

    sizes the current

    Parameters

    • event: MouseEvent
    • Optional focusPosition: PointXY

    Returns void

  • Private

    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.

    Parameters

    • resizedGroups: Record<string, {
          group: Group;
          newGroupSize: Size;
          originalGroupSize: Size;
      }>
    • Optional updateUI: boolean

    Returns void

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

    Type Parameters

    Parameters

    • group: string | Group
    • layoutParams: {
          options: LP;
          type: string;
      }
      • options: LP
      • type: string

    Returns void

  • 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!)

    Type Parameters

    Parameters

    • layoutParams: {
          options: LP;
          type: string;
      }
      • options: LP
      • type: string

    Returns void

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

    Parameters

    Returns void

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

    Type Parameters

    Parameters

    Returns T

  • Run the group auto size routine on every group in the Surface.

    Parameters

    • Optional force: boolean

      If true, this flag will override any autoSize:false directives on the groups in the Surface.

    Returns void

  • Wraps the underlying Toolkit's batch function with the added step of first suspending events being fired from this renderer.

    Parameters

    • fn: (() => any)

      Function to run while rendering and events are both suspended.

        • (): any
        • Returns any

    Returns void

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

    Type Parameters

    • T = any

    Parameters

    • event: string

      Name of the event(s) to bind to.

    • listener: ((a, e?) => any)

      Function to bind to the given event(s)

        • (a, e?): any
        • Parameters

          • a: T
          • Optional e: any

          Returns any

    • Optional insertAtStart: boolean

      Whether or not to insert this listener at the head of the listener queue. Defaults to false.

    Returns EventGenerator

  • 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

    Type Parameters

    • T extends Edge | Vertex | Node | Group | Port

    Parameters

    • event: string

      Name of the event to bind to.

    • selector: string

      CSS3 selector that identifies children of a vertex DOM element on which the event handler should be bound.

    • callback: ModelEventCallback<T>

      Function to call when the event is fired.

    Returns void

  • Centers the tracked content inside the viewport, but does not adjust the current zoom (so the content may still extend past the viewport bounds)

    Parameters

    Returns void

  • Takes a node/group as argument and positions the surface canvas such that the given node is at the center in both axes.

    Parameters

    • element: string | Element | Vertex

      The element to center. Can be a DOM element, vertex id, or a Node/Group.

    Returns void

  • Center on the current object and zoom in on it.

    Parameters

    • element: string | Element | Vertex

      The element to center. Can be a DOM element, vertex id, or a Node/Group

    • Optional fillRatio: number

      How 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: boolean

      by default, this operation will be animated.

    Returns void

  • Takes a node/group as argument and positions the surface canvas such that the given node is at the center in the horizontal axis.

    Parameters

    • element: string | Element | Vertex

      The element to center. Can be a DOM element, vertex id, or a Node/Group

    Returns void

  • Takes a node/group as argument and positions the surface canvas such that the given node is at the center in the vertical axis.

    Parameters

    • element: string | Element | Vertex

      The element to center. Can be a DOM element, vertex id, or a Node/Group

    Returns void

  • Clear the edits for the given connection, returning its path to the automatically computed path.

    Parameters

    • edgeOrConnection: string | Edge | Connection<BrowserElement>

    Returns boolean

  • Collapse the given group

    Parameters

    • group: string | Group

      Group ID, or Group, to collapse

    Returns void

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

    Returns void

  • Expand the given group

    Parameters

    • group: string | Group

      Group ID, or Group, to expand

    Returns void

  • Finds all vertices in the entire canvas (ie. on the main canvas and inside all groups, nested to any level) that intersct, or are enclosed by, a rectangle defined by the given origin and dimensions.

    Type Parameters

    • T extends Node<T>

    Parameters

    • origin: PointXY
    • dimensions: Size
    • Optional enclosed: boolean

    Returns IntersectingVertex<T>[]

  • Finds Groups (not Nodes) - that intersect a rectangle defined by the given origin and dimensions.

    Parameters

    • origin: PointXY

      Origin of the rectangle to test

    • dimensions: Size

      Width and height of the rectangle to test

    • Optional enclosed: boolean

      If true, vertices must be fully enclosed by the rectangle

    • Optional dontIncludeNestedGroups: boolean

      If true, Nodes inside Groups are omitted from the search

    Returns IntersectingVertex<Group>[]

  • Finds Nodes (not Groups) - that intersect a rectangle defined by the given origin and dimensions.

    Parameters

    • origin: PointXY

      Origin of the rectangle to test

    • dimensions: Size

      Width and height of the rectangle to test

    • Optional enclosed: boolean

      If true, vertices must be fully enclosed by the rectangle

    • Optional dontIncludeNodesInsideGroups: boolean

      If true, Nodes inside Groups are omitted from the search

    Returns IntersectingVertex<Node>[]

  • Finds vertices - Nodes or Groups - that intersect, or are enclosed by, a rectangle defined by the given origin and dimensions.

    Type Parameters

    • T extends Node<T>

    Parameters

    • origin: PointXY

      Origin of the rectangle to test

    • dimensions: Size

      Width and height of the rectangle to test

    • Optional enclosed: boolean

      If true, vertices must be fully enclosed by the rectangle

    • Optional dontIncludeGroups: boolean

      If true, Groups are omitted from the search

    • Optional dontIncludeNodes: boolean

      If true, Nodes are omitted from the search

    • Optional dontIncludeNodesInsideGroups: boolean

      If true, Nodes inside Groups are omitted from the search

    • Optional dontIncludeNestedGroups: boolean

      If true, Groups that are nested inside other Groups are omitted from the search

    Returns IntersectingVertex<T>[]

  • Fire the named event.

    Type Parameters

    • T

    Parameters

    • event: string

      Event to fire

    • Optional value: T

      Value to pass to event handlers

    • Optional originalEvent: Event

      Optional original event that caused this event to be fired.

    Returns any

  • Appends an element to the viewport such that it is zoomed with everything else, but constrains placement in one or both axes so that the element remains fixed with respect to the viewport origin as the canvas pans and/or zooms.

    Parameters

    • el: BrowserElement

      The element to append.

    • pos: PointXY

      Location of the element's origin.

    • Optional constraints: FixedElementConstraints

      Flags to indicate optional constraint to each axis.

    • Optional id: string

      Optional ID to assign to the element, for future retrieval

    Returns FixedElement

  • 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: BrowserElement

      Element to float.

    • pos: PointXY

      Position to float the element at.

    Returns void

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

    Parameters

    • left: number

      X location

    • top: number

      Y location

    Returns PointXY

    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.

    Parameters

    • Optional focus: string | Vertex

      Optional ID of a Vertex, or the Vertex itself, around which to gather elements.

    Returns void

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

    Returns PointXY

    Top left location of the canvas, relative to the viewport's 0,0.

  • Gets the underlying connection for the given Edge. Used internally.

    Parameters

    • edge: Edge

    Returns Connection<BrowserElement>

  • Gets an array of Connections for the given array of Edges.

    Parameters

    • edges: Edge[]

    Returns Connection<BrowserElement>[]

  • Returns the element used as container for the Surface.

    Returns any

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

    Parameters

    • el: string | Element | Vertex

      Vertex id, element, or Vertex to get position for.

    • Optional relativeToCanvasRoot: boolean

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

    Returns BoundingBox

    A RectangleXY if element was found, otherwise null.

  • Gets the decorator with the given id, or null if not found.

    Type Parameters

    Parameters

    • id: string

    Returns T

  • Get the current grid.

    Returns Grid

  • Gets the name of the attribute that is used to determine the label for the given edge.

    Parameters

    • edge: Edge

    Returns string

  • For a given element, retrieve the model object it represents.

    Parameters

    • el: Element
    • Optional searchAncestors: boolean

      Defaults to false. If true, ancestors of the given element are searched, up to the underlying container element.

    Returns Edge | Vertex | Node | Group | Port

    a Port, Node, Edge, Group, or null.

  • Gets the name of the attributes used to determine location from an object's backing data.

    Returns [string, string]

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

    Type Parameters

    • T extends Edge | Base | Vertex | Node | Group | Port

    Parameters

    • obj: string | Element | Edge | Node | Group | ObjectData | Connection<BrowserElement>

      Object to decode. Can be in many different forms - an existing model object, a vertex id, a DOM element, a Connection, some backing data.

    Returns SurfaceObjectInfo<T>

  • Gets the current origin of the panned content.

    Returns PointXY

    Position, in pixels, of the panned content, where 0,0 is the origin of the viewport.

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

    Parameters

    Returns UIPath

    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.

    Type Parameters

    Parameters

    • pluginType: string

    Returns T

  • Gets the underlying jsPlumb connection that was rendered for the Edge with the given id.

    Parameters

    • edgeId: string

      ID of the Edge to retrieve the Connection for.

    Returns Connection<BrowserElement>

    A jsPlumb Connection, null if not 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.

    Parameters

    • obj: string | Base

    Returns BrowserElement

    HTMLElement that represents the given node, group or port.

  • Gets the underlying jsPlumb Endpoint that was rendered for the given Port or Vertex.

    Parameters

    • vertexId: string

      The Port/Node/Group, or the ID of the Port/Node/Group, to retrieve the Endpoint for.

    Returns Endpoint<BrowserElement>

    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)

    Parameters

    • portId: string

      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.

    Returns BrowserElement

    DOM element for the given Port id, null if not found.

  • Gets the DOM node that was rendered for the Node/Group with the given id.

    Parameters

    • vertexId: string

      Id for node/group for which to retrieve the rendered element.

    Returns BrowserElement

    DOM element for the given vertex id, null if not found.

  • Gets the current zoom.

    Returns number

    Current zoom value

  • Gets the current zoom range.

    Returns ZoomRange

    Array of [min, max] current zoom values.

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

    Parameters

    Returns boolean

  • Returns whether or not the widget clamps the movement of the canvas during pan/zoom/

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

  • Returns whether or not rendering is currently suspended.

    Returns boolean

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

    Parameters

    • Optional focus: string | Vertex

    Returns void

  • Magnetize the elements in the display, using the location of the given event as the origin.

    Parameters

    • event: Event

    Returns void

  • Magnetize the elements in the display, using the given point as the origin.

    Parameters

    Returns void

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

    Parameters

    • event: Event

    Returns PointXY

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

    • Optional e: any

      Original event that caused the nudge. May be null.

    Returns void

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

    • Optional e: any

      Original event that caused the nudge. May be null.

    Returns number

    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.

    Parameters

    • el: Element | Document | BrowserElement | NodeListOf<BrowserElement>

      Element, or elements, from which to remove the event binding.

    • event: string

      Name of the event to unbind

    • handler: Function

      The function to unbind

    Returns void

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

    Parameters

    • el: Element | Document | BrowserElement | NodeListOf<BrowserElement>

      Element, or elements, to bind the event listener to.

    • event: string

      Name of the event to bind to

    • callbackOrSelector: string | Function

      Either a callback, or if 4 args are given, this is a selector identifying some element(s) within the given element.

    • Optional callback: Function

      Event callback.

    Returns void

  • Pans the canvas by a given amount in X and Y.

    Parameters

    • dx: number

      Amount to pan in X direction

    • dy: number

      Amount to pan in Y direction

    • Optional doNotAnimate: boolean

      By default this operation uses animation.

    Returns void

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

    Parameters

    • el: Element

      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.

    • Optional xShift: number

      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.

    • Optional yShift: number

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

    • Optional ensureOnScreen: boolean

      If true, will ensure that x and y positions are never negative.

    Returns void

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

    Parameters

    • el: Element

      Element to position.

    • evt: Event

      Event to position element at.

    • Optional xShift: number

      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.

    • Optional yShift: number

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

    Returns void

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

    Parameters

    • el: Element

      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.

    • Optional xShift: number

      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.

    • Optional yShift: number

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

    Returns void

  • Refresh the layout and update all connections.

    Parameters

    • Optional _internal: boolean

      For internal use. It is not recommended you set this flag if you call this method: it is a means for the Toolkit to override the suspension of rendering, if it needs to.

    Returns void

  • Register a custom tag on the Surface. This will only take effect if the Surface is using the Toolkit's default template renderer.

    Parameters

    Returns void

  • Clears and re-runs the layout, optionally with a new set of parameters.

    Parameters

    • Optional newParameters: any

    Returns void

  • Relayout the given group.

    Parameters

    • groupOrId: string | Group

      Group, or ID of group, to relayout.

    • reason: GroupRelayoutReason

    Returns void

  • When the Surface is rendering a Selection, this method triggers a reload on the selection, causing the UI to be cleared and recreated.

    Returns void

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

    Parameters

    Returns void

  • Redraw all connections.

    Returns void

  • Rotate the given vertex by the given number of degrees. The DOM element representing the vertex is rotated and the view is updated.

    Parameters

    • obj: string | Vertex

      Either a vertex ID, or a Node/Group

    • amountInDegrees: number

      Amount - in degrees - to rotate.

    Returns void

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

    Parameters

    • params: {
          element?: string | BrowserElement | Vertex;
          source?: string | BrowserElement | Vertex;
          target?: string | BrowserElement | Vertex;
      }

      Selection parameters

      • Optional element?: string | BrowserElement | Vertex

        Source or target node, as a Node/Group, a DOM element, or a string (including support for wildcard '*')

      • Optional source?: string | BrowserElement | Vertex

        Source node, as a Node/Group, a DOM element, or a string (including support for wildcard '*')

      • Optional target?: string | BrowserElement | Vertex

        Target node, as a Node/Group, a DOM element, or a string (including support for wildcard '*')

    Returns ConnectionSelection

  • 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: {
          element?: string | BrowserElement | Vertex;
          source?: string | BrowserElement | Vertex;
          target?: string | BrowserElement | Vertex;
      }

      Selection parameters

      • Optional element?: string | BrowserElement | Vertex

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

      • Optional source?: string | BrowserElement | Vertex

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

      • Optional target?: string | BrowserElement | Vertex

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

    Returns ConnectionSelection

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

    Location of the actual origin set, after 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.

    Parameters

    • clamping: boolean

      Whether or not to clamp movement.

    Returns void

  • Sets whether or not the given element, or element representing the given vertex, is draggable.

    Parameters

    • el: string | Element | Vertex

      Vertex id, vertex, or DOM element

    • draggable: boolean

    Returns void

  • Sets whether the given vertex is enabled for connection drag/drop.

    Parameters

    • v: Vertex

      The vertex to set enabled state for. In the UI this could resolve to an element, or to an Endpoint.

    • state: boolean

    Returns boolean

  • Sets the current grid for element dragging, magnetization and group sizing.

    Parameters

    • grid: Grid

      Grid to use. If you provide null as the value the grid will be cleared.

    Returns void

  • Sets whether hover events are currently suspended. Used by some plugins.

    Parameters

    • s: boolean

    Returns void

  • Apply the given layout to the viewport, by default refreshing the viewport afterwards.

    Type Parameters

    Parameters

    • layoutParams: {
          options?: LP;
          type: string;
      }
      • Optional options?: LP
      • type: string
    • Optional doNotRefresh: boolean

    Returns void

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

    Parameters

    • vertex: string | Element | Node | Group
    • x: number
    • y: number
    • Optional doNotUpdateElement: boolean

    Returns {
        movedElements: Record<string, {
            current: PointXY;
            original: PointXY;
        }>;
        resizedGroups: Record<string, {
            group: Group;
            newSize: Size;
            originalSize: Size;
        }>;
    }

    • movedElements: Record<string, {
          current: PointXY;
          original: PointXY;
      }>
    • resizedGroups: Record<string, {
          group: Group;
          newSize: Size;
          originalSize: Size;
      }>
  • Sets the current mode for the surface.

    Parameters

    • mode: SurfaceMode
    • Optional doNotClearSelection: boolean

      Defaults to false - when true, a mode change will not first cause the selection in the underlying Toolkit to be cleared.

    Returns void

  • Sets the visible state of the overlays specified by obj

    Parameters

    • obj: Edge | FilterableDataset | ArrayLike<Edge>

      An edge, array of edges, Selection or Path.

    • state: boolean

      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.

    Returns void

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

    • Optional animate: boolean

      Whether 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

        • (p): any
        • Parameters

          Returns any

    Returns void

  • Sets the pan and zoom for the Surface in one pass.

    Parameters

    • x: number

      Value for pan in x axis

    • y: number

      Value for pan in Y axis

    • zoom: number

      Value fo zoom

    • Optional animate: boolean

      Defaults to false. If true, the changes will be made with the widget animating.

    Returns void

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

    Parameters

    • vertex: string | Element | Node | Group

      The vertex to set the position for

    • x: number

      X position to set

    • y: number

      Y position to set

    • Optional andUpdateUI: boolean
    • Optional doNotRunGroupResize: boolean

    Returns void

  • Sets the size of element representing the given vertex in the DOM, updating the layout.

    Parameters

    • id: string
    • w: number
    • h: number

    Returns void

  • Sets whether rendering is suspended or not.

    Parameters

    • val: boolean
    • Optional thenRefresh: boolean

      If true, the surface will refresh after the change in state.

    Returns void

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

    Parameters

    • obj: ArrayLike<any> | Base | FilterableDataset

      Edge, Group, Node or Port, and array of these, or a FilterableDataset, such as a Selection.

    • state: boolean

      True if edges should be visible, false otherwise.

    • Optional doNotCascade: boolean

      Defaults to false. If true, don't cascade down to any nested vertices.

    Returns void

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

    • Optional animate: boolean

      If true, the surface will animate the transition in zoom by stepping through several intermediate levels in succession.

    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.

  • 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: ZoomRange

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

    • Optional doNotClamp: boolean

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

    Returns ZoomRange

    Array of [min, max] current zoom values.

  • Run the group auto size routine on a given groups, and moves element around as necessary

    Parameters

    • group: Group

      The group to auto size

    • Optional force: boolean

      If true, this flag will override an autoSize:false directive on the Group.

    Returns void

  • Snaps one or all vertices to the current grid or to the grid provided to this method.

    Parameters

    • Optional el: string | Element | Vertex

      ID of vertex, Vertex, or DOM element representing a Vertex.

    • Optional grid: Grid

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

    Returns Record<string, {
        current: PointXY;
        original: PointXY;
    }>

  • Start editing the given edge or connection, optionally with the given edit parameters.

    Type Parameters

    Parameters

    • edgeOrConnection: Edge | Connection<BrowserElement>
    • Optional params: T

    Returns void

  • Stop editing any connector paths.

    Returns void

  • Writes the current position for the given vertex into the data model.

    Parameters

    • params: string | {
          force?: boolean;
          id: string;
          leftAttribute?: string;
          obj?: Node | Group;
          pos?: PointXY;
          topAttribute?: string;
      }

      Parameters

    Returns PointXY

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

    Parameters

    • Optional params: {
          leftAttribute?: string;
          topAttribute?: string;
      }

      Parameters

      • Optional leftAttribute?: string

        Name of the attribute to use for the left position. Default is 'left'

      • Optional topAttribute?: string

        Name of the attribute to use for the top position. Default is 'top'

    Returns void

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

    Parameters

    • left: number

      X location

    • top: number

      Y location

    Returns PointXY

    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.

    Parameters

    Returns void

  • Expand/collapse the given group, depending on the current state.

    Parameters

    • group: string | Group

      Group ID, or Group, to expand/collapse.

    Returns void

  • Unbind the given event listener, or all listeners. If you call this method with no arguments then all event listeners are unbound.

    Parameters

    • Optional eventOrListener: string | Function

      Either an event name, or an event handler function

    • Optional listener: Function

      If eventOrListener is defined, this is the event handler to unbind.

    Returns EventGenerator

  • Unbinds a listener for a model event.

    Type Parameters

    • T = any

    Parameters

    Returns void

  • Removes an element that was previously fixed via the fixElement method.

    Parameters

    • el: BrowserElement

    Returns void

  • Zooms the display so that the background (if one is set) fits inside the viewport.

    Parameters

    • params: {
          doNotAnimate?: boolean;
          onComplete?: ((p) => any);
      }
      • Optional doNotAnimate?: boolean

        If true, centering content will not use animation.

      • Optional onComplete?: ((p) => any)

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

          • (p): any
          • Parameters

            Returns any

    Returns void

  • Zooms the display to fit the canvas and content plus any elements added by the given decorator.

    Parameters

    • zParams: {
          decorator: string | Decorator;
          doNotAnimate?: boolean;
          doNotFirePanEvent?: boolean;
          doNotZoomIfVisible?: boolean;
          fill?: number;
          onComplete?: ((p) => any);
          onStep?: (() => any);
      }
      • decorator: string | Decorator
      • Optional doNotAnimate?: boolean
      • Optional doNotFirePanEvent?: boolean
      • Optional doNotZoomIfVisible?: boolean
      • Optional fill?: number
      • Optional onComplete?: ((p) => any)
          • (p): any
          • Parameters

            Returns any

      • Optional onStep?: (() => any)
          • (): any
          • Returns any

    Returns void

  • Zooms the viewport so that all of the given elements are visible.

    Parameters

    • zParams: {
          doNotAnimate?: boolean;
          doNotFirePanEvent?: boolean;
          doNotZoomIfVisible?: boolean;
          elements: BrowserElement[];
          fill?: number;
          onComplete?: ((p) => any);
          onStep?: (() => any);
      }
      • Optional doNotAnimate?: boolean
      • Optional doNotFirePanEvent?: boolean
      • Optional doNotZoomIfVisible?: boolean
      • elements: BrowserElement[]
      • Optional fill?: number
      • Optional onComplete?: ((p) => any)
          • (p): any
          • Parameters

            Returns any

      • Optional onStep?: (() => any)
          • (): any
          • Returns any

    Returns void

  • Zooms the display to fit the given extents. You can provide one or more sets of extents to this method, and their combined area will be calculated.

    Parameters

    • zParams: {
          doNotAnimate?: boolean;
          doNotFirePanEvent?: boolean;
          doNotZoomIfVisible?: boolean;
          extents: BoundingBox | BoundingBox[];
          fill?: number;
          onComplete?: ((p) => any);
          onStep?: (() => any);
      }
      • Optional doNotAnimate?: boolean
      • Optional doNotFirePanEvent?: boolean
      • Optional doNotZoomIfVisible?: boolean
      • extents: BoundingBox | BoundingBox[]
      • Optional fill?: number
      • Optional onComplete?: ((p) => any)
          • (p): any
          • Parameters

            Returns any

      • Optional onStep?: (() => any)
          • (): any
          • Returns any

    Returns void

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

    Parameters

    • Optional params: {
          doNotAnimate?: boolean;
          doNotZoomIfVisible?: boolean;
          fill?: number;
          onComplete?: ((p) => any);
          onStep?: (() => any);
          padding?: number;
      }
      • Optional doNotAnimate?: boolean

        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.

      • Optional doNotZoomIfVisible?: boolean

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

      • Optional fill?: number

        Amount 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 onComplete?: ((p) => any)

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

          • (p): any
          • Parameters

            Returns any

      • Optional onStep?: (() => any)

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

          • (): any
          • Returns any

      • Optional padding?: number

        Optional padding to leave around all elements. Defaults to 0.

    Returns void

  • 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

    • Optional params: {
          doNotAnimate?: boolean;
          fill?: number;
          onComplete?: ((p) => any);
          onStep?: (() => any);
          padding?: number;
      }
      • Optional doNotAnimate?: boolean

        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.

      • Optional fill?: number

        Amount 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 onComplete?: ((p) => any)

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

          • (p): any
          • Parameters

            Returns any

      • Optional onStep?: (() => any)

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

          • (): any
          • Returns any

      • Optional padding?: number

        Optional padding to leave around all elements. Defaults to 0.

    Returns void

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

    Parameters

    • params: {
          doNotAnimate?: boolean;
          doNotZoomIfVisible?: boolean;
          fill?: number;
          filter?: ((o) => boolean | ObjectData);
          selection?: Selection<Edge | Node | Group>;
      }

      Optional method params

      • Optional doNotAnimate?: boolean

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

      • Optional doNotZoomIfVisible?: boolean

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

      • Optional fill?: number

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

          • (o): boolean | ObjectData
          • Parameters

            • o: Base

            Returns boolean | ObjectData

      • Optional selection?: Selection<Edge | Node | Group>

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

    Returns void