DraggingTool class

The DraggingTool is used to move or copy selected parts with the mouse. This sets the Part#location property; you may want to save the location to the model by using a TwoWay Binding on the "location" property in your Parts/Nodes/Groups templates.

Dragging the selection moves parts for which Part#canMove is true. If the user holds down the Control key (Option key on Mac), this tool will make a copy of the parts being dragged, for those parts for which Part#canCopy is true.

When the drag starts it calls #computeEffectiveCollection to find the actual collection of Parts to be dragged. Normally this collection includes not only the Diagram#selection, but also parts that belong to those selected parts, such as members of groups. If #dragsTree is true, the effective collection also includes all of the nodes and links that constitute the subtree starting from selected nodes. The result of #computeEffectiveCollection is not a Set but a Map which remembers the original Part#location for all of the dragged parts. This map is saved as the value of #draggedParts.

During the drag if the user holds down the Control/Option key this tool makes a copy of the #draggedParts and proceeds to drag it around. (It only copies the Diagram#selection, not the whole effective collection, if #copiesEffectiveCollection is false.) The collection of copied parts is held by #copiedParts. It too is a Map remembering the original locations of the parts. #copiedParts will be null when this tool is moving (not copying) at the moment.

Each Part's movement is limited by the Diagram#computeMove method. By default it limits the Part#location to be within the bounds given by Part#minLocation and Part#maxLocation. (Those default to minus Infinity to plus Infinity.) As a further convenience, the value of NaN in minLocation and maxLocation cause Diagram#computeMove to use the part's current location. So, for example, an easy way to declare that the user may only drag a node horizontally is to just set:

$(go.Node,
  . . .
  { minLocation: new go.Point(-Infinity, NaN), maxLocation: new go.Point(Infinity, NaN) },
  . . .
)

If you set #isGridSnapEnabled to true, dragged or copied parts will be snapped to points on a grid. The snapping occurs continuously during a drag unless you set #isGridSnapRealtime to false. Normally the grid points come from the Diagram#grid, even if that grid is not GraphObject#visible. However you can override those grid's properties for the snapping grid cell size and offset by setting the properties here: #gridSnapCellSize and #gridSnapOrigin. This computes the point to snap to for each dragged part. The resulting point is used as the new Part#location.

For the most general control over where a part may be dragged, either set the Part#dragComputation property or override Diagram#computeMove. For the common case of wanting to keep member nodes within the Group that they are members of, you can do something like:

 // this is a Part.dragComputation function for limiting where a Node may be dragged
  function stayInGroup(part, pt, gridpt) {
    // don't constrain top-level nodes
    var grp = part.containingGroup;
    if (grp === null) return pt;
    // try to stay within the background Shape of the Group
    var back = grp.resizeObject;
    if (back === null) return pt;
    // allow dragging a Node out of a Group if the Shift key is down
    if (part.diagram.lastInput.shift) return pt;
    var p1 = back.getDocumentPoint(go.Spot.TopLeft);
    var p2 = back.getDocumentPoint(go.Spot.BottomRight);
    var b = part.actualBounds;
    var loc = part.location;
    // find the padding inside the group's placeholder that is around the member parts
    var m = grp.placeholder.padding;
    // now limit the location appropriately, assuming no grid-snapping
    var x = Math.max(p1.x + m.left, Math.min(pt.x, p2.x - m.right - b.width - 1)) + (loc.x-b.x);
    var y = Math.max(p1.y + m.top, Math.min(pt.y, p2.y - m.bottom - b.height - 1)) + (loc.y-b.y);
    return new go.Point(x, y);
  }

Note that this expects there to be a "SHAPE" object within the Group's visual tree that delimits where the part may be dragged within the group. This also expects that Group#computesBoundsIncludingLinks is false. Then in your node template(s), just set:

$(go.Node,
  . . .,
  { dragComputation: stayInGroup },
  . . .
)

This tool does not utilize any Adornments or tool handles. If the drag is successful, it raises the "SelectionMoved" or "SelectionCopied" DiagramEvent and produces a "Move" or a "Copy" transaction.

