# Class RelinkingTool

GoJS® Diagramming Components
version 3.0.7
by Northwoods Software®

#### Hierarchy

- LinkingBaseTool
  - RelinkingTool

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.

      const 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

#####
Index

### Constructors

constructor

### Accessors

fromHandleArchetype
handle
toHandleArchetype

### Methods

canStart
copyLinkProperties
doActivate
doDeactivate
doMouseUp
doNoRelink
reconnectLink
updateAdornments

#####
Inherited Index

### Accessors

LinkingBaseTool.isForwards
LinkingBaseTool.isUnconnectedLinkValid
LinkingBaseTool.linkValidation
LinkingBaseTool.linkingCursor
LinkingBaseTool.originalFromNode
LinkingBaseTool.originalFromPort
LinkingBaseTool.originalLink
LinkingBaseTool.originalToNode
LinkingBaseTool.originalToPort
LinkingBaseTool.portGravity
LinkingBaseTool.portTargeted
LinkingBaseTool.targetPort
LinkingBaseTool.temporaryFromNode
LinkingBaseTool.temporaryFromPort
LinkingBaseTool.temporaryLink
LinkingBaseTool.temporaryToNode
LinkingBaseTool.temporaryToPort
Tool.diagram
Tool.isActive
Tool.isEnabled
Tool.name
Tool.transactionResult

### Methods

LinkingBaseTool.copyPortProperties
LinkingBaseTool.doMouseMove
LinkingBaseTool.findTargetPort
LinkingBaseTool.isInSameNode
LinkingBaseTool.isLinked
LinkingBaseTool.isValidCycle
LinkingBaseTool.isValidFrom
LinkingBaseTool.isValidLink
LinkingBaseTool.isValidTo
LinkingBaseTool.setNoTargetPortProperties
Tool.canStartMultiTouch
Tool.cancelWaitAfter
Tool.doCancel
Tool.doKeyDown
Tool.doKeyUp
Tool.doMouseDown
Tool.doMouseWheel
Tool.doStart
Tool.doWaitAfter
Tool.findToolHandleAt
Tool.isBeyondDragSize
Tool.standardMouseClick
Tool.standardMouseOver
Tool.standardMouseSelect
Tool.standardMouseWheel
Tool.standardPinchZoomMove
Tool.standardPinchZoomStart
Tool.standardWaitAfter
Tool.startTransaction
Tool.stopTool
Tool.stopTransaction

## Constructors

### constructor

- new RelinkingTool(init?: Partial<RelinkingTool>): RelinkingTool

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

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

  #### Parameters

  - ##### `Optional` init: Partial<RelinkingTool>

  #### Returns RelinkingTool

## Accessors

### fromHandleArchetype
: GraphObject

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

  Here is an example of changing the default handle to be larger green triangles:

      myDiagram.toolManager.relinkingTool.toHandleArchetype =
        $(go.Shape, "Triangle",
          { width: 10, height: 10, fill: "limegreen", segmentIndex: 0 });

  `see`

  toHandleArchetype

### handle
: GraphObject

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

  This property is also settable, but should only be set either within an override of doActivate or prior to calling doActivate.

### toHandleArchetype
: GraphObject

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

  Here is an example of changing the default handle to be larger orange triangles:

        myDiagram.toolManager.relinkingTool.toHandleArchetype =
        $(go.Shape, "Triangle",
          { width: 10, height: 10, fill: "orange", segmentIndex: -1 });

  `see`

  fromHandleArchetype

## Methods

### `Override` canStart

- canStart(): boolean

- This tool can run when the diagram allows relinking, the model is modifiable, and there is a relink handle at the mouse-down point.

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

  #### Returns boolean

### `Protected` `Virtual` copyLinkProperties

- copyLinkProperties(reallink: Link, templink: Link): void

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

  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.

  #### Parameters

  - ##### reallink: Link

  - ##### templink: Link

  #### Returns void

### `Override` doActivate

- doActivate(): void

- Start the relinking operation.

  Find the relink handle by calling Tool.findToolHandleAt looking for either the "RelinkFrom" adornment or the "RelinkTo" adornment, saving the result in handle.

  Normally when this method is called the value of LinkingBaseTool.originalLink and handle will be null, resulting in a call to Tool.findToolHandleAt to find a "RelinkFrom" or "RelinkTo" tool handle, which is then remembered as the value of handle. If when this method is called the value of handle is already set, then there is no need to call Tool.findToolHandleAt, because the programmer has already set up which relinking handle they want the user to be relinking. Finding a handle is not necessary if LinkingBaseTool.originalLink and isForwards have been set before calling this method.

  This starts a transaction, captures the mouse, and sets the cursor.

  If LinkingBaseTool.originalLink or handle was not set beforehand, the value of isForwards is set depending on the category of the relink handle found. The LinkingBaseTool.originalLink property and various "Original..." port and node properties are set too. The temporary nodes and temporary link are also initialized.

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

  #### Returns void

### `Override` doDeactivate

- doDeactivate(): void

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

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

  #### Returns void

### `Override` doMouseUp

- doMouseUp(): void

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

  A successful relinking calls reconnectLink to actually change the link. The "LinkRelinked" DiagramEvent is raised with the link as the DiagramEvent.subject and with the now-disconnected original port as the DiagramEvent.parameter. If the link was not reconnected, this calls doNoRelink. In any case this stops the tool.

  A failure to find a valid target port results in no changes and no DiagramEvent.

  This method may be overridden, but we recommend that you call this base method. You might find it easier to override reconnectLink. It is actually most common to implement a "LinkRelinked" DiagramEvent listener on the Diagram.

  #### Returns void

### `Virtual` doNoRelink

- doNoRelink(existinglink: Link, toend: boolean): void

- This method is called upon a mouse up when reconnectLink is not called.

  This method may be overridden. By default this method does nothing. If you want to successfully perform any side-effects, you will need to set Tool.transactionResult to a string; otherwise this tool's transaction will be rolled-back. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

  #### Parameters

  - ##### existinglink: Link

  - ##### toend: boolean

    If true, the user was trying to modify the link's "to" node and port.

  #### Returns void

### `Virtual` reconnectLink

- reconnectLink(existinglink: Link, newnode: Node, newport: GraphObject, toend: boolean): boolean

- Modify an existing Link to connect to a new node and port.

  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.

  #### Parameters

  - ##### existinglink: Link

  - ##### newnode: Node

    the Node to connect to or from.

  - ##### newport: GraphObject

    the GraphObject port to connect to or from.

  - ##### toend: boolean

    If true, this modifies the link's "to" node and port; otherwise it modifies the "from" node and port.

  #### Returns boolean

  true if successful.

  `see`

  doNoRelink

### `Override` updateAdornments

- updateAdornments(part: Part): void

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

  This method may be overridden.

  #### Parameters

  - ##### part: Part

  #### Returns void

Copyright © 1998-2024 by Northwoods Software Corporation.