LinkingTool class

The LinkingTool lets a user draw a new Link between two ports, using a mouse-drag operation.

By default an instance of this tool is installed as a mouse-move tool in the Diagram#toolManager as the ToolManager#linkingTool. However this tool may be used modally, as described below.

#canStart calls #findLinkablePort to find a valid "port" element from which (or to which) the user may interactively draw a new link. #doActivate sets up a temporary link and two temporary nodes, one at the start port and one following the mouse.

For a general discussion of validation, see Introduction to Validation.

This tool does not utilize any Adornments or tool handles.

This tool conducts a transaction while the tool is active. A successful linking will result in a "LinkDrawn" DiagramEvent and a "Linking" transaction.

If you want to programmatically start a new user mouse-gesture to draw a new link from a given GraphObject that either is a "port" or may be within the visual tree of a "port", set the #startObject property to let #findLinkablePort find the real "port" element. Then start and activate this tool:

  var tool = myDiagram.toolManager.linkingTool;
  tool.startObject = ...;
  myDiagram.currentTool = tool;
  tool.doActivate();
Implemented types
Available extensions
Annotations
  • @JS()
  • @staticInterop

Constructors

LinkingTool()
factory

Properties

archetypeLabelNodeData ↔ Object?

Available on LinkingTool, provided by the LinkingTool$Typings extension

Gets or sets an optional node data object representing a link label, that is copied by #insertLink and added to the GraphLinksModel when creating a new Link.
getter/setter pair
archetypeLinkData ↔ Object?

Available on LinkingTool, provided by the LinkingTool$Typings extension

Gets or sets a data object that is copied by #insertLink and added to the GraphLinksModel when creating a new Link. The default value is an empty Object, which will be copied. The value must be an Object for the linking operation to succeed. A null value will cause #insertLink to fail.
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
direction ↔ EnumValue

Available on LinkingTool, provided by the LinkingTool$Typings extension

Gets or sets the direction in which new links may be drawn. Possible values are LinkingTool.ForwardsOnly, LinkingTool.BackwardsOnly, or LinkingTool.Either. This defaults to LinkingTool.Either. Setting this property does not raise any events.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
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
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
isForwards ↔ bool

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets whether the linking operation is in the forwards direction, connecting from the "From" port to the "To" port.
getter/setter pair
isUnconnectedLinkValid ↔ bool

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets whether it is valid to have partly or completely unconnected links.
getter/setter pair
linkingCursor ↔ String

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the cursor used during the linking or relinking operation. This defaults to 'pointer'. Read more about cursors at Diagram#currentCursor
getter/setter pair
linkValidation ↔ bool Function(Node, GraphObject, Node, GraphObject, Link)?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets a predicate that determines whether or not a new link between two ports would be valid. This predicate is called in addition to the normal link checking performed by #isValidLink and any Node#linkValidation predicates on the "from" and "to" nodes. When relinking, the Link being considered for reconnection is passed as the fifth argument. The default predicate is null, which is equivalent to simply returning true.
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
originalFromNode ↔ Node?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the original Node from which the new link is being drawn or from which the #originalLink was connected when being relinked. Setting this property does not raise any events.
getter/setter pair
originalFromPort ↔ GraphObject?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the GraphObject that is the port in the #originalFromNode. Setting this property does not raise any events.
getter/setter pair

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the original Link being reconnected by the RelinkingTool. Setting this property does not raise any events.
getter/setter pair
originalToNode ↔ Node?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the original Node to which the new link is being drawn or to which the #originalLink was connected when being relinked. Setting this property does not raise any events.
getter/setter pair
originalToPort ↔ GraphObject?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the GraphObject that is the port in the #originalToNode. Setting this property does not raise any events.
getter/setter pair
portGravity ↔ num

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the distance at which link snapping occurs. The default value is 100.0. The value must be non-negative. Setting this property does not raise any events.
getter/setter pair
portTargeted ↔ void Function(Node, GraphObject, bool, [Node?, GraphObject?])?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets a function that is called as the tool targets the nearest valid port. The first two arguments specify the port by providing the Node that it is in and the GraphObject that is the actual port object. The next two arguments are the temporary port that has been moved and styled to be like the valid port. These values will be either the #temporaryToNode and #temporaryToPort or the #temporaryFromNode and #temporaryFromPort, depending on which end of the temporary link is being updated. The fifth argument is true if the target port represents a potential "to" end of a link; it is false if it is for the "from" end of a link.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
startObject ↔ GraphObject?

Available on LinkingTool, provided by the LinkingTool$Typings extension

