By default, this class sets a plain GraphViewerInputMode as the inputMode to enable basic exploratory interaction with the graph. To enable interactive editing, use a GraphEditorInputMode, instead.
If the graph and selection properties are not populated externally they will be initialized with default values upon first access. Thus, this instance can be used right away without any further initialization. This constructor creates a new htmlElement that needs to be manually added to the DOM.
Creates a new instance of the GraphComponent in the provided htmlElement.
If the graph and selection properties are not populated externally, they will be initialized with default values upon first access. Thus, this instance can be used right away without any further initialization.
All child nodes of the htmlElement are added to the overlayPanel.
if the htmlElement is already used by another component.
GraphComponent
(selector: string)
Creates a new instance of GraphComponent using the HTMLElement that is specified by the selector.
If the graph and selection properties are not populated externally they will be initialized with default values upon first access. Thus this instance can be used right away without any further initialization.
All child nodes of the HTMLElement are added to the overlayPanel.
Parameters
selector: string
The CSS selector or id for an existing HTMLElement. All child nodes of this element are added to the overlayPanel.
Gets or sets the world coordinate at the center of the control.
Setting this property moves the viewport, similarly to viewPoint. It will not change the zoom level.
conversionfinal
Examples
Setting a new center point for the viewport
console.log( `Current center: ${graphComponent.center} , and view point: ${graphComponent.viewPoint}`,)graphComponent.center = new Point(150, 50)console.log(`New center is: ${graphComponent.center}`)console.log( `The view point has also changed: ${graphComponent.viewPoint}`,)
Gets or sets an event recognizer that determines whether zooming with the mouse wheel should zoom to the center of the view instead of the mouse location.
The default is ALT_IS_DOWN, since by default shift will trigger horizontal panning and ctrl will trigger vertical panning.
final
Examples
Changing the recognizer to use Shift to zoom to the viewport center
Gets and sets the rectangle in world coordinates that holds the contents.
This influences the display of the scroll bars. If the content bounds are not currently visible in the viewport, scroll bars will be displayed, unless they are turned off completely. Note that in general, the content bounds are not updated automatically but declared as a fixed rectangle. Rather, the application programmer needs to set this value or call the respective automatic update methods.
Gets and sets the margins in view coordinates that should be used by the fitContent operation or zoom commands which zoom to a given rectangle.
This influences the amount of visible whitespace in the view coordinate system around the contentBounds after a fitContent operation. The default value is (10,10,10,10).
For the ZOOM_TO_CURRENT_ITEM on a GraphComponent, the margins define the visible whitespace around the rectangle in which the respective item is centered. This way it is also possible to get asymmetric whitespace around the item. The same applies to the ZOOM command with a Rect, IBoundsProvider, or an ILookup returning an IBoundsProvider as parameter.
Note limits that are enforced by the viewportLimiter have a higher priority than these margins.
The focused item is shown with a faint dotted border by default.
This is a concept related to selection. The main difference is that there can be at most one focused item, while multiple items can be selected at once.
final
Property Value
The current item by default is given focus indication using the focusIndicatorManager.
Sample Graphs
ShownSetting: Visual difference between a focused and a selected node
See Also
Developer's Guide
devicePixelRatio
: number
Gets or sets the scaling factor for WebGL and Canvas rendering.
Set this value to window.devicePixelRatio for crisp rendering on high DPI devices.
This value indicates the amount of time that may pass within which two subsequent pointer clicks are considered multi-clicks. The higher the value the easier it will be to double-click. The default value is 500 milliseconds.
Gets or sets the graph that is displayed in this control.
Some IInputModes (notably GraphViewerInputMode and GraphEditorInputMode) may retain references to items in the old graph until certain interactions, so it sometimes can be a good idea to re-create and replace the input mode when changing to graph so the old graph reference is eligible for garbage collection.
When changing the graph to one that uses the same IModelItem instances as the old one (e.g. when using FilteredGraphWrapper), the current selection is retained.
The following example shows how to highlight items:
// Add a highlightgraphComponent.highlightIndicatorManager.items?.add(node)// Determine whether an item is highlightedgraphComponent.highlightIndicatorManager.items?.includes(node)// Remove it againgraphComponent.highlightIndicatorManager.items?.remove(node)// Clear all highlightsgraphComponent.highlightIndicatorManager.items?.clear()
Gets or sets the collection model that stores the highlight state for the visualization.
The default implementation allows for highlighting elements that are not part of the graph and will thus not automatically clear the highlight of an element that gets removed from the graph.
A concept related to highlighting is selection and the currentItem, which represent the currently focused item. This is also shown in a selection- or highlight-like fashion.
final
Examples
The highlighted elements can be either queried for or manipulated to highlight items programmatically. The following example shows a few things that can be done:
// Add a highlightgraphComponent.highlights.add(node)// Determine whether an item is highlightedconst highlighted = graphComponent.highlights.includes(node)// Remove the highlightinggraphComponent.highlights.remove(node)// check whether there are any highlightsconst anyHighlights = graphComponent.highlights.size > 0// Iterate all highlighted itemsgraphComponent.highlights.forEach((highlightedItem) => { // ...})// Clear all highlightsgraphComponent.highlights.clear()// listen to low-level changes in the selectiongraphComponent.highlights.addEventListener('item-added', (args) => { console.log(`Highlighted ${args.item}`)})graphComponent.highlights.addEventListener('item-removed', (args) => { console.log(`Removed highlight from ${args.item}`)})
Gets or sets the radius of the area around the pointer in view coordinates in which an IHitTestable may lie to be considered a valid hit.
This value converted into world coordinates can be queried from within the IHitTestable implementation from the hitTestRadius property, which automatically takes the zoom level into account. Note that the context's property automatically switches between the value for mouse, touch, and stylus, based on the last input event.
The default value is 3 for MOUSE, 6 for PEN, and 12 for TOUCH.
Gets or sets the visibility policy for the horizontal scrollbar.
Scrollbars don't need to be displayed in order to move the viewport. This can be achieved programmatically or using special IInputMode instances. The default is AUTO.
Gets or sets a value indicating whether the maximum zoom level for fitContent and FIT_CONTENT is limited to 1.
If this property is true, fitContent and FIT_CONTENT will limit the maximum zoom level to 1. This can lead to very small graphs not filling the viewport. If this property is set to false, zooming will only be limited by maximumZoom.
Gets or sets the duration a pointing device must be held down without moving before the pointer-long-press event is raised.
Small pointer moves are ignored, so jittery pointer types like PEN or TOUCH will not block the event.
The default value is 250 milliseconds.
If you are listening for the context-menu event, we recommend lowering this value to, for exammple, 100ms because handling the context-menu event will stop other input modes from acting on the subsequent long-press event (e.g., edge creation). Therefore, lowering the longPressTime will extend the time frame between the long-press and the context-menu event.
Gets or sets the minimum zoom factor for this CanvasComponent.
This property sets a lower bound for the allowed values of the zoom property. If this property is written, the canvas will zoom to the new value while keeping the center of view at the same world coordinates. The default value is 0.0001, the enforced minimum 0.0000001.
final
Examples
Ensuring that the zoom level cannot go below 100 %
Gets or sets a value that specifies whether this control receives mouse input after the mouse is dragged out of its bounding area.
If enabled, this control receives mouse events when the mouse is moved out of its bounding area while a mouse button is pressed, until the button is release (the mouse up event is the last event this control listens to).
Gets or sets the action to perform when turning the mouse wheel.
Valid values for this property are as follows:
NONE – No action is being taken when turning the mouse wheel.
ZOOM – The zoom level of the viewport is adjusted when turning the mouse wheel or pinching on a touchpad.
SCROLL – The viewport is scrolled vertically when turning the mouse wheel, and horizontally when turning the mouse wheel while pressing the Shift key. No modifier key is required if bidirectional wheel events are available (e.g. touchpad or two-axis mouse wheel).
SCROLL, ZOOM – Both SCROLL and ZOOM can be combined to allow both scrolling and zooming. The default action without any modifiers pressed is zooming. Pressing the Shift key while turning the mouse wheel will scroll horizontally while pressing the Control key will result in vertically scrolling. This is the default.
Any of the above options, except for NONE can be combined with ONLY_WHEN_FOCUSED to allow the interaction only when the CanvasComponent is focused.
// The mouse wheel should be used for scrolling.graphComponent.mouseWheelBehavior = MouseWheelBehaviors.SCROLL// The mouse wheel can be used either for scrolling or zooming, depending on the modifiers// but only when the control is focused.graphComponent.mouseWheelBehavior = MouseWheelBehaviors.SCROLL | MouseWheelBehaviors.ZOOM | MouseWheelBehaviors.ONLY_WHEN_FOCUSED
Gets or sets a factor that controls how fast the viewport scrolls when the mouse wheel is turned.
Scrolling can work either a few lines at a time (per notch of the scroll wheel) or one page at a time. This is a system setting. This property controls how many pixels represent a line if scrolling is done by line. In case scrolling is done by page, this property has no effect.
The default value is 25 pixels. To speed up scrolling, set a larger value, to slow down scrolling, set a smaller value. Set negative values to invert the scrolling/panning behavior, e.g., for trackpads.
The default implementation detects whether ctrl or shift have been pressed separately or a precision trackpad is used for panning. In these cases, false will be returned, enabling zooming with the mouse both via scroll wheels and pinch zooming via trackpads.
Returns an HTML element that can be used to show arbitrary HTML content like overlays, fly-outs, or pop-ups on top of this CanvasComponent.
An HTML element that was added to the overlay panel is drawn above the content of this CanvasComponent but below its scrollbars. In contrast to labels or other model items, this element keeps its size when the canvas is zoomed. It should be placed with the CSS property position: absolute to prevent multiple overlay elements to interfere with each other.
If a container element is passed to the constructor of this CanvasComponent, all its child nodes are passed to this overlay panel. Apart from that, content may be added to and removed from this panel at any time.
Gets or sets a value indicating whether input coordinates (mouse and touch) should be quantized depending on the zoom level to give nicer values.
By default, the coordinates of input events are translated directly to world coordinates, which, with many zoom levels can end up with world coordinates like 326.76821937283548; this excessive precision is an artifact of the fact that every viewport pixel covers a fractional amount of world coordinates.
This option quantizes the coordinates depending on the zoom level so that above value may end up, e.g. as 326.75 instead. This is done in a way to minimize visual deviation from the exact value (much less than a pixel), so visually almost nothing changes. Zooming in will increase the precision as much as necessary, but not so far to be excessive. The benefit is that coordinates are easier to recognize in a debugger, graph elements end up with locations that are easier to read, GraphML files become smaller because less space is wasted on unnecessary floating point precision, and numerical instability in certain cases (e.g. some snapping scenarios) is eliminated.
Gets a value indicating whether the UI is right to left.
The value is fetched and cached on first access and the cache gets invalidated when the size of the component has changed. This is to avoid costly queries into the CSS engine.
readonlyfinal
Property Value
true if the main UI direction is right to left; otherwise, false.
Gets or sets the selection model that stores the selection state for the visualization.
The selection model instance needs to be adjusted, typically when the graph instance is changed.
A concept related to selection is the currentItem, which represents the currently focused item. This is also shown in a selection-like fashion.
final
Examples
The selection can be either queried for selected items or manipulated to select or deselect items programmatically. The following example shows a few things that can be done:
// Determine whether an item is selectedlet selected = graphComponent.selection.includes(node)// alternatively, if you know the type:selected = graphComponent.selection.nodes.includes(node)// Deselect an edgegraphComponent.selection.remove(edge)// check whether the selection is emptyconst isEmpty = graphComponent.selection.size === 0// Iterate over selected nodesfor (const n of graphComponent.selection.nodes) { // ...}// Iterate all selected itemsgraphComponent.selection.forEach((selection) => { // ...})// Unselect all edgesgraphComponent.selection.edges.clear()// clear the whole selectiongraphComponent.selection.clear()// select all nodesgraphComponent.graph.nodes.forEach((n) => { graphComponent.selection.nodes.add(n)})// listen to low-level changes in the selectiongraphComponent.selection.addEventListener('item-added', (args) => { console.log(`Selected ${args.item}`)})graphComponent.selection.addEventListener('item-removed', (args) => { console.log(`Deselected ${args.item}`)})
Sample Graphs
ShownSetting: Visual difference between a focused and a selected node
Gets or sets the visibility policy for the vertical scrollbar.
Scrollbars don't need to be displayed in order to move the viewport. This can be achieved programmatically or using special IInputMode instances. The default is AUTO.
The viewpoint is the point in world coordinates that is mapped to the top left corner point in the current viewport. Setting this point to another value will redispatch the last pointer event as the mouse will appear to have been moved or dragged in the world coordinate system.
conversionfinal
Examples
Setting a new value for the ViewPoint property
console.log( `Current view point: ${graphComponent.viewPoint} , and center: ${graphComponent.center}`,)graphComponent.viewPoint = new Point(150, 50)console.log(`New view point is: ${graphComponent.viewPoint}`)console.log(`The center has also changed: ${graphComponent.center}`)
Gets or sets the policy for caching Visuals which are temporarily removed from the visual tree.
Visuals are temporarily removed when they are moved outside the visual part of the canvas (the viewport ) and re-added when they enter the viewport again. Caching prevents the need to re-build the visuals from scratch.
Visuals are only cached if this property is set to other value than NEVER and if a dispose visual callback is registered during creation.
If the visual is using the ISvgDefsCreator, the visual additionally needs to check in updateVisual whether the defs element is still in the DOM. The ISvgDefsCreator may have removed the defs element in the meantime if it was unused.
A zoom level of 1.0 will make each unit in world-coordinate space appear exactly one unit in screen coordinates wide. The default is 1.0. When setting this property to change the zoom level, the center point will remain the same.
This method is not available unless the module view-layout-bridge is loaded. Either load the module 'view-layout-bridge' explicitly or ensure that the LayoutExecutor type is available at runtime.
Cleans up by removing any connection from the htmlElement element to the GraphComponent instance and any associated element that was created during the lifetime of the component.
The graph instance is not affected by this and will keep its references and listeners. To remove them, set the graph to a new empty default graph. Otherwise, re-using the graph in another component may cause unexpected behavior.
In addition, the entire visual tree is cleared and an immediate final visual tree update is performed. As a result, pending dispose callbacks for registered visuals are executed and associated resources can be released.
This method is a convenience method to obtain a context for special visual creator implementations and normally needs not be used by application developers.
Ensures that the provided points in world coordinates are all visible by adjusting the viewport accordingly.
This is particularly useful when using a projection because rectangles in the viewport may not be rectangles in world coordinates, sometimes requiring excessive padding.
Adjusts the viewport to fully encompass the contentBounds.
This is usually used to make sure a large graph fits into the viewport. The limitFitContentZoom property controls the behavior for small graphs. If limitFitContentZoom is true, the maximum zoom level is 1; setting the property to false will zoom in far enough so that even small graphs fit the viewport (limited to maximumZoom, though).
Determines the animation duration for a viewport animation.
Returning ZERO will disable the animation completely. For viewport changes that have been disabled via animatedViewportChanges the duration is never queried.
When overriding this method, it is recommended to always call the base implementation first, and, if ZERO is returned, to return that value immediately as well. The reason behind that is that high-precision scroll devices, like Apple's Trackpad, Microsoft's Precision Touchpad, or mice with free-turning scroll wheels, are automatically detected and the animation is turned off to improve interaction smoothness.
The kind of viewport change that triggered this method. Even though ViewportChanges supports multiple values as bitwise flags, only one of them is ever passed here.
A TimeSpan indicating the desired animation duration.
Examples
The following example shows a few different ways how this method can be used to customize the animation duration (or whether to animate at all):Customizing the viewport animation duration for different scenarios
protected getViewportAnimationDuration( newCenter: Point, newZoom: number, viewportChanges: ViewportChanges,): TimeSpan { if ( viewportChanges == ViewportChanges.MOUSE_WHEEL_SCROLL && this.center.distanceTo(newCenter) > 200 ) { // Use a duration between 100 and 500 ms depending on the distance scrolled return TimeSpan.fromMilliseconds( Math.max(Math.min(this.center.distanceTo(newCenter), 500), 100), ) } if ( (viewportChanges == ViewportChanges.ZOOM_COMMAND || viewportChanges == ViewportChanges.MOUSE_WHEEL_ZOOM) && newZoom > this.zoom ) { // Use a shorter duration when zooming in return TimeSpan.fromMilliseconds(100) } if (viewportChanges == ViewportChanges.FIT_CONTENT_COMMAND) { // Never animate FIT_CONTENT or FIT_GRAPH_BOUNDS return TimeSpan.ZERO } return super.getViewportAnimationDuration( newCenter, newZoom, viewportChanges, )}
Returns an instance that implements the given type or null.
Typically, this method will be called to obtain a different view or aspect of the current instance. This is quite similar to casting or using a super type or interface of this instance, but is not limited to inheritance or compile-time constraints. An instance implementing this method is not required to return non-null implementations for the types, nor does it have to return the same instance any time. Also, it depends on the type and context whether the instance returned stays up to date or needs to be re-obtained for further use.
Parameters
type: Constructor<T>
the type for which an instance shall be returned
Return Value
T
an instance that is assignable to the type or null
This method is queried for each mouse, touch or pointer event that occurs on this instance. By overriding this method, the browser's default behavior can effectively be controlled for every single event.
This method will be called when the mouse wheel was turned and if the mouseWheelBehavior property is set to ZOOM.
This method will adjust the current zoom level. If the Control key modifier has not been pressed, this method will keep the world coordinates at the current mouse position, i.e. the zoom will not necessarily be into the center of the canvas.
Stops the mouse capture and returns to normal event capturing.
When mouseCapture is set to true and a mouse down event is received, the control starts capturing all mouse events by registering handlers on the document element. Mouse capturing is normally stopped when the mouse button is released. Mouse capture can be manually stopped by calling this function.
Updates the contentBounds to encompass the bounds of all elements in the current scene graph plus the given margins.
This method will traverse all visible elements in the subgraph below the given group of scene graph and query their bounds. The resulting bounds will be set to the content bounds plus the provided margins.
Updates the visual tree that displays the contents of this control.
Calling this method will synchronously update the visual tree and the SVG DOM and Canvas rendering.
This method will create or update the visuals that make up the visual tree.
Note that most of the time this method does not need to be called by client code. Instead calling invalidate will ultimately trigger this method. However invalidation calls will be coalesced and the actual execution of the update will be delayed until the next event dispatch.
This event is raised when conditions which might determine the executability of a Command might have changed. This can apply to all Commands, so implementors have to re-query canExecuteCommand for each command where a change might be relevant.
This event delivers PointerEventArgs in world coordinates using double precision floating points.
If the mouse enters this canvas control with a mouse button pressed, this event is fired instantly but the current button state reported by the PointerEventArgs does not include this button unless the browser supports the property MouseEvent.buttons. See the Known Issues for more details.
This event delivers PointerEventArgs in world coordinates using double precision floating points.
If the mouse leaves this canvas control with the mouse button pressed, this event is deferred until the mouse button is released. Thus, this event will not interfere with the typical mouse button event cycle.
Occurs when the mouse has been moved in world coordinates.
This event delivers PointerEventArgs in world coordinates using double precision floating points.
Move elements are delivered if no mouse button is pressed. This event will be fired, too, if the mouse does not move but the world coordinates to which the current mouse position maps change. E.g. this will happen if the zoom level or the view point is changed.
Occurs if the selection instance has been changed, not when the selected items change.
This event fires rarely. The selection property is only the selection model, thus this event is raised when the selection model instance itself changes. To listen to changes in the GraphComponent's selection, please refer to the appropriate events on IGraphSelection.