If you want to programmatically start a new user's dragging of a particular existing node, you can make sure that node is selected, set the #currentPart property, and then start and activate the tool.

  var node = ...;
  myDiagram.select(node);        // in this case the only selected node
  var tool = myDiagram.toolManager.draggingTool;
  tool.currentPart = node;       // the DraggingTool will not call standardMouseSelect
  myDiagram.currentTool = tool;  // starts the DraggingTool
  tool.doActivate();             // activates the DraggingTool

Implemented types

• Tool

Available extensions

• DraggingTool$Typings
• Tool$Typings

Annotations

• @JS()
• @staticInterop

Constructors

DraggingTool()

factory

Properties

copiedParts ↔ Map<Part, DraggingInfo>?

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets the collection of Parts that this tool has copied. The value is a Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part. The value is null when moving instead of copying.

getter/setter pair

copiesEffectiveCollection ↔ bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets whether for a copying operation the extended selection is copied or only the selected parts. The default value is true. Setting this property does not raise any events.

getter/setter pair

copyCursor ↔ String

Available on DraggingTool, provided by the DraggingTool$Typings extension

The cursor to show when a drop is allowed and will result in a copy. This defaults to 'copy'. Read more about cursors at Diagram#currentCursor

getter/setter pair

currentPart ↔ Part?

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets the Part found at the mouse point. This is normally set by a call to #standardMouseSelect.

getter/setter pair

delay ↔ num

Available on DraggingTool, provided by the DraggingTool$Typings extension

On touch gestures only, this property gets or sets the time in milliseconds for which the mouse must be stationary before this tool can be started. The default value is 100 milliseconds. Setting this property does not raise any events.

getter/setter pair

diagram ↔ Diagram

Available on Tool, provided by the Tool$Typings extension

This read-only property returns the Diagram that owns this tool and for which this tool is handling input events.

getter/setter pair

draggedParts ↔ Map<Part, DraggingInfo>?

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets the collection of Parts being moved. The value is a Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part.

getter/setter pair

draggingParts ↔ Set<Part>

Available on DraggingTool, provided by the DraggingTool$Typings extension

(undocumented) This read-only property returns a Set that holds all of the Parts that are currently being dragged for either copying or moving.

getter/setter pair

dragOptions ↔ DraggingOptions

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets the DraggingTool's DraggingOptions instance, which controls several dragging properties.

getter/setter pair

dragsLink ↔ bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets whether the user can drag a single Link, disconnecting it from its connected nodes and possibly connecting it to valid ports when the link is dropped. The default value is false. Setting this property does not raise any events.

getter/setter pair

dragsTree ↔ bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets whether moving or copying a node also includes all of the node's tree children and their descendants, along with the links to those additional nodes. The default value is false. Setting this property does not raise any events.

getter/setter pair

gridSnapCellSize ↔ Size

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets the size of the grid cell used when snapping during a drag if the value of #isGridSnapEnabled is true. By default this property is the Size(NaN, NaN), which causes this tool to use the Panel#gridCellSize value of the Diagram#grid. Setting this property does not raise any events.

getter/setter pair

gridSnapCellSpot ↔ Spot

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets the Spot that specifies what point in the grid cell dragged parts snap to, if the value of #isGridSnapEnabled is true. By default this property is Spot.TopLeft: node locations will snap exactly to the grid point. Setting this property does not raise any events.

getter/setter pair

gridSnapOrigin ↔ Point

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets the snapping grid's origin point, in document coordinates, if the value of #isGridSnapEnabled is true. By default this property is the Point(NaN, NaN), which causes this tool to use the Panel#gridOrigin value from the Diagram#grid. Setting this property does not raise any events.

getter/setter pair

hashCode → int

The hash code for this object.

no setter, inherited

isActive ↔ bool

Available on Tool, provided by the Tool$Typings extension

Gets or sets whether this tool is started and is actively doing something.

getter/setter pair

isComplexRoutingRealtime ↔ bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets whether link routing takes some short-cuts during dragging. When false Links whose routing is AvoidsNodes are not routed to avoid Nodes, in order to improve dragging performance. The default value is true.

getter/setter pair

isCopyEnabled ↔ bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets whether for any internal copying operation is permitted by control-drag-and-drop. This property affects the behavior of #mayCopy, but does not affect whether copied objects may be dropped into this diagram from a different diagram.

getter/setter pair