Gets or sets the GraphObject at which #findLinkablePort should start its search. The default value is null. Setting this property does not raise any events.
getter/setter pair
targetPort ↔ GraphObject?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets a proposed GraphObject port for connecting a link. Whether this is a "to" port or a "from" port depends on the direction (#isForwards) in which the link is being drawn or reconnected.
getter/setter pair
temporaryFromNode ↔ Node

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the temporary Node at the "from" end of the #temporaryLink while the user is drawing or reconnecting a link. Setting this property does not raise any events.
getter/setter pair
temporaryFromPort ↔ GraphObject

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the GraphObject that is the port at the "from" end of the #temporaryLink while the user is drawing or reconnecting a link. Setting this property does not raise any events.
getter/setter pair

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the temporary Link that is shown while the user is drawing or reconnecting a link. Setting this property does not raise any events.
getter/setter pair
temporaryToNode ↔ Node

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the temporary Node at the "to" end of the #temporaryLink while the user is drawing or reconnecting a link. Setting this property does not raise any events.
getter/setter pair
temporaryToPort ↔ GraphObject

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Gets or sets the GraphObject that is the port at the "to" end of the #temporaryLink while the user is drawing or reconnecting a link. 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 LinkingTool, provided by the LinkingTool$Typings extension

This tool can run when the diagram allows linking, the model is modifiable, the left-button mouse drag has moved far enough away to not be a click, and when #findLinkablePort has returned a valid port or when #startObject is a valid port.
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
copyPortProperties(Node tempnode, GraphObject tempport, bool toend, [Node? realnode, GraphObject? realport]) → void

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Make a temporary port look and act like a real one.
doActivate() → void

Available on LinkingTool, provided by the LinkingTool$Typings extension

Start the linking operation.
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 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 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.
doDeactivate() → void

Available on LinkingTool, provided by the LinkingTool$Typings extension

Finishing the linking operation stops the transaction, releases the mouse, and resets the cursor.
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.
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 LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Mouse movement results in a temporary node moving to where a valid target port is located, or to where the mouse is if there is no valid target port nearby.
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 LinkingTool, provided by the LinkingTool$Typings extension

A mouse-up ends the linking operation; if there is a valid #targetPort nearby, this adds a new Link by calling #insertLink.
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.
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.

Available on LinkingTool, provided by the LinkingTool$Typings extension

This method is called upon a mouse up when no new link is drawn, either because no valid LinkingBaseTool#targetPort was found or because #insertLink returned null.
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.
findLinkablePort() → GraphObject?

Available on LinkingTool, provided by the LinkingTool$Typings extension

Return the GraphObject at the mouse-down point, if it is part of a node and if it is valid to link with it.
findTargetPort(bool toend) → GraphObject?

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Find a port with which the user could complete a valid link.
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.

Available on LinkingTool, provided by the LinkingTool$Typings extension

Make a copy of the #archetypeLinkData, set its node and port properties, and add it to the GraphLinksModel. If the model is a TreeModel, set the parent key of the child's node data object.
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.
isInSameNode([GraphObject? fromport, GraphObject? toport]) → bool

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

This predicate is true if both argument ports are in the same Node. This is called by #isValidLink.
isLinked([GraphObject? fromport, GraphObject? toport]) → bool

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

This predicate is true if there is a link in the diagram going from the given port to the given port. This is called by #isValidLink.
isValidCycle([Node? from, Node? to, Link? ignore]) → bool

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Checks whether a proposed link would be valid according to Diagram#validCycle. This does not distinguish between different ports on a node, so this method does not need to take port arguments. This is called by #isValidLink.
isValidFrom([Node? fromnode, GraphObject? fromport]) → bool

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

This predicate is true if it is permissible to connect a link from a given node/port. This is called by #isValidLink.

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

This predicate should be true when it is logically valid to connect a new link from one node/port to another node/port. When this is called by the RelinkingTool, that tool sets #originalLink to be the Link being reconnected.
isValidTo([Node? tonode, GraphObject? toport]) → bool

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

This predicate is true if it is permissible to connect a link to a given node/port. This is called by #isValidLink.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
setNoTargetPortProperties(Node tempnode, GraphObject tempport, bool toend) → void

Available on LinkingBaseTool, provided by the LinkingBaseTool$Typings extension

Reset a temporary port's properties to neutral values when there is no target port.
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 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.
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

Static Properties

backwardsOnly ↔ EnumValue
This value for LinkingTool#direction indicates that users may draw new links backwards only (i.e. from "to" node to "from" node).
getter/setter pair
either ↔ EnumValue
This value for LinkingTool#direction indicates that users may draw new links in either direction.
getter/setter pair
forwardsOnly ↔ EnumValue
This value for LinkingTool#direction indicates that users may draw new links forwards only (i.e. from "from" node to "to" node).
getter/setter pair