C

PortRelocationHandle

Show Usages
A sophisticated implementation of the IHandle interface that lets the user change an edge's source and targetPort.
ImplementsInheritance Hierarchy

Remarks

This handle will move one of the edge's end points visually to another IPort or IPortCandidate and upon finalization of the gesture will set the new ports for the edge. This class heavily relies on the implementation of the IEdgeReconnectionPortCandidateProvider that is queried from the IEdge this handle is acting on.

Examples

Instances of this IHandle are provided by the PortRelocationHandleProvider. The most commonly used settings are available on the PortRelocationHandleProvider, too:

graph.decorator.edges.portHandleProvider.addFactory((edge) => {
  const portRelocationHandleProvider = new PortRelocationHandleProvider(
    graph,
    edge,
  )
  portRelocationHandleProvider.visualization = Visualization.LIVE
  portRelocationHandleProvider.showPortCandidates = false
  return portRelocationHandleProvider
})

For less frequently used settings a custom PortRelocationHandleProvider has to be provided and its createPortRelocationHandle method has to be overridden to provide the configured PortRelocationHandle:

graph.decorator.edges.portHandleProvider.addFactory((edge) => {
  const portRelocationHandleProvider = new MyHandleProvider(graph, edge)
  portRelocationHandleProvider.visualization = Visualization.LIVE
  portRelocationHandleProvider.showPortCandidates = false
  return portRelocationHandleProvider
})

class MyHandleProvider extends PortRelocationHandleProvider {
  constructor(graph: IGraph, edge: IEdge) {
    super(graph, edge)
  }

  createPortRelocationHandle(
    graph: IGraph,
    edge: IEdge,
    sourceEnd: boolean,
  ): IHandle {
    const portRelocationHandle = new PortRelocationHandle(
      graph,
      edge,
      sourceEnd,
    )
    portRelocationHandle.addExistingPort = true
    return portRelocationHandle
  }
}

See Also

Developer's Guide

API

getPortCandidates, reconnectionPortCandidateProvider

Members

Show:

Constructors

PortRelocationHandle

(
graph: IGraph
edge: IEdge
sourceEnd: boolean
)
Creates a new instance of the PortRelocationHandle class.

Parameters

graph: IGraph
The graph or null. If the graph instance is not specified, the handle will try to receive the graph from the IInputModeContext it is passed in during initializeDrag.
edge: IEdge
The edge.
sourceEnd: boolean
if set to true the source end will be subject to relocation, otherwise it will be the target port.

Properties

addExistingPort

: boolean
Gets or sets a property that determines whether the existing port should be available as a possible port candidate, too.
The default is true. If this property is set to false, getPortCandidates will return only the ports provided by the IPortCandidateProvider in the node's lookup.
final

allowCyclicPortDependencies

: boolean
Gets or sets whether or not cyclic port dependencies are allowed.
If edge to edge connections are allowed by this instance, this property determines whether getClosestCandidates will yield candidates that would result in the edge being modified creating a cyclic dependency. The default is false.
final

allowEdgeToEdgeConnections

: boolean
Gets or sets whether or not edges are allowed to connect to other edges.
The default is true.
final

cursor

: Cursor
Gets the cursor to display when the mouse hovers over or drags this handle.
conversion

Implements

IHandle.cursor

edge

: IEdge
protectedreadonly
Gets the edge this instance acts upon.
protectedreadonlyfinal

Property Value

The edge.

location

: IPoint
readonly
Gets a view of the location of the item.
This implementation returns this.
readonly

maximumSnapDistance

: number
Gets or sets the maximum distance the pointer may be away from a candidate in order to be snapped to the candidate.
The distance is measured in view coordinates. The default value is 50.0.
final

See Also

Developer's Guide
API
maximumSnapDistance

parentInputModeContext

: IInputModeContext
protected
Gets or sets the context to operate on.
protectedfinal

portCandidateRenderer

: IObjectRenderer<PortCandidateRenderTag>
Gets or sets the IObjectRenderer<PortCandidateRenderTag> that visualizes the IPortCandidates.

When queried for an IVisualCreator to obtain the visualizations for port candidates, this renderer is passed instances of PortCandidateRenderTag as render tag. The renderer may change the appearance of a port candidate depending on isCurrentCandidate and validity.

