Class LinkingTool

Extends LinkingBaseTool. 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 may be 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();

Constructor Summary Details

Name Description
LinkingTool()

You do not normally need to create an instance of this tool because one already exists as the ToolManager.linkingTool, which you can modify.More...

The Tool.name of this tool is "Linking".

Properties Summary Details

Name, Value Type Description
archetypeLabelNodeData
{Object}

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.More...

The default value is null, which causes no such label node data to be added to the model along with the new link data.

insertLink calls GraphLinksModel.addLabelKeyForLinkData to associate the label node data with the link data.

Setting this property does not raise any events. This property is ignored if the Diagram.model is not a GraphLinksModel.

archetypeLinkData
{Object}

Gets or sets a data object that is copied by insertLink and added to the GraphLinksModel when creating a new Link.More... 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.

The copied link data's GraphLinksModel.linkFromKeyProperty and GraphLinksModel.linkToKeyProperty properties are set to the corresponding node's data's key values. If the ports have GraphObject.portId values that are not null, the link data's GraphLinksModel.linkFromPortIdProperty and GraphLinksModel.linkToPortIdProperty properties are also set.

Setting this property does not raise any events. This property is ignored if the Diagram.model is not a GraphLinksModel.

direction
{EnumValue}

Gets or sets the direction in which new links may be drawn.More... Possible values are LinkingTool.ForwardsOnly, LinkingTool.BackwardsOnly, or LinkingTool.Either. This defaults to LinkingTool.Either. Setting this property does not raise any events.

startObject

Gets or sets the GraphObject at which findLinkablePort should start its search.More... The default value is null. Setting this property does not raise any events.

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

  var tool = myDiagram.toolManager.linkingTool;
  tool.startObject = ...;
  myDiagram.currentTool = tool;
  tool.doActivate();
Properties borrowed from class LinkingBaseTool:
isForwards, isUnconnectedLinkValid, linkValidation, originalFromNode, originalFromPort, originalLink, originalToNode, originalToPort, portGravity, portTargeted, targetPort, temporaryFromNode, temporaryFromPort, temporaryLink, temporaryToNode, temporaryToPort
Properties borrowed from class Tool:
diagram, isActive, isEnabled, name, transactionResult

Method Summary Details

Name, Return Type Description
canStart()
{boolean}

This tool can run when the diagram allows 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.More...

This method may be overridden, but we recommend that you call this base method.

Returns:
{boolean}
doActivate()

Start the linking operation.More...

If the startObject is already set, it uses that object to find the starting port. If it is not set, this calls findLinkablePort and remembers it as the starting port.

It then start a transaction, captures the mouse, and changes the cursor. Next it initializes and adds the LinkingBaseTool.temporaryFromNode, LinkingBaseTool.temporaryToNode, and LinkingBaseTool.temporaryLink to the diagram. The temporary nodes that are positioned and sized to be like the real LinkingBaseTool.originalFromPort and LinkingBaseTool.originalToPort ports. The temporary link connects the two temporary ports, of course.

This method may be overridden, but we recommend that you call this base method.

doDeactivate()

Finishing the linking operation stops the transaction, releases the mouse, and resets the cursor.More...

This method may be overridden, but we recommend that you call this base method.

doMouseUp()

A mouse-up ends the linking operation; if there is a valid targetPort nearby, this adds a new Link by calling insertLink.More...

If there is a new link, it is selected and the "LinkDrawn" DiagramEvent is raised. In any case this stops the tool.

This method may be overridden, but we recommend that you call this base method. It is usually easier to override insertLink or just set archetypeLinkData. It is also common to implement a "LinkDrawn" DiagramEvent listener on the Diagram.

findLinkablePort()

Return the GraphObject at the mouse-down point, if it is part of a node and if it is valid to link with it.More...

This method may be overridden, but we recommend that you call this base method. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

Returns:
{GraphObject} If the direction is Either or ForwardsOnly, this checks the element and its parent Node by calling LinkingBaseTool.isValidFrom. If the direction is Either or BackwardsOnly, this checks the element and its parent Node by calling LinkingBaseTool.isValidTo. In either case finding a matching port will return that port and set LinkingBaseTool.isForwards appropriately. Otherwise this will return null.
Methods borrowed from class LinkingBaseTool:
copyPortProperties, doMouseMove, findTargetPort, isInSameNode, isLinked, isValidCycle, isValidFrom, isValidLink, isValidTo, setNoTargetPortProperties
Methods borrowed from class Tool:
cancelWaitAfter, canStartMultiTouch, doCancel, doKeyDown, doKeyUp, doMouseDown, doMouseWheel, doStart, doStop, doWaitAfter, findToolHandleAt, isBeyondDragSize, standardMouseClick, standardMouseOver, standardMouseSelect, standardMouseWheel, standardPinchZoomMove, standardPinchZoomStart, standardWaitAfter, startTransaction, stopTool, stopTransaction, updateAdornments

Constants Summary Details

Name Description
BackwardsOnly {EnumValue}

This value for LinkingTool.direction indicates that users may draw new links backwards only (i.e.More... from "to" node to "from" node).

Either {EnumValue}

This value for LinkingTool.direction indicates that users may draw new links in either direction.

ForwardsOnly {EnumValue}

This value for LinkingTool.direction indicates that users may draw new links forwards only (i.e.More... from "from" node to "to" node).