isEnabled ↔ bool

Available on Tool, provided by the Tool$Typings extension

Gets or sets whether this tool can be started by a mouse event.

getter/setter pair

isGridSnapEnabled ↔ bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets whether the DraggingTool snaps objects to grid points. Whether the snapping movement of the dragged parts occurs during the drag or only upon a drop is determined by the value of #isGridSnapRealtime.

getter/setter pair

isGridSnapRealtime ↔ bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets whether the DraggingTool snaps objects to grid points during the drag. This property is ignored unless #isGridSnapEnabled is true. By default this property is true; when false parts are only snapped to grid locations upon the drop (i.e. mouse-up). Setting this property does not raise any events.

getter/setter pair

moveCursor ↔ String

Available on DraggingTool, provided by the DraggingTool$Typings extension

The cursor to show when a drop is allowed and will result in a move. This defaults to the empty string, which refers to the Diagram#defaultCursor. Read more about cursors at Diagram#currentCursor

getter/setter pair

name ↔ String

Available on Tool, provided by the Tool$Typings extension

Gets or sets the name of this tool. The default name is an empty string, but the constructor for each instance of a subclass of Tool will initialize it appropriately. For example, the name of the DragSelectingTool is "DragSelecting".

getter/setter pair

nodropCursor ↔ String

Available on DraggingTool, provided by the DraggingTool$Typings extension

The cursor to show when a drop is not allowed. This defaults to 'no-drop'. Read more about cursors at Diagram#currentCursor

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

startPoint ↔ Point

Available on DraggingTool, provided by the DraggingTool$Typings extension

Gets or sets the mouse point from which parts start to move. The value is a Point in document coordinates. This property is normally set to the diagram's mouse-down point in #doActivate, but may be set to a different point if parts are being copied from a different control. Setting this property does not raise any events.

getter/setter pair

transactionResult ↔ String?

Available on Tool, provided by the Tool$Typings extension

Gets or sets the name of the transaction to be committed by #stopTransaction

getter/setter pair

Methods

cancelWaitAfter() → void

Available on Tool, provided by the Tool$Typings extension

This is called to cancel any running "WaitAfter" timer.

canStart() → bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

This tool can run if the diagram allows selection and moves/copies/dragging-out, if the mouse has moved far enough away to be a drag and not a click, and if #findDraggablePart has found a selectable part at the mouse-down point.

canStart() → bool

Available on Tool, provided by the Tool$Typings extension

This predicate is used by the ToolManager to decide if this tool can be started mode-lessly by mouse and touch events. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.

canStartMultiTouch() → bool

Available on Tool, provided by the Tool$Typings extension

Called by ToolManager#doMouseDown and ToolManager#doMouseMove, this method determines whether or not to allow pinch zooming from a multi-touch event. By default this predicate just returns true. This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose @return {boolean} @see #standardPinchZoomStart @see #standardPinchZoomMove @since 1.5

computeEffectiveCollection(Iterable<Part> parts, DraggingOptions options) → Map<Part, DraggingInfo>

Available on DraggingTool, provided by the DraggingTool$Typings extension

This just calls CommandHandler#computeEffectiveCollection. The implementation of this method was moved to CommandHandler for 2.0.

computeMove(Part n, Point newloc, [Map<Part, DraggingInfo>? draggedparts, Point? result]) → Point

Available on DraggingTool, provided by the DraggingTool$Typings extension

This method computes the new location for a Node or simple Part, given a new desired location and an optional Map of dragged parts, taking any grid-snapping into consideration, any Part#dragComputation function, and any Part#minLocation and Part#maxLocation.

doActivate() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Start the dragging operation. This calls #computeEffectiveCollection and saves the result as #draggedParts.

doActivate() → void

Available on Tool, provided by the Tool$Typings extension

The Diagram calls this method after setting Diagram#currentTool, to make the new tool active. This should set #isActive to true. Overrides of this method might call #startTransaction, if this tool's activity involves modification of the model. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.

doCancel() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Abort any dragging operation.

doCancel() → void

Available on Tool, provided by the Tool$Typings extension

