Class LinkingBaseTool

Namespace

Northwoods.Go.Tools

Assembly

Northwoods.GoDiagram.WinForms.dll

This abstract class is the base class for the LinkingTool and RelinkingTool classes.

public abstract class LinkingBaseTool : Tool

Inheritance

object

Tool

LinkingBaseTool

Derived

LinkingTool

RelinkingTool

Inherited Members

Tool.Diagram

Tool.UpdateAdornments(Part)

Tool.CanStart()

Tool.DoStart()

Tool.DoActivate()

Tool.DoDeactivate()

Tool.DoStop()

Tool.DoCancel()

Tool.StopTool()

Tool.DoMouseDown()

Tool.DoMouseUp()

Tool.DoMouseWheel()

Tool.CanStartMultiTouch()

Tool.StandardPinchZoomStart()

Tool.StandardPinchZoomMove()

Tool.DoKeyDown()

Tool.DoKeyUp()

Tool.StartTransaction(string)

Tool.StopTransaction()

Tool.StandardMouseSelect()

Tool.StandardMouseClick(Func<GraphObject, GraphObject>, Predicate<GraphObject>)

Tool.StandardMouseClick(Func<GraphObject, GraphObject>)

Tool.StandardMouseOver()

Tool.StandardMouseWheel()

Tool.StandardWaitAfter(double, InputEvent)

Tool.CancelWaitAfter()

Tool.DoWaitAfter(InputEvent)

Tool.FindToolHandleAt(Point, string)

Tool.IsBeyondDragSize(Point?, Point?)

Tool.Name

Tool.IsEnabled

Tool.IsActive

Tool.TransactionResult

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This class includes properties for defining and accessing any temporary nodes and temporary link that are used during any linking operation, as well as access to the existing diagram's nodes and link (if any) that are involved with the linking operation.

For a general discussion of link routing, see: Introduction to Links, Introduction to Link Labels, and Introduction to Link Connection Points. For customizing the linking tools, see Introduction to the Linking Tools. For customizing the reshaping of Links, see Introduction to the LinkReshapingTool. For a general discussion of validation, see Introduction to Validation.

Constructors

LinkingBaseTool()

Don't construct this directly -- this is an abstract class.

public LinkingBaseTool()

Properties

IsForwards

Gets whether the linking operation is in the forwards direction, connecting from the "from" port to the "to" port.

public bool IsForwards { get; set; }

Property Value

bool

IsUnconnectedLinkValid

Gets or sets whether it is valid to have partly or completely unconnected links.

public bool IsUnconnectedLinkValid { get; set; }

Property Value

bool

Remarks

The default value is false -- the user cannot draw or reconnect a link to "nowhere". Setting this property does not raise any events.

LinkValidation

Gets or sets a predicate that determines whether or not a new link between two ports would be valid.

public Func<Node, GraphObject, Node, GraphObject, Link, bool> LinkValidation { get; set; }

Property Value

Func<Node, GraphObject, Node, GraphObject, Link, bool>

Remarks

This predicate is called in addition to the normal link checking performed by IsValidLink(Node, GraphObject, Node, GraphObject) and any 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.

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

The function, if supplied, must not have any side-effects.

LinkingCursor

Gets or sets the cursor used during the linking or relinking operation.

public string LinkingCursor { get; set; }

Property Value

string

Remarks

The default value is "pointer".

OriginalFromNode

Gets or sets the original Node from which the new link is being drawn or from which the OriginalLink was connected when being relinked.

public Node OriginalFromNode { get; set; }

Property Value

Node

Remarks

Setting this property does not raise any events.

OriginalFromPort

Gets or sets the GraphObject that is the port in the OriginalFromNode.

public GraphObject OriginalFromPort { get; set; }

Property Value

GraphObject

Remarks

Setting this property does not raise any events.

OriginalLink

Gets or sets the original Link being reconnected by the RelinkingTool.

public Link OriginalLink { get; set; }

Property Value

Link

Remarks

Setting this property does not raise any events.

OriginalToNode

Gets or sets the original Node to which the new link is being drawn or to which the OriginalLink was connected when being relinked.

public Node OriginalToNode { get; set; }

Property Value

Node

Remarks

Setting this property does not raise any events.

OriginalToPort

