GoJS® DragSelectingTool Class

Class DragSelectingTool

Extends Tool. The DragSelectingTool lets the user select multiple parts within a rectangular area drawn by the user. There is a temporary part, the box, that shows the current area encompassed between the mouse-down point and the current mouse point. The default drag selection box is a magenta rectangle. You can change the box to customize its appearance -- see its documentation for an example.

This tool is a standard mouse-move tool, the ToolManager.dragSelectingTool. However this cannot start running unless there has been a motionless delay after the mouse-down event of at least delay milliseconds.

This tool does not utilize any Adornments or tool handles, but it does temporarily add the box part to the diagram. This tool does not modify the model or conduct any transaction.

Selection occurs on a mouse-up when it calls selectInRect with the value of computeBoxBounds. Selectable parts are selected when their bounds fall entirely within the rectangle, unless isPartialInclusion is set to true.

For customizing the DragSelectingTool, see Introduction to the DragSelectingTool.

If you implement your own drag-in-the-background-to-do-something tool, you may need to disable this tool or insert your new tool in the ToolManager.mouseMoveTools list before this tool, in order for your tool to run. There are examples of such tools defined in the extensions directory: Realtime Drag Selecting Tool, Drag Creating Tool, and Drag Zooming Tool.

Constructor Summary Details

Name	Description
DragSelectingTool()	You do not normally need to create an instance of this tool because one already exists as the ToolManager.dragSelectingTool, which you can modify.More... The Tool.name of this tool is "DragSelecting".

Properties Summary Details

Name, Value Type	Description
box {Part}	Gets or sets the Part used as the "rubber-band selection box" that is stretched to follow the mouse, as feedback for what area will be passed to selectInRect upon a mouse-up.More... Initially this is a Part containing only a simple magenta rectangular Shape. The object to be resized during dragging should be named "SHAPE". Setting this property does not raise any events. Here is an example of changing the selection box to be a thicker bright green rectangle: myDiagram.toolManager.dragSelectingTool.box = $(go.Part, { layerName: "Tool", selectable: false }, $(go.Shape, { name: "SHAPE", fill: null, stroke: "chartreuse", strokeWidth: 3 })); Note that the Part should be put into a Layer that Layer.isTemporary. Modifying this property while this tool Tool.isActive might have no effect.
delay {number}	Gets or sets the time in milliseconds for which the mouse must be stationary before this tool can be started.More... The default value is 175 milliseconds. Setting this property does not raise any events.
isPartialInclusion {boolean}	Gets or sets whether a selectable Part may be only partly or must be completely enclosed by the rectangle given to selectInRect.More... The default value is false: parts must be completely inside the rectangle. Setting this property does not raise any events.

Properties borrowed from class Tool:: diagram, isActive, isEnabled, name, transactionResult

Method Summary Details

Name, Return Type	Description
canStart() {boolean}	This tool can run when the diagram allows selection, there has been delay of at least delay milliseconds after the mouse-down before a mouse-move, there has been a mouse-drag far enough away not to be a click, and there is no selectable part at the mouse-down point.More... The delay required to start this tool enables both this tool and the ToolManager.panningTool to co-exist as mode-less mouse-move tools. This method may be overridden. Returns: {boolean}
computeBoxBounds() {Rect}	This just returns a Rect stretching from the mouse-down point to the current mouse point.More... This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method. Returns: {Rect} a Rect in document coordinates.
doActivate()	Capture the mouse and show the box.
doDeactivate()	Release the mouse and remove any box.
doMouseMove()	Update the box's position and size according to the value of computeBoxBounds.
doMouseUp()	Call selectInRect with the value of a call to computeBoxBounds.
selectInRect(r)	This method is called to select some parts within the area of a given rectangle.More... The normal behavior is to set the diagram's selection collection to only those parts in the given rectangle according to the isPartialInclusion policy. However, if the Shift key modifier is used, no parts are deselected -- this adds to the selection the parts in the rectangle not already selected. If the Control key (Command on Mac) modifier is used, this toggles the selectedness of the parts in the rectangle. If the Control key (Command on Mac) and Shift key modifiers are both used, this deselects the parts in the rectangle. This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method. Parameters: {Rect} r a rectangular bounds in document coordinates.