This is an extension and not part of the main GoJS library. Note that the API for this class may change at any time. If you intend to use an extension in production, you should copy the code to your own source directory. See the Extensions intro page for more information.
Optionalinit: Partial<NonRealtimeDraggingTool>Gets or sets the collection of Parts that this tool has copied. The value is a go.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.
draggedParts provides the map of Parts that are being moved and from which this collection was copied.
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.
The CommandHandler.copiesConnectedLinks property serves a similar role for the CommandHandler.copySelection command,
when the user types Ctrl-C to copy the currently selected parts.
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
since2.2
Gets or sets the Part found at the mouse point. This is normally set by a call to standardMouseSelect.
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.
Gets or sets the collection of Parts being moved. The value is a go.Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part.
copiedParts provides the map of Parts that have been copied during a copying operation, if any.
Gets or sets the DraggingTool's DraggingOptions instance, which controls several dragging properties.
Several DraggingTool properties are just convenience properties:
Setting any of these properties really sets the corresponding dragOptions property.
Setting this property does not raise any events.
since2.0
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.
In order to avoid too many cases of having both ends of a dragged Link connect to the same node (if allowed), it is commonplace to decrease the LinkingBaseTool.portGravity to a smaller value such as 10 or 20.
This property is a convenience getter/setter, and sets a value on dragOptions.
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.
The CommandHandler.copiesTree property serves a similar role for the CommandHandler.copySelection command,
when the user types Ctrl-C to copy the currently selected parts.
This property is a convenience getter/setter, and sets a value on dragOptions.
Gets or sets how long the movement animation should be to move the actual parts upon a mouse-up. The default value is zero -- there is no animation of the movement.
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.
This property is a convenience getter/setter, and sets a value on dragOptions.
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.
This property is a convenience getter/setter, and sets a value on dragOptions.
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.
This property is a convenience getter/setter, and sets a value on dragOptions.
Gets or sets whether this tool is started and is actively doing something.
You can set this to true after your tool is started (i.e. when it is the Diagram.currentTool and doStart had been called), but when it is not yet in a state that it is actually "doing" something, because it is waiting for the right circumstances. This is typically only important when the tool is used in a modal fashion.
The default value is false. This is normally set by doActivate and doDeactivate.
In 3.0 this is superceded by Router.isRealtime, and setting this property attempts to set that property on the "AvoidsLinks" Router.
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.
deprecated
Gets or sets whether for any internal copying operation is permitted by control-drag-and-drop (or alt-drag-and-drop on Mac). This property affects the behavior of mayCopy, but does not affect whether copied objects may be dropped into this diagram from a different diagram.
The default value is true. Setting this property does not raise any events.
Gets or sets whether this tool can be started by a mouse event.
Set this to false to prevent canStart from returning true. Setting this property to false should prevent this tool from being used in a mode-less fashion by the ToolManager with a mouse down/move/up event. However, even when this property is false, this tool can still be used in a modal fashion: it can still be started by explicitly setting the Diagram.currentTool property to this tool.
The default value is true.
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.
This property does not affect dragging disconnected links, but those links do respect the Part.dragComputation, which can be used to snap them.
By default this property is false. Setting this property does not raise any events.
This property is a convenience getter/setter, and sets a value on dragOptions.
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.
This property is a convenience getter/setter, and sets a value on dragOptions.
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
since2.2
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".
This name is sometimes used by tools that use Adornments as the Part.category for their Adornments. It is also sometimes used by tools that conduct transactions as the transaction name.
The cursor to show when a drop is not allowed. This defaults to 'no-drop'. Read more about cursors at Diagram.currentCursor
since2.2
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.
Gets or sets the name of the transaction to be committed by stopTransaction
If null, the transaction will be rolled back.
If this is non-null at the time of a call to stopTransaction, it calls Diagram.commitTransaction with this transaction name; if this is null at that time, it calls Diagram.rollbackTransaction.
The default value is null; startTransaction will also set this to null. Because a value of null when stopTransaction is called will rollback the transaction, it is important that your code sets this property to a non-null value when it thinks it has succeeded.
This property exists so that no matter what execution path occurs to end the usage of a tool, any ongoing transaction can be properly committed or rolled-back. Many tools call startTransaction and stopTransaction; thus they set this property for their transaction to be committed. doCancel also sets this property to null.
VirtualcancelThis is called to cancel any running "WaitAfter" timer.
This is called when a tool is stopped.
This method is rarely overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualcanThis 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.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualcanThis method controls for some Tools whether canStart may return true depending on the button being used. Normally this returns true if InputEvent.left is true. This method may be overridden to consider other buttons, or to ignore which button by just returning true.
true, if the left mouse button is being held down
since4.0
VirtualcanAs of version 4, this predicate method is no longer called by the ToolManager. Most of the responsibility for pinch zooming has been moved to the PanningTool.
deprecatedOverridecomputeVirtualcomputeThis 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.
This just calls Diagram.computeMove and remains for compatibility.
This method may be overridden, but should usually be overridden on Diagram. Please read the Learn page on Extensions for how to override methods and how to call this base method.
the Node or simple Part that is being moved
the proposed new location
Optionaldraggedparts: Map<Part, DraggingInfo> | nullan optional Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part.
Optionalresult: Pointan optional Point that is modified and returned
the possibly grid-snapped computed Point that is within the minimum and maximum permitted locations
OverridedoWhen activated, replace the draggedParts with the ghost dragged parts, which consists of just one Part, the image, added to the Diagram at the current mouse point.
Abort any dragging operation.
OverridedoWhen deactivated, make sure any image is removed from the Diagram and all references are cleared out.
VirtualdoPerform 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).
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
a Point in document coordinates.
the GraphObject at the point, excluding what is being dragged or temporary objects; the argument may be null if the drag is occurring in the background of the diagram. Use GraphObject.part to get the Node or Part at the root of the visual tree of the stationary object.
VirtualdoPerform 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).
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
a Point in document coordinates.
the GraphObject where the drop occurred, excluding what was dropped or temporary objects; the argument may be null if the drop occurred in the background of the diagram. Use GraphObject.part to get the Node or Part at the root of the visual tree of the stationary object.
OverridedoIf the user changes to "copying" mode by holding down the Control key, return to the regular behavior and remove the image.
OverridedoIf the user changes back to "moving" mode, show the image again and go back to dragging the ghost dragged parts.
VirtualdoThe 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.
By default this method checks isActive; if that is false it calls canStart. If that in turn is true, this calls doActivate. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Move the draggedParts (or if copying, the copiedParts) to follow the current mouse point.
If this creates any temporary parts, by default it adds them to the Tool layer.
This calls doDragOver for any side-effects on stationary parts.
OverridedoDo the normal mouse-up behavior, but only after restoring draggedParts.
VirtualdoThe 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.
By default this method does nothing. (But the ToolManager.doMouseWheel override will call Tool.standardMouseWheel.) This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualdoThe 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.
You should not call this method -- only the Diagram.currentTool property setter should call this method.
By default this method does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
If you override this method, it is commonplace to also override doStop to clean up whatever you set up in this method.
VirtualdoThe 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.
You should not call this method -- only the Diagram.currentTool property setter should call this method. If you want to stop a tool unexpectedly, you should call doCancel. If your implementation of a tool wants to stop itself, you should call stopTool.
By default this method does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
It is commonplace to override this method in order to clean up whatever you have set up in an override of doStart.
VirtualdoThis 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.
By default this does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
The event that caused standardWaitAfter.
VirtualfindReturn 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.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualfindThis 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.
This method is very infrequently overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
a Point in document coordinates.
the required Part.category of the Adornment.
VirtualisReturn 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.
This uses the value of ToolManager.dragSize. On touch devices the value is automatically increased to accommodate the unavoidable movement of fingers.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Optionalfirst: PointPoint in view coordinates, defaults to Diagram.firstInput's InputEvent.viewPoint.
Optionallast: PointPoint in view coordinates, defaults to Diagram.lastInput's InputEvent.viewPoint.
VirtualmayThis 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).
This method may be overridden, although in most cases it is easiest to set Part.copyable. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualmayThis predicate is true when the diagram allows objects to be moved, and some object in the selection is movable.
This method may be overridden, although in most cases it is easiest to set Part.movable. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualmoveMove a collection Map of Parts by a given offset.
If check is true this respects the Part.canMove predicate for Nodes or simple Parts when this is the Diagram.currentTool. It also respects isGridSnapEnabled in order to try to automatically snap part locations to a grid. And it also uses the Part.dragComputation function, if any, to determine the new location for each part.
The first argument is a go.Map as produced by computeEffectiveCollection, not a List or go.Set or Iterator of Parts. Call Diagram.moveParts if you want to move a simple collection of Parts without having to create the argument Map.
a Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part.
The offset, before snapping, to move parts. This offset reflects the total amount moved during tool operation, based on original Part locations remembered when the DraggingTool activated.
Optionalcheck: booleanWhether to check Part.canMove on each part. The default value is false.
VirtualstandardImplement the standard behavior for mouse clicks, searching for and calling click handler functions on GraphObjects or on Diagram, and raising the corresponding DiagramEvent.
A click on a GraphObject of the diagram will raise one of the following DiagramEvents: "ObjectSingleClicked", "ObjectDoubleClicked", or "ObjectContextClicked". This will also look at the corresponding click property: GraphObject.click, GraphObject.doubleClick, or GraphObject.contextClick. If the value is a function, this will call it, passing the current InputEvent and the GraphObject. If the value is null, it tries looking at the parent GraphObject.panel, and so on, walking up the visual tree until it finds the appropriate function to call. After calling the click function, if the value of InputEvent.handled is false, this method will continue walking up the visual tree looking for more click functions to call. Once it has looked at the top-level object (a Part) for a click function, this method stops.
A click in the background of the diagram will raise one of the following DiagramEvents: "BackgroundSingleClicked", "BackgroundDoubleClicked", or "BackgroundContextClicked". This will also look at the corresponding click property: Diagram.click, Diagram.doubleClick, or Diagram.contextClick. If the value is a function, this will call it, passing the current InputEvent.
This method is not responsible for selecting or deselecting any parts. Call standardMouseSelect for that functionality.
Note that this calls GraphObject.isEnabledObject on the target object; if it returns false, no click action will occur.
The ClickSelectingTool calls this method in its override of doMouseUp in order to raise "click" events. Note that by default GraphObjects in Layers that are Layer.isTemporary will not be "clicked". To change that behavior it is easiest to set GraphObject.isActionable to true on those objects for which you wish to handle "click" events. Then the ActionTool's doMouseUp override will raise the standard "click" events.
This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Optionalnavig: ((a: GraphObject) => T | null) | nullAn optional custom navigation function to find target objects. This argument is passed to Diagram.findObjectAt.
Optionalpred: ((a: T) => boolean) | nullAn optional custom predicate function to find target objects. A null value is effectively the same as a function that always returns true. This argument is passed to Diagram.findObjectAt, unless the value is undefined, which means to use a predicate to consider only objects in layers holding permanent objects.
true if InputEvent.handled had been set to true on the Diagram.lastInput.
VirtualstandardImplement 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.
The GraphObject.mouseEnter property provides a function to call when the mouse first enters an object or any of its contained objects (if the object is actually a Panel).
The GraphObject.mouseLeave property provides a function to call when the mouse leaves an object and all of its contained objects (if the object is actually a Panel).
The GraphObject.mouseOver property and Diagram.mouseOver properties provide functions to call when the mouse moves but stays within the same GraphObject or when the mouse moves in the background of the Diagram.
This method is also responsible for updating the Diagram.currentCursor according to the value of GraphObject.cursor and Diagram.defaultCursor.
This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstandardThis override prevents the Control modifier unselecting an already selected part. This also remembers the selectable currentPart at the current mouse point.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstandardImplement the standard behavior for mouse wheel events. ToolManager.doMouseWheel calls this method.
Turning the mouse wheel if Diagram.allowVerticalScroll is true causes the diagram to scroll up or down. If InputEvent.shift and Diagram.allowHorizontalScroll are true, the diagram scrolls left or right.
If InputEvent.control and Diagram.allowZoom are true, turning the mouse wheel changes the diagram's scale, zooming in or out while trying to keep the point in the model at the same point as the mouse.
The value of ToolManager.mouseWheelBehavior affects what operations might occur upon mouse wheel events.
This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstandardAs of version 4, this method is no longer called by the ToolManager. Most of the responsibility for pinch zooming has been moved to the PanningTool.
deprecatedVirtualstandardAs of version 4, this method is no longer called by the ToolManager. Most of the responsibility for pinch zooming has been moved to the PanningTool.
deprecatedVirtualstandardThis 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.
This is normally used to implement mouse hover and mouse hold events. If the mouse has moved, it must not have moved beyond the distance as determined by Tool.isBeyondDragSize for it be considered "stationary". So the regular ToolManager.doMouseMove implementation only calls this method when the mouse has moved beyond the drag size.
This method is rarely overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
The delay, in milliseconds.
Optionalevent: InputEventAn optional event that caused this timer. Defaults to Diagram.lastInput. This gets passed on to doWaitAfter.
Call Diagram.startTransaction with the given transaction name. This always sets transactionResult to null.
This is normally called in an override of doActivate, if the tool modifies the model, along with a call to stopTransaction in an override of doDeactivate. Alternatively, you can surround a block of code that sets the transactionResult with calls to startTransaction and stopTransaction.
Optionaltname: stringa string describing the transaction.
the value of the call to Diagram.startTransaction.
VirtualstopIf 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.
If you want to stop the current tool and have it restore the original state, call doCancel. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstopThis 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.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
the result of the call to rollback or commit the transaction.
VirtualupdateThe 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.
By default this method does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
The NonRealtimeDraggingTool class lets the user drag an image instead of actually moving any selected nodes, until the mouse-up event.
If you want to experiment with this extension, try the Non Realtime Dragging sample.