Options
All
  • Public
  • Public/Protected
  • All
Menu

Class LinkingTool

Hierarchy

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();

Index

Constructors

constructor

Properties

archetypeLabelNodeData : ObjectData | null

archetypeLinkData : ObjectData | null

direction : EnumValue

startObject : GraphObject | null

  • Gets or sets the GraphObject at which findLinkablePort should start its search. 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();
    

Methods

Override canStart

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

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

    Returns boolean

Override doActivate

  • doActivate(): 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 linking operation; if there is a valid targetPort nearby, this adds a new Link by calling insertLink.

    If there is a new link, it is selected and the "LinkDrawn" DiagramEvent is raised with the new link as the DiagramEvent.subject. If there is no new link, this calls doNoLink. 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.

    Returns void

Virtual doNoLink

  • This method is called upon a mouse up when no new link is drawn, either because no valid LinkingBaseTool.targetPort was found or because insertLink returned null.

    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.

    since

    1.7

    Parameters

    • fromnode: Node | null
    • fromport: GraphObject | null

      the from-port, or null to use the node itself

    • tonode: Node | null
    • toport: GraphObject | null

      the to-port, or null to use the node itself

    Returns void

Virtual findLinkablePort

Virtual insertLink

  • Make a copy of the archetypeLinkData, set its node and port properties, and add it to the GraphLinksModel. If the model is a TreeModel, set the parent key of the child's node data object.

    For GraphLinksModels, if archetypeLabelNodeData is non-null, this method also adds that node data as an initial label node for the new link data.

    For TreeModels, if Diagram.isTreePathToChildren is false, the roles of the fromnode and tonode arguments are exchanged.

    This method may be overridden, but we recommend that you call this base method. Usually though it is easiest to just set archetypeLinkData to control what kind of link is created. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    see

    doNoLink

    Parameters

    • fromnode: Node | null
    • fromport: GraphObject | null

      the from-port, or null to use the node itself

    • tonode: Node | null
    • toport: GraphObject | null

      the to-port, or null to use the node itself

    Returns Link | null

    the newly created Link, or null if it failed.

Constants

Static BackwardsOnly : EnumValue

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

Static Either : EnumValue

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

Static ForwardsOnly : EnumValue

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