RelinkingTool class

The RelinkingTool allows the user to reconnect an existing Link if the Link#relinkableTo and/or Link#relinkableFrom properties are true.

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

By default an instance of this tool is installed as a mouse-down tool in the Diagram#toolManager as the ToolManager#relinkingTool.

This tool makes use of two Adornments, each including a relink handle (potentially one for each end of the link), shown when a link is selected.

This tool conducts a transaction while the tool is active. A successful relinking will result in a "LinkRelinked" DiagramEvent and a "Relinking" transaction.

If you want to programmatically start a new user's relinking of a Link, you can set the #handle property to the specific "RelinkFrom" or "RelinkTo" handle and then start and activate the tool.

  var tool = myDiagram.toolManager.relinkingTool;
  tool.originalLink = ...;   // specify which Link to have the user reconnect
  tool.isForwards = true;    // specify which end of the Link to reconnect
  myDiagram.currentTool = tool;  // starts the RelinkingTool
  tool.doActivate();             // activates the RelinkingTool
Implemented types
Available extensions
Annotations
  • @JS()
  • @staticInterop

Constructors

RelinkingTool()
factory

Properties

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
fromHandleArchetype ↔ GraphObject?

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

Gets or sets a small GraphObject that is copied as a relinking handle for the selected link path at the "from" end of the link. By default this is a Shape that is a small blue diamond. Setting this property does not raise any events.
getter/setter pair
handle ↔ GraphObject?

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

Returns the GraphObject that is the tool handle being dragged by the user. This will be contained by an Adornment whose category is "RelinkFrom" or "RelinkTo". Its Adornment#adornedPart is the same as the #originalLink.
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
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
toHandleArchetype ↔ GraphObject?

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

Gets or sets a small GraphObject that is copied as a relinking handle for the selected link path at the "to" end of the link. By default this is a Shape that is a small blue diamond. 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 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.
canStart() → bool

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

This tool can run when the diagram allows relinking, the model is modifiable, and there is a relink handle at the mouse-down point.
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
copyLinkProperties(Link templink, [Link? reallink]) → void

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

Make a temporary link look and act like the real Link being relinked. By default this method copies many of the routing-oriented properties from the LinkingBaseTool#originalLink to the LinkingBaseTool#temporaryLink.
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 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.
doActivate() → void

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

Start the relinking 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 RelinkingTool, provided by the RelinkingTool$Typings extension

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

A mouse-up ends the relinking operation; if there is a valid #targetPort nearby, this modifies the old link to connect with the target port.
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 RelinkingTool, provided by the RelinkingTool$Typings extension

This method is called upon a mouse up when #reconnectLink is not called.
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.
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.
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.
makeAdornment(GraphObject selelt, bool toend) → Adornment?

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

(undocumented) Create and return an Adornment that lets the user grab a handle to reconnect one end of the selected link.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited

Available on RelinkingTool, provided by the RelinkingTool$Typings extension

Modify an existing Link to connect to a new node and port.
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 RelinkingTool, provided by the RelinkingTool$Typings extension

Show an Adornment for each end of the Link that the user may reconnect. The Adornment may have a copy of #fromHandleArchetype and/or #toHandleArchetype.
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