The default value is an instance of PortCandidateRenderer.

final

Property Value

The renderer for the port candidate visualizations.

See Also

API
portCandidateRenderer

portCandidateResolutionRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to resolve a DYNAMIC port candidate.

Note that this property has no effect if resolvePortCandidates is set to false.

The default detects the current platform and delegates either to META_IS_DOWN (macOS) or CTRL_IS_DOWN (other platforms).

final

previewEdge

: SimpleEdge
protectedreadonly
Gets the preview edge this instance uses during the edit.
Only used if visualization is set to PLACEHOLDER.
protectedreadonlyfinal

Property Value

The preview edge.

See Also

API
visualization

resolvePortCandidates

: boolean
Gets or sets a value indicating whether a DYNAMIC port candidate should be resolved for the current mouse location.
By default, this feature is enabled and the portCandidateResolutionRecognizer is configured so that the resolution mechanism is used if the user holds the Ctrl modifier during the gesture.
final

See Also

API
portCandidateResolutionRecognizer, resolveCandidate

showHitPortOwnerCandidatesOnly

: boolean
Gets or sets a value indicating whether to show the candidates of hit IPortOwners only.
final

Property Value

true if only candidates of hit nodes and edges are shown; false otherwise. Default is true.

See Also

Developer's Guide
API
showHitPortOwnerCandidatesOnly

showPortCandidates

: boolean
Gets or sets a value indicating whether to show port candidates.
final

Property Value

true port candidates should be shown; false otherwise. Default is true.

See Also

Developer's Guide
API
showPortCandidates

showTargetHighlight

: boolean
Gets or sets whether the owner of the current IPortCandidate should be highlighted.
The default is true.
final

See Also

Developer's Guide
API
updateHighlight, showTargetHighlight

sourceEnd

: boolean
protectedreadonly
Gets a value indicating whether the source end of the edge is handled by this instance.
protectedreadonlyfinal

Property Value

true if the source end is handled; false otherwise.

tag

: any
Gets an optional tag object associated with the handle.
The value can be used in custom handlesRenderer
final

Implements

IHandle.tag

type

: HandleType
Gets the type of the handle that can be used by the rendering engine to render types differently.
conversion

Implements

IHandle.type

visualization

: Visualization
Gets or sets how the changed edge should be shown during the gesture.

This property must not be changed during the gesture.

If this property is set to LIVE it is crucial that constructor's graph parameter is not null and its edge parameter is an edge which is contained in that graph.

Default is PLACEHOLDER.

conversionfinal

See Also

Developer's Guide
API
visualization

Methods

cancelDrag

(context: IInputModeContext, originalLocation: Point)
Called by clients to indicate that the dragging has been canceled by the user.
This method may be called after the initial initializeDrag and zero or more invocations of handleMove. Implementations should reset the position of the items they modify to their initial state. Alternatively to this method the dragFinished method might be called.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.
originalLocation: Point
The value of the coordinate of the location property at the time of initializeDrag.

createExistingPortCandidate

(port: IPort): IPortCandidate
protected
Factory method that creates the candidate for the existing port.
protected

Parameters

port: IPort
The port to create a candidate for.

Return Value

IPortCandidate
The candidate or null.

See Also

API
getPortCandidates, addExistingPort

createPreviewEdge

(edge: IEdge): SimpleEdge
protected
Factory method that creates the preview edge that will be shown during the drag operation.
protected

Parameters

edge: IEdge
The edge to be represented by the preview edge.

Return Value

SimpleEdge
The preview edge instance to use.

See Also

API
visualization

dragFinished

(
context: IInputModeContext
originalLocation: Point
newLocation: Point
)
Called by clients to indicate that the repositioning has just been finished.
This method may be called after the initial initializeDrag and zero or more invocations of handleMove. Alternatively to this method the cancelDrag method might be called.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.
originalLocation: Point
The value of the location property at the time of initializeDrag.
newLocation: Point
The coordinates in the world coordinate system that the client wants the handle to be at. Depending on the implementation the location may or may not be modified to reflect the new value. This is the same value as delivered in the last invocation of handleMove.