Gets or sets the GraphObject that is the port in the OriginalToNode.

public GraphObject OriginalToPort { get; set; }

Property Value

GraphObject

Remarks

Setting this property does not raise any events.

PortGravity

Gets or sets the distance at which link snapping occurs.

public double PortGravity { get; set; }

Property Value

double

Remarks

The default value is 100.0. The value must be non-negative. Setting this property does not raise any events.

PortTargeted

Gets or sets a function that is called as the tool targets the nearest valid port.

public Action<Node, GraphObject, Node, GraphObject, bool> PortTargeted { get; set; }

Property Value

Action<Node, GraphObject, Node, GraphObject, bool>

Remarks

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.

When there is no valid port within the PortGravity, the first two arguments are null.

The function, if supplied, must not add or remove any links or nodes or port objects, nor may it change the validity of any potential link connection.

TargetPort

Gets or sets a proposed GraphObject port for connecting a link.

public GraphObject TargetPort { get; set; }

Property Value

GraphObject

Remarks

Whether this is a "to" port or a "from" port depends on the direction (IsForwards) in which the link is being drawn or reconnected.

This is set when the mouse is being dragged and when a mouse-up event occurs with the result of a call to FindTargetPort(bool). Setting this property does not raise any events.

TemporaryFromNode

Gets or sets the temporary Node at the "from" end of the TemporaryLink while the user is drawing or reconnecting a link.

public Node TemporaryFromNode { get; set; }

Property Value

Node

Remarks

Setting this property does not raise any events.

TemporaryFromPort

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.

public GraphObject TemporaryFromPort { get; set; }

Property Value

GraphObject

Remarks

Setting this property does not raise any events.

TemporaryLink

Gets or sets the temporary Link that is shown while the user is drawing or reconnecting a link.

public Link TemporaryLink { get; set; }

Property Value

Link

Remarks

Setting this property does not raise any events.

TemporaryToNode

Gets or sets the temporary Node at the "to" end of the TemporaryLink while the user is drawing or reconnecting a link.

public Node TemporaryToNode { get; set; }

Property Value

Node

Remarks

Setting this property does not raise any events.

TemporaryToPort

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.

public GraphObject TemporaryToPort { get; set; }

Property Value

GraphObject

Remarks

Setting this property does not raise any events.

Methods

CopyPortProperties(Node, GraphObject, Node, GraphObject, bool)

Make a temporary port look and act like a real one.

protected virtual void CopyPortProperties(Node realnode, GraphObject realport, Node tempnode, GraphObject tempport, bool toend)

Parameters

realnode Node

realport GraphObject

tempnode Node

tempport GraphObject

toend bool

Remarks

This is called by DoMouseMove() as the tool finds new valid target ports. If FindTargetPort(bool) returns null, it calls SetNoTargetPortProperties(Node, GraphObject, bool) instead.

If the PortTargeted property is a function, that function is called. It is easier to customize the behavior by setting that functional property than it is to override this method and the SetNoTargetPortProperties(Node, GraphObject, bool) method. But you may want to call this method to get the standard behavior for dynamically adapting the temporary node/port to "act like" the target port. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoMouseMove()

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.

public override void DoMouseMove()

Remarks

This calls FindTargetPort(bool) to update the TargetPort given the new mouse point. If a valid target port is found this moves the temporary node/port and makes them appear like the target node/port by calling CopyPortProperties(Node, GraphObject, Node, GraphObject, bool). If no valid target port is found, this moves the temporary node to where the mouse currently is and removes any node/port appearance, by calling SetNoTargetPortProperties(Node, GraphObject, bool).

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

FindTargetPort(bool)

Find a port with which the user could complete a valid link.

public virtual GraphObject FindTargetPort(bool toend)

Parameters

toend bool

true if looking for a "to" port.

Returns

GraphObject

a valid port, or null if no such port is near the current mouse point within the PortGravity distance.

Remarks

This finds objects near to the current mouse point for which a valid link connection is possible.

For each port element found, this calls IsValidLink(Node, GraphObject, Node, GraphObject) to find out if a link between the original node/port and the found node/port would be valid. The result is saved in a cache for faster decisions later during operation of this tool. The closest valid port is returned.

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.

IsInSameNode(GraphObject, GraphObject)