The diagram will call this method when the user wishes to cancel the current tool's operation. Typically this is called when the user hits the ESCAPE key. This should restore the original state of what was modified by this tool, and then it should call #stopTool. This method is not responsible for cleaning up any side-effects that should be performed by #doDeactivate and/or #doStop, which will always be called whether the tool stops normally or abnormally.

doDeactivate() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Stop the dragging operation by stopping the transaction and cleaning up any temporary state.

doDeactivate() → void

Available on Tool, provided by the Tool$Typings extension

The Diagram calls this method on the old tool when Diagram#currentTool is set to a new tool. This needs to set #isActive to false. Overrides of this method might call #stopTransaction, if this tool's activity involves modification of the model.

doDragOver(Point pt, [GraphObject? obj]) → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Perform any additional side-effects during a drag, whether an internal move or copy or an external drag, that may affect the existing non-moved object(s).

doDropOnto(Point pt, [GraphObject? obj]) → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Perform any additional side-effects after a drop, whether an internal move or copy or an external drop, that may affect the existing non-moved object(s).

doKeyDown() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Handle switching between copying and moving modes as the Control/Option key is pressed or released.

doKeyDown() → void

Available on Tool, provided by the Tool$Typings extension

The diagram will call this method upon a key down event. By default this just calls #doCancel if the key is the ESCAPE key. Implementations of this method can look at Diagram#lastInput to get the key.

doKeyUp() → void

Available on Tool, provided by the Tool$Typings extension

The diagram will call this method upon a key up event. Implementations of this method can look at Diagram#lastInput to get the key.

doKeyUp() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Handle switching between copying and moving modes as the Control/Option key is pressed or released.

doMouseDown() → void

Available on Tool, provided by the Tool$Typings extension

The diagram will call this method upon a mouse down event. This is normally overridden for mouse-down tools; it is not called for mouse-move or mouse-up tools. However it may also be called when the tool is run in a modal fashion, when code explicitly sets the diagram's Diagram#currentTool. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.

doMouseMove() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Move the #draggedParts (or if copying, the #copiedParts) to follow the current mouse point.

doMouseMove() → void

Available on Tool, provided by the Tool$Typings extension

The diagram will call this method upon a mouse move event. This is normally overridden for mouse-move tools; it is not called for mouse-up tools. However it may also be called when the tool is run in a modal fashion, when code explicitly sets the diagram's Diagram#currentTool. An override of this method usually does nothing when #isActive is false. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.

doMouseUp() → void

Available on Tool, provided by the Tool$Typings extension

The diagram will call this method upon a mouse up event. This is normally overridden for mouse-up tools. An override of this method usually does nothing when #isActive is false, except for calling #stopTool. Tools normally stop upon a mouse up, by calling #stopTool. If you want to handle multiple mouse down-up gestures in one tool activation, you will need to override this method to only stop the tool when you want. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.

doMouseUp() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

On a mouse-up finish moving or copying the effective selection.

doMouseWheel() → void

Available on Tool, provided by the Tool$Typings extension

The diagram will call this method as the mouse wheel is rotated. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.

doStart() → void

Available on Tool, provided by the Tool$Typings extension

The Diagram calls this method when this tool becomes the current tool; you should not call this method. Tool implementations should perform their per-use initialization here, such as setting up internal data structures, or capturing the mouse. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.

doStop() → void

Available on Tool, provided by the Tool$Typings extension

The Diagram calls this method when this tool stops being the current tool; you should not call this method. Tool implementations should perform their per-use cleanup here, such as releasing mouse capture.

doWaitAfter(InputEvent event) → void

Available on Tool, provided by the Tool$Typings extension

This is called a certain delay after a call to #standardWaitAfter if there has not been any call to #cancelWaitAfter. The ToolManager overrides this method in order to implement support for mouse-hover behavior and tooltips.

findDraggablePart() → Part?

Available on DraggingTool, provided by the DraggingTool$Typings extension

Return the selectable and movable/copyable Part at the mouse-down point. This is called by #canStart to decide if this tool is ready to run.

findDragOverObject(Point pt) → GraphObject?

Available on DraggingTool, provided by the DraggingTool$Typings extension

(undocumented)

findToolHandleAt(Point p, String category) → GraphObject?

Available on Tool, provided by the Tool$Typings extension

