Selection

General

The selected items are managed by the IGraphSelection instance found in the GraphComponent's selection property. The IGraphSelection provides IObservableCollection<T> instances for nodes, labels, edges, ports, and bends and acts as a composite of those instances.

To select an item, add it to the IGraphSelection instance or the corresponding property matching the item’s type. Removing an item from those IObservableCollection<T>s deselects it.

An item is selected if it is contained in the IObservableCollection<T>s.

Interactive selection of graph items is supported by both GraphEditorInputMode and GraphViewerInputMode. Both provide access to the selection they manage through the property graphSelection. This is the same instance found in the selection property of the GraphComponent managed by these input modes.

Both modes provide convenience methods to directly select or deselect a single item, as well as all marquee-selectable items in a given area: setSelected(IModelItem, boolean) and marqueeSelect(Rect, SelectionPolicy).

GraphEditorInputMode and GraphViewerInputMode support four ways to select elements interactively: selection by click, marquee selection, lasso selection, and the select all command. The items that can be selected by these methods can be defined using the properties ending with SelectableItems. These properties define the item types that can be selected using a combination of the values defined in GraphItemTypes.

You can achieve finer control by changing the properties ending with SelectablePredicate:

Note that an item is only selected if all conditions are met. For example, an item is only considered for click selection if its type is set in both selectableItems and clickSelectableItems. Additionally, click selection is only handled for items which are clickable, see section Pointer Handling.

IGraphSelection dispatches events for each item whose selection state changes, specifically the item-added and item-removed events. On a higher level, both GraphEditorInputMode and GraphViewerInputMode dispatch events at the beginning and the end of a user interaction that changes the selection state of one or more graph items: multi-selection-started and multi-selection-finished. Despite their names, these events are also dispatched when the state of only one item changes.

You can further customize click selection by modifying the click handling as discussed in section Pointer Handling.

Marquee selection

For marquee selection, GraphEditorInputMode and GraphViewerInputMode let their child input mode MarqueeSelectionInputMode handle the marquee rectangle. MarqueeSelectionInputMode allows for customization by changing the recognizers for some gestures. This can be important to avoid conflicts with input modes that share the same gesture (i.e., dragging on an empty canvas), e.g., MoveViewportInputMode.

The following recognizers are used:

During the drag gesture, different modifier keys can be used to change the current selectionPolicy. The following table lists the event recognizer properties used to detect the current policy, the default modifier key for those recognizers, and the chosen selectionPolicy:

When the selectionPolicy changes, the corresponding extendSelectionCursor, subtractSelectionCursor, or toggleSelectionCursor is used if it isn’t null (which is the default). The marqueeCursor is used as a fallback.

Furthermore, MarqueeSelectionInputMode dispatches a sequence of events during the marquee gesture:

The visualization of the marquee rectangle can be customized by setting a custom

IObjectRenderer<TRenderTag> to MarqueeSelectionInputMode’s marqueeRenderer property. If only the fill or stroke of the marquee rectangle should be adjusted, it is recommended to use CSS styling instead as explained in Styling of Marquee Rectangle:

.yfiles-marquee-rect-template {
  fill: #ff0000b0;
  stroke: red;
  stroke-dasharray: 1.5, 1.5;
}

Above example results in the following marquee selection rectangle:

Custom marquee selection rectangle

Lasso selection

Lasso selection in GraphEditorInputMode and GraphViewerInputMode is performed by their child input mode LassoSelectionInputMode, which handles drawing a path within which to select items. This child input mode is disabled by default to avoid conflicting with marquee selection. LassoSelectionInputMode allows customization by changing the recognizers for some gestures. This is important to avoid conflicts with input modes which share the same gesture (i.e., dragging on an empty canvas), e.g., MoveViewportInputMode.

By default, LassoSelectionInputMode is configured to draw the path around the selection area in a freehand gesture while dragging the pointer. The gesture finishes after releasing the pointer, and the path is closed with a straight line from the current location to its start.

By changing one or more of its various event recognizers, LassoSelectionInputMode can be configured to support a polyline path or a mixture of freehand and straight segments. It is also possible to configure the input mode to finish only when the gesture ends in an area around the start point of the path.

When the pointer is inside the finishRadius, the validEndCursor is used.

The following settings configure LassoSelectionInputMode to support a polyline lasso, i.e., a path consisting of straight segments:

const lassoSelectionInputMode =
  graphEditorInputMode.lassoSelectionInputMode
lassoSelectionInputMode.dragFreeHandRecognizer =
  EventRecognizers.MOUSE_DRAG