filterCandidates

(
context: IInputModeContext
location: Point
allCandidates: IEnumerable<IPortCandidate>
): IEnumerable<IPortCandidate>
protected
Filters the given allCandidates to return the subset of candidates which are relevant at the given location.

If showHitPortOwnerCandidatesOnly is set to true, this implementation returns only the candidates of the port owner at the given location. Otherwise, it returns the entire allCandidates.

Developers can override this method to apply a different filter, e.g., all port candidates in a defined radius around the location.

protected

Parameters

context: IInputModeContext
The context that is used to retrieve the candidates for.
location: Point
The current location.
allCandidates: IEnumerable<IPortCandidate>
All possible port candidates.

Return Value

IEnumerable<IPortCandidate>
The filtered list of port candidates.

getClosestCandidate

(
context: IInputModeContext
location: Point
candidates: IEnumerable<IPortCandidate>
): IPortCandidate
protected
Finds the closest candidate from the given set of candidates.
protected

Parameters

context: IInputModeContext
The context in which the closest handle candidate is sought.
location: Point
The location for which to find a candidate.
candidates: IEnumerable<IPortCandidate>
The list of possible candidates.

Return Value

IPortCandidate
The closest candidate or null.

getCurrentOwner

(context: IInputModeContext, location: Point): IPortOwner
protected
Gets the IPortOwner at the given location.
protected

Parameters

context: IInputModeContext
The input mode context.
location: Point
The location to find a port owner at.

Return Value

IPortOwner
The IPortOwner at the given location or null.

getGraph

(context: IInputModeContext): IGraph
protected
Gets the graph to use from the context.
protected

Parameters

context: IInputModeContext
The input mode context.

Return Value

IGraph
A graph instance or null.

getPort

(
context: IInputModeContext
portCandidate: IPortCandidate
suggestedLocation: Point
): IPort
protected
Called during dragFinished to actually get the new port from the chosen candidate.
This implementation returns the result of createPort or calls addPort if the result was null.
protected

Parameters

context: IInputModeContext
portCandidate: IPortCandidate
The candidate to get a port instance from.
suggestedLocation: Point
The suggested location for the port.

Return Value

IPort
A non-null port instance.

See Also

API
setPorts

getPortCandidates

(
context: IInputModeContext
edge: IEdge
sourcePort: boolean
): IEnumerable<IPortCandidate>
protected
Gets the possible candidates for the given edge.
This implementation uses the IEdgeReconnectionPortCandidateProvider from the edge's lookup to retrieve the candidate sets. If addExistingPort is enabled, the existing port will be part of the candidates.
protected

Parameters

context: IInputModeContext
The context that is used to retrieve the candidates for.
edge: IEdge
The edge.
sourcePort: boolean
Whether to look for source port candidates.

Return Value

IEnumerable<IPortCandidate>
A non-null enumerable over the candidates.

getPortCandidatesDuringMove

(
context: IInputModeContext
edge: IEdge
sourcePort: boolean
): IEnumerable<IPortCandidate>
protected
Retrieves the port candidates during handleMove.
This implementation returns candidates which were collected in initializeDrag. Developers who want to newly determine the candidates with each move might override this method to delegate to getPortCandidates instead.
protected

Parameters

context: IInputModeContext
The context that is used to retrieve the candidates for.
edge: IEdge
The edge.
sourcePort: boolean
Whether to look for source port candidates.

Return Value

IEnumerable<IPortCandidate>
A non-null enumerable over the candidates.

handleClick

(evt: ClickEventArgs)
Called to indicate that the handle has been clicked or tapped by the user.

This method is called by HandleInputMode when clickRecognizer or clickRecognizerTouch is triggered.

Changing the cursor or type of the clicked handle will instantly be considered by the HandleInputMode but handles won't be re-queried automatically. If, for example, different handles should be used as a result of the click, requeryHandles has to be called.

Parameters

evt: ClickEventArgs
Arguments describing the click.

handleMove

