Selection

Selection is a mechanism that provides the ability for the user to operate commands or tools on a subset of the Parts in a Diagram. GoJS provides built-in appearances and behaviors for selection. Although this page describes how those built-in appearances and behaviors can be customized, if you want a more general highlighting capability with no built-in appearances or behaviors, please read the page on Highlighting.

Users normally select Parts manually by clicking on them and they deselect them by clicking in the background. This behavior is implemented by the ClickSelectingTool. Users can also deselect all Parts by pressing the Esc key.

Users can also drag in the background in order to select the Parts that are within a rectangular area, via the DragSelectingTool. Read more about that in the learn page on Tools at DragSelectingTool.

You can select parts programmatically by setting Part.isSelected or calling one of several Diagram methods such as Diagram.select, Diagram.selectCollection, and Diagram.clearSelection.

The Diagram keeps a collection of selected parts, Diagram.selection. That collection is read-only -- the only way to add or remove a Part in the Diagram.selection collection is by setting its Part.isSelected property. You can limit how many parts the user may select by setting Diagram.maxSelectionCount. Prevent all selection by the user by setting Diagram.allowSelect to false. Or prevent a particular Part from being selected by setting or binding its Part.selectable property to false.

You can show that a part is selected by either or both of two general techniques: adding Adornments or changing the appearance of some of the elements in the visual tree of the selected Part.

Selection Adornments

It is common to show that a Part is selected by displaying a selection Adornment -- for nodes, normally a blue rectangle. If you do not want such an adornment, you can set Part.selectionAdorned to false. By default the adornment surrounds the whole Node. What if you want attention to be drawn only to the main piece of a node? You can accomplish that by naming that object and setting Part.selectionObjectName to that name.

The diagram below shows both behaviors at once. Both nodes use the same template except for one property: the left node doesn't set Part.selectionObjectName; the right node sets it to "ICON", so the adornment goes around only the named "ICON" Shape and ignores the text.

Note how the Part.selectionObjectName property is similar to the Part.locationObjectName in helping to treat a node as if only one piece of it really matters.

Custom selection Adornments

If you do want a selection adornment but want something different than the standard one, you can customize it. Such customization can be done by setting the Part.selectionAdornmentTemplate. It's a template because it gets copied for each selected Part. In this example, nodes get thick blue circles surrounding the "ICON" of the selected Node, and links get thick blue lines following the selected link's path.

Note that an Adornment is just a Part. Adornments for nodes must contain a Placeholder in their visual tree. The Placeholder gets positioned where the selected object is.

Adornments for links are assumed to be panels of Panel.type that is Panel.Link. Hence the main element may be a Shape that gets the geometry of the selected Link's path shape, and the other elements of the adornment may be positioned on or near the segments of the link route just as for a regular Link.

More complex Adornments

The custom Adornment for a Node need not be only a simple Shape outlining the selected node. Here is an adornment that adds a button to the adornment which inserts a node and a link to that new node.

Select any node and click the "ADD" button. Note how the diagram is automatically laid out as a tree.

Data binding

Like all Parts, Adornments support data binding. If the adorned Part has a data binding (i.e. if Part.data is non-null), all adornments for that part will also be bound to the same data object.

Notice how each Adornment has the same color as the selected node's data.color.

Selection appearance changes

Adding a selection adornment is not the only way to indicate visually that a Part is selected. You can also modify the appearance of one or more objects in your Part.

One way to do this is with data binding. Here we data bind the Shape.fill, Shape.stroke, and TextBlock.fill to the Part.isSelected property with a conversion function that converts the boolean value to a color string or brush. We also turn off the regular rectangular blue selection adornment.

Here the "Paris" node is selected initially. Now when you select a node its background color changes to cyan.

More generally you can execute code to modify the Part when Part.isSelected has changed value. In this example we will have the same side effects as the previous example.

This basically has the same effect as the GraphObject.bindObject binding of the previous example, but the possible changes you could make to that node are much greater and probably simpler than trying to use Bindings.

There are some restrictions on what you can do in such an event handler: you should not select or deselect any parts, and you should not add or remove any parts from the diagram.