This convenience function finds the front-most GraphObject that is at a given point and that is an element of an Adornment that is of a given category. The tool handle must be an immediate element of the Adornment, not a GraphObject that is nested within Panels within the Adornment.

isBeyondDragSize([Point? first, Point? last]) → bool

Available on Tool, provided by the Tool$Typings extension

Return true when the last mouse point is far enough away from the first mouse down point to constitute a drag operation instead of just a potential click.

mayCopy() → bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

This predicate is true when the diagram allows objects to be copied and inserted, and some object in the selection is copyable, and the user is holding down the Control key (Option key on Mac).

mayMove() → bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

This predicate is true when the diagram allows objects to be moved, and some object in the selection is movable.

moveParts(Map<Part, DraggingInfo> parts, Point offset, [bool? check]) → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

Move a collection Map of Parts by a given offset.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

simulatedMouseMove(dynamic e, Point modelpt, [Diagram? overdiag]) → bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

(undocumented) @expose @param {Event} e @param {Point} modelpt @param {Diagram} overdiag the diagram attached to the target of the mouse move event, if any. @return {boolean}

simulatedMouseUp(dynamic e, Point modelpt, [Diagram? curdiag]) → bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

(undocumented) @expose @param {Event} e @param {Point} modelpt @param {Diagram} curdiag @return {boolean}

standardMouseClick<T extends GraphObject>([T? navig(GraphObject)?, bool pred(T)?]) → bool

Available on Tool, provided by the Tool$Typings extension

Implement the standard behavior for mouse clicks, searching for and calling click handler functions on GraphObjects or on Diagram, and raising the corresponding DiagramEvent.

standardMouseOver() → void

Available on Tool, provided by the Tool$Typings extension

Implement the standard behavior for mouse enter, over, and leave events, where the mouse is moving but no button is pressed. This should be called by mouse move event handlers when wanting to detect and invoke mouse enter/over/leave event handlers.

standardMouseSelect() → void

Available on DraggingTool, provided by the DraggingTool$Typings extension

This override prevents the Control modifier unselecting an already selected part. This also remembers the selectable #currentPart at the current mouse point.

standardMouseSelect() → void

Available on Tool, provided by the Tool$Typings extension

Implement the standard behavior for selecting parts with the mouse, depending on the control and shift modifier keys.

standardMouseWheel() → void

Available on Tool, provided by the Tool$Typings extension

Implement the standard behavior for mouse wheel events. ToolManager#doMouseWheel calls this method.

standardPinchZoomMove() → void

Available on Tool, provided by the Tool$Typings extension

Continues pinch-zooming (started by #standardPinchZoomStart on multi-touch devices.

standardPinchZoomStart() → void

Available on Tool, provided by the Tool$Typings extension

Initiates pinch-zooming on multi-touch devices.

standardWaitAfter(num delay, [InputEvent? event]) → void

Available on Tool, provided by the Tool$Typings extension

This is called to start a new timer to call #doWaitAfter after a given delay. It first cancels any previously running "WaitAfter" timer, by calling #cancelWaitAfter.

startTransaction([String? tname]) → bool

Available on Tool, provided by the Tool$Typings extension

Call Diagram#startTransaction with the given transaction name. This always sets #transactionResult to null.

stopTool() → void

Available on Tool, provided by the Tool$Typings extension

If the Diagram#currentTool is this tool, stop this tool and start the Diagram#defaultTool by making it be the new current tool. The implementation of various tool methods can call this method to stop the current tool. This will call #doStop -- you should not call that method directly.

stopTransaction() → bool

Available on Tool, provided by the Tool$Typings extension

If #transactionResult is null, call Diagram#rollbackTransaction, otherwise call Diagram#commitTransaction.

stopTransaction() → bool

Available on DraggingTool, provided by the DraggingTool$Typings extension

This calls the super Tool#stopTransaction method, and if the result is true, attempts to optimize the transaction by removing all changes except the first and last by calling Transaction#optimize.

toString() → String

A string representation of this object.

inherited

updateAdornments(Part part) → void

Available on Tool, provided by the Tool$Typings extension

The diagram asks each tool to update any adornments the tool might use for a given part. If the tool uses its own tool handles, this should display them or hide them as appropriate. Typically this should only show them if the part is selected.

Operators

operator ==(Object other) → bool

The equality operator.

inherited