// start a segment immediately at the beginning of the gesture or after the last segment is ended
lassoSelectionInputMode.startSegmentRecognizer = EventRecognizers.ALWAYS
// end a segment when the mouse button is pressed or released
lassoSelectionInputMode.endSegmentRecognizer = (
  eventSource: any,
  evt: EventArgs
) =>
  EventRecognizers.MOUSE_LEFT_DOWN(eventSource, evt) ||
  EventRecognizers.MOUSE_LEFT_UP(eventSource, evt)
lassoSelectionInputMode.dragSegmentRecognizer =
  EventRecognizers.MOUSE_DRAG
// outside the finish radius finish only with double click
lassoSelectionInputMode.finishRecognizer =
  EventRecognizers.MOUSE_LEFT_DOUBLE_CLICK
// or finish within the finish radius around the start point
lassoSelectionInputMode.finishRadius = 10

Note that the gesture can now only be ended in one of two ways. The first option is a double click, which automatically closes the path by drawing a straight segment between the current location and the start of the path. The second option is to end a segment within the finishRadius around its start point.

It is also possible to mix the freehand and polyline gestures. The following settings configure LassoSelectionInputMode to draw a freehand path while dragging the mouse with the left button down and straight segments when the button is released. Similar to the freehand configuration, the gesture can now only be finished with a double click or by pressing or releasing the mouse button within the finishRadius around its start point.

const lassoSelectionInputMode =
  graphEditorInputMode.lassoSelectionInputMode
// start a segment when the mouse button is released
lassoSelectionInputMode.startSegmentRecognizer =
  EventRecognizers.MOUSE_LEFT_UP
// outside the finish radius finish only with double click
lassoSelectionInputMode.finishRecognizer =
  EventRecognizers.MOUSE_LEFT_DOUBLE_CLICK
// or finish within the finish radius around the start point
lassoSelectionInputMode.finishRadius = 10

During the drag gesture, LassoSelectionInputMode supports changing the selectionPolicy and dispatches a sequence of events analogous to the MarqueeSelectionInputMode. The details about detecting the policy and the dispatched events are explained in the corresponding sections for Marquee selection.

The visualization of the region uses an outline in --yfiles-theme-secondary and a half-transparent fill using the --yfiles-theme-secondary as explained in Lasso and Marquee.

During the gesture, LassoSelectionInputMode can display an indicator for the region around the start location where the lasso gesture can be finished. The default circular visualization can be configured with the CSS class yfiles-lasso-finish-region. For full control an individual visualization can be set via the finishRegionRenderer property.

You can set the cursor shown during dragging using the lassoCursor property.

Single Item Selection

All interactive selection gestures support selecting multiple items simultaneously. Sometimes, you might want only one or no item to be selected at a time. To enable this "single selection mode," disable MarqueeSelectionInputMode and set the multiSelectionRecognizer to NEVER. Then, remove SELECT_ALL and TOGGLE_ITEM_SELECTION from availableCommands, and EXTEND_SELECTION_LEFT, EXTEND_SELECTION_RIGHT, EXTEND_SELECTION_UP, EXTEND_SELECTION_DOWN, EXTEND_SELECTION_HIERARCHY_UP, and EXTEND_SELECTION_HIERARCHY_DOWN from navigationInputMode.availableCommands. You can find an example in Single Selection.

// disable marquee selection
geim.marqueeSelectionInputMode.enabled = false
// disable multi selection with Ctrl-Click
geim.multiSelectionRecognizer = EventRecognizers.NEVER

// deactivate commands which can lead to multi selection
geim.availableCommands.remove(Command.TOGGLE_ITEM_SELECTION)
geim.availableCommands.remove(Command.SELECT_ALL)

geim.navigationInputMode.availableCommands.remove(
  Command.EXTEND_SELECTION_LEFT
)
geim.navigationInputMode.availableCommands.remove(
  Command.EXTEND_SELECTION_UP
)
geim.navigationInputMode.availableCommands.remove(
  Command.EXTEND_SELECTION_DOWN
)
geim.navigationInputMode.availableCommands.remove(
  Command.EXTEND_SELECTION_RIGHT
)
geim.navigationInputMode.availableCommands.remove(
  Command.EXTEND_SELECTION_HIERARCHY_UP
)
geim.navigationInputMode.availableCommands.remove(
  Command.EXTEND_SELECTION_HIERARCHY_DOWN
)

// Disable selection of (possibly multiple) items
geim.pasteSelectableItems = GraphItemTypes.NONE