(
context: IInputModeContext
originalLocation: Point
newLocation: Point
)
Called by clients to indicate that the element has been dragged and its position should be updated.
This method may be called more than once after an initial initializeDrag and the final call will be followed by either one dragFinished or one cancelDrag call.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.
originalLocation: Point
The value of the location property at the time of initializeDrag.
newLocation: Point
The coordinates in the world coordinate system that the client wants the handle to be at. Depending on the implementation, the location may or may not be modified to reflect the new value.

hideOriginalEdge

(context: IInputModeContext, edge: IEdge)
protected
Hides the original edge that during the drag operation.
Only called if visualization is set to PLACEHOLDER.
protected

Parameters

context: IInputModeContext
The context to get the canvas the edge should be hidden from.
edge: IEdge
The edge to hide.

See Also

API
unhideOriginalEdge, visualization

initializeDrag

(context: IInputModeContext)
Called by clients to indicate that the element is going to be dragged.
This call will be followed by one or more calls to handleMove, and a final dragFinished or cancelDrag.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.

isPortCandidateResolutionEnabled

(context: IInputModeContext): boolean
protected
Determines whether port candidate resolution is enabled for the current gesture.
This implementation checks whether the parent input mode is an instance of HandleInputMode, the portCandidateResolutionRecognizer recognizes its PointerEventArgs, and the currentHandle's location is equal to this location.
protected

Parameters

context: IInputModeContext
The context to inspect.

Return Value

boolean
true if port candidates may be resolved; false otherwise.

resolveCandidate

(
context: IInputModeContext
portCandidate: IPortCandidate
location: Point
): IPortCandidate
protected
Tries to resolve a dynamic port candidate for the given location.
protected

Parameters

context: IInputModeContext
The context in which the candidate is resolved.
portCandidate: IPortCandidate
The candidate.
location: Point
The current location.

Return Value

IPortCandidate
A candidate.

setClosestCandidate

(portCandidate: IPortCandidate)
protected
Updates the closest candidate for visual feedback.
protected

Parameters

portCandidate: IPortCandidate
The IPortCandidate to set as closest candidate.

setPort

(
context: IInputModeContext
edge: IEdge
setSourcePort: boolean
portCandidate: IPortCandidate
suggestedLocation: Point
)
protected
Triggered by dragFinished to actually change the port.
protected

Parameters

context: IInputModeContext
The context.
edge: IEdge
The edge to change ports.
setSourcePort: boolean
Whether to set the source port. false for target ports.
portCandidate: IPortCandidate
The candidate that has been chosen.
suggestedLocation: Point
The suggested location for the port.

setPorts

(
context: IInputModeContext
edge: IEdge
sourcePort: IPort
targetPort: IPort
)
protected
Finally sets the ports for the edge to the new values.
protected

Parameters

context: IInputModeContext
The context in which the ports are set.
edge: IEdge
The edge to set the ports for.
sourcePort: IPort
The (possibly) new source port.
targetPort: IPort
The (possibly) new target port.

setPosition

(location: Point)
protected
Updates the position of the handle.
protected

Parameters

location: Point
The new location of the handle.

setToPortCandidate

(
preview: SimpleEdge
source: boolean
portCandidate: IPortCandidate
)
protected
Updates the preview edge's visual appearance to reflect the new port candidate.
protected

Parameters

preview: SimpleEdge
The preview edge.
source: boolean
Whether to update the source or target port.
portCandidate: IPortCandidate
The new candidate to indicate.

unhideOriginalEdge

(edge: IEdge, canvasComponent: CanvasComponent)
protected
Unhides the original edge that was hidden during the drag operation.
protected

Parameters

edge: IEdge
The edge to unhide.
canvasComponent: CanvasComponent
The control the edge was hidden from.

See Also

API
hideOriginalEdge, visualization

updateHighlight

(oldCandidate: IPortCandidate, newCandidate: IPortCandidate)
protected
Draws the highlight for the owner of the current port candidate.

This implementation retrieves the HighlightIndicatorManager<T> from the parentInputModeContext's ILookup.

Overriders have to take care of removal of the highlight of the oldCandidate's owner, too.

protected

Parameters

oldCandidate: IPortCandidate
The port candidate whose owner is currently highlighted.
newCandidate: IPortCandidate
The port candidate whose owner should be highlighted.

See Also

API
showTargetHighlight