This predicate is true if both argument ports are in the same Node.

public virtual bool IsInSameNode(GraphObject fromport, GraphObject toport)

Parameters

fromport GraphObject

toport GraphObject

Returns

bool

Remarks

This is called by IsValidLink(Node, GraphObject, Node, GraphObject).

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

IsLinked(GraphObject, GraphObject)

This predicate is true if there is a link in the diagram going from the given port to the given port.

public virtual bool IsLinked(GraphObject fromport, GraphObject toport)

Parameters

fromport GraphObject

toport GraphObject

Returns

bool

Remarks

This is called by IsValidLink(Node, GraphObject, Node, GraphObject).

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

IsValidCycle(Node, Node, Link)

Checks whether a proposed link would be valid according to ValidCycle.

public virtual bool IsValidCycle(Node from, Node to, Link ignore = null)

Parameters

from Node

to Node

ignore Link

Returns

bool

Remarks

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(Node, GraphObject, Node, GraphObject).

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

IsValidFrom(Node, GraphObject)

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

public virtual bool IsValidFrom(Node fromnode, GraphObject fromport)

Parameters

fromnode Node

fromport GraphObject

Returns

bool

False if the node is in a Layer that does not AllowLink. False if the port's FromLinkable is either false or null. False if the double of links connected to the port would exceed the port's FromMaxLinks. Otherwise true.

Remarks

This is called by IsValidLink(Node, GraphObject, Node, GraphObject).

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

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.

IsValidLink(Node, GraphObject, Node, GraphObject)

This predicate should be true when it is logically valid to connect a new link from one node/port to another node/port.

public virtual bool IsValidLink(Node fromnode, GraphObject fromport, Node tonode, GraphObject toport)

Parameters

fromnode Node

the "from" Node.

fromport GraphObject

the "from" GraphObject port.

tonode Node

the "to" Node.

toport GraphObject

the "to" GraphObject port.

Returns

bool

False if IsValidFrom(Node, GraphObject) is false for the "from" node/port. False if IsValidTo(Node, GraphObject) is false for the "to" node/port. False if IsInSameNode(GraphObject, GraphObject) is true unless FromLinkableSelfNode and ToLinkableSelfNode are true for the two ports. False if IsLinked(GraphObject, GraphObject) is true unless FromLinkableDuplicates and ToLinkableDuplicates are true for the two ports. False if trying to link to the link's own label node(s). If LinkValidation is a predicate on either or both of the "from" node and the "to" node, the predicate is called and if it returns false, this predicate returns false. If LinkValidation is a predicate and if it returns false, this predicate returns false. Otherwise this predicate is true.

Remarks

When this is called by the RelinkingTool, that tool sets OriginalLink to be the Link being reconnected.

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

This method may be overridden, although it is usually much easier to just set LinkValidation or LinkValidation in order to add some application-specific link validation. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

IsValidTo(Node, GraphObject)

This predicate is true if it is permissible to connect a link to a given node/port.

public virtual bool IsValidTo(Node tonode, GraphObject toport)

Parameters

tonode Node

toport GraphObject

Returns

bool

False if the node is in a Layer that does not AllowLink. False if the port's ToLinkable is either false or null. False if the double of links connected from the port would exceed the port's ToMaxLinks. Otherwise true.

Remarks

This is called by IsValidLink(Node, GraphObject, Node, GraphObject).

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

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.

SetNoTargetPortProperties(Node, GraphObject, bool)

Reset a temporary port's properties to neutral values when there is no target port.

protected virtual void SetNoTargetPortProperties(Node tempnode, GraphObject tempport, bool toend)

Parameters

tempnode Node

tempport GraphObject

toend bool

Remarks

This is called by DoMouseMove() when the tool finds no new valid target port. If FindTargetPort(bool) returns non-null, it calls CopyPortProperties(Node, GraphObject, Node, GraphObject, bool) instead.

If the PortTargeted property is a function, that function is called with null values as the first two arguments. It is easier to customize the behavior by setting that functional property than it is to override this method and the CopyPortProperties(Node, GraphObject, Node, GraphObject, bool) method. But you may want to call this method to get the standard behavior for dynamically adapting the temporary node/port to "act like" it is not connecting with any target port. Please read the Introduction page on Extensions for how to override methods and how to call this base method.