Class RelinkingTool

GoDiagram®
v10.0.8
by Northwoods Software®

The RelinkingTool allows the user to reconnect an existing Link if the RelinkableTo and/or RelinkableFrom properties are true.

Inheritance
object
Tool
LinkingBaseTool
RelinkingTool
Namespace: Northwoods.Go.Tools
Assembly: Northwoods.GoDiagram.WinForms.dll
Syntax
public class RelinkingTool : LinkingBaseTool
Remarks

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 ToolManager as the 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

Constructors

RelinkingTool()

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

The Name of this tool is "Relinking".

Declaration
public RelinkingTool()

Properties

FromHandleArchetype

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.

Declaration
public GraphObject FromHandleArchetype { get; set; }
Property Value
Type Description
GraphObject
Remarks

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 =
  new Shape("Triangle") { Width = 10, Height = 10, Fill = "limegreen", SegmentIndex = 0 };
See Also

Handle

Returns the GraphObject that is the tool handle being dragged by the user.

Declaration
public GraphObject Handle { get; set; }
Property Value
Type Description
GraphObject
Remarks

This will be contained by an Adornment whose category is "RelinkFrom" or "RelinkTo". Its 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

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.

Declaration
public GraphObject ToHandleArchetype { get; set; }
Property Value
Type Description
GraphObject
Remarks

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 =
  new Shape("Triangle") { Width = 10, Height = 10, Fill = "orange", SegmentIndex = -1 };
See Also

Methods

CanStart()

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

Declaration
public override bool CanStart()
Returns
Type Description
bool
Overrides
Remarks

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

CopyLinkProperties(Link, Link)

Make a temporary link look and act like the real Link being relinked.

Declaration
protected virtual void CopyLinkProperties(Link reallink, Link templink)
Parameters
Type Name Description
Link reallink
Link templink
Remarks

By default this method copies many of the routing-oriented properties from the OriginalLink to the 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.

DoActivate()

Start the relinking operation.

Declaration
public override void DoActivate()
Overrides
Remarks

Find the relink handle by calling FindToolHandleAt(Point, string) looking for either the "RelinkFrom" adornment or the "RelinkTo" adornment, saving the result in Handle.

Normally when this method is called the value of OriginalLink and Handle will be null, resulting in a call to FindToolHandleAt(Point, string) 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 FindToolHandleAt(Point, string), because the programmer has already set up which relinking handle they want the user to be relinking. Finding a handle is not necessary if OriginalLink and IsForwards have been set before calling this method.

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

If OriginalLink or Handle was not set beforehand, the value of IsForwards is set depending on the category of the relink handle found. The 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.

DoDeactivate()

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

Declaration
public override void DoDeactivate()
Overrides
Remarks

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

DoMouseUp()

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.

Declaration
public override void DoMouseUp()
Overrides
Remarks

A successful relinking calls ReconnectLink(Link, Node, GraphObject, bool) to actually change the link. The "LinkRelinked" DiagramEvent is raised with the link as the Subject and with the now-disconnected original port as the Parameter. If the link was not reconnected, this calls DoNoRelink(Link, bool). 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(Link, Node, GraphObject, bool). It is actually most common to implement a "LinkRelinked" DiagramEvent listener on the Diagram.

DoNoRelink(Link, bool)

This method is called upon a mouse up when ReconnectLink(Link, Node, GraphObject, bool) is not called.

Declaration
public virtual void DoNoRelink(Link existinglink, bool toend)
Parameters
Type Name Description
Link existinglink
bool toend

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

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

ReconnectLink(Link, Node, GraphObject, bool)

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

Declaration
public virtual bool ReconnectLink(Link existinglink, Node newnode, GraphObject newport, bool toend)
Parameters
Type Name Description
Link existinglink
Node newnode

the Node to connect to or from.
GraphObject newport

the GraphObject port to connect to or from.
bool toend

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

true if successful.
Remarks

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.

See Also

UpdateAdornments(Part)

Show an Adornment for each end of the Link that the user may reconnect.

Declaration
public override void UpdateAdornments(Part part)
Parameters
Type Name Description
Part part
Overrides
Remarks

The Adornment may have a copy of FromHandleArchetype and/or ToHandleArchetype.

This method may be overridden.